2019-06-25 04:02:19 +00:00
# Lighthouse: Ethereum 2.0
An open-source Ethereum 2.0 client, written in Rust and maintained by Sigma Prime.
2018-07-06 07:54:07 +00:00
2019-07-31 21:53:30 +00:00
[![Build Status]][Build Link] [![Doc Status]][Doc Link] [![Chat Badge]][Chat Link]
2019-05-10 01:49:28 +00:00
[Build Status]: https://gitlab.sigmaprime.io/sigp/lighthouse/badges/master/build.svg
[Build Link]: https://gitlab.sigmaprime.io/sigp/lighthouse/pipelines
2019-07-31 21:53:30 +00:00
[Chat Badge]: https://img.shields.io/badge/chat-discord-%237289da
[Chat Link]: https://discord.gg/cyAszAh
2019-05-10 01:49:28 +00:00
[Doc Status]: https://img.shields.io/badge/docs-master-blue.svg
[Doc Link]: http://lighthouse-docs.sigmaprime.io/
2018-07-12 05:01:28 +00:00
2019-06-25 04:02:19 +00:00
## Overview
Lighthouse is:
- Fully open-source, licensed under Apache 2.0.
2019-07-26 19:26:06 +00:00
- Security-focused, fuzzing has begun and security reviews are planned
2019-06-25 04:02:19 +00:00
for late-2019.
- Built in [Rust ](https://www.rust-lang.org/ ), a modern language providing unique safety guarantees and
excellent performance (comparable to C++).
- Funded by various organisations, including Sigma Prime, the
2019-07-26 19:26:06 +00:00
Ethereum Foundation, ConsenSys and private individuals.
2019-06-25 04:02:19 +00:00
- Actively working to promote an inter-operable, multi-client Ethereum 2.0.
## 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:
Update to frozen spec ❄️ (v0.8.1) (#444)
* types: first updates for v0.8
* state_processing: epoch processing v0.8.0
* state_processing: block processing v0.8.0
* tree_hash_derive: support generics in SignedRoot
* types v0.8: update to use ssz_types
* state_processing v0.8: use ssz_types
* ssz_types: add bitwise methods and from_elem
* types: fix v0.8 FIXMEs
* ssz_types: add bitfield shift_up
* ssz_types: iterators and DerefMut for VariableList
* types,state_processing: use VariableList
* ssz_types: fix BitVector Decode impl
Fixed a typo in the implementation of ssz::Decode for BitVector, which caused it
to be considered variable length!
* types: fix test modules for v0.8 update
* types: remove slow type-level arithmetic
* state_processing: fix tests for v0.8
* op_pool: update for v0.8
* ssz_types: Bitfield difference length-independent
Allow computing the difference of two bitfields of different lengths.
* Implement compact committee support
* epoch_processing: committee & active index roots
* state_processing: genesis state builder v0.8
* state_processing: implement v0.8.1
* Further improve tree_hash
* Strip examples, tests from cached_tree_hash
* Update TreeHash, un-impl CachedTreeHash
* Update bitfield TreeHash, un-impl CachedTreeHash
* Update FixedLenVec TreeHash, unimpl CachedTreeHash
* Update update tree_hash_derive for new TreeHash
* Fix TreeHash, un-impl CachedTreeHash for ssz_types
* Remove fixed_len_vec, ssz benches
SSZ benches relied upon fixed_len_vec -- it is easier to just delete
them and rebuild them later (when necessary)
* Remove boolean_bitfield crate
* Fix fake_crypto BLS compile errors
* Update ef_tests for new v.8 type params
* Update ef_tests submodule to v0.8.1 tag
* Make fixes to support parsing ssz ef_tests
* `compact_committee...` to `compact_committees...`
* Derive more traits for `CompactCommittee`
* Flip bitfield byte-endianness
* Fix tree_hash for bitfields
* Modify CLI output for ef_tests
* Bump ssz crate version
* Update ssz_types doc comment
* Del cached tree hash tests from ssz_static tests
* Tidy SSZ dependencies
* Rename ssz_types crate to eth2_ssz_types
* validator_client: update for v0.8
* ssz_types: update union/difference for bit order swap
* beacon_node: update for v0.8, EthSpec
* types: disable cached tree hash, update min spec
* state_processing: fix slot bug in committee update
* tests: temporarily disable fork choice harness test
See #447
* committee cache: prevent out-of-bounds access
In the case where we tried to access the committee of a shard that didn't have a committee in the
current epoch, we were accessing elements beyond the end of the shuffling vector and panicking! This
commit adds a check to make the failure safe and explicit.
* fix bug in get_indexed_attestation and simplify
There was a bug in our implementation of get_indexed_attestation whereby
incorrect "committee indices" were used to index into the custody bitfield. The
bug was only observable in the case where some bits of the custody bitfield were
set to 1. The implementation has been simplified to remove the bug, and a test
added.
* state_proc: workaround for compact committees bug
https://github.com/ethereum/eth2.0-specs/issues/1315
* v0.8: updates to make the EF tests pass
* Remove redundant max operation checks.
* Always supply both messages when checking attestation signatures -- allowing
verification of an attestation with no signatures.
* Swap the order of the fork and domain constant in `get_domain`, to match
the spec.
* rustfmt
* ef_tests: add new epoch processing tests
* Integrate v0.8 into master (compiles)
* Remove unused crates, fix clippy lints
* Replace v0.6.3 tags w/ v0.8.1
* Remove old comment
* Ensure lmd ghost tests only run in release
* Update readme
2019-07-30 02:44:51 +00:00
- Specification `v0.8.1` implemented, optimized and passing test vectors.
- Rust-native libp2p with Gossipsub and Discv5.
2019-06-25 04:02:19 +00:00
- Metrics via Prometheus.
- Basic gRPC API, soon to be replaced with RESTful HTTP/JSON.
### Roadmap
Update to frozen spec ❄️ (v0.8.1) (#444)
* types: first updates for v0.8
* state_processing: epoch processing v0.8.0
* state_processing: block processing v0.8.0
* tree_hash_derive: support generics in SignedRoot
* types v0.8: update to use ssz_types
* state_processing v0.8: use ssz_types
* ssz_types: add bitwise methods and from_elem
* types: fix v0.8 FIXMEs
* ssz_types: add bitfield shift_up
* ssz_types: iterators and DerefMut for VariableList
* types,state_processing: use VariableList
* ssz_types: fix BitVector Decode impl
Fixed a typo in the implementation of ssz::Decode for BitVector, which caused it
to be considered variable length!
* types: fix test modules for v0.8 update
* types: remove slow type-level arithmetic
* state_processing: fix tests for v0.8
* op_pool: update for v0.8
* ssz_types: Bitfield difference length-independent
Allow computing the difference of two bitfields of different lengths.
* Implement compact committee support
* epoch_processing: committee & active index roots
* state_processing: genesis state builder v0.8
* state_processing: implement v0.8.1
* Further improve tree_hash
* Strip examples, tests from cached_tree_hash
* Update TreeHash, un-impl CachedTreeHash
* Update bitfield TreeHash, un-impl CachedTreeHash
* Update FixedLenVec TreeHash, unimpl CachedTreeHash
* Update update tree_hash_derive for new TreeHash
* Fix TreeHash, un-impl CachedTreeHash for ssz_types
* Remove fixed_len_vec, ssz benches
SSZ benches relied upon fixed_len_vec -- it is easier to just delete
them and rebuild them later (when necessary)
* Remove boolean_bitfield crate
* Fix fake_crypto BLS compile errors
* Update ef_tests for new v.8 type params
* Update ef_tests submodule to v0.8.1 tag
* Make fixes to support parsing ssz ef_tests
* `compact_committee...` to `compact_committees...`
* Derive more traits for `CompactCommittee`
* Flip bitfield byte-endianness
* Fix tree_hash for bitfields
* Modify CLI output for ef_tests
* Bump ssz crate version
* Update ssz_types doc comment
* Del cached tree hash tests from ssz_static tests
* Tidy SSZ dependencies
* Rename ssz_types crate to eth2_ssz_types
* validator_client: update for v0.8
* ssz_types: update union/difference for bit order swap
* beacon_node: update for v0.8, EthSpec
* types: disable cached tree hash, update min spec
* state_processing: fix slot bug in committee update
* tests: temporarily disable fork choice harness test
See #447
* committee cache: prevent out-of-bounds access
In the case where we tried to access the committee of a shard that didn't have a committee in the
current epoch, we were accessing elements beyond the end of the shuffling vector and panicking! This
commit adds a check to make the failure safe and explicit.
* fix bug in get_indexed_attestation and simplify
There was a bug in our implementation of get_indexed_attestation whereby
incorrect "committee indices" were used to index into the custody bitfield. The
bug was only observable in the case where some bits of the custody bitfield were
set to 1. The implementation has been simplified to remove the bug, and a test
added.
* state_proc: workaround for compact committees bug
https://github.com/ethereum/eth2.0-specs/issues/1315
* v0.8: updates to make the EF tests pass
* Remove redundant max operation checks.
* Always supply both messages when checking attestation signatures -- allowing
verification of an attestation with no signatures.
* Swap the order of the fork and domain constant in `get_domain`, to match
the spec.
* rustfmt
* ef_tests: add new epoch processing tests
* Integrate v0.8 into master (compiles)
* Remove unused crates, fix clippy lints
* Replace v0.6.3 tags w/ v0.8.1
* Remove old comment
* Ensure lmd ghost tests only run in release
* Update readme
2019-07-30 02:44:51 +00:00
- **Early-September 2019**: `lighthouse-0.0.1` release: A stable testnet for
developers with a useful HTTP API.
2019-06-25 04:02:19 +00:00
- **September 2019**: Inter-operability with other Ethereum 2.0 clients.
- **October 2019**: Public, multi-client testnet with user-facing functionality.
- **January 2020**: Production Beacon Chain testnet.
## Usage
Lighthouse consists of multiple binaries:
- [`beacon_node/` ](beacon_node/ ): produces and verifies blocks from the P2P
connected validators and the P2P network. Provides an API for external services to
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
**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.
2018-10-03 08:37:28 +00:00
2019-06-25 04:02:19 +00:00
First, clone this repository, [setup a development
environment](docs/installation.md) and navigate to the root directory of this repository.
2018-10-31 11:37:23 +00:00
2019-06-25 04:02:19 +00:00
Then, run `$ cargo build --all --release` and navigate to the `target/release`
2019-07-04 05:24:36 +00:00
directory and follow the steps:
2018-10-03 08:37:28 +00:00
2019-06-25 04:02:19 +00:00
#### 1. Generate Validator Keys
2018-10-03 08:37:28 +00:00
2019-06-25 04:02:19 +00:00
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
2019-07-04 05:05:57 +00:00
In another terminal window, start another boot that will connect to the
2019-06-25 04:02:19 +00:00
running node.
2019-07-04 05:05:57 +00:00
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.
2019-06-25 04:02:19 +00:00
```
2019-07-04 05:24:36 +00:00
$ ./beacon_node -r --boot-nodes < boot-node-ENR > --listen-address 127.0.0.1 --port 9001 --datadir /tmp/.lighthouse
2019-06-25 04:02:19 +00:00
```
2019-07-04 05:05:57 +00:00
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` .
2019-06-25 04:02:19 +00:00
2019-07-04 05:24:36 +00:00
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.
2019-07-04 05:05:57 +00:00
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.
2019-06-25 04:02:19 +00:00
#### 4. Start a Validator Client
In a third terminal window, start a validator client:
```
2019-07-30 09:40:45 +00:00
$ ./validator_client
2019-06-25 04:02:19 +00:00
```
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
2019-02-14 01:09:18 +00:00
- [About Lighthouse ](docs/lighthouse.md ): Goals, Ideology and Ethos surrounding
this implementation.
- [What is Ethereum Serenity ](docs/serenity.md ): an introduction to Ethereum Serenity.
2019-05-01 05:14:51 +00:00
- [Lighthouse Technical Documentation ](http://lighthouse-docs.sigmaprime.io/ ): The Rust generated documentation, updated regularly.
2019-02-14 01:09:18 +00:00
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
[company website ](https://sigmaprime.io ).
2018-10-03 08:37:28 +00:00
2019-06-25 04:02:19 +00:00
## Directory Structure
2019-02-28 13:18:53 +00:00
2019-02-28 13:25:11 +00:00
- [`beacon_node/` ](beacon_node/ ): the "Beacon Node" binary and crates exclusively
2019-02-28 13:18:53 +00:00
associated with it.
2019-03-01 02:10:50 +00:00
- [`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` ).
2019-02-28 13:25:11 +00:00
- [`eth2/` ](eth2/ ): Crates containing common logic across the Lighthouse project. For
2019-03-01 02:10:50 +00:00
example: Ethereum 2.0 types ([`BeaconBlock`](eth2/types/src/beacon_block.rs), [`BeaconState` ](eth2/types/src/beacon_state.rs ), etc) and
2019-02-28 13:18:53 +00:00
SimpleSerialize (SSZ).
2019-03-01 02:10:50 +00:00
- [`protos/` ](protos/ ): protobuf/gRPC definitions that are common across the Lighthouse project.
2019-02-28 13:25:11 +00:00
- [`validator_client/` ](validator_client/ ): the "Validator Client" binary and crates exclusively
2019-02-28 13:18:53 +00:00
associated with it.
Update to frozen spec ❄️ (v0.8.1) (#444)
* types: first updates for v0.8
* state_processing: epoch processing v0.8.0
* state_processing: block processing v0.8.0
* tree_hash_derive: support generics in SignedRoot
* types v0.8: update to use ssz_types
* state_processing v0.8: use ssz_types
* ssz_types: add bitwise methods and from_elem
* types: fix v0.8 FIXMEs
* ssz_types: add bitfield shift_up
* ssz_types: iterators and DerefMut for VariableList
* types,state_processing: use VariableList
* ssz_types: fix BitVector Decode impl
Fixed a typo in the implementation of ssz::Decode for BitVector, which caused it
to be considered variable length!
* types: fix test modules for v0.8 update
* types: remove slow type-level arithmetic
* state_processing: fix tests for v0.8
* op_pool: update for v0.8
* ssz_types: Bitfield difference length-independent
Allow computing the difference of two bitfields of different lengths.
* Implement compact committee support
* epoch_processing: committee & active index roots
* state_processing: genesis state builder v0.8
* state_processing: implement v0.8.1
* Further improve tree_hash
* Strip examples, tests from cached_tree_hash
* Update TreeHash, un-impl CachedTreeHash
* Update bitfield TreeHash, un-impl CachedTreeHash
* Update FixedLenVec TreeHash, unimpl CachedTreeHash
* Update update tree_hash_derive for new TreeHash
* Fix TreeHash, un-impl CachedTreeHash for ssz_types
* Remove fixed_len_vec, ssz benches
SSZ benches relied upon fixed_len_vec -- it is easier to just delete
them and rebuild them later (when necessary)
* Remove boolean_bitfield crate
* Fix fake_crypto BLS compile errors
* Update ef_tests for new v.8 type params
* Update ef_tests submodule to v0.8.1 tag
* Make fixes to support parsing ssz ef_tests
* `compact_committee...` to `compact_committees...`
* Derive more traits for `CompactCommittee`
* Flip bitfield byte-endianness
* Fix tree_hash for bitfields
* Modify CLI output for ef_tests
* Bump ssz crate version
* Update ssz_types doc comment
* Del cached tree hash tests from ssz_static tests
* Tidy SSZ dependencies
* Rename ssz_types crate to eth2_ssz_types
* validator_client: update for v0.8
* ssz_types: update union/difference for bit order swap
* beacon_node: update for v0.8, EthSpec
* types: disable cached tree hash, update min spec
* state_processing: fix slot bug in committee update
* tests: temporarily disable fork choice harness test
See #447
* committee cache: prevent out-of-bounds access
In the case where we tried to access the committee of a shard that didn't have a committee in the
current epoch, we were accessing elements beyond the end of the shuffling vector and panicking! This
commit adds a check to make the failure safe and explicit.
* fix bug in get_indexed_attestation and simplify
There was a bug in our implementation of get_indexed_attestation whereby
incorrect "committee indices" were used to index into the custody bitfield. The
bug was only observable in the case where some bits of the custody bitfield were
set to 1. The implementation has been simplified to remove the bug, and a test
added.
* state_proc: workaround for compact committees bug
https://github.com/ethereum/eth2.0-specs/issues/1315
* v0.8: updates to make the EF tests pass
* Remove redundant max operation checks.
* Always supply both messages when checking attestation signatures -- allowing
verification of an attestation with no signatures.
* Swap the order of the fork and domain constant in `get_domain`, to match
the spec.
* rustfmt
* ef_tests: add new epoch processing tests
* Integrate v0.8 into master (compiles)
* Remove unused crates, fix clippy lints
* Replace v0.6.3 tags w/ v0.8.1
* Remove old comment
* Ensure lmd ghost tests only run in release
* Update readme
2019-07-30 02:44:51 +00:00
- [`tests/` ](tests/ ): code specific to testing, most notably contains the
Ethereum Foundation test vectors.
2019-02-28 13:18:53 +00:00
2019-06-25 04:02:19 +00:00
## Contributing
**Lighthouse welcomes contributors.**
2019-02-14 01:09:18 +00:00
If you are looking to contribute, please head to our
[onboarding documentation ](https://github.com/sigp/lighthouse/blob/master/docs/onboarding.md ).
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!
2018-07-06 07:54:07 +00:00
## Contact
2019-07-31 21:53:30 +00:00
The best place for discussion is the [Lighthouse Discord
server](https://discord.gg/cyAszAh). Alternatively, you may use the
[sigp/lighthouse gitter ](https://gitter.im/sigp/lighthouse ).
2018-10-03 08:37:28 +00:00
2019-06-25 04:02:19 +00:00
## Donations
2018-12-19 01:54:31 +00:00
2019-06-25 04:02:19 +00:00
If you support the cause, we accept donations to help fund development:
2018-12-19 01:54:31 +00:00
2019-05-27 00:24:44 +00:00
`0x25c4a76E7d118705e7Ea2e9b7d8C59930d8aCD3b` (donation.sigmaprime.eth)
