Refactor docs into mdbook (#547)
* Refactor documentation, ef_tests makefile * Add makefile to root * Tidy readme * Fix readme badges * Tidy logs * Add terminalize gif * Update readme image * Update readme image * Tidy logs * Update readme image * Update readme * Update readme * Fix book link * Update makefiles * Update book * Fix link in book * Add readme for book * Remove old docs, move api spec YAML * Fix eth2/ dir readme * Add readme for lcli * Add about this book section * Minor formatting improvements * Address mehdi's comments
This commit is contained in:
Paul Hauner
GitHub
parent
7eb82125ef
commit
9aedb12bfc
47
Makefile
47
Makefile
@ -1,31 +1,30 @@
|
|||||||
TESTS_TAG := v0.8.3
|
.PHONY: tests
|
||||||
TESTS = general minimal mainnet
|
|
||||||
|
|
||||||
TESTS_BASE_DIR := ./tests/ef_tests
|
EF_TESTS = "tests/ef_tests"
|
||||||
REPO_NAME := eth2.0-spec-tests
|
|
||||||
OUTPUT_DIR := $(TESTS_BASE_DIR)/$(REPO_NAME)
|
|
||||||
|
|
||||||
BASE_URL := https://github.com/ethereum/$(REPO_NAME)/releases/download/$(SPEC_VERSION)
|
|
||||||
|
|
||||||
|
# Builds the entire workspace in release (optimized).
|
||||||
|
#
|
||||||
|
# Binaries will most likely be found in `./target/release`
|
||||||
release:
|
release:
|
||||||
cargo build --all --release
|
cargo build --release --all
|
||||||
|
|
||||||
clean_ef_tests:
|
# Runs the full workspace tests, without downloading any additional test
|
||||||
rm -r $(OUTPUT_DIR)
|
# vectors.
|
||||||
|
test:
|
||||||
|
cargo test --all --all-features --release
|
||||||
|
|
||||||
ef_tests: download_tests extract_tests
|
# Runs the entire test suite, downloading test vectors if required.
|
||||||
mkdir $(OUTPUT_DIR)
|
test-full: make-ef-tests test
|
||||||
for test in $(TESTS); do \
|
|
||||||
tar -C $(OUTPUT_DIR) -xvf $(TESTS_BASE_DIR)/$$test.tar ;\
|
|
||||||
rm $(TESTS_BASE_DIR)/$$test.tar ;\
|
|
||||||
done
|
|
||||||
|
|
||||||
extract_tests:
|
# Runs the makefile in the `ef_tests` repo.
|
||||||
for test in $(TESTS); do \
|
#
|
||||||
gzip -df $(TESTS_BASE_DIR)/$$test.tar.gz ;\
|
# May download and extract an archive of test vectors from the ethereum
|
||||||
done
|
# repositories. At the time of writing, this was several hundred MB of
|
||||||
|
# downloads which extracts into several GB of test vectors.
|
||||||
|
make-ef-tests:
|
||||||
|
make -C $(EF_TESTS)
|
||||||
|
|
||||||
download_tests:
|
# Performs a `cargo` clean and cleans the `ef_tests` directory.
|
||||||
for test in $(TESTS); do \
|
clean:
|
||||||
wget -P $(TESTS_BASE_DIR) $(BASE_URL)/$$test.tar.gz; \
|
cargo clean
|
||||||
done
|
make -C $(EF_TESTS) clean
|
||||||
|
|||||||
172
README.md
172
README.md
@ -2,172 +2,77 @@
|
|||||||
|
|
||||||
An open-source Ethereum 2.0 client, written in Rust and maintained by Sigma Prime.
|
An open-source Ethereum 2.0 client, written in Rust and maintained by Sigma Prime.
|
||||||
|
|
||||||
[![Build Status]][Build Link] [![Doc Status]][Doc Link] [![Chat Badge]][Chat Link]
|
[![Build Status]][Build Link] [![Book Status]][Book Link] [![RustDoc Status]][RustDoc Link] [![Chat Badge]][Chat Link] [![Swagger Badge]][Swagger Link]
|
||||||
|
|
||||||
[Build Status]: https://gitlab.sigmaprime.io/sigp/lighthouse/badges/master/build.svg
|
[Build Status]: https://gitlab.sigmaprime.io/sigp/lighthouse/badges/master/build.svg
|
||||||
[Build Link]: https://gitlab.sigmaprime.io/sigp/lighthouse/pipelines
|
[Build Link]: https://gitlab.sigmaprime.io/sigp/lighthouse/pipelines
|
||||||
[Chat Badge]: https://img.shields.io/badge/chat-discord-%237289da
|
[Chat Badge]: https://img.shields.io/badge/chat-discord-%237289da
|
||||||
[Chat Link]: https://discord.gg/cyAszAh
|
[Chat Link]: https://discord.gg/cyAszAh
|
||||||
[Doc Status]: https://img.shields.io/badge/docs-master-blue.svg
|
[Book Status]:https://img.shields.io/badge/user--docs-master-informational
|
||||||
[Doc Link]: http://lighthouse-docs.sigmaprime.io/
|
[Book Link]: http://lighthouse-book.sigmaprime.io/
|
||||||
|
[RustDoc Status]:https://img.shields.io/badge/code--docs-master-orange
|
||||||
|
[RustDoc Link]: http://lighthouse-docs.sigmaprime.io/
|
||||||
|
[Swagger Badge]: https://img.shields.io/badge/Open%20API-0.2.0-success
|
||||||
|
[Swagger Link]: https://app.swaggerhub.com/apis-docs/spble/lighthouse_rest_api/0.2.0
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## Overview
|
## Overview
|
||||||
|
|
||||||
Lighthouse is:
|
Lighthouse is:
|
||||||
|
|
||||||
- Fully open-source, licensed under Apache 2.0.
|
- Fully open-source, licensed under Apache 2.0.
|
||||||
- Security-focused, fuzzing has begun and security reviews are planned
|
- Security-focused. Fuzzing has begun and security reviews are planned
|
||||||
for late-2019.
|
for late-2019.
|
||||||
- Built in [Rust](https://www.rust-lang.org/), a modern language providing unique safety guarantees and
|
- Built in [Rust](https://www.rust-lang.org/), a modern language providing unique safety guarantees and
|
||||||
excellent performance (comparable to C++).
|
excellent performance (comparable to C++).
|
||||||
- Funded by various organisations, including Sigma Prime, the
|
- Funded by various organisations, including Sigma Prime, the
|
||||||
Ethereum Foundation, ConsenSys and private individuals.
|
Ethereum Foundation, ConsenSys and private individuals.
|
||||||
- Actively working to promote an inter-operable, multi-client Ethereum 2.0.
|
- Actively involved in the specification and security analysis of the emerging
|
||||||
|
Ethereum 2.0 specification.
|
||||||
|
|
||||||
|
Like all Ethereum 2.0 clients, Lighthouse is a work-in-progress.
|
||||||
|
|
||||||
## Development Status
|
## Development Status
|
||||||
|
|
||||||
Lighthouse, like all Ethereum 2.0 clients, is a work-in-progress. Instructions
|
|
||||||
are provided for running the client, however these instructions are designed
|
|
||||||
for developers and researchers working on the project. We do not (yet) provide
|
|
||||||
user-facing functionality.
|
|
||||||
|
|
||||||
Current development overview:
|
Current development overview:
|
||||||
|
|
||||||
- Specification `v0.8.1` implemented, optimized and passing test vectors.
|
- Specification `v0.8.3` implemented, optimized and passing test vectors.
|
||||||
- Rust-native libp2p with Gossipsub and Discv5.
|
- Rust-native libp2p with Gossipsub and Discv5.
|
||||||
|
- RESTful JSON API via HTTP server.
|
||||||
|
- Events via WebSocket.
|
||||||
- Metrics via Prometheus.
|
- Metrics via Prometheus.
|
||||||
- Basic gRPC API, soon to be replaced with RESTful HTTP/JSON.
|
|
||||||
|
|
||||||
### Roadmap
|
### Roadmap
|
||||||
|
|
||||||
- **Early-September 2019**: `lighthouse-0.0.1` release: A stable testnet for
|
- ~~**April 2019**: Inital single-client testnets.~~
|
||||||
developers with a useful HTTP API.
|
- ~~**September 2019**: Inter-operability with other Ethereum 2.0 clients.~~
|
||||||
- **September 2019**: Inter-operability with other Ethereum 2.0 clients.
|
- **Early-October 2019**: `lighthouse-0.0.1` release: All major phase 0
|
||||||
- **October 2019**: Public, multi-client testnet with user-facing functionality.
|
features implemented.
|
||||||
- **January 2020**: Production Beacon Chain testnet.
|
- **Q4 2019**: Public, multi-client testnet with user-facing functionality.
|
||||||
|
- **Q4 2019**: Third-party security review.
|
||||||
|
- **Q1 2020**: Production Beacon Chain testnet (tentative).
|
||||||
|
|
||||||
## Usage
|
|
||||||
|
|
||||||
Lighthouse consists of multiple binaries:
|
## Documentation
|
||||||
|
|
||||||
- [`beacon_node/`](beacon_node/): produces and verifies blocks from the P2P
|
The [Lighthouse Book](http://lighthouse-book.sigmaprime.io/) contains information
|
||||||
connected validators and the P2P network. Provides an API for external services to
|
for testnet users and developers.
|
||||||
interact with Ethereum 2.0.
|
|
||||||
- [`validator_client/`](validator_client/): connects to a `beacon_node` and
|
|
||||||
performs the role of a proof-of-stake validator.
|
|
||||||
- [`account_manager/`](account_manager/): a stand-alone component providing key
|
|
||||||
management and creation for validators.
|
|
||||||
|
|
||||||
### Simple Local Testnet
|
Code documentation is generated via `cargo doc` and hosted at
|
||||||
|
[lighthouse-docs.sigmaprime.io](http://lighthouse-docs.sigmaprime.io/).
|
||||||
**Note: these instructions are intended for developers and researchers. We do
|
|
||||||
not yet support end-users.**
|
|
||||||
|
|
||||||
In this example we use the `account_manager` to create some keys, launch two
|
|
||||||
`beacon_node` instances and connect a `validator_client` to one. The two
|
|
||||||
`beacon_nodes` should stay in sync and build a Beacon Chain.
|
|
||||||
|
|
||||||
First, clone this repository, [setup a development
|
|
||||||
environment](docs/env.md) and navigate to the root directory of this repository.
|
|
||||||
|
|
||||||
Then, run `$ cargo build --all --release` and navigate to the `target/release`
|
|
||||||
directory and follow the steps:
|
|
||||||
|
|
||||||
#### 1. Generate Validator Keys
|
|
||||||
|
|
||||||
Generate 16 validator keys and store them in `~/.lighthouse-validator`:
|
|
||||||
|
|
||||||
```
|
|
||||||
$ ./account_manager -d ~/.lighthouse-validator generate_deterministic -i 0 -n 16
|
|
||||||
```
|
|
||||||
|
|
||||||
_Note: these keys are for development only. The secret keys are
|
|
||||||
deterministically generated from low integers. Assume they are public
|
|
||||||
knowledge._
|
|
||||||
|
|
||||||
#### 2. Start a Beacon Node
|
|
||||||
|
|
||||||
This node will act as the boot node and provide an API for the
|
|
||||||
`validator_client`.
|
|
||||||
|
|
||||||
```
|
|
||||||
$ ./beacon_node --recent-genesis --rpc
|
|
||||||
```
|
|
||||||
|
|
||||||
_Note: `--recent-genesis` defines the genesis time as either the start of the
|
|
||||||
current hour, or half-way through the current hour (whichever is most recent).
|
|
||||||
This makes it very easy to create a testnet, but does not allow nodes to
|
|
||||||
connect if they were started in separate 30-minute windows._
|
|
||||||
|
|
||||||
#### 3. Start Another Beacon Node
|
|
||||||
|
|
||||||
In another terminal window, start another boot that will connect to the
|
|
||||||
running node.
|
|
||||||
|
|
||||||
The running node will display it's ENR as a base64 string. This ENR, by default, has a target address of `127.0.0.1` meaning that any new node will connect to this node via `127.0.0.1`. If a boot node should be connected to on a different address, it should be run with the `--discovery-address` CLI flag to specify how other nodes may connect to it.
|
|
||||||
```
|
|
||||||
$ ./beacon_node -r --boot-nodes <boot-node-ENR> --listen-address 127.0.0.1 --port 9001 --datadir /tmp/.lighthouse
|
|
||||||
```
|
|
||||||
Here <boot-node-ENR> is the ENR string displayed in the terminal from the first node. The ENR can also be obtained from it's default directory `.lighthouse/network/enr.dat`.
|
|
||||||
|
|
||||||
The `--datadir` flag tells this Beacon Node to store it's files in a different
|
|
||||||
directory. If you're on a system that doesn't have a `/tmp` dir (e.g., Mac,
|
|
||||||
Windows), substitute this with any directory that has write access.
|
|
||||||
|
|
||||||
Note that all future created nodes can use the same boot-node ENR. Once connected to the boot node, all nodes should discover and connect with each other.
|
|
||||||
#### 4. Start a Validator Client
|
|
||||||
|
|
||||||
In a third terminal window, start a validator client:
|
|
||||||
|
|
||||||
```
|
|
||||||
$ ./validator_client
|
|
||||||
```
|
|
||||||
|
|
||||||
You should be able to observe the validator signing blocks, the boot node
|
|
||||||
processing these blocks and publishing them to the other node. If you have
|
|
||||||
issues, try restarting the beacon nodes to ensure they have the same genesis
|
|
||||||
time. Alternatively, raise an issue and include your terminal output.
|
|
||||||
|
|
||||||
## Further Reading
|
|
||||||
|
|
||||||
- [About Lighthouse](docs/lighthouse.md): Goals, Ideology and Ethos surrounding
|
|
||||||
this implementation.
|
|
||||||
- [What is Ethereum Serenity](docs/serenity.md): an introduction to Ethereum Serenity.
|
|
||||||
- [Lighthouse Technical Documentation](http://lighthouse-docs.sigmaprime.io/): The Rust generated documentation, updated regularly.
|
|
||||||
|
|
||||||
If you'd like some background on Sigma Prime, please see the [Lighthouse Update
|
If you'd like some background on Sigma Prime, please see the [Lighthouse Update
|
||||||
\#00](https://lighthouse.sigmaprime.io/update-00.html) blog post or the
|
\#00](https://lighthouse.sigmaprime.io/update-00.html) blog post or
|
||||||
[company website](https://sigmaprime.io).
|
[sigmaprime.io](https://sigmaprime.io).
|
||||||
|
|
||||||
## Directory Structure
|
|
||||||
|
|
||||||
- [`beacon_node/`](beacon_node/): the "Beacon Node" binary and crates exclusively
|
|
||||||
associated with it.
|
|
||||||
- [`docs/`](docs/): documentation related to the repository. This includes contributor
|
|
||||||
guides, etc. (It does not include code documentation, which can be produced with `cargo doc`).
|
|
||||||
- [`eth2/`](eth2/): Crates containing common logic across the Lighthouse project. For
|
|
||||||
example: Ethereum 2.0 types ([`BeaconBlock`](eth2/types/src/beacon_block.rs), [`BeaconState`](eth2/types/src/beacon_state.rs), etc) and
|
|
||||||
SimpleSerialize (SSZ).
|
|
||||||
- [`protos/`](protos/): protobuf/gRPC definitions that are common across the Lighthouse project.
|
|
||||||
- [`validator_client/`](validator_client/): the "Validator Client" binary and crates exclusively
|
|
||||||
associated with it.
|
|
||||||
- [`tests/`](tests/): code specific to testing, most notably contains the
|
|
||||||
Ethereum Foundation test vectors.
|
|
||||||
|
|
||||||
## Contributing
|
## Contributing
|
||||||
|
|
||||||
**Lighthouse welcomes contributors.**
|
Lighthouse welcomes contributors.
|
||||||
|
|
||||||
If you are looking to contribute, please head to our
|
If you are looking to contribute, please head to the
|
||||||
[onboarding documentation](https://github.com/sigp/lighthouse/blob/master/docs/onboarding.md).
|
[Contributing](http://lighthouse-book.sigmaprime.io/contributing.html) section
|
||||||
|
of the Lighthouse book.
|
||||||
If you'd like to contribute, try having a look through the [open
|
|
||||||
issues](https://github.com/sigp/lighthouse/issues) (tip: look for the [good
|
|
||||||
first
|
|
||||||
issue](https://github.com/sigp/lighthouse/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
|
|
||||||
tag) and ping us on the [gitter](https://gitter.im/sigp/lighthouse) channel. We need
|
|
||||||
your support!
|
|
||||||
|
|
||||||
## Contact
|
## Contact
|
||||||
|
|
||||||
@ -175,8 +80,13 @@ The best place for discussion is the [Lighthouse Discord
|
|||||||
server](https://discord.gg/cyAszAh). Alternatively, you may use the
|
server](https://discord.gg/cyAszAh). Alternatively, you may use the
|
||||||
[sigp/lighthouse gitter](https://gitter.im/sigp/lighthouse).
|
[sigp/lighthouse gitter](https://gitter.im/sigp/lighthouse).
|
||||||
|
|
||||||
|
Encrypt sensitive messages using our [PGP
|
||||||
|
key](https://keybase.io/sigp/pgp_keys.asc?fingerprint=dcf37e025d6c9d42ea795b119e7c6cf9988604be).
|
||||||
|
|
||||||
## Donations
|
## Donations
|
||||||
|
|
||||||
If you support the cause, we accept donations to help fund development:
|
Lighthouse is an open-source project and a public good. Funding public goods is
|
||||||
|
hard and we're grateful for the donations we receive from the community via:
|
||||||
|
|
||||||
`0x25c4a76E7d118705e7Ea2e9b7d8C59930d8aCD3b` (donation.sigmaprime.eth)
|
- [Gitcoin Grants](https://gitcoin.co/grants/25/lighthouse-ethereum-20-client).
|
||||||
|
- Ethereum address: `0x25c4a76E7d118705e7Ea2e9b7d8C59930d8aCD3b` (donation.sigmaprime.eth).
|
||||||
|
|||||||
@ -10,7 +10,7 @@ use lmd_ghost::LmdGhost;
|
|||||||
use operation_pool::DepositInsertStatus;
|
use operation_pool::DepositInsertStatus;
|
||||||
use operation_pool::{OperationPool, PersistedOperationPool};
|
use operation_pool::{OperationPool, PersistedOperationPool};
|
||||||
use parking_lot::RwLock;
|
use parking_lot::RwLock;
|
||||||
use slog::{error, info, trace, warn, Logger};
|
use slog::{debug, error, info, trace, warn, Logger};
|
||||||
use slot_clock::SlotClock;
|
use slot_clock::SlotClock;
|
||||||
use ssz::Encode;
|
use ssz::Encode;
|
||||||
use state_processing::per_block_processing::{
|
use state_processing::per_block_processing::{
|
||||||
@ -646,8 +646,8 @@ impl<T: BeaconChainTypes> BeaconChain<T> {
|
|||||||
trace!(
|
trace!(
|
||||||
self.log,
|
self.log,
|
||||||
"Beacon attestation imported";
|
"Beacon attestation imported";
|
||||||
"shard" => attestation.data.crosslink.shard,
|
|
||||||
"target_epoch" => attestation.data.target.epoch,
|
"target_epoch" => attestation.data.target.epoch,
|
||||||
|
"shard" => attestation.data.crosslink.shard,
|
||||||
);
|
);
|
||||||
let _ = self
|
let _ = self
|
||||||
.event_handler
|
.event_handler
|
||||||
@ -1397,12 +1397,16 @@ impl<T: BeaconChainTypes> BeaconChain<T> {
|
|||||||
info!(
|
info!(
|
||||||
self.log,
|
self.log,
|
||||||
"New head beacon block";
|
"New head beacon block";
|
||||||
|
"root" => format!("{}", beacon_block_root),
|
||||||
|
"slot" => new_slot,
|
||||||
|
);
|
||||||
|
debug!(
|
||||||
|
self.log,
|
||||||
|
"Head beacon block";
|
||||||
"justified_root" => format!("{}", beacon_state.current_justified_checkpoint.root),
|
"justified_root" => format!("{}", beacon_state.current_justified_checkpoint.root),
|
||||||
"justified_epoch" => beacon_state.current_justified_checkpoint.epoch,
|
"justified_epoch" => beacon_state.current_justified_checkpoint.epoch,
|
||||||
"finalized_root" => format!("{}", beacon_state.finalized_checkpoint.root),
|
"finalized_root" => format!("{}", beacon_state.finalized_checkpoint.root),
|
||||||
"finalized_epoch" => beacon_state.finalized_checkpoint.epoch,
|
"finalized_epoch" => beacon_state.finalized_checkpoint.epoch,
|
||||||
"root" => format!("{}", beacon_block_root),
|
|
||||||
"slot" => new_slot,
|
|
||||||
);
|
);
|
||||||
};
|
};
|
||||||
|
|
||||||
|
|||||||
@ -13,7 +13,7 @@ use exit_future::Signal;
|
|||||||
use futures::{future::Future, Stream};
|
use futures::{future::Future, Stream};
|
||||||
use network::Service as NetworkService;
|
use network::Service as NetworkService;
|
||||||
use rest_api::NetworkInfo;
|
use rest_api::NetworkInfo;
|
||||||
use slog::{crit, error, info, o};
|
use slog::{crit, debug, error, info, o};
|
||||||
use slot_clock::SlotClock;
|
use slot_clock::SlotClock;
|
||||||
use std::marker::PhantomData;
|
use std::marker::PhantomData;
|
||||||
use std::sync::Arc;
|
use std::sync::Arc;
|
||||||
@ -309,11 +309,16 @@ fn log_new_slot<T: BeaconChainTypes>(chain: &Arc<BeaconChain<T>>, log: &slog::Lo
|
|||||||
info!(
|
info!(
|
||||||
log,
|
log,
|
||||||
"Slot start";
|
"Slot start";
|
||||||
|
"best_slot" => best_slot,
|
||||||
|
"slot" => current_slot,
|
||||||
|
);
|
||||||
|
debug!(
|
||||||
|
log,
|
||||||
|
"Slot info";
|
||||||
"skip_slots" => current_slot.saturating_sub(best_slot),
|
"skip_slots" => current_slot.saturating_sub(best_slot),
|
||||||
"best_block_root" => format!("{}", latest_block_root),
|
"best_block_root" => format!("{}", latest_block_root),
|
||||||
"best_block_slot" => best_slot,
|
|
||||||
"slot" => current_slot,
|
"slot" => current_slot,
|
||||||
)
|
);
|
||||||
} else {
|
} else {
|
||||||
error!(
|
error!(
|
||||||
log,
|
log,
|
||||||
|
|||||||
@ -103,8 +103,9 @@ impl<T: BeaconChainTypes> AttestationService for AttestationServiceInstance<T> {
|
|||||||
// Attestation was successfully processed.
|
// Attestation was successfully processed.
|
||||||
info!(
|
info!(
|
||||||
self.log,
|
self.log,
|
||||||
"PublishAttestation";
|
"Valid attestation from RPC";
|
||||||
"type" => "valid_attestation",
|
"target_epoch" => attestation.data.target.epoch,
|
||||||
|
"shard" => attestation.data.crosslink.shard,
|
||||||
);
|
);
|
||||||
|
|
||||||
// valid attestation, propagate to the network
|
// valid attestation, propagate to the network
|
||||||
@ -123,8 +124,7 @@ impl<T: BeaconChainTypes> AttestationService for AttestationServiceInstance<T> {
|
|||||||
.unwrap_or_else(|e| {
|
.unwrap_or_else(|e| {
|
||||||
error!(
|
error!(
|
||||||
self.log,
|
self.log,
|
||||||
"PublishAttestation";
|
"Failed to gossip attestation";
|
||||||
"type" => "failed to publish attestation to gossipsub",
|
|
||||||
"error" => format!("{:?}", e)
|
"error" => format!("{:?}", e)
|
||||||
);
|
);
|
||||||
});
|
});
|
||||||
@ -135,8 +135,7 @@ impl<T: BeaconChainTypes> AttestationService for AttestationServiceInstance<T> {
|
|||||||
// Attestation was invalid
|
// Attestation was invalid
|
||||||
warn!(
|
warn!(
|
||||||
self.log,
|
self.log,
|
||||||
"PublishAttestation";
|
"Invalid attestation from RPC";
|
||||||
"type" => "invalid_attestation",
|
|
||||||
"error" => format!("{:?}", e),
|
"error" => format!("{:?}", e),
|
||||||
);
|
);
|
||||||
resp.set_success(false);
|
resp.set_success(false);
|
||||||
@ -146,8 +145,7 @@ impl<T: BeaconChainTypes> AttestationService for AttestationServiceInstance<T> {
|
|||||||
// Some other error
|
// Some other error
|
||||||
warn!(
|
warn!(
|
||||||
self.log,
|
self.log,
|
||||||
"PublishAttestation";
|
"Failed to process attestation from RPC";
|
||||||
"type" => "beacon_chain_error",
|
|
||||||
"error" => format!("{:?}", e),
|
"error" => format!("{:?}", e),
|
||||||
);
|
);
|
||||||
resp.set_success(false);
|
resp.set_success(false);
|
||||||
|
|||||||
@ -105,8 +105,8 @@ impl<T: BeaconChainTypes> BeaconBlockService for BeaconBlockServiceInstance<T> {
|
|||||||
info!(
|
info!(
|
||||||
self.log,
|
self.log,
|
||||||
"Valid block from RPC";
|
"Valid block from RPC";
|
||||||
"block_slot" => block.slot,
|
"root" => format!("{}", block_root),
|
||||||
"block_root" => format!("{}", block_root),
|
"slot" => block.slot,
|
||||||
);
|
);
|
||||||
|
|
||||||
// create the network topic to send on
|
// create the network topic to send on
|
||||||
@ -126,8 +126,7 @@ impl<T: BeaconChainTypes> BeaconBlockService for BeaconBlockServiceInstance<T> {
|
|||||||
.unwrap_or_else(|e| {
|
.unwrap_or_else(|e| {
|
||||||
error!(
|
error!(
|
||||||
self.log,
|
self.log,
|
||||||
"PublishBeaconBlock";
|
"Failed to gossip beacon block";
|
||||||
"type" => "failed to publish to gossipsub",
|
|
||||||
"error" => format!("{:?}", e)
|
"error" => format!("{:?}", e)
|
||||||
);
|
);
|
||||||
});
|
});
|
||||||
@ -151,8 +150,7 @@ impl<T: BeaconChainTypes> BeaconBlockService for BeaconBlockServiceInstance<T> {
|
|||||||
// Some failure during processing.
|
// Some failure during processing.
|
||||||
error!(
|
error!(
|
||||||
self.log,
|
self.log,
|
||||||
"PublishBeaconBlock";
|
"Failed to process beacon block";
|
||||||
"type" => "failed_to_process",
|
|
||||||
"error" => format!("{:?}", e)
|
"error" => format!("{:?}", e)
|
||||||
);
|
);
|
||||||
|
|
||||||
|
|||||||
17
book/README.md
Normal file
17
book/README.md
Normal file
@ -0,0 +1,17 @@
|
|||||||
|
# Lighthouse Book
|
||||||
|
|
||||||
|
Contains an [mdBook](https://github.com/rust-lang-nursery/mdBook) that serves
|
||||||
|
as the primary source of Lighthouse user documentation.
|
||||||
|
|
||||||
|
The book is hosted at [lighthouse-book.sigmaprime.io](http://lighthouse-book.sigmaprime.io).
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
The [mdBook docs](https://github.com/rust-lang-nursery/mdBook#usage) are the
|
||||||
|
best source of information for building the book.
|
||||||
|
|
||||||
|
### Example
|
||||||
|
|
||||||
|
1. Install mdBook: `$ cargo install mdbook`
|
||||||
|
1. Build the book, open it in a browser and build after file changes: `$ mdbook
|
||||||
|
watch --open`
|
||||||
@ -3,4 +3,4 @@ authors = ["Paul Hauner"]
|
|||||||
language = "en"
|
language = "en"
|
||||||
multilingual = false
|
multilingual = false
|
||||||
src = "src"
|
src = "src"
|
||||||
title = "Lighthouse"
|
title = "Lighthouse Book"
|
||||||
|
|||||||
@ -1,11 +1,12 @@
|
|||||||
# Summary
|
# Summary
|
||||||
|
|
||||||
* [Introduction](./intro.md)
|
* [Introduction](./intro.md)
|
||||||
* [Development Environment](./setup.md)
|
* [CLI](./cli.md)
|
||||||
* [Websocket Interface](./websockets.md)
|
* [Testnets](./testnets.md)
|
||||||
* [Simple Local Testnet](./simple-testnet.md)
|
* [Simple Local Testnet](./simple-testnet.md)
|
||||||
* [Interop](./interop.md)
|
* [API](./api.md)
|
||||||
* [Environment](./interop-environment.md)
|
* [HTTP (RESTful JSON)](./http.md)
|
||||||
* [CLI Overview](./interop-cli.md)
|
* [WebSocket](./websockets.md)
|
||||||
* [Scenarios](./interop-scenarios.md)
|
* [Contributing](./contributing.md)
|
||||||
* [Cheat-sheet](./interop-cheat-sheet.md)
|
* [Development Environment](./setup.md)
|
||||||
|
* [CI & Testing](./ci.md)
|
||||||
|
|||||||
13
book/src/api.md
Normal file
13
book/src/api.md
Normal file
@ -0,0 +1,13 @@
|
|||||||
|
# APIs
|
||||||
|
|
||||||
|
The Lighthouse `beacon_node` provides two APIs for local consumption:
|
||||||
|
|
||||||
|
- A [RESTful JSON HTTP API](http.html) which provides beacon chain, node and network
|
||||||
|
information.
|
||||||
|
- A read-only [WebSocket API](websockets.html) providing beacon chain events, as they occur.
|
||||||
|
|
||||||
|
|
||||||
|
## Security
|
||||||
|
|
||||||
|
These endpoints are not designed to be exposed to the public Internet or
|
||||||
|
untrusted users. They may pose a considerable DoS attack vector when used improperly.
|
||||||
33
book/src/ci.md
Normal file
33
book/src/ci.md
Normal file
@ -0,0 +1,33 @@
|
|||||||
|
# Contiguous Integration (CI) and Testing
|
||||||
|
|
||||||
|
Lighthouse uses a self-hosted Gitlab CI server to run tests and deploy docs.
|
||||||
|
|
||||||
|
For security reasons, **CI will only be run automatically for Lighthouse
|
||||||
|
maintainers.** Contributors without maintainer privileges will need to have CI
|
||||||
|
triggered for them prior to a PR being merged.
|
||||||
|
|
||||||
|
You can see the full set of tests we run in the
|
||||||
|
[gitlab-ci.yml](https://github.com/sigp/lighthouse/blob/master/.gitlab-ci.yml)
|
||||||
|
file. The following two commands should complete successfully before CI can
|
||||||
|
pass:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ cargo test --all --all-features
|
||||||
|
$ cargo fmt --all --check
|
||||||
|
```
|
||||||
|
|
||||||
|
_Note: Travis CI is also used, however it does not run the full test suite._
|
||||||
|
|
||||||
|
### Ethereum 2.0 Spec Tests
|
||||||
|
|
||||||
|
The
|
||||||
|
[ethereum/eth2.0-spec-tests](https://github.com/ethereum/eth2.0-spec-tests/)
|
||||||
|
repository contains a large set of tests that verify Lighthouse behaviour
|
||||||
|
against the Ethereum Foundation specifications.
|
||||||
|
|
||||||
|
These tests are quite large (100's of MB), so we don't download them by
|
||||||
|
default. Developers should ensure they have downloaded these tests using the
|
||||||
|
`Makefile` in
|
||||||
|
[tests/ef_tests](https://github.com/sigp/lighthouse/tree/master/tests/ef_tests).
|
||||||
|
|
||||||
|
**Failures in these tests should prevent CI from passing.**
|
||||||
62
book/src/cli.md
Normal file
62
book/src/cli.md
Normal file
@ -0,0 +1,62 @@
|
|||||||
|
# Command-Line Interface (CLI)
|
||||||
|
|
||||||
|
Lighthouse a collection of CLI applications. The two primary binaries are:
|
||||||
|
|
||||||
|
- `beacon_node`: the largest and most fundamental component which connects to
|
||||||
|
the p2p network, processes messages and tracks the head of the beacon
|
||||||
|
chain.
|
||||||
|
- `validator_client`: a lightweight but important component which loads a validators private
|
||||||
|
key and signs messages using a `beacon_node` as a source-of-truth.
|
||||||
|
|
||||||
|
There are also some ancillary binaries:
|
||||||
|
|
||||||
|
- `account_manager`: generates cryptographic keys.
|
||||||
|
- `lcli`: a general-purpose utility for troubleshooting Lighthouse state
|
||||||
|
transitions (developer tool).
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
Presently, we recommend building Lighthouse using the `$ cargo build --release
|
||||||
|
--all` command and executing binaries from the
|
||||||
|
`<lighthouse-repository>/target/release` directory.
|
||||||
|
|
||||||
|
## Documentation
|
||||||
|
|
||||||
|
Each binary supports the `--help` flag, this is the best source of
|
||||||
|
documentation.
|
||||||
|
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ ./beacon_node --help
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ ./validator_client --help
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ ./account_manager --help
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ ./lcli --help
|
||||||
|
```
|
||||||
|
|
||||||
|
## Beacon Node
|
||||||
|
|
||||||
|
The `beacon_node` CLI has two primary tasks:
|
||||||
|
|
||||||
|
- **Resuming** an existing database with `$ ./beacon_node`.
|
||||||
|
- **Creating** a new testnet database using `$ ./beacon_node testnet`.
|
||||||
|
|
||||||
|
## Creating a new database
|
||||||
|
|
||||||
|
Use the `$./beacon_node testnet` command (see [testnets](./testnets.md) for more
|
||||||
|
information).
|
||||||
|
|
||||||
|
## Resuming from an existing database
|
||||||
|
|
||||||
|
Once a database has been created, it can be resumed by running `$ ./beacon_node`.
|
||||||
|
|
||||||
|
Presently, this command will fail if no existing database is found. You must
|
||||||
|
use the `$ ./beacon_node testnet` command to create a new database.
|
||||||
118
book/src/contributing.md
Normal file
118
book/src/contributing.md
Normal file
@ -0,0 +1,118 @@
|
|||||||
|
# Contributing to Lighthouse
|
||||||
|
|
||||||
|
[![Chat Badge]][Chat Link]
|
||||||
|
|
||||||
|
[Chat Badge]: https://img.shields.io/badge/chat-discord-%237289da
|
||||||
|
[Chat Link]: https://discord.gg/cyAszAh
|
||||||
|
|
||||||
|
|
||||||
|
Lighthouse welcomes contributions. If you are interested in contributing to the
|
||||||
|
Ethereum ecosystem, and you want to learn Rust, Lighthouse is a great project
|
||||||
|
to work on.
|
||||||
|
|
||||||
|
To start contributing,
|
||||||
|
|
||||||
|
1. Setup a [development environment](./setup.md).
|
||||||
|
2. Browse through the [open issues](https://github.com/sigp/lighthouse/issues)
|
||||||
|
(tip: look for the [good first
|
||||||
|
issue](https://github.com/sigp/lighthouse/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
|
||||||
|
tag).
|
||||||
|
3. Comment on an issue before starting work.
|
||||||
|
4. Share your work via a pull-request.
|
||||||
|
|
||||||
|
If you have questions, please reach out via
|
||||||
|
[Discord](https://discord.gg/cyAszAh).
|
||||||
|
|
||||||
|
## Ethereum 2.0
|
||||||
|
|
||||||
|
Lighthouse is an implementation of the Ethereum 2.0 specification, as defined
|
||||||
|
in the [ethereum/eth2.0-specs](https://github.com/ethereum/eth2.0-specs)
|
||||||
|
repository.
|
||||||
|
|
||||||
|
We recommend reading Danny Ryan's (incomplete) [Phase 0 for
|
||||||
|
Humans](https://notes.ethereum.org/@djrtwo/Bkn3zpwxB?type=view) before diving
|
||||||
|
into the canonical spec.
|
||||||
|
|
||||||
|
## Rust
|
||||||
|
|
||||||
|
Lighthouse adheres to Rust code conventions as outlined in the [**Rust
|
||||||
|
Styleguide**](https://github.com/rust-dev-tools/fmt-rfcs/blob/master/guide/guide.md).
|
||||||
|
|
||||||
|
Please use [clippy](https://github.com/rust-lang/rust-clippy) and
|
||||||
|
[rustfmt](https://github.com/rust-lang/rustfmt) to detect common mistakes and
|
||||||
|
inconsistent code formatting:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ cargo clippy --all
|
||||||
|
$ cargo fmt --all --check
|
||||||
|
```
|
||||||
|
|
||||||
|
### Panics
|
||||||
|
|
||||||
|
Generally, **panics should be avoided at all costs**. Lighthouse operates in an
|
||||||
|
adversarial environment (the Internet) and it's a severe vulnerability if
|
||||||
|
people on the Internet can cause Lighthouse to crash via a panic.
|
||||||
|
|
||||||
|
Always prefer returning a `Result` or `Option` over causing a panic. For
|
||||||
|
example, prefer `array.get(1)?` over `array[1]`.
|
||||||
|
|
||||||
|
If you know there won't be a panic but can't express that to the compiler,
|
||||||
|
use `.expect("Helpful message")` instead of `.unwrap()`. Always provide
|
||||||
|
detailed reasoning in a nearby comment when making assumptions about panics.
|
||||||
|
|
||||||
|
### TODOs
|
||||||
|
|
||||||
|
All `TODO` statements should be accompanied by a GitHub issue.
|
||||||
|
|
||||||
|
```rust
|
||||||
|
pub fn my_function(&mut self, _something &[u8]) -> Result<String, Error> {
|
||||||
|
// TODO: something_here
|
||||||
|
// https://github.com/sigp/lighthouse/issues/XX
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Comments
|
||||||
|
|
||||||
|
**General Comments**
|
||||||
|
|
||||||
|
* Prefer line (``//``) comments to block comments (``/* ... */``)
|
||||||
|
* Comments can appear on the line prior to the item or after a trailing space.
|
||||||
|
```rust
|
||||||
|
// Comment for this struct
|
||||||
|
struct Lighthouse {}
|
||||||
|
fn make_blockchain() {} // A comment on the same line after a space
|
||||||
|
```
|
||||||
|
|
||||||
|
**Doc Comments**
|
||||||
|
|
||||||
|
* The ``///`` is used to generate comments for Docs.
|
||||||
|
* The comments should come before attributes.
|
||||||
|
|
||||||
|
```rust
|
||||||
|
/// Stores the core configuration for this Lighthouse instance.
|
||||||
|
/// This struct is general, other components may implement more
|
||||||
|
/// specialized config structs.
|
||||||
|
#[derive(Clone)]
|
||||||
|
pub struct LighthouseConfig {
|
||||||
|
pub data_dir: PathBuf,
|
||||||
|
pub p2p_listen_port: u16,
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Rust Resources
|
||||||
|
|
||||||
|
Rust is an extremely powerful, low-level programming language that provides
|
||||||
|
freedom and performance to create powerful projects. The [Rust
|
||||||
|
Book](https://doc.rust-lang.org/stable/book/) provides insight into the Rust
|
||||||
|
language and some of the coding style to follow (As well as acting as a great
|
||||||
|
introduction and tutorial for the language).
|
||||||
|
|
||||||
|
Rust has a steep learning curve, but there are many resources to help. We
|
||||||
|
suggest:
|
||||||
|
|
||||||
|
* [Rust Book](https://doc.rust-lang.org/stable/book/)
|
||||||
|
* [Rust by example](https://doc.rust-lang.org/stable/rust-by-example/)
|
||||||
|
* [Learning Rust With Entirely Too Many Linked Lists](http://cglab.ca/~abeinges/blah/too-many-lists/book/)
|
||||||
|
* [Rustlings](https://github.com/rustlings/rustlings)
|
||||||
|
* [Rust Exercism](https://exercism.io/tracks/rust)
|
||||||
|
* [Learn X in Y minutes - Rust](https://learnxinyminutes.com/docs/rust/)
|
||||||
85
book/src/http.md
Normal file
85
book/src/http.md
Normal file
@ -0,0 +1,85 @@
|
|||||||
|
# HTTP API
|
||||||
|
|
||||||
|
[![Swagger Badge]][Swagger Link]
|
||||||
|
|
||||||
|
[Swagger Badge]: https://img.shields.io/badge/Open%20API-0.2.0-success
|
||||||
|
[Swagger Link]: https://app.swaggerhub.com/apis-docs/spble/lighthouse_rest_api/0.2.0
|
||||||
|
|
||||||
|
|
||||||
|
**The Lighthouse API is documented in Open API format and is available at
|
||||||
|
[SwaggerHub: Lighthouse REST
|
||||||
|
API](https://app.swaggerhub.com/apis-docs/spble/lighthouse_rest_api/0.2.0).**
|
||||||
|
|
||||||
|
By default, a Lighthouse `beacon_node` exposes a HTTP server on `localhost:5052`.
|
||||||
|
|
||||||
|
The following CLI flags control the HTTP server:
|
||||||
|
|
||||||
|
- `--no-api`: disable the HTTP server.
|
||||||
|
- `--api-port`: specify the listen port of the server.
|
||||||
|
- `--api-address`: specify the listen address of the server.
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
|
||||||
|
In addition to the complete Open API docs (see above), some examples are
|
||||||
|
provided below.
|
||||||
|
|
||||||
|
_Examples assume there is a Lighthouse node exposing a HTTP API on
|
||||||
|
`localhost:5052`. Responses are JSON._
|
||||||
|
|
||||||
|
### Get the node's beacon chain head
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ curl localhost:5052/beacon/head
|
||||||
|
|
||||||
|
{"slot":0,"block_root":"0x827bf71805540aa13f6d8c7d18b41b287b2094a4d7a28cbb8deb061dbf5df4f5","state_root":"0x90a78d73294bc9c7519a64e1912161be0e823eb472012ff54204e15a4d717fa5"}%
|
||||||
|
```
|
||||||
|
|
||||||
|
### Get the node's finalized checkpoint
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ curl localhost:5052/beacon/latest_finalized_checkpoint
|
||||||
|
|
||||||
|
{"epoch":0,"root":"0x0000000000000000000000000000000000000000000000000000000000000000"}%
|
||||||
|
```
|
||||||
|
|
||||||
|
### Get the node's ENR
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ curl localhost:5052/network/enr
|
||||||
|
|
||||||
|
"-IW4QFyf1VlY5pZs0xZuvKMRZ9_cdl9WMCDAAJXZiZiuGcfRYoU40VPrYDLQj5prneJIz3zcbTjHp9BbThc-yiymJO8HgmlwhH8AAAGDdGNwgiMog3VkcIIjKIlzZWNwMjU2azGhAjg0-DsTkQynhJCRnLLttBK1RS78lmUkLa-wgzAi-Ob5"%
|
||||||
|
```
|
||||||
|
|
||||||
|
### Get a list of connected peer ids
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ curl localhost:5052/network/peers
|
||||||
|
|
||||||
|
["QmeMFRTWfo3KbVG7dEBXGhyRMa29yfmnJBXW84rKuGEhuL"]%
|
||||||
|
```
|
||||||
|
|
||||||
|
### Get the node's peer id
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ curl localhost:5052/network/peer_id
|
||||||
|
|
||||||
|
"QmRD1qs2AqNNRdBcGHUGpUGkpih5cmdL32mhh22Sy79xsJ"%
|
||||||
|
```
|
||||||
|
|
||||||
|
### Get the list of listening libp2p addresses
|
||||||
|
|
||||||
|
Lists all the libp2p multiaddrs that the node is listening on.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ curl localhost:5052/network/listen_addresses
|
||||||
|
|
||||||
|
["/ip4/127.0.0.1/tcp/9000","/ip4/192.168.1.121/tcp/9000","/ip4/172.17.0.1/tcp/9000","/ip4/172.42.0.1/tcp/9000","/ip6/::1/tcp/9000","/ip6/fdd3:c293:1bc::203/tcp/9000","/ip6/fdd3:c293:1bc:0:9aa9:b2ea:c610:44db/tcp/9000"]%
|
||||||
|
```
|
||||||
|
|
||||||
|
### Pretty-print the genesis state and state root
|
||||||
|
|
||||||
|
Returns the genesis state and state root in your terminal, in YAML.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ curl --header "Content-Type: application/yaml" "localhost:5052/beacon/state?slot=0"
|
||||||
|
```
|
||||||
@ -1,149 +0,0 @@
|
|||||||
# Interop Cheat-sheet
|
|
||||||
|
|
||||||
This document contains a list of tips and tricks that may be useful during
|
|
||||||
interop testing.
|
|
||||||
|
|
||||||
- When starting a beacon node:
|
|
||||||
- [Specify a boot node by multiaddr](#boot-node-multiaddr)
|
|
||||||
- [Specify a boot node by ENR](#boot-node-enr)
|
|
||||||
- [Avoid port clashes when starting multiple nodes](#port-bump)
|
|
||||||
- [Specify a custom slot time](#slot-time)
|
|
||||||
- Using the beacon node HTTP API:
|
|
||||||
- [Pretty-print the genesis state and state root](#http-state)
|
|
||||||
- [Curl a node's ENR](#http-enr)
|
|
||||||
- [Curl a node's connected peers](#http-peer-ids)
|
|
||||||
- [Curl a node's local peer id](#http-peer-id)
|
|
||||||
- [Curl a node's listening multiaddrs](#http-listen-addresses)
|
|
||||||
- [Curl a node's beacon chain head](#http-head)
|
|
||||||
- [Curl a node's finalized checkpoint](#http-finalized)
|
|
||||||
|
|
||||||
## Category: CLI
|
|
||||||
|
|
||||||
The `--help` command provides detail on the CLI interface. Here are some
|
|
||||||
interop-specific CLI commands.
|
|
||||||
|
|
||||||
<a name="boot-node-multiaddr"></a>
|
|
||||||
### Specify a boot node by multiaddr
|
|
||||||
|
|
||||||
You can specify a static list of multiaddrs when booting Lighthouse using
|
|
||||||
the `--libp2p-addresses` command.
|
|
||||||
|
|
||||||
#### Example:
|
|
||||||
|
|
||||||
```
|
|
||||||
$ ./beacon_node --libp2p-addresses /ip4/192.168.0.1/tcp/9000
|
|
||||||
```
|
|
||||||
|
|
||||||
<a name="boot-node-enr"></a>
|
|
||||||
### Specify a boot node by ENR
|
|
||||||
|
|
||||||
You can specify a static list of Discv5 addresses when booting Lighthouse using
|
|
||||||
the `--boot-nodes` command.
|
|
||||||
|
|
||||||
#### Example:
|
|
||||||
|
|
||||||
```
|
|
||||||
$ ./beacon_node --boot-nodes -IW4QB2Hi8TPuEzQ41Cdf1r2AUU1FFVFDBJdJyOkWk2qXpZfFZQy2YnJIyoT_5fnbtrXUouoskmydZl4pIg90clIkYUDgmlwhH8AAAGDdGNwgiMog3VkcIIjKIlzZWNwMjU2azGhAjg0-DsTkQynhJCRnLLttBK1RS78lmUkLa-wgzAi-Ob5
|
|
||||||
```
|
|
||||||
|
|
||||||
<a name="port-bump"></a>
|
|
||||||
### Avoid port clashes when starting nodes
|
|
||||||
|
|
||||||
Starting a second Lighthouse node on the same machine will fail due to TCP/UDP
|
|
||||||
port collisions. Use the `-b` (`--port-bump`) flag to increase all listening
|
|
||||||
ports by some `n`.
|
|
||||||
|
|
||||||
#### Example:
|
|
||||||
|
|
||||||
Increase all ports by `10` (using multiples of `10` is recommended).
|
|
||||||
|
|
||||||
```
|
|
||||||
$ ./beacon_node -b 10
|
|
||||||
```
|
|
||||||
|
|
||||||
<a name="slot-time"></a>
|
|
||||||
### Start a testnet with a custom slot time
|
|
||||||
|
|
||||||
Lighthouse can run at quite low slot times when there are few validators (e.g.,
|
|
||||||
`500 ms` slot times should be fine for 8 validators).
|
|
||||||
|
|
||||||
#### Example
|
|
||||||
|
|
||||||
The `-t` (`--slot-time`) flag specifies the milliseconds per slot.
|
|
||||||
|
|
||||||
```
|
|
||||||
$ ./beacon_node testnet -t 500 recent 8
|
|
||||||
```
|
|
||||||
|
|
||||||
> Note: `bootstrap` loads the slot time via HTTP and therefore conflicts with
|
|
||||||
> this flag.
|
|
||||||
|
|
||||||
## Category: HTTP API
|
|
||||||
|
|
||||||
Examples assume there is a Lighthouse node exposing a HTTP API on
|
|
||||||
`localhost:5052`. Responses are JSON.
|
|
||||||
|
|
||||||
<a name="http-state"></a>
|
|
||||||
### Pretty-print the genesis state and state root
|
|
||||||
|
|
||||||
Returns the genesis state and state root in your terminal, in YAML.
|
|
||||||
|
|
||||||
```
|
|
||||||
$ curl --header "Content-Type: application/yaml" "localhost:5052/beacon/state?slot=0"
|
|
||||||
```
|
|
||||||
|
|
||||||
<a name="http-enr"></a>
|
|
||||||
### Get the node's ENR
|
|
||||||
|
|
||||||
```
|
|
||||||
$ curl localhost:5052/network/enr
|
|
||||||
|
|
||||||
"-IW4QFyf1VlY5pZs0xZuvKMRZ9_cdl9WMCDAAJXZiZiuGcfRYoU40VPrYDLQj5prneJIz3zcbTjHp9BbThc-yiymJO8HgmlwhH8AAAGDdGNwgiMog3VkcIIjKIlzZWNwMjU2azGhAjg0-DsTkQynhJCRnLLttBK1RS78lmUkLa-wgzAi-Ob5"%
|
|
||||||
```
|
|
||||||
|
|
||||||
<a name="http-peer-ids"></a>
|
|
||||||
### Get a list of connected peer ids
|
|
||||||
|
|
||||||
```
|
|
||||||
$ curl localhost:5052/network/peers
|
|
||||||
|
|
||||||
["QmeMFRTWfo3KbVG7dEBXGhyRMa29yfmnJBXW84rKuGEhuL"]%
|
|
||||||
```
|
|
||||||
|
|
||||||
<a name="http-peer-id"></a>
|
|
||||||
### Get the node's peer id
|
|
||||||
|
|
||||||
```
|
|
||||||
curl localhost:5052/network/peer_id
|
|
||||||
|
|
||||||
"QmRD1qs2AqNNRdBcGHUGpUGkpih5cmdL32mhh22Sy79xsJ"%
|
|
||||||
```
|
|
||||||
|
|
||||||
<a name="http-listen-addresses"></a>
|
|
||||||
### Get the list of listening libp2p addresses
|
|
||||||
|
|
||||||
Lists all the libp2p multiaddrs that the node is listening on.
|
|
||||||
|
|
||||||
```
|
|
||||||
curl localhost:5052/network/listen_addresses
|
|
||||||
|
|
||||||
["/ip4/127.0.0.1/tcp/9000","/ip4/192.168.1.121/tcp/9000","/ip4/172.17.0.1/tcp/9000","/ip4/172.42.0.1/tcp/9000","/ip6/::1/tcp/9000","/ip6/fdd3:c293:1bc::203/tcp/9000","/ip6/fdd3:c293:1bc:0:9aa9:b2ea:c610:44db/tcp/9000"]%
|
|
||||||
```
|
|
||||||
|
|
||||||
<a name="http-head"></a>
|
|
||||||
### Get the node's beacon chain head
|
|
||||||
|
|
||||||
```
|
|
||||||
curl localhost:5052/beacon/head
|
|
||||||
|
|
||||||
{"slot":0,"block_root":"0x827bf71805540aa13f6d8c7d18b41b287b2094a4d7a28cbb8deb061dbf5df4f5","state_root":"0x90a78d73294bc9c7519a64e1912161be0e823eb472012ff54204e15a4d717fa5"}%
|
|
||||||
```
|
|
||||||
|
|
||||||
<a name="http-finalized"></a>
|
|
||||||
### Get the node's finalized checkpoint
|
|
||||||
|
|
||||||
```
|
|
||||||
curl localhost:5052/beacon/latest_finalized_checkpoint
|
|
||||||
|
|
||||||
{"epoch":0,"root":"0x0000000000000000000000000000000000000000000000000000000000000000"}%
|
|
||||||
```
|
|
||||||
@ -1,29 +0,0 @@
|
|||||||
# Interop CLI Overview
|
|
||||||
|
|
||||||
The Lighthouse CLI has two primary tasks:
|
|
||||||
|
|
||||||
- **Resuming** an existing database with `$ ./beacon_node`.
|
|
||||||
- **Creating** a new testnet database using `$ ./beacon_node testnet`.
|
|
||||||
|
|
||||||
_See [Scenarios](./interop-scenarios.md) for methods we've anticipated will be
|
|
||||||
used interop._
|
|
||||||
|
|
||||||
## Creating a new database
|
|
||||||
|
|
||||||
There are several methods for creating a new beacon node database:
|
|
||||||
|
|
||||||
- `quick`: using the `(validator_client, genesis_time)` tuple.
|
|
||||||
- `recent`: as above but `genesis_time` is set to the start of some recent time
|
|
||||||
window.
|
|
||||||
- `file`: loads the genesis file from disk in one of multiple formats.
|
|
||||||
- `bootstrap`: a Lighthouse-specific method where we connect to a running node
|
|
||||||
and download it's specification and genesis state via the HTTP API.
|
|
||||||
|
|
||||||
See `$ ./beacon_node testnet --help` for more detail.
|
|
||||||
|
|
||||||
## Resuming from an existing database
|
|
||||||
|
|
||||||
Once a database has been created, it can be resumed by running `$ ./beacon_node`.
|
|
||||||
|
|
||||||
Presently, this command will fail if no existing database is found. You must
|
|
||||||
use the `$ ./beacon_node testnet` command to create a new database.
|
|
||||||
@ -1,30 +0,0 @@
|
|||||||
# Interop Environment
|
|
||||||
|
|
||||||
All that is required for inter-op is a built and tested [development
|
|
||||||
environment](./setup.md).
|
|
||||||
|
|
||||||
## Repositories
|
|
||||||
|
|
||||||
You will only require the [sigp/lighthouse](http://github.com/sigp/lighthouse)
|
|
||||||
library.
|
|
||||||
|
|
||||||
To allow for faster build/test iterations we will use the
|
|
||||||
[`interop`](https://github.com/sigp/lighthouse/tree/interop) branch of
|
|
||||||
[sigp/lighthouse](https://github.com/sigp/lighthouse/tree/interop) for
|
|
||||||
September 2019 interop. **Please use ensure you `git checkout interop` after
|
|
||||||
cloning the repo.**
|
|
||||||
|
|
||||||
## File System
|
|
||||||
|
|
||||||
When lighthouse boots, it will create the following
|
|
||||||
directories:
|
|
||||||
|
|
||||||
- `~/.lighthouse`: database and configuration for the beacon node.
|
|
||||||
- `~/.lighthouse-validator`: database and configuration for the validator
|
|
||||||
client.
|
|
||||||
|
|
||||||
After building the binaries with `cargo build --release --all`, there will be a
|
|
||||||
`target/release` directory in the root of the Lighthouse repository. This is
|
|
||||||
where the `beacon_node` and `validator_client` binaries are located.
|
|
||||||
|
|
||||||
You do not need to create any of these directories manually.
|
|
||||||
@ -1,101 +0,0 @@
|
|||||||
# Interop Scenarios
|
|
||||||
|
|
||||||
Here we demonstrate some expected interop scenarios.
|
|
||||||
|
|
||||||
All scenarios assume a working [development environment](./setup.md) and
|
|
||||||
commands are based in the `target/release` directory (this is the build dir for
|
|
||||||
`cargo`).
|
|
||||||
|
|
||||||
Additional functions can be found in the [interop
|
|
||||||
cheat-sheet](./interop-cheat-sheet.md).
|
|
||||||
|
|
||||||
### Table of contents
|
|
||||||
|
|
||||||
- [Starting from a`validator_count, genesis_time` tuple](#quick-start)
|
|
||||||
- [Starting a node from a genesis state file](#state-file)
|
|
||||||
- [Starting a validator client](#val-client)
|
|
||||||
- [Exporting a genesis state file](#export) from a running Lighthouse
|
|
||||||
node
|
|
||||||
|
|
||||||
|
|
||||||
<a name="quick-start"></a>
|
|
||||||
### Start beacon node given a validator count and genesis_time
|
|
||||||
|
|
||||||
|
|
||||||
To start a brand-new beacon node (with no history) use:
|
|
||||||
|
|
||||||
```
|
|
||||||
$ ./beacon_node testnet -f quick 8 <GENESIS_TIME>
|
|
||||||
```
|
|
||||||
|
|
||||||
Where `GENESIS_TIME` is in [unix time](https://duckduckgo.com/?q=unix+time&t=ffab&ia=answer).
|
|
||||||
|
|
||||||
> Notes:
|
|
||||||
>
|
|
||||||
> - This method conforms the ["Quick-start
|
|
||||||
genesis"](https://github.com/ethereum/eth2.0-pm/tree/6e41fcf383ebeb5125938850d8e9b4e9888389b4/interop/mocked_start#quick-start-genesis)
|
|
||||||
method in the `ethereum/eth2.0-pm` repository.
|
|
||||||
> - The `-f` flag ignores any existing database or configuration, backing them
|
|
||||||
> up before re-initializing.
|
|
||||||
> - `8` is the validator count and `1567222226` is the genesis time.
|
|
||||||
> - See `$ ./beacon_node testnet quick --help` for more configuration options.
|
|
||||||
|
|
||||||
<a name="state-file"></a>
|
|
||||||
### Start Beacon Node given a genesis state file
|
|
||||||
|
|
||||||
A genesis state can be read from file using the `testnet file` subcommand.
|
|
||||||
There are three supported formats:
|
|
||||||
|
|
||||||
- `ssz` (default)
|
|
||||||
- `json`
|
|
||||||
- `yaml`
|
|
||||||
|
|
||||||
Start a new node using `/tmp/genesis.ssz` as the genesis state:
|
|
||||||
|
|
||||||
```
|
|
||||||
$ ./beacon_node testnet --spec minimal -f file ssz /tmp/genesis.ssz
|
|
||||||
```
|
|
||||||
|
|
||||||
> Notes:
|
|
||||||
>
|
|
||||||
> - The `-f` flag ignores any existing database or configuration, backing them
|
|
||||||
> up before re-initializing.
|
|
||||||
> - See `$ ./beacon_node testnet file --help` for more configuration options.
|
|
||||||
> - The `--spec` flag is required to allow SSZ parsing of fixed-length lists.
|
|
||||||
|
|
||||||
<a name="val-client"></a>
|
|
||||||
### Start an auto-configured validator client
|
|
||||||
|
|
||||||
To start a brand-new validator client (with no history) use:
|
|
||||||
|
|
||||||
```
|
|
||||||
$ ./validator_client testnet -b insecure 0 8
|
|
||||||
```
|
|
||||||
|
|
||||||
> Notes:
|
|
||||||
>
|
|
||||||
> - The `-b` flag means the validator client will "bootstrap" specs and config
|
|
||||||
> from the beacon node.
|
|
||||||
> - The `insecure` command dictates that the [interop keypairs](https://github.com/ethereum/eth2.0-pm/tree/6e41fcf383ebeb5125938850d8e9b4e9888389b4/interop/mocked_start#pubkeyprivkey-generation)
|
|
||||||
> will be used.
|
|
||||||
> - The `0 8` indicates that this validator client should manage 8 validators,
|
|
||||||
> starting at validator 0 (the first deposited validator).
|
|
||||||
> - The validator client will try to connect to the beacon node at `localhost`.
|
|
||||||
> See `--help` to configure that address and other features.
|
|
||||||
> - The validator client will operate very unsafely in `testnet` mode, happily
|
|
||||||
> swapping between chains and creating double-votes.
|
|
||||||
|
|
||||||
<a name="export"></a>
|
|
||||||
### Exporting a genesis file
|
|
||||||
|
|
||||||
Genesis states can downloaded from a running Lighthouse node via the HTTP API. Three content-types are supported:
|
|
||||||
|
|
||||||
- `application/json`
|
|
||||||
- `application/yaml`
|
|
||||||
- `application/ssz`
|
|
||||||
|
|
||||||
Using `curl`, a genesis state can be downloaded to `/tmp/genesis.ssz`:
|
|
||||||
|
|
||||||
```
|
|
||||||
$ curl --header "Content-Type: application/ssz" "localhost:5052/beacon/state/genesis" -o /tmp/genesis.ssz
|
|
||||||
```
|
|
||||||
@ -1,11 +0,0 @@
|
|||||||
# Lighthouse Interop Guide
|
|
||||||
|
|
||||||
This guide is intended for other Ethereum 2.0 client developers performing
|
|
||||||
inter-operability testing with Lighthouse.
|
|
||||||
|
|
||||||
## Chapters
|
|
||||||
|
|
||||||
- Read about the required [development environment](./interop-environment.md).
|
|
||||||
- Get an [overview](./interop-cli.md) of the Lighthouse CLI.
|
|
||||||
- See how we expect to handle some [interop scenarios](./interop-scenarios.md).
|
|
||||||
- See the [interop cheat-sheet](./interop-cheat-sheet.md) for useful CLI tips.
|
|
||||||
@ -1,9 +1,9 @@
|
|||||||
# Lighthouse Documentation
|
# Lighthouse Book
|
||||||
|
|
||||||
[![Build Status]][Build Link] [![Doc Status]][Doc Link] [![Chat Badge]][Chat Link]
|
_Documentation for Lighthouse users and developers._
|
||||||
|
|
||||||
|
[![Doc Status]][Doc Link] [![Chat Badge]][Chat Link]
|
||||||
|
|
||||||
[Build Status]: https://gitlab.sigmaprime.io/sigp/lighthouse/badges/master/build.svg
|
|
||||||
[Build Link]: https://gitlab.sigmaprime.io/sigp/lighthouse/pipelines
|
|
||||||
[Chat Badge]: https://img.shields.io/badge/chat-discord-%237289da
|
[Chat Badge]: https://img.shields.io/badge/chat-discord-%237289da
|
||||||
[Chat Link]: https://discord.gg/cyAszAh
|
[Chat Link]: https://discord.gg/cyAszAh
|
||||||
[Doc Status]:https://img.shields.io/badge/rust--docs-master-orange
|
[Doc Status]:https://img.shields.io/badge/rust--docs-master-orange
|
||||||
@ -12,16 +12,27 @@
|
|||||||
Lighthouse is an **Ethereum 2.0 client** that connects to other Ethereum 2.0
|
Lighthouse is an **Ethereum 2.0 client** that connects to other Ethereum 2.0
|
||||||
clients to form a resilient and decentralized proof-of-stake blockchain.
|
clients to form a resilient and decentralized proof-of-stake blockchain.
|
||||||
|
|
||||||
It is written in Rust, maintained by Sigma Prime and funded by the Ethereum
|
We implement the specification as defined in the
|
||||||
Foundation, Consensys and other individuals and organisations.
|
[ethereum/eth2.0-specs](https://github.com/ethereum/eth2.0-specs) repository.
|
||||||
|
|
||||||
## Developer Resources
|
## Topics
|
||||||
|
|
||||||
Documentation is presently targeted at **researchers and developers**. It
|
You may read this book from start to finish, or jump to some of these topics:
|
||||||
assumes significant prior knowledge of Ethereum 2.0.
|
|
||||||
|
|
||||||
Topics:
|
|
||||||
|
|
||||||
- Get started with [development environment setup](./setup.md).
|
- Get started with [development environment setup](./setup.md).
|
||||||
- See the [interop docs](./interop.md).
|
- Utilize the whole stack by starting a [simple local testnet](./simple-testnet.md).
|
||||||
- [Run a simple testnet](./simple-testnet.md) in Only Three CLI Commands™.
|
- Query the [RESTful HTTP API](./http.md) using `curl`.
|
||||||
|
- Listen to events with the [JSON WebSocket API](./websockets.md).
|
||||||
|
- View the [Rust code docs](http://lighthouse-docs.sigmaprime.io/).
|
||||||
|
|
||||||
|
|
||||||
|
Prospective contributors can read the [Contributing](./contributing.md) section
|
||||||
|
to understand how we develop and test Lighthouse.
|
||||||
|
|
||||||
|
## About this Book
|
||||||
|
|
||||||
|
This book is open source, contribute at
|
||||||
|
[github.com/sigp/lighthouse/book](https://github.com/sigp/lighthouse/tree/master/book).
|
||||||
|
|
||||||
|
The Lighthouse CI/CD system maintains a hosted version of the `master` branch
|
||||||
|
at [lighthouse-book.sigmaprime.io](http://lighthouse-book.sigmaprime.io).
|
||||||
|
|||||||
@ -1,81 +1,29 @@
|
|||||||
# Development Environment Setup
|
# Development Environment Setup
|
||||||
|
|
||||||
Follow this guide to get a Lighthouse development environment up-and-running.
|
## Linux, MacOS & Windows
|
||||||
|
|
||||||
See the [Quick instructions](#quick-instructions) for a summary or the
|
1. Install Rust and Cargo with [rustup](https://rustup.rs/).
|
||||||
[Detailed instructions](#detailed-instructions) for clarification.
|
- Use the `stable` toolchain (it's the default).
|
||||||
|
|
||||||
## Quick instructions
|
|
||||||
|
|
||||||
1. Install Rust + Cargo with [rustup](https://rustup.rs/).
|
|
||||||
1. Install build dependencies using your package manager.
|
1. Install build dependencies using your package manager.
|
||||||
- `$ <package-manager> clang protobuf libssl-dev cmake`
|
- `clang`, `protobuf`, `libssl-dev`, `cmake`
|
||||||
1. Clone the [sigp/lighthouse](https://github.com/sigp/lighthouse).
|
1. Clone the [github.com/sigp/lighthouse](https://github.com/sigp/lighthouse)
|
||||||
1. In the root of the repo, run the tests with `cargo test --all --release`.
|
repository.
|
||||||
1. Then, build the binaries with `cargo build --all --release`.
|
1. Run `$ make` to build Lighthouse.
|
||||||
1. Lighthouse is now fully built and tested.
|
1. Run `$ make test` to run the test suite
|
||||||
|
- If you experience any failures, please reach out on
|
||||||
|
[discord](https://discord.gg/cyAszAh).
|
||||||
|
- Developers use `$ make test-full` to ensure you have the full set of
|
||||||
|
test vectors.
|
||||||
|
|
||||||
_Note: first-time compilation may take several minutes._
|
> - The `beacon_node`, `validator_client` and other binaries are created in
|
||||||
|
> `target/release` directory.
|
||||||
|
> - First-time compilation may take several minutes.
|
||||||
|
|
||||||
## Detailed instructions
|
### Windows
|
||||||
|
|
||||||
A fully-featured development environment can be achieved with the following
|
Perl may also be required to build Lighthouse. You can install [Strawberry
|
||||||
steps:
|
Perl](http://strawberryperl.com/), or alternatively if you're using the [Chocolatey](https://chocolatey.org/) package manager for Windows, use the following choco install command: `choco install strawberryperl`.
|
||||||
|
|
||||||
1. Install [rustup](https://rustup.rs/).
|
|
||||||
1. Use the command `rustup show` to get information about the Rust
|
|
||||||
installation. You should see that the active tool-chain is the stable
|
|
||||||
version.
|
|
||||||
- Updates can be performed using` rustup update`, Lighthouse generally
|
|
||||||
requires a recent version of Rust.
|
|
||||||
1. Install build dependencies (Arch packages are listed here, your
|
|
||||||
distribution will likely be similar):
|
|
||||||
- `clang`: required by RocksDB.
|
|
||||||
- `protobuf`: required for protobuf serialization (gRPC)
|
|
||||||
- `libssl-dev`: also gRPC
|
|
||||||
- `cmake`: required for building protobuf
|
|
||||||
1. Clone the repository with submodules: `git clone
|
|
||||||
https://github.com/sigp/lighthouse`.
|
|
||||||
1. Change directory to the root of the repository.
|
|
||||||
1. Run the test suite with `cargo test --all --release`. The build and test
|
|
||||||
process can take several minutes. If you experience any failures on
|
|
||||||
`master`, please raise an
|
|
||||||
[issue](https://github.com/sigp/lighthouse/issues).
|
|
||||||
|
|
||||||
### Notes:
|
|
||||||
|
|
||||||
Lighthouse targets Rust `stable` but generally runs on `nightly` too.
|
|
||||||
|
|
||||||
#### Note for Windows users:
|
|
||||||
|
|
||||||
Perl may also be required to build lighthouse. You can install [Strawberry
|
|
||||||
Perl](http://strawberryperl.com/), or alternatively use a choco install command
|
|
||||||
`choco install strawberryperl`.
|
|
||||||
|
|
||||||
Additionally, the dependency `protoc-grpcio v0.3.1` is reported to have issues
|
Additionally, the dependency `protoc-grpcio v0.3.1` is reported to have issues
|
||||||
compiling in Windows. You can specify a known working version by editing
|
compiling in Windows. You can specify a known working version by editing
|
||||||
version in `protos/Cargo.toml` section to `protoc-grpcio = "<=0.3.0"`.
|
version in `protos/Cargo.toml` section to `protoc-grpcio = "<=0.3.0"`.
|
||||||
|
|
||||||
## eth2.0-spec-tests
|
|
||||||
|
|
||||||
The
|
|
||||||
[ethereum/eth2.0-spec-tests](https://github.com/ethereum/eth2.0-spec-tests/)
|
|
||||||
repository contains a large set of tests that verify Lighthouse behaviour
|
|
||||||
against the Ethereum Foundation specifications.
|
|
||||||
|
|
||||||
The `tests/ef_tests` crate runs these tests and it has some interesting
|
|
||||||
behaviours:
|
|
||||||
|
|
||||||
- If the `tests/ef_tests/eth2.0-spec-tests` directory is not present, all tests
|
|
||||||
indicate a `pass` when they did not actually run.
|
|
||||||
- If that directory _is_ present, the tests are executed faithfully, failing if
|
|
||||||
a discrepancy is found.
|
|
||||||
|
|
||||||
The `tests/ef_tests/eth2.0-spec-tests` directory is not present by default. To
|
|
||||||
obtain it, use the Makefile in the root of the repository:
|
|
||||||
|
|
||||||
```
|
|
||||||
make ef_tests
|
|
||||||
```
|
|
||||||
|
|
||||||
_Note: this will download 100+ MB of test files from the [ethereum/eth2.0-spec-tests](https://github.com/ethereum/eth2.0-spec-tests/)._
|
|
||||||
|
|||||||
@ -1,32 +1,24 @@
|
|||||||
# Simple Local Testnet
|
# Simple Local Testnet
|
||||||
|
|
||||||
You can setup a local, two-node testnet in **Only Three CLI Commands™**.
|
With a functional [development environment](./setup.md), starting a local multi-node
|
||||||
|
testnet is easy:
|
||||||
Follow the [Quick instructions](#tldr) version if you're confident, or see
|
|
||||||
[Detailed instructions](#detail) for more.
|
|
||||||
|
|
||||||
|
|
||||||
## Quick instructions
|
|
||||||
|
|
||||||
Setup a development environment, build the project and navigate to the
|
|
||||||
`target/release` directory.
|
|
||||||
|
|
||||||
1. Start the first node: `$ ./beacon_node testnet -f recent 8`
|
1. Start the first node: `$ ./beacon_node testnet -f recent 8`
|
||||||
1. Start a validator client: `$ ./validator_client testnet -b insecure 0 8`
|
1. Start a validator client: `$ ./validator_client testnet -b insecure 0 8`
|
||||||
1. Start another node `$ ./beacon_node -b 10 testnet -f bootstrap http://localhost:5052`
|
1. Start more nodes with `$ ./beacon_node -b 10 testnet -f bootstrap
|
||||||
|
http://localhost:5052`
|
||||||
|
- Increment the `-b` value by `10` for each additional node.
|
||||||
|
|
||||||
_Repeat #3 to add more nodes._
|
## Detailed Instructions
|
||||||
|
|
||||||
## Detailed instructions
|
|
||||||
|
|
||||||
First, setup a Lighthouse development environment and navigate to the
|
First, setup a Lighthouse development environment and navigate to the
|
||||||
`target/release` directory (this is where the binaries are located).
|
`target/release` directory (this is where the binaries are located).
|
||||||
|
|
||||||
## Starting the Beacon Node
|
## Starting a beacon node
|
||||||
|
|
||||||
Start a new node (creating a fresh database and configuration in `~/.lighthouse`), using:
|
Start a new node (creating a fresh database and configuration in `~/.lighthouse`), using:
|
||||||
|
|
||||||
```
|
```bash
|
||||||
$ ./beacon_node testnet -f recent 8
|
$ ./beacon_node testnet -f recent 8
|
||||||
```
|
```
|
||||||
|
|
||||||
@ -38,11 +30,11 @@ $ ./beacon_node testnet -f recent 8
|
|||||||
> - See `$ ./beacon_node testnet recent --help` for more configuration options,
|
> - See `$ ./beacon_node testnet recent --help` for more configuration options,
|
||||||
> including `minimal`/`mainnet` specification.
|
> including `minimal`/`mainnet` specification.
|
||||||
|
|
||||||
## Starting the Validator Client
|
## Starting a validator client
|
||||||
|
|
||||||
In a new terminal window, start the validator client with:
|
In a new terminal window, start the validator client with:
|
||||||
|
|
||||||
```
|
```bash
|
||||||
$ ./validator_client testnet -b insecure 0 8
|
$ ./validator_client testnet -b insecure 0 8
|
||||||
```
|
```
|
||||||
|
|
||||||
@ -57,15 +49,15 @@ $ ./validator_client testnet -b insecure 0 8
|
|||||||
> - The validator client will try to connect to the beacon node at `localhost`.
|
> - The validator client will try to connect to the beacon node at `localhost`.
|
||||||
> See `--help` to configure that address and other features.
|
> See `--help` to configure that address and other features.
|
||||||
|
|
||||||
## Adding another Beacon Node
|
## Adding another beacon node
|
||||||
|
|
||||||
You may connect another (non-validating) node to your local network using the
|
You may connect another (non-validating) node to your local network using the
|
||||||
lighthouse `bootstrap` command.
|
lighthouse `bootstrap` command.
|
||||||
|
|
||||||
In a new terminal terminal, run:
|
In a new terminal window, run:
|
||||||
|
|
||||||
|
|
||||||
```
|
```bash
|
||||||
$ ./beacon_node -b 10 testnet -r bootstrap
|
$ ./beacon_node -b 10 testnet -r bootstrap
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|||||||
@ -1,10 +1,158 @@
|
|||||||
# Testnets
|
# Testnets
|
||||||
|
|
||||||
Lighthouse does not offer a public testnet _yet_. In the meantime, it's easy to
|
The Lighthouse CLI has a `testnet` sub-command to allow creating or connecting
|
||||||
start a local testnet:
|
to Eth2 beacon chain testnets.
|
||||||
|
|
||||||
- [Run a simple testnet](testnets.html) in Only Three CLI Commands™.
|
For detailed documentation, use the `--help` flag on the CLI:
|
||||||
- Developers of other Eth2 clients should see the [interop guide](interop.html).
|
|
||||||
- The [sigp/lighthouse-docker](https://github.com/sigp/lighthouse-docker) repo
|
```bash
|
||||||
contains a `docker-compose` setup that runs a multi-node network with
|
$ ./beacon_node testnet --help
|
||||||
built-in metrics and monitoring dashboards, all from your local machine.
|
```
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ ./validator_client testnet --help
|
||||||
|
```
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
|
||||||
|
All examples assume a working [development environment](./setup.md) and
|
||||||
|
commands are based in the `target/release` directory (this is the build dir for
|
||||||
|
`cargo`).
|
||||||
|
|
||||||
|
### Start a beacon node given a validator count and genesis_time
|
||||||
|
|
||||||
|
|
||||||
|
To start a brand-new beacon node (with no history) use:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ ./beacon_node testnet -f quick 8 <GENESIS_TIME>
|
||||||
|
```
|
||||||
|
|
||||||
|
Where `GENESIS_TIME` is in [unix time](https://duckduckgo.com/?q=unix+time&t=ffab&ia=answer).
|
||||||
|
|
||||||
|
> Notes:
|
||||||
|
>
|
||||||
|
> - This method conforms the ["Quick-start
|
||||||
|
genesis"](https://github.com/ethereum/eth2.0-pm/tree/6e41fcf383ebeb5125938850d8e9b4e9888389b4/interop/mocked_start#quick-start-genesis)
|
||||||
|
method in the `ethereum/eth2.0-pm` repository.
|
||||||
|
> - The `-f` flag ignores any existing database or configuration, backing them
|
||||||
|
> up before re-initializing.
|
||||||
|
> - `8` is the validator count and `1567222226` is the genesis time.
|
||||||
|
> - See `$ ./beacon_node testnet quick --help` for more configuration options.
|
||||||
|
|
||||||
|
### Start a beacon node given a genesis state file
|
||||||
|
|
||||||
|
A genesis state can be read from file using the `testnet file` subcommand.
|
||||||
|
There are three supported formats:
|
||||||
|
|
||||||
|
- `ssz` (default)
|
||||||
|
- `json`
|
||||||
|
- `yaml`
|
||||||
|
|
||||||
|
Start a new node using `/tmp/genesis.ssz` as the genesis state:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ ./beacon_node testnet --spec minimal -f file ssz /tmp/genesis.ssz
|
||||||
|
```
|
||||||
|
|
||||||
|
> Notes:
|
||||||
|
>
|
||||||
|
> - The `-f` flag ignores any existing database or configuration, backing them
|
||||||
|
> up before re-initializing.
|
||||||
|
> - See `$ ./beacon_node testnet file --help` for more configuration options.
|
||||||
|
> - The `--spec` flag is required to allow SSZ parsing of fixed-length lists.
|
||||||
|
> Here the `minimal` eth2 specification is chosen, allowing for lower
|
||||||
|
> validator counts. See
|
||||||
|
> [eth2.0-specs/configs](https://github.com/ethereum/eth2.0-specs/tree/dev/configs)
|
||||||
|
> for more info.
|
||||||
|
|
||||||
|
### Start an auto-configured validator client
|
||||||
|
|
||||||
|
To start a brand-new validator client (with no history) use:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ ./validator_client testnet -b insecure 0 8
|
||||||
|
```
|
||||||
|
|
||||||
|
> Notes:
|
||||||
|
>
|
||||||
|
> - The `-b` flag means the validator client will "bootstrap" specs and config
|
||||||
|
> from the beacon node.
|
||||||
|
> - The `insecure` command dictates that the [interop keypairs](https://github.com/ethereum/eth2.0-pm/tree/6e41fcf383ebeb5125938850d8e9b4e9888389b4/interop/mocked_start#pubkeyprivkey-generation)
|
||||||
|
> will be used.
|
||||||
|
> - The `0 8` indicates that this validator client should manage 8 validators,
|
||||||
|
> starting at validator 0 (the first deposited validator).
|
||||||
|
> - The validator client will try to connect to the beacon node at `localhost`.
|
||||||
|
> See `--help` to configure that address and other features.
|
||||||
|
> - The validator client will operate very unsafely in `testnet` mode, happily
|
||||||
|
> swapping between chains and creating double-votes.
|
||||||
|
|
||||||
|
### Exporting a genesis file
|
||||||
|
|
||||||
|
Genesis states can downloaded from a running Lighthouse node via the HTTP API. Three content-types are supported:
|
||||||
|
|
||||||
|
- `application/json`
|
||||||
|
- `application/yaml`
|
||||||
|
- `application/ssz`
|
||||||
|
|
||||||
|
Using `curl`, a genesis state can be downloaded to `/tmp/genesis.ssz`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ curl --header "Content-Type: application/ssz" "localhost:5052/beacon/state/genesis" -o /tmp/genesis.ssz
|
||||||
|
```
|
||||||
|
|
||||||
|
## Advanced
|
||||||
|
|
||||||
|
Below are some CLI commands useful when working with testnets.
|
||||||
|
|
||||||
|
### Specify a boot node by multiaddr
|
||||||
|
|
||||||
|
You can specify a static list of multiaddrs when booting Lighthouse using
|
||||||
|
the `--libp2p-addresses` command.
|
||||||
|
|
||||||
|
#### Example:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ ./beacon_node --libp2p-addresses /ip4/192.168.0.1/tcp/9000
|
||||||
|
```
|
||||||
|
|
||||||
|
### Specify a boot node by ENR (Ethereum Name Record)
|
||||||
|
|
||||||
|
You can specify a static list of Discv5 addresses when booting Lighthouse using
|
||||||
|
the `--boot-nodes` command.
|
||||||
|
|
||||||
|
#### Example:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ ./beacon_node --boot-nodes -IW4QB2Hi8TPuEzQ41Cdf1r2AUU1FFVFDBJdJyOkWk2qXpZfFZQy2YnJIyoT_5fnbtrXUouoskmydZl4pIg90clIkYUDgmlwhH8AAAGDdGNwgiMog3VkcIIjKIlzZWNwMjU2azGhAjg0-DsTkQynhJCRnLLttBK1RS78lmUkLa-wgzAi-Ob5
|
||||||
|
```
|
||||||
|
|
||||||
|
### Avoid port clashes when starting nodes
|
||||||
|
|
||||||
|
Starting a second Lighthouse node on the same machine will fail due to TCP/UDP
|
||||||
|
port collisions. Use the `-b` (`--port-bump`) flag to increase all listening
|
||||||
|
ports by some `n`.
|
||||||
|
|
||||||
|
#### Example:
|
||||||
|
|
||||||
|
Increase all ports by `10` (using multiples of `10` is recommended).
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ ./beacon_node -b 10
|
||||||
|
```
|
||||||
|
|
||||||
|
### Start a testnet with a custom slot time
|
||||||
|
|
||||||
|
Lighthouse can run at quite low slot times when there are few validators (e.g.,
|
||||||
|
`500 ms` slot times should be fine for 8 validators).
|
||||||
|
|
||||||
|
#### Example:
|
||||||
|
|
||||||
|
The `-t` (`--slot-time`) flag specifies the milliseconds per slot.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ ./beacon_node testnet -t 500 recent 8
|
||||||
|
```
|
||||||
|
|
||||||
|
> Note: `bootstrap` loads the slot time via HTTP and therefore conflicts with
|
||||||
|
> this flag.
|
||||||
|
|||||||
@ -1,4 +1,4 @@
|
|||||||
# Websocket Interface
|
# Websocket API
|
||||||
|
|
||||||
By default, a Lighthouse `beacon_node` exposes a websocket server on `localhost:5053`.
|
By default, a Lighthouse `beacon_node` exposes a websocket server on `localhost:5053`.
|
||||||
|
|
||||||
|
|||||||
@ -1,69 +0,0 @@
|
|||||||
# Lighthouse Documentation
|
|
||||||
|
|
||||||
_Lighthouse is a work-in-progress. Instructions are provided for running the
|
|
||||||
client, however these instructions are designed for developers and researchers
|
|
||||||
working on the project. We do not (yet) provide user-facing functionality._
|
|
||||||
|
|
||||||
## Introduction
|
|
||||||
|
|
||||||
- [Overview of Ethereum 2.0](serenity.md)
|
|
||||||
- [Development Environment Setup](env.md)
|
|
||||||
|
|
||||||
For client implementers looking to inter-op, see the [Inter-Op
|
|
||||||
Docs](interop.md).
|
|
||||||
|
|
||||||
## Command-line Interface
|
|
||||||
|
|
||||||
With the [development environment](env.md) configured, run `cargo build --all
|
|
||||||
--release` (this can take several minutes on the first build). Then,
|
|
||||||
navigate to the `target/release/` directory and read the CLI documentation
|
|
||||||
using:
|
|
||||||
|
|
||||||
```
|
|
||||||
$ ./beacon_node -h
|
|
||||||
```
|
|
||||||
|
|
||||||
The main [`README.md`](../README.md#simple-local-testnet) provides instructions
|
|
||||||
for running a small, local testnet.
|
|
||||||
|
|
||||||
## REST API
|
|
||||||
|
|
||||||
The beacon node provides a RESTful HTTP API which serves information about the
|
|
||||||
Beacon Chain, the P2P network and more.
|
|
||||||
|
|
||||||
This API is documented in the [`rest_oapi.yaml`](rest_oapi.yaml) Swagger YAML
|
|
||||||
file. There's an interactive version hosted on
|
|
||||||
[SwaggerHub](https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0).
|
|
||||||
|
|
||||||
The implementation of the Swagger API in Lighthouse is incomplete, we do not
|
|
||||||
(yet) guarantee that all routes are implemented.
|
|
||||||
|
|
||||||
## Configuration Files
|
|
||||||
|
|
||||||
Lighthouse uses [TOML](https://github.com/toml-lang/toml) files for
|
|
||||||
configuration. The following binaries use the following config files (they are
|
|
||||||
generated from defaults if they don't already exist):
|
|
||||||
|
|
||||||
- [Beacon Node](/beacon_node)
|
|
||||||
- [`~/.lighthouse/beacon_node.toml`](#beacon-nodetoml): the primary
|
|
||||||
configuration file for a beacon node.
|
|
||||||
- `~/.lighthouse/eth2-spec.toml`: defines chain-specific "constants" that
|
|
||||||
define an Ethereum 2.0 network.
|
|
||||||
- [Validator Client](/validator_client)
|
|
||||||
- `~/.lighthouse/validator_client.toml`: the primary configuration file for
|
|
||||||
a validator client.
|
|
||||||
- `~/.lighthouse/eth2-spec.toml`: defines chain-specific "constants" that
|
|
||||||
define an Ethereum 2.0 network.
|
|
||||||
|
|
||||||
_Note: default directories are shown, CLI flags can be used to override these
|
|
||||||
defaults._
|
|
||||||
|
|
||||||
#### `beacon-node.toml`
|
|
||||||
|
|
||||||
A TOML configuration file that defines the behaviour of the beacon node
|
|
||||||
runtime.
|
|
||||||
|
|
||||||
- Located in the `datadir` (default `~/.lighthouse`) as `beacon-node.toml`.
|
|
||||||
- Created from defaults if not present.
|
|
||||||
|
|
||||||
See the [example](config_examples/beacon-node.toml) for more information.
|
|
||||||
@ -1,90 +0,0 @@
|
|||||||
#
|
|
||||||
# Beacon Node TOML configuration file.
|
|
||||||
#
|
|
||||||
# Defines the runtime configuration of a Lighthouse Beacon Node.
|
|
||||||
#
|
|
||||||
|
|
||||||
# The directory where beacon-node specific files will be placed. Includes the
|
|
||||||
# database and configuration files.
|
|
||||||
data_dir = ".lighthouse"
|
|
||||||
# The type of database used. Can be either:
|
|
||||||
#
|
|
||||||
# - "disk": LevelDB (almost always desired).
|
|
||||||
# - "memory": an in-memory hashmap (only used for testing).
|
|
||||||
db_type = "disk"
|
|
||||||
# The name of the LevelDB database directory, if any.
|
|
||||||
db_name = "chain_db"
|
|
||||||
# If specified, all logs will be written to this file.
|
|
||||||
log_file = ""
|
|
||||||
# Defines the Ethereum 2.0 specification set to be used:
|
|
||||||
#
|
|
||||||
# - "mainnet": parameters expected to be used for Eth2 mainnet.
|
|
||||||
# - "minimal": smaller, more efficient parameters used for testing.
|
|
||||||
spec_constants = "minimal"
|
|
||||||
|
|
||||||
#
|
|
||||||
# The "genesis_state" object defines how the genesis state should be created.
|
|
||||||
#
|
|
||||||
|
|
||||||
# The "RecentGenesis" type assumes that genesis started at the beginning of the
|
|
||||||
# most-recent 30 minute window (e.g., 08:00, 08:30, 09:00, ...).
|
|
||||||
[genesis_state]
|
|
||||||
type = "RecentGenesis"
|
|
||||||
validator_count = 16
|
|
||||||
|
|
||||||
# "Generated" is the same as "RecentGenesis", however allows for manual
|
|
||||||
# specification of the genesis_time.
|
|
||||||
#
|
|
||||||
# [genesis_state]
|
|
||||||
# type = "Generated"
|
|
||||||
# validator_count = 16
|
|
||||||
# genesis_time = 1564620118
|
|
||||||
|
|
||||||
# "Yaml" loads a full genesis state from YAML file.
|
|
||||||
#
|
|
||||||
# [genesis_state]
|
|
||||||
# type = "Yaml"
|
|
||||||
# file = "~/genesis_state.yaml"
|
|
||||||
|
|
||||||
#
|
|
||||||
# P2P networking configuration.
|
|
||||||
#
|
|
||||||
[network]
|
|
||||||
# The directory for storing p2p network related files. E.g., p2p keys, peer
|
|
||||||
# lists, etc.
|
|
||||||
network_dir = "/home/paul/.lighthouse/network"
|
|
||||||
# The address that libp2p should use for incoming connections.
|
|
||||||
listen_address = "127.0.0.1"
|
|
||||||
# The port that libp2p should use for incoming connections.
|
|
||||||
libp2p_port = 9000
|
|
||||||
# The address that should listen for UDP peer-discovery.
|
|
||||||
discovery_address = "127.0.0.1"
|
|
||||||
# The port that should listen for UDP peer-discovery.
|
|
||||||
discovery_port = 9000
|
|
||||||
# Maximum number of libp2p peers.
|
|
||||||
max_peers = 10
|
|
||||||
# Boot nodes for initial peer discovery.
|
|
||||||
boot_nodes = []
|
|
||||||
# The client version, may be customized.
|
|
||||||
client_version = "Lighthouse/v0.1.0-unstable/x86_64-linux"
|
|
||||||
# A list of libp2p topics. Purpose unknown.
|
|
||||||
topics = []
|
|
||||||
|
|
||||||
#
|
|
||||||
# gRPC configuration. To be removed.
|
|
||||||
#
|
|
||||||
[rpc]
|
|
||||||
enabled = false
|
|
||||||
listen_address = "127.0.0.1"
|
|
||||||
port = 5051
|
|
||||||
|
|
||||||
#
|
|
||||||
# RESTful HTTP API server configuration.
|
|
||||||
#
|
|
||||||
[rest_api]
|
|
||||||
# Set to `true` to enable the gRPC server.
|
|
||||||
enabled = true
|
|
||||||
# The listen port for the HTTP server.
|
|
||||||
listen_address = "127.0.0.1"
|
|
||||||
# The listen port for the HTTP server.
|
|
||||||
port = 5052
|
|
||||||
@ -1,14 +0,0 @@
|
|||||||
# Lighthouse Technical Documentation
|
|
||||||
|
|
||||||
The technical documentation, as generated by Rust, is available at [lighthouse-docs.sigmaprime.io](http://lighthouse-docs.sigmaprime.io/).
|
|
||||||
|
|
||||||
This documentation is generated from Lighthouse and updated regularly.
|
|
||||||
|
|
||||||
|
|
||||||
### How to update:
|
|
||||||
|
|
||||||
- `cargo doc`: builds the docs inside the `target/doc/` directory.
|
|
||||||
- `aws s3 sync target/doc/ s3://lighthouse-docs.sigmaprime.io/`: Uploads all of the docs, as generated with `cargo doc`, to the S3 bucket.
|
|
||||||
|
|
||||||
**Note**: You will need appropriate credentials to make the upload.
|
|
||||||
|
|
||||||
53
docs/env.md
53
docs/env.md
@ -1,53 +0,0 @@
|
|||||||
# Development Environment Setup
|
|
||||||
|
|
||||||
_This document describes how to setup a development environment. It is intended
|
|
||||||
for software developers and researchers who wish to contribute to development._
|
|
||||||
|
|
||||||
Lighthouse is a Rust project and [`cargo`](https://doc.rust-lang.org/cargo/) is
|
|
||||||
used extensively. As such, you'll need to install Rust in order to build the
|
|
||||||
project. Generally, Rust is installed using the
|
|
||||||
[rustup](https://www.rust-lang.org/tools/install) tool-chain manager.
|
|
||||||
|
|
||||||
## Steps
|
|
||||||
|
|
||||||
A fully-featured development environment can be achieved with the following
|
|
||||||
steps:
|
|
||||||
|
|
||||||
1. Install [rustup](https://rustup.rs/).
|
|
||||||
1. Use the command `rustup show` to get information about the Rust
|
|
||||||
installation. You should see that the active tool-chain is the stable
|
|
||||||
version.
|
|
||||||
- Updates can be performed using` rustup update`, Lighthouse generally
|
|
||||||
requires a recent version of Rust.
|
|
||||||
1. Install build dependencies (Arch packages are listed here, your
|
|
||||||
distribution will likely be similar):
|
|
||||||
- `clang`: required by RocksDB.
|
|
||||||
- `protobuf`: required for protobuf serialization (gRPC)
|
|
||||||
- `libssl-dev`: also gRPC
|
|
||||||
- `cmake`: required for building protobuf
|
|
||||||
- `git-lfs`: The Git extension for [Large File
|
|
||||||
Support](https://git-lfs.github.com/) (required for Ethereum Foundation
|
|
||||||
test vectors).
|
|
||||||
1. Clone the repository with submodules: `git clone --recursive
|
|
||||||
https://github.com/sigp/lighthouse`. If you're already cloned the repo,
|
|
||||||
ensure testing submodules are present: `$ git submodule init; git
|
|
||||||
submodule update`
|
|
||||||
1. Change directory to the root of the repository.
|
|
||||||
1. Run the test suite with `cargo test --all --release`. The build and test
|
|
||||||
process can take several minutes. If you experience any failures on
|
|
||||||
`master`, please raise an
|
|
||||||
[issue](https://github.com/sigp/lighthouse/issues).
|
|
||||||
|
|
||||||
## Notes:
|
|
||||||
|
|
||||||
Lighthouse targets Rust `stable` but generally runs on `nightly` too.
|
|
||||||
|
|
||||||
### Note for Windows users:
|
|
||||||
|
|
||||||
Perl may also be required to build lighthouse. You can install [Strawberry
|
|
||||||
Perl](http://strawberryperl.com/), or alternatively use a choco install command
|
|
||||||
`choco install strawberryperl`.
|
|
||||||
|
|
||||||
Additionally, the dependency `protoc-grpcio v0.3.1` is reported to have issues
|
|
||||||
compiling in Windows. You can specify a known working version by editing
|
|
||||||
version in `protos/Cargo.toml` section to `protoc-grpcio = "<=0.3.0"`.
|
|
||||||
109
docs/interop.md
109
docs/interop.md
@ -1,109 +0,0 @@
|
|||||||
# Lighthouse Inter-Op Docs
|
|
||||||
|
|
||||||
_These documents are intended for a highly technical audience, specifically
|
|
||||||
Ethereum 2.0 implementers._
|
|
||||||
|
|
||||||
This document provides details on how to use Lighthouse for inter-op testing.
|
|
||||||
|
|
||||||
## Steps
|
|
||||||
|
|
||||||
_Note: binaries are compiled into the `target/release` directory of the
|
|
||||||
repository. In this example, we run binaries assuming the user is in this
|
|
||||||
directory. E.g., running the beacon node binary can be achieved with
|
|
||||||
`$ ./target/release/beacon_node`. Those familiar with `cargo` may use the
|
|
||||||
equivalent (and more-convenient) `cargo run --release --` commands._
|
|
||||||
|
|
||||||
1. Setup a Lighthouse [development environment](env.md).
|
|
||||||
1. Build all the binaries using `cargo build --all --release`
|
|
||||||
1. Create default configuration files by running `$ ./beacon_node` and pressing
|
|
||||||
Ctrl+C after the node has started.
|
|
||||||
1. Follow the steps in [Genesis](#genesis) to configure the genesis state.
|
|
||||||
1. Follow the steps in [Networking](#networking) to launch a node with
|
|
||||||
appropriate networking parameters.
|
|
||||||
|
|
||||||
## Genesis
|
|
||||||
|
|
||||||
Lighthouse supports the following methods for generating a genesis state:
|
|
||||||
|
|
||||||
- [`Yaml`](#yaml): loads the genesis state from some YAML file (recommended
|
|
||||||
method).
|
|
||||||
- [`Generated`](#generated): generates a state given a `(validator_count,
|
|
||||||
genesis_time)`
|
|
||||||
tuple. _Note: this method is not yet fully specified and the state
|
|
||||||
generated is almost certainly not identical to other implementations._
|
|
||||||
- [`RecentGenesis`](#recentgenesis): identical to `Generated`, however the
|
|
||||||
`genesis_time` is set
|
|
||||||
to the previous 30-minute window. For example, if a state is generated at
|
|
||||||
`0845`, the genesis time will be `0830`.
|
|
||||||
|
|
||||||
You may configure a `beacon_node` to use one of these methods using the
|
|
||||||
[`beacon_node.toml`](README.md#beacon-nodetoml). There is a [documented
|
|
||||||
example](config_examples/) configuration file which includes an example for
|
|
||||||
each of these methods (see the `genesis_state` object).
|
|
||||||
|
|
||||||
### Yaml
|
|
||||||
|
|
||||||
This method involves loading a `BeaconState` from a YAML file. We provide
|
|
||||||
instructions for generating that YAML file and starting from it. If starting
|
|
||||||
from a pre-existing YAML file, simply skip the generation steps.
|
|
||||||
|
|
||||||
#### Generating a YAML file
|
|
||||||
|
|
||||||
The [cli_util](/tests/cli_util) generate YAML genesis state files. You can run
|
|
||||||
`$ ./cli_util genesis_yaml -h` to see documentation. We provide an example to
|
|
||||||
generate a YAML file with the following properties:
|
|
||||||
|
|
||||||
- 10 initial validators, each with [deterministic
|
|
||||||
keypairs](https://github.com/ethereum/eth2.0-pm/issues/60#issuecomment-512157915).
|
|
||||||
- The genesis file is stored in `~/.lighthouse/`, the default data directory
|
|
||||||
(an absolute path must be supplied).
|
|
||||||
- Genesis time is set to the time when the command is run (it can be customized
|
|
||||||
with the `-g` flag).
|
|
||||||
|
|
||||||
```
|
|
||||||
$ ./cli_util genesis_yaml -n 10 -f /home/user/.lighthouse/genesis_state.yaml
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Configuring the Beacon Node
|
|
||||||
|
|
||||||
Modify the [`beacon-node.toml`](README.md#beacon-nodetoml) file to have the
|
|
||||||
following `genesiss_state` object (choosing the `file`):
|
|
||||||
|
|
||||||
```
|
|
||||||
[genesis_state]
|
|
||||||
type = "Yaml"
|
|
||||||
file = "/home/user/.lighthouse/genesis_state.yaml"
|
|
||||||
```
|
|
||||||
|
|
||||||
### Generated
|
|
||||||
|
|
||||||
Modify the [`beacon-node.toml`](README.md#beacon-nodetoml) file to have the
|
|
||||||
following `genesis_state` object (choosing the `validator_count` and
|
|
||||||
`genesis_time`):
|
|
||||||
|
|
||||||
```
|
|
||||||
[genesis_state]
|
|
||||||
type = "Generated"
|
|
||||||
validator_count = 16
|
|
||||||
genesis_time = 1564620118
|
|
||||||
```
|
|
||||||
|
|
||||||
### RecentGenesis
|
|
||||||
|
|
||||||
Modify the [`beacon-node.toml`](README.md#beacon-nodetoml) file to have the
|
|
||||||
following `genesis_state` object (choosing the `validator_count`):
|
|
||||||
|
|
||||||
```
|
|
||||||
[genesis_state]
|
|
||||||
type = "RecentGenesis"
|
|
||||||
validator_count = 16
|
|
||||||
```
|
|
||||||
|
|
||||||
## Networking
|
|
||||||
|
|
||||||
_TODO: provide details on config required to connect to some IP address._
|
|
||||||
|
|
||||||
## References
|
|
||||||
|
|
||||||
The BLS key generation method used should be identical to [this
|
|
||||||
implementation](https://github.com/ethereum/eth2.0-pm/issues/60#issuecomment-512157915).
|
|
||||||
161
docs/serenity.md
161
docs/serenity.md
@ -1,161 +0,0 @@
|
|||||||
# Ethereum Serenity
|
|
||||||
|
|
||||||
This document aims at providing a high level understanding of Ethereum and the
|
|
||||||
Serenity phase of the Ethereum roadmap.
|
|
||||||
|
|
||||||
## The Blockchain
|
|
||||||
|
|
||||||
A blockchain can be seen as a decentralized, distributed ledger. The ledger of
|
|
||||||
transactions is replicated onto all nodes in the network. When a transaction
|
|
||||||
occurs, it is first propagated to the nodes. Once the nodes receive the
|
|
||||||
transaction, and verifies the correctness, the nodes attempt to batch the
|
|
||||||
transactions into a block and append the block to the ledger. Once the ledger
|
|
||||||
has been successfully appended onto, they propagate the block to the network.
|
|
||||||
If accepted, this block now becomes the latest block in the chain. If two people
|
|
||||||
propose a block at the same time, the one canonical blockchain forks. At this
|
|
||||||
point it must be resolved, and each system has it's own way of resolving these
|
|
||||||
forks.
|
|
||||||
|
|
||||||
|
|
||||||
<center>Figure 1. Example blockchain with a resolved fork.</center>
|
|
||||||
|
|
||||||
<br>
|
|
||||||
|
|
||||||
The idea of the blockchain was first proposed in the seminal [Bitcoin
|
|
||||||
whitepaper](https://bitcoin.org/bitcoin.pdf) by Satoshi Nakamoto. Since then, a
|
|
||||||
vast number of updates and blockchains have taken shape providing different
|
|
||||||
functionality or properties to the original blockchain.
|
|
||||||
|
|
||||||
## What is Ethereum?
|
|
||||||
|
|
||||||
Ethereum is an open blockchain protocol, allowing for the building and use of
|
|
||||||
decentralized applications that run on blockchain technology. Ethereum was one
|
|
||||||
of the initial platforms providing turing-complete code to be run on the
|
|
||||||
blockchain, allowing for conditional payments to occur through the use of this
|
|
||||||
code. Since then, Ethereum has advanced to allow for a number of Decentralized
|
|
||||||
Applications (DApps) to be developed and run completely with the blockchain as
|
|
||||||
the backbone.
|
|
||||||
|
|
||||||
General Ethereum Introduction:
|
|
||||||
|
|
||||||
* [What is Ethereum](http://ethdocs.org/en/latest/introduction/what-is-ethereum.html)
|
|
||||||
* [Ethereum Introduction](https://github.com/ethereum/wiki/wiki/Ethereum-introduction)
|
|
||||||
|
|
||||||
|
|
||||||
### Proof-of-Work and the current state of Ethereum.
|
|
||||||
|
|
||||||
Currently, Ethereum is based on the Proof-of-Work model, a Sybil resilient
|
|
||||||
mechanism to allow nodes to propose blocks to the network. Although it provides
|
|
||||||
properties that allow the blockchain to operate in an open, public
|
|
||||||
(permissionless) network, it faces it's challenges and as a result impacts
|
|
||||||
the operation of the blockchain.
|
|
||||||
|
|
||||||
The main goals to advance Ethereum is to (1) increase the scalability and
|
|
||||||
overall transaction processing power of the Ethereum world computer and (2)
|
|
||||||
find a suitable replacement for Proof-of-Work that still provides the necessary
|
|
||||||
properties that we need.
|
|
||||||
|
|
||||||
* [Proof-of-Work in Cryptocurrencies: an accessible introduction](https://blog.sigmaprime.io/what-is-proof-of-work.html)
|
|
||||||
|
|
||||||
## Serenity
|
|
||||||
|
|
||||||
Ethereum Serenity refers to a new blockchain system currently under development
|
|
||||||
by the Ethereum Foundation and the Ethereum community.
|
|
||||||
|
|
||||||
As part of the original Ethereum roadmap
|
|
||||||
[\[1\]](https://blog.ethereum.org/2015/03/03/ethereum-launch-process/)
|
|
||||||
[\[2\]](http://ethdocs.org/en/latest/introduction/the-homestead-release.html),
|
|
||||||
the Proof-of-Stake integration falls under **Release Step 4: *Serenity***. With
|
|
||||||
this, a number of changes are to be made to the current Ethereum protocol to
|
|
||||||
incorporate some of the new Proof-of-Stake mechanisms as well as improve on
|
|
||||||
some of the hindrances faced by the current Proof-of-Work chain.
|
|
||||||
|
|
||||||
To now advance the current Ethereum, the decision is made to move to a sharded
|
|
||||||
Beacon chain structure where multiple shard-chains will be operating and
|
|
||||||
interacting with a central beacon chain.The Serenity blockchain consists of
|
|
||||||
1,025 proof-of-stake blockchains. This includes the "beacon chain" and 1,024
|
|
||||||
"shard chains".
|
|
||||||
|
|
||||||
Ethereum Serenity is also known as "Ethereum 2.0" and "Shasper". We prefer
|
|
||||||
Serenity as it more accurately reflects the established Ethereum roadmap (plus
|
|
||||||
we think it's a nice name).
|
|
||||||
|
|
||||||
(Be mindful, the specifications change occasionally, so check these to keep up
|
|
||||||
to date)
|
|
||||||
|
|
||||||
* Current Specifications:
|
|
||||||
* [Danny Ryan's "State of the Spec"](https://notes.ethereum.org/s/BJEZWNoyE) (A nice summary of the current specifications)
|
|
||||||
* [Ethereum Serenity - Phase 0: Beacon Chain Spec](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md)
|
|
||||||
* [Ethereum Serenity - Phase 1: Sharded Data Chains](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/1_shard-data-chains.md)
|
|
||||||
* [Beacon Chain - Vitalik Buterin and Justin Drake explain](https://www.youtube.com/watch?v=GAywmwGToUI)
|
|
||||||
* Understanding Sharding:
|
|
||||||
* [Prysmatic Labs: Sharding Explained](https://medium.com/prysmatic-labs/how-to-scale-ethereum-sharding-explained-ba2e283b7fce)
|
|
||||||
* Other relevant resources
|
|
||||||
* [Proof of Stake - Casper FFG](https://www.youtube.com/watch?v=uQ3IqLDf-oo)
|
|
||||||
* [Justin Drake VDF Devcon4 Talk](https://www.youtube.com/watch?v=zqL_cMlPjOI)
|
|
||||||
|
|
||||||
|
|
||||||
### Beacon Chain
|
|
||||||
|
|
||||||
The concept of a beacon chain differs from existing blockchains, such as
|
|
||||||
Bitcoin and Ethereum, in that it doesn't process transactions per se. Instead,
|
|
||||||
it maintains a set of bonded (staked) validators and coordinates these to
|
|
||||||
provide services to a static set of *sub-blockchains* (i.e. shards). Each of
|
|
||||||
these shard blockchains processes normal transactions (e.g. "Transfer 5 ETH
|
|
||||||
from A to B") in parallel whilst deferring consensus mechanisms to the beacon
|
|
||||||
chain.
|
|
||||||
|
|
||||||
Major services provided by the beacon chain to its shards include the following:
|
|
||||||
|
|
||||||
- A source of entropy, likely using a [RANDAO + VDF
|
|
||||||
scheme](https://ethresear.ch/t/minimal-vdf-randomness-beacon/3566).
|
|
||||||
- Validator management, including:
|
|
||||||
- Inducting and ejecting validators.
|
|
||||||
- Assigning randomly-shuffled subsets of validators to particular shards.
|
|
||||||
- Penalizing and rewarding validators.
|
|
||||||
- Proof-of-stake consensus for shard chain blocks.
|
|
||||||
|
|
||||||
### Shard Chains
|
|
||||||
|
|
||||||
Shards are analogous to CPU cores - they're a resource where transactions can
|
|
||||||
execute in series (one-after-another). Presently, Ethereum is single-core and
|
|
||||||
can only _fully_ process one transaction at a time. Sharding allows processing
|
|
||||||
of multiple transactions simultaneously, greatly increasing the per-second
|
|
||||||
transaction capacity of Ethereum.
|
|
||||||
|
|
||||||
Each shard uses a proof-of-stake consensus mechanism and shares its validators
|
|
||||||
(stakers) with other shards. The beacon chain rotates validators
|
|
||||||
pseudo-randomly between different shards. Shards will likely be the basis of
|
|
||||||
layer-2 transaction processing schemes, however, that is not in scope of this
|
|
||||||
discussion.
|
|
||||||
|
|
||||||
### The Proof-of-Work Chain
|
|
||||||
|
|
||||||
The present-Ethereum proof-of-work (PoW) chain will host a smart contract that
|
|
||||||
enables accounts to deposit 32 ETH, a BLS public key, and some [other
|
|
||||||
parameters](https://github.com/ethereum/eth2.0-specs/blob/master/specs/casper_sharding_v2.1.md#pow-chain-changes),
|
|
||||||
allowing them to become beacon chain validators. Each beacon chain will
|
|
||||||
reference a PoW block hash allowing PoW clients to use the beacon chain as a
|
|
||||||
source of [Casper FFG finality](https://arxiv.org/abs/1710.09437), if desired.
|
|
||||||
|
|
||||||
It is a requirement that ETH can move freely between shard chains, as well as between
|
|
||||||
Serenity and present-Ethereum blockchains. The exact mechanics of these transfers remain
|
|
||||||
an active topic of research and their details are yet to be confirmed.
|
|
||||||
|
|
||||||
## Serenity Progress
|
|
||||||
|
|
||||||
Ethereum Serenity is not fully specified and a working implementation does not
|
|
||||||
yet exist. Some teams have demos available which indicate progress, but do not
|
|
||||||
constitute a complete product. We look forward to providing user functionality
|
|
||||||
once we are ready to provide a minimum-viable user experience.
|
|
||||||
|
|
||||||
The work-in-progress specifications live in the
|
|
||||||
[ethereum/eth2.0-specs](https://github.com/ethereum/eth2.0-specs) repository.
|
|
||||||
There is active discussion about the specification in the
|
|
||||||
[ethereum/sharding](https://gitter.im/ethereum/sharding) gitter channel. A
|
|
||||||
proof-of-concept implementation in Python is available at
|
|
||||||
[ethereum/beacon_chain](https://github.com/ethereum/beacon_chain).
|
|
||||||
|
|
||||||
Presently, the specification focuses almost exclusively on the beacon chain,
|
|
||||||
as it is the focus of current development efforts. Progress on shard chain
|
|
||||||
specification will soon follow.
|
|
||||||
@ -1,35 +1,3 @@
|
|||||||
# Ethereum 2.0 Common Crates
|
# eth2
|
||||||
|
|
||||||
Rust crates containing logic common across the Lighthouse project.
|
Common crates containing eth2-specific logic.
|
||||||
|
|
||||||
## Per-Crate Summary
|
|
||||||
|
|
||||||
- [`attester/`](attester/): Core logic for attesting to beacon and shard blocks.
|
|
||||||
- [`block_proposer/`](block_proposer/): Core logic for proposing beacon blocks.
|
|
||||||
- [`fork_choice/`](fork_choice/): A collection of fork-choice algorithms for
|
|
||||||
the Beacon Chain.
|
|
||||||
- [`state_processing/`](state_processing/): Provides per-slot, per-block, and
|
|
||||||
per-epoch state processing.
|
|
||||||
- [`types/`](types/): Defines base Ethereum 2.0 types (e.g., `BeaconBlock`,
|
|
||||||
`BeaconState`, etc).
|
|
||||||
- [`utils/`](utils/):
|
|
||||||
- [`bls`](utils/bls/): A wrapper for an external BLS encryption library.
|
|
||||||
- [`fisher-yates-shuffle`](utils/fisher-yates-shuffle/): shuffles a list
|
|
||||||
pseudo-randomly.
|
|
||||||
- [`hashing`](utils/hashing/): A wrapper for external hashing libraries.
|
|
||||||
- [`honey-badger-split`](utils/honey-badger-split/): Splits a list in `n`
|
|
||||||
parts without giving AF about the length of the list, `n`, or anything
|
|
||||||
else.
|
|
||||||
- [`int-to-bytes`](utils/int-to-bytes/): Simple library which converts ints
|
|
||||||
into byte-strings of various lengths.
|
|
||||||
- [`slot_clock`](utils/slot_clock/): translates the system time into Beacon
|
|
||||||
Chain "slots". (Also provides another slot clock that's useful during
|
|
||||||
testing.)
|
|
||||||
- [`ssz`](utils/ssz/): an implementation of the SimpleSerialize
|
|
||||||
serialization/deserialization protocol used by Eth 2.0.
|
|
||||||
- [`ssz_derive`](utils/ssz_derive/): provides procedural macros for
|
|
||||||
deriving SSZ `Encode`, `Decode`, and `TreeHash` methods.
|
|
||||||
- [`swap_or_not_shuffle`](utils/swap_or_not_shuffle/): a list-shuffling
|
|
||||||
method which is slow, but allows for a subset of indices to be shuffled.
|
|
||||||
- [`test_random_derive`](utils/test_random_derive/): provides procedural
|
|
||||||
macros for deriving the `TestRandom` trait defined in `types`.
|
|
||||||
|
|||||||
11
lcli/README.md
Normal file
11
lcli/README.md
Normal file
@ -0,0 +1,11 @@
|
|||||||
|
# lcli
|
||||||
|
|
||||||
|
A command-line debugging tool, inspired by [zcli](https://github.com/protolambda/zcli).
|
||||||
|
|
||||||
|
Allows for replaying state transitions from SSZ files to assist in fault-finding.
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
```
|
||||||
|
$ cargo run --release -- --help
|
||||||
|
```
|
||||||
18
tests/ef_tests/Makefile
Normal file
18
tests/ef_tests/Makefile
Normal file
@ -0,0 +1,18 @@
|
|||||||
|
TESTS_TAG := v0.8.3
|
||||||
|
TESTS = general minimal mainnet
|
||||||
|
|
||||||
|
REPO_NAME := eth2.0-spec-tests
|
||||||
|
OUTPUT_DIR := ./$(REPO_NAME)
|
||||||
|
|
||||||
|
BASE_URL := https://github.com/ethereum/$(REPO_NAME)/releases/download/$(TESTS_TAG)
|
||||||
|
|
||||||
|
eth2.0-spec-tests:
|
||||||
|
mkdir $(OUTPUT_DIR)
|
||||||
|
for test in $(TESTS); do \
|
||||||
|
wget $(BASE_URL)/$$test.tar.gz; \
|
||||||
|
tar -xzvf $$test.tar.gz -C $(OUTPUT_DIR);\
|
||||||
|
rm $$test.tar.gz;\
|
||||||
|
done
|
||||||
|
|
||||||
|
clean:
|
||||||
|
rm -r $(OUTPUT_DIR)
|
||||||
30
tests/ef_tests/README.md
Normal file
30
tests/ef_tests/README.md
Normal file
@ -0,0 +1,30 @@
|
|||||||
|
# Ethereum 2.0 Specification Tests
|
||||||
|
|
||||||
|
This crate parses and executes the test vectors at [ethereum/eth2.0-spec-tests](https://github.com/ethereum/eth2.0-spec-tests).
|
||||||
|
|
||||||
|
Functionality is achieved only via the `$ cargo test` command.
|
||||||
|
|
||||||
|
## Tests
|
||||||
|
|
||||||
|
Because the test vectors are very large, we do not download the
|
||||||
|
tests vectors or require that the tests pass by default. Specifically;
|
||||||
|
|
||||||
|
- If the `tests/ef_tests/eth2.0-spec-tests` directory is not present, all tests
|
||||||
|
indicate a `pass` when they did not actually run.
|
||||||
|
- If that directory _is_ present, the tests are executed faithfully, failing if
|
||||||
|
a discrepancy is found.
|
||||||
|
|
||||||
|
## Downloading Test Vectors
|
||||||
|
|
||||||
|
The `eth2.0-spec-tests` directory is not present by default. To
|
||||||
|
obtain it, use the Makefile:
|
||||||
|
|
||||||
|
```
|
||||||
|
$ make
|
||||||
|
```
|
||||||
|
|
||||||
|
_Note: this may download hundreds of MB of compressed archives from the
|
||||||
|
[ethereum/eth2.0-spec-tests](https://github.com/ethereum/eth2.0-spec-tests/),
|
||||||
|
which may expand into several GB of files._
|
||||||
|
|
||||||
|
Remove the tests to save space or update to a new version with `$ make clean`.
|
||||||
@ -6,7 +6,6 @@ pub use self::beacon_node_block::{BeaconNodeError, PublishOutcome};
|
|||||||
pub use self::grpc::BeaconBlockGrpcClient;
|
pub use self::grpc::BeaconBlockGrpcClient;
|
||||||
use crate::signer::Signer;
|
use crate::signer::Signer;
|
||||||
use core::marker::PhantomData;
|
use core::marker::PhantomData;
|
||||||
use serde_json;
|
|
||||||
use slog::{error, info, trace, warn};
|
use slog::{error, info, trace, warn};
|
||||||
use std::sync::Arc;
|
use std::sync::Arc;
|
||||||
use tree_hash::{SignedRoot, TreeHash};
|
use tree_hash::{SignedRoot, TreeHash};
|
||||||
@ -99,10 +98,7 @@ impl<'a, B: BeaconNodeBlock, S: Signer, E: EthSpec> BlockProducer<'a, B, S, E> {
|
|||||||
warn!(self.log, "Signing rejected"; "message" => format!("{:?}", message));
|
warn!(self.log, "Signing rejected"; "message" => format!("{:?}", message));
|
||||||
return Ok(ValidatorEvent::SignerRejection(self.slot));
|
return Ok(ValidatorEvent::SignerRejection(self.slot));
|
||||||
}
|
}
|
||||||
Some(signature) => {
|
Some(signature) => signature,
|
||||||
info!(self.log, "Signed tree_hash_root for randao_reveal"; "message" => format!("{:?}", message), "signature" => serde_json::to_string(&signature).expect("We should always be able to serialize a signature as JSON."));
|
|
||||||
signature
|
|
||||||
}
|
|
||||||
};
|
};
|
||||||
|
|
||||||
if let Some(block) = self
|
if let Some(block) = self
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user