Ethereum consensus client in Rust
Go to file
Luke Anderson 0052ea711e First RESTful HTTP API (#399)
* Added generated code for REST API.
 - Created a new crate rest_api, which will adapt the openapi generated code to Lighthouse
 - Committed automatically generated code from openapi-generator-cli (via docker). Should hopfully not have to modify this at all, and do all changes in the rest_api crate.

* Removed openapi generated code, because it was the rust client, not the rust server.

* Added the correct rust-server code, automatically generated from openapi.

* Added generated code for REST API.
 - Created a new crate rest_api, which will adapt the openapi generated code to Lighthouse
 - Committed automatically generated code from openapi-generator-cli (via docker). Should hopfully not have to modify this at all, and do all changes in the rest_api crate.

* Removed openapi generated code, because it was the rust client, not the rust server.

* Added the correct rust-server code, automatically generated from openapi.

* Included REST API in configuratuion.
 - Started adding the rest_api into the beacon node's dependencies.
 - Set up configuration file for rest_api and integrated into main client config
 - Added CLI flags for REST API.

* Futher work on REST API.
 - Adding the dependencies to rest_api crate
 - Created a skeleton BeaconNodeService, which will handle /node requests.
 - Started the rest_api server definition, with the high level request handling logic.

* Added generated code for REST API.
 - Created a new crate rest_api, which will adapt the openapi generated code to Lighthouse
 - Committed automatically generated code from openapi-generator-cli (via docker). Should hopfully not have to modify this at all, and do all changes in the rest_api crate.

* Removed openapi generated code, because it was the rust client, not the rust server.

* Added the correct rust-server code, automatically generated from openapi.

* Included REST API in configuratuion.
 - Started adding the rest_api into the beacon node's dependencies.
 - Set up configuration file for rest_api and integrated into main client config
 - Added CLI flags for REST API.

* Futher work on REST API.
 - Adding the dependencies to rest_api crate
 - Created a skeleton BeaconNodeService, which will handle /node requests.
 - Started the rest_api server definition, with the high level request handling logic.

* WIP: Restructured REST API to use hyper_router and separate services.

* WIP: Fixing rust for REST API

* WIP: Fixed up many bugs in trying to get router to compile.

* WIP: Got the beacon_node to compile with the REST changes

* Basic API works!
 - Changed CLI flags from rest-api* to api*
 - Fixed port cli flag
 - Tested, works over HTTP

* WIP: Moved things around so that we can get state inside the handlers.

* WIP: Significant API updates.
 - Started writing a macro for getting the handler functions.
 - Added the BeaconChain into the type map, gives stateful access to the beacon state.
 - Created new generic error types (haven't figured out yet), to reduce code duplication.
 - Moved common stuff into lib.rs

* WIP: Factored macros, defined API result and error.
 - did more logging when creating HTTP responses
 - Tried moving stuff into macros, but can't get macros in macros to compile.
 - Pulled out a lot of placeholder code.

* Fixed macros so that things compile.

* Cleaned up code.
 - Removed unused imports
 - Removed comments
 - Addressed all compiler warnings.
 - Ran cargo fmt.

* Removed auto-generated OpenAPI code.

* Addressed Paul's suggestions.
 - Fixed spelling mistake
 - Moved the simple macros into functions, since it doesn't make sense for them to be macros.
 - Removed redundant code & inclusions.

* Removed redundant validate_request function.

* Included graceful shutdown in Hyper server.

* Fixing the dropped exit_signal, which prevented the API from starting.

* Wrapped the exit signal, to get an API shutdown log line.
2019-07-31 18:29:41 +10:00
.github Add PR and issue templates 2018-10-14 14:51:59 +11:00
account_manager Update to frozen spec ❄️ (v0.8.1) (#444) 2019-07-30 12:44:51 +10:00
beacon_node First RESTful HTTP API (#399) 2019-07-31 18:29:41 +10:00
docs Spec. for REST API (#455) 2019-07-29 10:01:56 +10:00
eth2 Add cargo fmt to .travis.yml (#474) 2019-07-31 14:45:09 +10:00
protos Fix lots of typos. 2019-07-26 15:26:06 -04:00
tests/ef_tests Add v0.8 genesis tests (#466) 2019-07-30 17:02:38 +10:00
validator_client add logging functionality for aligning key value pairs after message (#461) 2019-07-31 09:06:53 +10:00
.editorconfig Add editorconfig template 2019-03-11 15:09:57 +11:00
.gitignore Add benches, examples for cached hashing. 2019-04-28 11:38:32 +10:00
.gitlab-ci.yml ci: run EF tests that require fake crypto 2019-06-17 17:22:37 +10:00
.gitmodules Add basic code for new testing format 2019-05-13 17:56:46 +10:00
.travis.yml Add cargo fmt to .travis.yml (#474) 2019-07-31 14:45:09 +10:00
Cargo.toml First RESTful HTTP API (#399) 2019-07-31 18:29:41 +10:00
CONTRIBUTING.md Revert "Merge pull request #200 from sigp/new-structure" 2019-02-14 12:09:18 +11:00
Dockerfile Updated docker file to include the git-lfs installation. 2019-06-17 15:25:25 +10:00
LICENSE Update License to Apache 2.0 2019-04-15 16:47:35 +10:00
README.md Update README.md 2019-07-30 10:40:45 +01:00

Lighthouse: Ethereum 2.0

An open-source Ethereum 2.0 client, written in Rust and maintained by Sigma Prime.

Build Status Doc Status Gitter Badge

Overview

Lighthouse is:

  • Fully open-source, licensed under Apache 2.0.
  • Security-focused, fuzzing has begun and security reviews are planned for late-2019.
  • Built in Rust, 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.

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.8.1 implemented, optimized and passing test vectors.
  • Rust-native libp2p with Gossipsub and Discv5.
  • Metrics via Prometheus.
  • Basic gRPC API, soon to be replaced with RESTful HTTP/JSON.

Roadmap

  • Early-September 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/: 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/: connects to a beacon_node and performs the role of a proof-of-stake validator.
  • 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 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 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

If you'd like some background on Sigma Prime, please see the Lighthouse Update #00 blog post or the company website.

Directory Structure

  • beacon_node/: the "Beacon Node" binary and crates exclusively associated with it.
  • 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/: Crates containing common logic across the Lighthouse project. For example: Ethereum 2.0 types (BeaconBlock, BeaconState, etc) and SimpleSerialize (SSZ).
  • protos/: protobuf/gRPC definitions that are common across the Lighthouse project.
  • validator_client/: the "Validator Client" binary and crates exclusively associated with it.
  • tests/: code specific to testing, most notably contains the Ethereum Foundation test vectors.

Contributing

Lighthouse welcomes contributors.

If you are looking to contribute, please head to our onboarding documentation.

If you'd like to contribute, try having a look through the open issues (tip: look for the good first issue tag) and ping us on the gitter channel. We need your support!

Contact

The best place for discussion is the sigp/lighthouse gitter.

Donations

If you support the cause, we accept donations to help fund development:

0x25c4a76E7d118705e7Ea2e9b7d8C59930d8aCD3b (donation.sigmaprime.eth)