From 698af6d7ecd6eb252bc5e85530e7bfec1bdd1a4e Mon Sep 17 00:00:00 2001 From: Paul Hauner Date: Fri, 10 Jan 2020 13:56:48 +1100 Subject: [PATCH] Update docs for testnet3 (#773) * Start docker docs * Add progress * Update docker.md * Add note about geth syncing * Fix env to use geth * Update docs * Remove sigp goerli node * Change text about eth1 syncing * Address comments from @pscott * Add links to beaconcha.in * Add instructions for starting an eth1 node * Fix typo * Re-organise Syncing log --- README.md | 4 +- beacon_node/client/src/notifier.rs | 4 +- beacon_node/src/cli.rs | 2 +- book/src/SUMMARY.md | 2 + book/src/become-a-validator-docker.md | 67 +++++++++++++ book/src/become-a-validator-source.md | 132 ++++++++++++++++++++++++ book/src/become-a-validator.md | 138 ++++---------------------- book/src/docker.md | 78 +++++++++++++-- 8 files changed, 297 insertions(+), 130 deletions(-) create mode 100644 book/src/become-a-validator-docker.md create mode 100644 book/src/become-a-validator-source.md diff --git a/README.md b/README.md index 20f427f4f8..21e716db32 100644 --- a/README.md +++ b/README.md @@ -12,8 +12,8 @@ An open-source Ethereum 2.0 client, written in Rust and maintained by Sigma Prim [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 +[Swagger Badge]: https://img.shields.io/badge/testnet--explorer-beaconcha.in-informational +[Swagger Link]: https://lighthouse-testnet3.beaconcha.in/ [Documentation](http://lighthouse-book.sigmaprime.io/) diff --git a/beacon_node/client/src/notifier.rs b/beacon_node/client/src/notifier.rs index 17db1537ee..e0c97c93c7 100644 --- a/beacon_node/client/src/notifier.rs +++ b/beacon_node/client/src/notifier.rs @@ -122,9 +122,9 @@ pub fn spawn_notifier( log, "Syncing"; "peers" => peer_count_pretty(connected_peer_count), - "est_time" => estimated_time_pretty(speedo.estimated_time_till_slot(current_slot)), + "distance" => distance, "speed" => sync_speed_pretty(speedo.slots_per_second()), - "distance" => distance + "est_time" => estimated_time_pretty(speedo.estimated_time_till_slot(current_slot)), ); return Ok(()); diff --git a/beacon_node/src/cli.rs b/beacon_node/src/cli.rs index de0f7ff29e..bf40b83b5d 100644 --- a/beacon_node/src/cli.rs +++ b/beacon_node/src/cli.rs @@ -189,7 +189,7 @@ pub fn cli_app<'a, 'b>() -> App<'a, 'b> { .value_name("HTTP-ENDPOINT") .help("Specifies the server for a web3 connection to the Eth1 chain.") .takes_value(true) - .default_value("https://goerli.public.sigp.io") + .default_value("http://127.0.0.1:8545") ) .arg( Arg::with_name("slots-per-restore-point") diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 096a572709..8253cd0630 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -2,6 +2,8 @@ * [Introduction](./intro.md) * [Become a Validator](./become-a-validator.md) + * [Using Docker](./become-a-validator-docker.md) + * [Building from Source](./become-a-validator-source.md) * [Installation](./installation.md) * [Docker](./docker.md) * [CLI](./cli.md) diff --git a/book/src/become-a-validator-docker.md b/book/src/become-a-validator-docker.md new file mode 100644 index 0000000000..22649a9306 --- /dev/null +++ b/book/src/become-a-validator-docker.md @@ -0,0 +1,67 @@ +# Become a Validator: Using Docker + +Sigma Prime maintains the +[sigp/lighthouse-docker](https://github.com/sigp/lighthouse-docker) repository +which provides an easy way to run Lighthouse without building the Lighthouse +binary yourself. + +> Note: when you're running the Docker Hub image you're relying upon a +> pre-built binary instead of building from source. If you want the highest +> assurance you're running the _real_ Lighthouse, +> [build the docker image yourself](./docker.md) instead. You'll need some +> experience with docker-compose to integrate your locally built docker image +> with the docker-compose environment. + +### 1. Clone the repository + +Once you have docker-compose +[installed](https://docs.docker.com/compose/install/), clone the +[sigp/lighthouse-docker](https://github.com/sigp/lighthouse-docker) repository. + +```bash +$ git clone https://github.com/sigp/lighthouse-docker +$ cd lighthouse-docker +``` + +### 2. Configure the docker environment + +Then, create a file named `.env` with the following contents (these values are +documented +[here](https://github.com/sigp/lighthouse-docker/blob/master/default.env)): + +```bash +DEBUG_LEVEL=info +START_GETH=true +START_VALIDATOR=true +VALIDATOR_COUNT=1 +VOTING_ETH1_NODE=http://geth:8545 +DEPOSIT_VALUE=3200000000 +``` + +_This `.env` file should live in the `lighthouse-docker` directory alongside the +`docker-compose.yml` file_. + +### 3. Start Lighthouse + +Start the docker-compose environment (you may need to use `sudo`): + +```bash +$ docker-compose up +``` + +> Note: the docker-compose setup includes a fast-synced geth node. You can +> expect the `beacon_node` to log some eth1-related errors whilst the geth node +> boots and becomes synced. This will only happen on the first start of the +> compose environment or if geth loses sync. + +### Installation complete! + +In the next step you'll need to locate your `eth1_deposit_data.rlp` file from +your `.lighthouse/validators` directory. + +The `./lighthouse` directory is in the root of the `lighthouse-docker` +repository. For example, if you ran Step 1 in `/home/karlm/` then you can find +your validator directory in +`/home/karlm/lighthouse-docker/.lighthouse/validators/`. + +You can now go to [Become a Validator: Step 2](become-a-validator.html#2-submit-your-deposit-to-goerli). diff --git a/book/src/become-a-validator-source.md b/book/src/become-a-validator-source.md new file mode 100644 index 0000000000..1e197e2b4a --- /dev/null +++ b/book/src/become-a-validator-source.md @@ -0,0 +1,132 @@ +# Become an Validator: Building from Source + +## 1. Download and install Lighthouse + +If you already have Rust installed, you can install Lighthouse with the +following three commands: + +- `$ git clone https://github.com/sigp/lighthouse.git` +- `$ cd lighthouse` +- `$ make` + +You've completed this step when you can run `$ lighthouse --help` and see the +help menu. + +> - If you're not familiar with Rust or you'd like more detailed instructions, +> see the [Installation Guide](./installation.md) which contains a +> [Troubleshooting](installation.html#troubleshooting) section. + +## 2. Start an Eth1 client + +As Eth2 relies upon the Eth1 chain for validator on-boarding and eventually +Eth1 may use the Eth2 chain as a finality gadget, all Eth2 validators must have +a connection to an Eth1 node. + +We provide instructions for using Geth (this is, by chance, what we ended up +testing with), but you could use any client that implements the JSON RPC via +HTTP. At least for Geth, a fast-synced node is sufficient. + +### Starting Geth + +[Install geth](https://github.com/ethereum/go-ethereum/wiki/Installing-Geth) +and then use this command (or equivalent) to start your Eth1 node: + +```bash +$ geth --goerli --rpc +``` + +## 3. Start your Beacon Node + +The beacon node is the core component of Eth2, it connects to other peers over +the Internet and maintains a view of the chain. + +Start your beacon node with: + +```bash +$ lighthouse beacon --eth1 --http +``` + +Your beacon node has started syncing when you see the following (truncated) +log: + +``` +Dec 09 12:57:18.026 INFO Syncing est_time: 2 hrs ... +``` + +The `distance` value reports the time since eth2 genesis, whilst the `est_time` +reports an estimate of how long it will take your node to become synced. + +It has finished syncing once you see the following (truncated) log: + +``` +Dec 09 12:27:06.010 INFO Synced slot: 16835, ... +``` + +> - The `--http` flag enables the HTTP API for the validator client. +> - The `--eth1` flag tells the beacon node that it should sync with an Ethereum +> 1 node (e.g., Geth). This is only required if you wish to run a validator. + +## 4. Generate your validator key + +Generate new validator BLS keypairs using: + +```shell +$ lighthouse account validator new random +``` + + +You've completed this step when you see the equivalent line: + +``` +Dec 02 21:42:01.337 INFO Generated validator directories count: 1, base_path: "/home/karl/.lighthouse/validators" +``` + +> - This will generate a new _validator directory_ in the `.lighthouse/validators` +> directory. Your validator directory will be identified by it's public key, +> which looks something like `0xc483de...`. You'll need to find this directory +> for the next step. +> - These keys are good enough for the Lighthouse testnet, however they shouldn't +> be considered secure until we've undergone a security audit (planned Jan +> 2020). + +## 5. Start your validator client + +For security reasons, the validator client runs separately to the beacon node. +The validator client stores private keys and signs messages generated by the +beacon node. + +You'll need both your beacon node _and_ validator client running if you want to +stake. + +Start the validator client with: + +```bash +$ lighthouse validator +``` + +The validator client is running and has found your validator keys from step 3 +when you see the following log: + +``` +Dec 09 13:08:59.171 INFO Loaded validator keypair store voting_validators: 1 +Dec 09 13:09:09.000 INFO Awaiting activation slot: 17787, ... +``` + +If your beacon node hasn't finished syncing yet, you'll see some `ERRO` +messages indicating that your node isn't synced yet. It is safest to wait for +your node to sync before moving onto the next step, otherwise your validator +may activate before you're able to produce blocks and attestations. However, it +generally takes 4-8+ hours after deposit for a validator to become active. If +your `est_time` is less than 4 hours, you _should_ be fine to just move to the +next step. After all, this is a testnet and you're only risking Goerli ETH. + +## Installation complete! + +In the next step you'll need to locate your `eth1_deposit_data.rlp` file from +your `.lighthouse/validators` directory. + +The `./lighthouse` directory is in your `$HOME` directory. For example, if +you're in Linux and your user is `karlm`, you can find your validator directory +in `/home/karlm/.lighthouse/validators/`. + +You can now go to [Become a Validator: Step 2](become-a-validator.html#2-submit-your-deposit-to-goerli). diff --git a/book/src/become-a-validator.md b/book/src/become-a-validator.md index 86b6ac7a11..a3d6e14cb4 100644 --- a/book/src/become-a-validator.md +++ b/book/src/become-a-validator.md @@ -1,135 +1,33 @@ # Become an Ethereum 2.0 Validator* ---- - -**The lighthouse testnet is currently down, we expect to raise a new one soon. -See [Lighthouse Update #20](https://lighthouse.sigmaprime.io/update-20.html) -for more information.** - ---- - _* Testnet validator_ Running Lighthouse validator is easy if you're familiar with the terminal. It -runs on Linux, MacOS and Windows. +runs on Linux, MacOS and Windows and we have a Docker work-flow. Before you start, you'll need [Metamask](https://metamask.io/) and 3.2 gETH (Goerli ETH). We recommend the [mudit.blog faucet](https://faucet.goerli.mudit.blog/) for those familiar with Goerli, or [goerli.net](https://goerli.net/) for an overview of the testnet. -### 1. Download and install Lighthouse +## 1. Install and start Lighthouse -If you already have Rust installed, you can install Lighthouse with the -following three commands: +There are two, different ways to install and start a Lighthouse validator: -- `$ git clone https://github.com/sigp/lighthouse.git` -- `$ cd lighthouse` -- `$ make` +- [Using `docker-compose`](./become-a-validator-docker.md): this is the easiest method. +- [Building from source](./become-a-validator-source.md): this is a little more involved, however it + gives a more hands-on experience. -You've completed this step when you can run `$ lighthouse --help` and see the -help menu. +Once you have completed **only one** of these steps, move onto the next step. -> - If you're not familiar with Rust or you'd like more detailed instructions, see -> the [Installation Guide](./installation.md). -> - The [Docker Guide](./docker.md) is great if you have Docker installed and would -> like to avoid installing Rust. - -### 2. Start your Beacon Node - -The beacon node is the core component of Eth2, it connects to other peers over -the Internet and maintains a view of the chain. - -Start your beacon node with: - -```bash -$ lighthouse beacon --eth1 --http -``` - -Your beacon node has started syncing when you see the following (truncated) -log: - -``` -Dec 09 12:57:18.026 INFO Syncing distance: 16837 slots (2 days 8 hrs), ... -``` - -Don't be overly concerned about the "distance" because "est_time" for syncing will be much lower. - -It has finished syncing once you see the following (truncated) log: - -``` -Dec 09 12:27:06.010 INFO Synced slot: 16835, ... -``` - -> - The `--http` flag enables the HTTP API for the validator client. -> - The `--eth1` flag tells the beacon node that it should sync with an Ethereum -> 1 node (e.g., Geth). This is only required if you wish to run a validator. -> - We are hosting a public Goerli archive node and have set this as the -> default, but you can specify your own Eth1 node using the `--eth1-endpoint` -> flag. Presently we require the node to be a full archive node, but we're -> working to [fix](https://github.com/sigp/lighthouse/issues/637) this. - -### 3. Generate your validator key - -Generate new validator BLS keypairs using: - -```shell -$ lighthouse account validator new random -``` - - -You've completed this step when you see the equivalent line: - -``` -Dec 02 21:42:01.337 INFO Generated validator directories count: 1, base_path: "/home/karl/.lighthouse/validators" -``` - -> - This will generate a new _validator directory_ in the `.lighthouse/validators` -> directory. Your validator directory will be identified by it's public key, -> which looks something like `0xc483de...`. You'll need to find this directory -> for the next step. -> - These keys are good enough for the Lighthouse testnet, however they shouldn't -> be considered secure until we've undergone a security audit (planned Jan -> 2020). - -### 4. Start your validator client - -For security reasons, the validator client runs separately to the beacon node. -The validator client stores private keys and signs messages generated by the -beacon node. - -You'll need both your beacon node _and_ validator client running if you want to -stake. - -Start the validator client with: - -```bash -$ lighthouse validator -``` - -The validator client is running and has found your validator keys from step 3 -when you see the following log: - -``` -Dec 09 13:08:59.171 INFO Loaded validator keypair store voting_validators: 1 -Dec 09 13:09:09.000 INFO Awaiting activation slot: 17787, ... -``` - -If your beacon node hasn't finished syncing yet, you'll see some `ERRO` -messages indicating that your node isn't synced yet. It is safest to wait for -your node to sync before moving onto the next step, otherwise your validator -may activate before you're able to produce blocks and attestations. However, it -generally takes 4-8+ hours after deposit for a validator to become active. If -your `est_time` is less than 4 hours, you _should_ be fine to just move to the -next step. After all, this is a testnet and you're only risking Goerli ETH. - -### 5. Submit your deposit +## 2. Submit your deposit to Goerli