Update readme
This commit is contained in:
parent
0f7867096a
commit
d87c84b5c5
240
README.md
240
README.md
@ -1,4 +1,6 @@
|
||||
# Lighthouse: an Ethereum Serenity client
|
||||
# Lighthouse: Ethereum 2.0
|
||||
|
||||
An open-source Ethereum 2.0 client, written in Rust and maintained by Sigma Prime.
|
||||
|
||||
[![Build Status]][Build Link] [![Doc Status]][Doc Link] [![Gitter Badge]][Gitter Link]
|
||||
|
||||
@ -9,24 +11,119 @@
|
||||
[Doc Status]: https://img.shields.io/badge/docs-master-blue.svg
|
||||
[Doc Link]: http://lighthouse-docs.sigmaprime.io/
|
||||
|
||||
A work-in-progress, open-source implementation of the Serenity Beacon
|
||||
Chain, maintained by Sigma Prime.
|
||||
## Overview
|
||||
|
||||
The "Serenity" project is also known as "Ethereum 2.0" or "Shasper".
|
||||
Lighthouse is:
|
||||
|
||||
## Lighthouse Client
|
||||
- Fully open-source, licensed under Apache 2.0.
|
||||
- Security-focussed, fuzzing has begun and security reviews are planned
|
||||
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
|
||||
Ethereum Foundation, Consensys and private individuals.
|
||||
- Actively working to promote an inter-operable, multi-client Ethereum 2.0.
|
||||
|
||||
Lighthouse is an open-source Ethereum Serenity client that is currently under
|
||||
development. Designed as a Serenity-only client, Lighthouse will not
|
||||
re-implement the existing proof-of-work protocol. Maintaining a forward-focus
|
||||
on Ethereum Serenity ensures that Lighthouse avoids reproducing the high-quality
|
||||
work already undertaken by existing projects. As such, Lighthouse will connect
|
||||
to existing clients, such as
|
||||
[Geth](https://github.com/ethereum/go-ethereum) or
|
||||
[Parity-Ethereum](https://github.com/paritytech/parity-ethereum), via RPC to enable
|
||||
present-Ethereum functionality.
|
||||
|
||||
### Further Reading
|
||||
## 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:
|
||||
|
||||
- Specification `v0.6.3` implemented, optimized and passing test vectors.
|
||||
- Rust-native libp2p integrated, with Gossipsub.
|
||||
- Discv5 (P2P discovery mechanism) integration started.
|
||||
- Metrics via Prometheus.
|
||||
- Basic gRPC API, soon to be replaced with RESTful HTTP/JSON.
|
||||
|
||||
### Roadmap
|
||||
|
||||
- **July 2019**: `lighthouse-0.0.1` release: A stable testnet for developers with a useful
|
||||
HTTP API.
|
||||
- **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.
|
||||
|
||||
First, clone this repository, [setup a development
|
||||
environment](docs/installation.md) and navigate to the root directory of this repository.
|
||||
|
||||
Then, run `$ cargo build --all --release` and navigate to the `target/release`
|
||||
directory.
|
||||
|
||||
#### 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 node that will connect to the
|
||||
running node.
|
||||
|
||||
```
|
||||
$ ./beacon_node -r --boot-nodes /ip4/127.0.0.1/tcp/9000 --listen-address /ip4/127.0.0.1/tcp/9001
|
||||
```
|
||||
|
||||
#### 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.
|
||||
@ -37,7 +134,7 @@ 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).
|
||||
|
||||
### Directory Structure
|
||||
## Directory Structure
|
||||
|
||||
- [`beacon_node/`](beacon_node/): the "Beacon Node" binary and crates exclusively
|
||||
associated with it.
|
||||
@ -50,112 +147,10 @@ If you'd like some background on Sigma Prime, please see the [Lighthouse Update
|
||||
- [`validator_client/`](validator_client/): the "Validator Client" binary and crates exclusively
|
||||
associated with it.
|
||||
|
||||
### Components
|
||||
|
||||
The following list describes some of the components actively under development
|
||||
by the team:
|
||||
## Contributing
|
||||
|
||||
- **BLS cryptography**: Lighthouse presently use the [Apache
|
||||
Milagro](https://milagro.apache.org/) cryptography library to create and
|
||||
verify BLS aggregate signatures. BLS signatures are core to Serenity as they
|
||||
allow the signatures of many validators to be compressed into a constant 96
|
||||
bytes and efficiently verified. The Lighthouse project is presently
|
||||
maintaining its own [BLS aggregates
|
||||
library](https://github.com/sigp/signature-schemes), gratefully forked from
|
||||
[@lovesh](https://github.com/lovesh).
|
||||
- **DoS-resistant block pre-processing**: Processing blocks in proof-of-stake
|
||||
is more resource intensive than proof-of-work. As such, clients need to
|
||||
ensure that bad blocks can be rejected as efficiently as possible. At
|
||||
present, blocks having 10 million ETH staked can be processed in 0.006
|
||||
seconds, and invalid blocks are rejected even more quickly. See
|
||||
[issue #103](https://github.com/ethereum/beacon_chain/issues/103) on
|
||||
[ethereum/beacon_chain](https://github.com/ethereum/beacon_chain).
|
||||
- **P2P networking**: Serenity will likely use the [libp2p
|
||||
framework](https://libp2p.io/). Lighthouse is working alongside
|
||||
[Parity](https://www.parity.io/) to ensure
|
||||
[libp2p-rust](https://github.com/libp2p/rust-libp2p) is fit-for-purpose.
|
||||
- **Validator duties** : The project involves development of "validator
|
||||
services" for users who wish to stake ETH. To fulfill their duties,
|
||||
validators require a consistent view of the chain and the ability to vote
|
||||
upon blocks from both shard and beacon chains.
|
||||
- **New serialization formats**: Lighthouse is working alongside researchers
|
||||
from the Ethereum Foundation to develop *simpleserialize* (SSZ), a
|
||||
purpose-built serialization format for sending information across a network.
|
||||
Check out the [SSZ
|
||||
implementation](https://github.com/ethereum/eth2.0-specs/blob/00aa553fee95963b74fbec84dbd274d7247b8a0e/specs/simple-serialize.md)
|
||||
and this
|
||||
[research](https://github.com/sigp/serialization_sandbox/blob/report/report/serialization_report.md)
|
||||
on serialization formats for more information.
|
||||
- **Fork-choice**: The current fork choice rule is
|
||||
[*LMD Ghost*](https://vitalik.ca/general/2018/12/05/cbc_casper.html#lmd-ghost),
|
||||
which effectively takes the latest messages and forms the canonical chain using
|
||||
the [GHOST](https://eprint.iacr.org/2013/881.pdf) mechanism.
|
||||
- **Efficient state transition logic**: State transition logic governs
|
||||
updates to the validator set as validators log in/out, penalizes/rewards
|
||||
validators, rotates validators across shards, and implements other core tasks.
|
||||
- **Fuzzing and testing environments**: Implementation of lab environments with
|
||||
continuous integration (CI) workflows, providing automated security analysis.
|
||||
|
||||
In addition to these components we are also working on database schemas, RPC
|
||||
frameworks, specification development, database optimizations (e.g.,
|
||||
bloom-filters), and tons of other interesting stuff (at least we think so).
|
||||
|
||||
### Running
|
||||
|
||||
**NOTE: The cryptography libraries used in this implementation are
|
||||
experimental. As such all cryptography is assumed to be insecure.**
|
||||
|
||||
This code-base is still very much under-development and does not provide any
|
||||
user-facing functionality. For developers and researchers, there are several
|
||||
tests and benchmarks which may be of interest.
|
||||
|
||||
A few basic steps are needed to get set up:
|
||||
|
||||
1. Install [rustup](https://rustup.rs/). It's a toolchain manager for Rust (Linux | macOS | Windows). For installation, download the script with `$ curl -f https://sh.rustup.rs > rustup.sh`, review its content (e.g. `$ less ./rustup.sh`) and run the script `$ ./rustup.sh` (you may need to change the permissions to allow execution, i.e. `$ chmod +x rustup.sh`)
|
||||
2. (Linux & MacOS) To configure your current shell run: `$ source $HOME/.cargo/env`
|
||||
3. Use the command `rustup show` to get information about the Rust installation. You should see that the
|
||||
active toolchain is the stable version.
|
||||
4. Run `rustc --version` to check the installation and version of rust.
|
||||
- Updates can be performed using` rustup update` .
|
||||
5. Install build dependencies (Arch packages are listed here, your distribution will likely be similar):
|
||||
- `clang`: required by RocksDB.
|
||||
- `protobuf`: required for protobuf serialization (gRPC).
|
||||
- `cmake`: required for building protobuf
|
||||
6. Navigate to the working directory.
|
||||
7. Run the test by using command `cargo test --all`. By running, it will pass all the required test cases.
|
||||
If you are doing it for the first time, then you can grab a coffee in the meantime. Usually, it takes time
|
||||
to build, compile and pass all test cases. If there is no error then it means everything is working properly
|
||||
and it's time to get your hands dirty.
|
||||
In case, if there is an error, then please raise the [issue](https://github.com/sigp/lighthouse/issues).
|
||||
We will help you.
|
||||
8. As an alternative to, or instead of the above step, you may also run benchmarks by using
|
||||
the command `cargo bench --all`
|
||||
|
||||
##### Note:
|
||||
Lighthouse presently runs on Rust `stable`, however, benchmarks currently require the
|
||||
`nightly` version.
|
||||
|
||||
##### 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's "build-dependencies" section to
|
||||
`protoc-grpcio = "<=0.3.0"`.
|
||||
|
||||
### Contributing
|
||||
|
||||
**Lighthouse welcomes contributors with open-arms.**
|
||||
|
||||
If you would like to learn more about Ethereum Serenity and/or
|
||||
[Rust](https://www.rust-lang.org/), we are more than happy to on-board you
|
||||
and assign you some tasks. We aim to be as accepting and understanding as
|
||||
possible; we are more than happy to up-skill contributors in exchange for their
|
||||
assistance with the project.
|
||||
|
||||
Alternatively, if you are an ETH/Rust veteran, we'd love your input. We're
|
||||
always looking for the best way to implement things and welcome all
|
||||
respectful criticisms.
|
||||
**Lighthouse welcomes contributors.**
|
||||
|
||||
If you are looking to contribute, please head to our
|
||||
[onboarding documentation](https://github.com/sigp/lighthouse/blob/master/docs/onboarding.md).
|
||||
@ -170,10 +165,9 @@ your support!
|
||||
## Contact
|
||||
|
||||
The best place for discussion is the [sigp/lighthouse gitter](https://gitter.im/sigp/lighthouse).
|
||||
Ping @paulhauner or @AgeManning to get the quickest response.
|
||||
|
||||
# Donations
|
||||
## Donations
|
||||
|
||||
If you support the cause, we could certainly use donations to help fund development:
|
||||
If you support the cause, we accept donations to help fund development:
|
||||
|
||||
`0x25c4a76E7d118705e7Ea2e9b7d8C59930d8aCD3b` (donation.sigmaprime.eth)
|
||||
|
37
docs/installation.md
Normal file
37
docs/installation.md
Normal file
@ -0,0 +1,37 @@
|
||||
# Development Environment Setup
|
||||
|
||||
A few basic steps are needed to get set up (skip to #5 if you already have Rust
|
||||
installed):
|
||||
|
||||
1. Install [rustup](https://rustup.rs/). It's a toolchain manager for Rust (Linux | macOS | Windows). For installation, download the script with `$ curl -f https://sh.rustup.rs > rustup.sh`, review its content (e.g. `$ less ./rustup.sh`) and run the script `$ ./rustup.sh` (you may need to change the permissions to allow execution, i.e. `$ chmod +x rustup.sh`)
|
||||
2. (Linux & MacOS) To configure your current shell run: `$ source $HOME/.cargo/env`
|
||||
3. Use the command `rustup show` to get information about the Rust installation. You should see that the
|
||||
active toolchain is the stable version.
|
||||
4. Run `rustc --version` to check the installation and version of rust.
|
||||
- Updates can be performed using` rustup update` .
|
||||
5. Install build dependencies (Arch packages are listed here, your distribution will likely be similar):
|
||||
- `clang`: required by RocksDB.
|
||||
- `protobuf`: required for protobuf serialization (gRPC).
|
||||
- `cmake`: required for building protobuf
|
||||
6. Navigate to the working directory.
|
||||
7. Run the test by using command `cargo test --all`. By running, it will pass all the required test cases.
|
||||
If you are doing it for the first time, then you can grab a coffee in the meantime. Usually, it takes time
|
||||
to build, compile and pass all test cases. If there is no error then it means everything is working properly
|
||||
and it's time to get your hands dirty.
|
||||
In case, if there is an error, then please raise the [issue](https://github.com/sigp/lighthouse/issues).
|
||||
We will help you.
|
||||
8. As an alternative to, or instead of the above step, you may also run benchmarks by using
|
||||
the command `cargo bench --all`
|
||||
|
||||
## Notes:
|
||||
|
||||
Lighthouse targets Rust `stable` but _should_ run on `nightly`.
|
||||
|
||||
### 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's "build-dependencies" section to
|
||||
`protoc-grpcio = "<=0.3.0"`.
|
Loading…
Reference in New Issue
Block a user