diff --git a/book/.gitignore b/book/.gitignore new file mode 100644 index 000000000..7585238ef --- /dev/null +++ b/book/.gitignore @@ -0,0 +1 @@ +book diff --git a/book/book.toml b/book/book.toml new file mode 100644 index 000000000..829c7b99c --- /dev/null +++ b/book/book.toml @@ -0,0 +1,6 @@ +[book] +authors = ["Paul Hauner"] +language = "en" +multilingual = false +src = "src" +title = "Lighthouse" diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md new file mode 100644 index 000000000..e08af247c --- /dev/null +++ b/book/src/SUMMARY.md @@ -0,0 +1,7 @@ +# Summary + +* [Introduction](./intro.md) +* [Development Environment](./setup.md) +* [Testnets](./testnets.md) + * [Simple local testnet](./testnets.md) + * [Interop](./interop.md) diff --git a/book/src/interop.md b/book/src/interop.md new file mode 100644 index 000000000..79d4a1376 --- /dev/null +++ b/book/src/interop.md @@ -0,0 +1,70 @@ +# Lighthouse Interop Guide + +This guide is intended for other Ethereum 2.0 client developers performing +inter-operability testing with Lighthouse. + +To allow for faster iteration cycles without the "merging to master" overhead, +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.** + +## Environment + +All that is required for inter-op is a built and tested [development +environment](setup). 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. + +## Interop Procedure + +The following scenarios are documented: + +- [Starting a "quick-start" beacon node](#quick-start-beacon-node) from a + `(validator_count, genesis)` tuple. +- [Starting a validator client](#validator-client) with `n` interop keypairs. +- [Starting a node from a genesis state file](#starting-from-a-genesis-file). +- [Exporting a genesis state file](#exporting-a-genesis-file) from a running Lighthouse + node. + +First, setup a Lighthouse development environment and navigate to the +`target/release` directory (this is where the binaries are located). + +#### Quick-start Beacon Node + + +To start the node (each time creating a fresh database and configuration in +`~/.lighthouse`), use: + +``` +$ ./beacon_node testnet -f quick 8 1567222226 +``` + +>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. + +#### Validator Client + +**TODO** + +#### Starting from a genesis file + +**TODO** + +#### Exporting a genesis file + +**TODO** diff --git a/book/src/intro.md b/book/src/intro.md new file mode 100644 index 000000000..f290b7e40 --- /dev/null +++ b/book/src/intro.md @@ -0,0 +1,47 @@ +# Lighthouse Documentation + +[![Build Status]][Build Link] [![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 Link]: https://discord.gg/cyAszAh +[Doc Status]:https://img.shields.io/badge/rust--docs-master-orange +[Doc Link]: http://lighthouse-docs.sigmaprime.io/ + +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. + +It is written in Rust, maintained by Sigma Prime and funded by the Ethereum +Foundation, Consensys and other individuals and organisations. + +## Developer Resources + +Documentation is provided for **researchers and developers** working on +Ethereum 2.0 and assumes prior knowledge on the topic. + +- Get started with [development environment setup](setup.html). +- [Run a simple testnet](testnets.html) in Only Three CLI Commands™. +- Read about our interop workflow. +- API? + +## Release + +Ethereum 2.0 is not fully specified or implemented and as such, Lighthouse is +still **under development**. + +We are on-track to provide a public, multi-client testnet in late-2019 and an +initial production-grade blockchain in 2020. + +## Features + +Lighthouse has been in development since mid-2018 and has an extensive feature +set: + +- Libp2p networking stack, featuring Discovery v5. +- Optimized `BeaconChain` state machine, up-to-date and + passing all tests. +- RESTful HTTP API. +- Documented and feature-rich CLI interface. +- Capable of running small, local testnets with 250ms slot times. +- Detailed metrics exposed in the Prometheus format. diff --git a/book/src/setup.md b/book/src/setup.md new file mode 100644 index 000000000..e53ca93d8 --- /dev/null +++ b/book/src/setup.md @@ -0,0 +1,65 @@ +# Development Environment Setup + +Follow this guide to get a Lighthouse development environment up-and-running. + +See the [Quick instructions](#quick-instructions) for a summary or the +[Detailed instructions](#detailed-instructions) for clarification. + +## Quick instructions + +1. Install Rust + Cargo with [rustup](https://rustup.rs/). +1. Install build dependencies using your package manager. + - `$ clang protobuf libssl-dev cmake git-lfs` + - Ensure [git-lfs](https://git-lfs.github.com/) is installed with `git lfs + install`. +1. Clone the [sigp/lighthouse](https://github.com/sigp/lighthouse), ensuring to + **initialize submodules**. +1. In the root of the repo, run the tests with `cargo test --all --release`. +1. Then, build the binaries with `cargo build --all --release`. +1. Lighthouse is now fully built and tested. + +_Note: first-time compilation may take several minutes._ + +## Detailed instructions + +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"`. diff --git a/book/src/testnets.md b/book/src/testnets.md new file mode 100644 index 000000000..c07797ba0 --- /dev/null +++ b/book/src/testnets.md @@ -0,0 +1,64 @@ +# Simple Local Testnet + +You can setup a local, two-node testnet in **Only Three CLI Commands™**. + +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 a validator client: **TODO** +1. Start another node `$ ./beacon_node -b 10 testnet -f bootstrap http://localhost:5052` + +_Repeat #3 to add more nodes._ + +## Detailed instructions + +First, setup a Lighthouse development environment and navigate to the +`target/release` directory (this is where the binaries are located). + +## Starting the Beacon Node + +Start a new node (creating a fresh database and configuration in `~/.lighthouse`), using: + +``` +$ ./beacon_node testnet -f recent 8 +``` + +> The `-f` flag ignores any existing database or configuration, backing them up +before re-initializing. `8` is number of validators with deposits in the +genesis state. +> +> See `$ ./beacon_node testnet recent --help` for more configuration options, +including `minimal`/`mainnet` specification. + +## Starting the Validator Client + +**TODO** + +## Adding another Beacon Node + +You may connect another (non-validating) node to your local network using the +lighthouse `bootstrap` command. + +In a new terminal terminal, run: + + +``` +$ ./beacon_node -b 10 testnet -r bootstrap http://localhost:5052 +``` + +> The `-b` (or `--port-bump`) increases all the listening TCP/UDP ports of the +new node to `10` higher. Your first node's HTTP server was at TCP `5052` but +this one will be at `5062`. +> +> The `-r` flag creates a new data directory in your home with a random string +appended, to avoid conflicting with any other running node. +> +> The HTTP address is the API of the first node. The new node will download +configuration via HTTP before starting sync via libp2p.