diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index f0ad411449..4ffa694cd4 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -2,7 +2,9 @@ * [Introduction](./intro.md) * [Development Environment](./setup.md) -* [Testnets](./testnets.md) - * [Simple Local Testnet](./simple-testnet.md) - * [Interop](./interop.md) - * [Interop Tips & Tricks](./interop-tips.md) +* [Simple Local Testnet](./simple-testnet.md) +* [Interop](./interop.md) + * [Environment](./interop-environment.md) + * [CLI Overview](./interop-cli.md) + * [Scenarios](./interop-scenarios.md) + * [Cheat-sheet](./interop-cheat-sheet.md) diff --git a/book/src/interop-cheat-sheet.md b/book/src/interop-cheat-sheet.md new file mode 100644 index 0000000000..4f6f079b47 --- /dev/null +++ b/book/src/interop-cheat-sheet.md @@ -0,0 +1,143 @@ +# Interop Cheat-sheet + +This document contains a list of tips and tricks that may be useful during +interop testing. + +- When starting a beacon node: + - [Specify a boot node by multiaddr](#boot-node-multiaddr) + - [Specify a boot node by ENR](#boot-node-enr) + - [Avoid port clashes when starting multiple nodes](#port-bump) + - [Specify a custom slot time](#slot-time) +- Using the beacon node HTTP API: + - [Curl a nodes ENR](#http-enr) + - [Curl a nodes connected peers](#http-peer-ids) + - [Curl a nodes local peer id](#http-peer-id) + - [Curl a nodes listening multiaddrs](#http-listen-addresses) + - [Curl a nodes beacon chain head](#http-head) + - [Curl a nodes finalized checkpoint](#http-finalized) + +## Category: CLI + +The `--help` command provides detail on the CLI interface. Here are some +interop-specific CLI commands. + + +### Specify a boot node by multiaddr + +You can specify a static list of multiaddrs when booting Lighthouse using +the `--libp2p-addresses` command. + +#### Example: + +Runs an 8 validator quick-start chain, peering with `/ip4/192.168.0.1/tcp/9000` on boot. + +``` +$ ./beacon_node --libp2p-addresses /ip4/192.168.0.1/tcp/9000 testnet -f quick 8 1567222226 +``` + + +### Specify a boot node by ENR + +You can specify a static list of Discv5 addresses when booting Lighthouse using +the `--boot-nodes` command. + +#### Example: + +Runs an 8 validator quick-start chain, peering with `-IW4QB2...` on boot. + +``` +$ ./beacon_node --boot-nodes -IW4QB2Hi8TPuEzQ41Cdf1r2AUU1FFVFDBJdJyOkWk2qXpZfFZQy2YnJIyoT_5fnbtrXUouoskmydZl4pIg90clIkYUDgmlwhH8AAAGDdGNwgiMog3VkcIIjKIlzZWNwMjU2azGhAjg0-DsTkQynhJCRnLLttBK1RS78lmUkLa-wgzAi-Ob5 testnet -f quick 8 1567222226 +``` + + +### Avoid port clashes when starting nodes + +Starting a second Lighthouse node on the same machine will fail due to TCP/UDP +port collisions. Use the `-b` (`--port-bump`) flag to increase all listening +ports by some `n`. + +#### Example: + +Increase all ports by `10` (using multiples of `10` is recommended). + +``` +$ ./beacon_node -b 10 testnet -f quick 8 1567222226 +``` + + +### Start a testnet with a custom slot time + +Lighthouse can run at quite low slot times when there are few validators (e.g., +`500 ms` slot times should be fine for 8 validators). + +#### Example + +The `-t` (`--slot-time`) flag specifies the milliseconds per slot. + +``` +$ ./beacon_node -b 10 testnet -t 500 -f quick 8 1567222226 +``` + +> Note: `bootstrap` loads the slot time via HTTP and therefore conflicts with +> this flag. + +## Category: HTTP API + +Examples assume there is a Lighthouse node exposing a HTTP API on +`localhost:5052`. Responses are JSON. + + +### Get the node's ENR + +``` +$ curl localhost:5052/network/enr + +"-IW4QFyf1VlY5pZs0xZuvKMRZ9_cdl9WMCDAAJXZiZiuGcfRYoU40VPrYDLQj5prneJIz3zcbTjHp9BbThc-yiymJO8HgmlwhH8AAAGDdGNwgiMog3VkcIIjKIlzZWNwMjU2azGhAjg0-DsTkQynhJCRnLLttBK1RS78lmUkLa-wgzAi-Ob5"% +``` + + +### Get a list of connected peer ids + +``` +$ curl localhost:5052/network/peers + +["QmeMFRTWfo3KbVG7dEBXGhyRMa29yfmnJBXW84rKuGEhuL"]% +``` + + +### Get the node's peer id + +``` +curl localhost:5052/network/peer_id + +"QmRD1qs2AqNNRdBcGHUGpUGkpih5cmdL32mhh22Sy79xsJ"% +``` + + +### Get the list of listening libp2p addresses + +Lists all the libp2p multiaddrs that the node is listening on. + +``` +curl localhost:5052/network/listen_addresses + +["/ip4/127.0.0.1/tcp/9000","/ip4/192.168.1.121/tcp/9000","/ip4/172.17.0.1/tcp/9000","/ip4/172.42.0.1/tcp/9000","/ip6/::1/tcp/9000","/ip6/fdd3:c293:1bc::203/tcp/9000","/ip6/fdd3:c293:1bc:0:9aa9:b2ea:c610:44db/tcp/9000"]% +``` + + +### Get the node's beacon chain head + +``` +curl localhost:5052/beacon/head + +{"slot":0,"block_root":"0x827bf71805540aa13f6d8c7d18b41b287b2094a4d7a28cbb8deb061dbf5df4f5","state_root":"0x90a78d73294bc9c7519a64e1912161be0e823eb472012ff54204e15a4d717fa5"}% +``` + + +### Get the node's finalized checkpoint + +``` +curl localhost:5052/beacon/latest_finalized_checkpoint + +{"epoch":0,"root":"0x0000000000000000000000000000000000000000000000000000000000000000"}% +``` diff --git a/book/src/interop-cli.md b/book/src/interop-cli.md new file mode 100644 index 0000000000..3658781d49 --- /dev/null +++ b/book/src/interop-cli.md @@ -0,0 +1,29 @@ +# Interop CLI Overview + +The Lighthouse CLI has two primary tasks: + +- **Resuming** an existing database with `$ ./beacon_node`. +- **Creating** a new testnet database using `$ ./beacon_node testnet`. + +_See [Scenarios](./interop-scenarios.md) for methods we're likely to use +during interop._ + +## Creating a new database + +There are several methods for creating a new beacon node database: + +- `quick`: using the `(validator_client, genesis_time)` tuple. +- `recent`: as above but `genesis_time` is set to the start of some recent time + window. +- `file`: loads the genesis file from disk in one of multiple formats. +- `bootstrap`: a Lighthouse-specific method where we connect to a running node + and download it's specification and genesis state via the HTTP API. + +See `$ ./beacon_node testnet --help` for more detail. + +## Resuming from an existing database + +Once a database has been created, it can be resumed by running `$ ./beacon_node`. + +Presently, this command will fail if no existing database is found. You must +use the `$ ./beacon_node testnet` command to create a new database. diff --git a/book/src/interop-environment.md b/book/src/interop-environment.md new file mode 100644 index 0000000000..6d3568e29e --- /dev/null +++ b/book/src/interop-environment.md @@ -0,0 +1,30 @@ +# Interop Environment + +All that is required for inter-op is a built and tested [development +environment](./setup.md). + +## Repositories + +You will only require the [sigp/lighthouse](http://github.com/sigp/lighthouse) +library. + +To allow for faster build/test iterations 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.** + +## File System + +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. + +You do not need to create any of these directories manually. diff --git a/book/src/interop-scenarios.md b/book/src/interop-scenarios.md new file mode 100644 index 0000000000..d54772ee8c --- /dev/null +++ b/book/src/interop-scenarios.md @@ -0,0 +1,97 @@ +# Interop Scenarios + +Here we demonstrate some expected interop scenarios. + +All scenarios assume a working [development environment](./setup.md) and +commands are based in the `target/release` directory (this is the build dir for +`cargo`). + +Additional functions can be found in the [interop +cheat-sheet](./interop-cheat-sheet.md). + +### Table of contents + +- [Starting from a`validator_count, genesis_time` tuple](#quick-start) +- [Starting a node from a genesis state file](#state-file) +- [Starting a validator client](#val-client) +- [Exporting a genesis state file](#export) from a running Lighthouse + node + + + +### Start beacon node given a validator count and genesis_time + + +To start a brand-new beacon node (with no history) use: + +``` +$ ./beacon_node testnet -f quick 8 1567222226 +``` +> Notes: +> +> - 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. + + +### Start Beacon Node given a genesis state file + +A genesis state can be read from file using the `testnet file` subcommand. +There are three supported formats: + +- `ssz` (default) +- `json` +- `yaml` + +Start a new node using `/tmp/genesis.ssz` as the genesis state: + +``` +$ ./beacon_node testnet --spec minimal -f file ssz /tmp/genesis.ssz +``` + +> Notes: +> +> - The `-f` flag ignores any existing database or configuration, backing them +> up before re-initializing. +> - See `$ ./beacon_node testnet file --help` for more configuration options. + + +### Start an auto-configured validator client + +To start a brand-new validator client (with no history) use: + +``` +$ ./validator_client testnet -b insecure 0 8 +``` + +> Notes: +> +> - The `-b` flag means the validator client will "bootstrap" specs and config +> from the beacon node. +> - The `insecure` command dictates that the [interop keypairs](https://github.com/ethereum/eth2.0-pm/tree/6e41fcf383ebeb5125938850d8e9b4e9888389b4/interop/mocked_start#pubkeyprivkey-generation) +> will be used. +> - The `0 8` indicates that this validator client should manage 8 validators, +> starting at validator 0 (the first deposited validator). +> - The validator client will try to connect to the beacon node at `localhost`. +> See `--help` to configure that address and other features. +> - The validator client will operate very unsafely in `testnet` mode, happily +> swapping between chains and creating double-votes. + + +### Exporting a genesis file + +Genesis states can downloaded from a running Lighthouse node via the HTTP API. Three content-types are supported: + +- `application/json` +- `application/yaml` +- `application/ssz` + +Using `curl`, a genesis state can be downloaded to `/tmp/genesis.ssz`: + +``` +$ curl --header "Content-Type: application/ssz" "localhost:5052/beacon/state/genesis" -o /tmp/genesis.ssz +``` diff --git a/book/src/interop-tips.md b/book/src/interop-tips.md index 969d49b4f3..0d52e896ac 100644 --- a/book/src/interop-tips.md +++ b/book/src/interop-tips.md @@ -1,120 +1 @@ # Interop Tips & Tricks - -This document contains a list of tips and tricks that may be useful during -interop testing. - -## Command-line Interface - -The `--help` command provides detail on the CLI interface. Here are some -interop-specific CLI commands. - -### Specify a boot node by multiaddr - -You can specify a static list of multiaddrs when booting Lighthouse using -the `--libp2p-addresses` command. - -#### Example: - -Runs an 8 validator quick-start chain, peering with `/ip4/192.168.0.1/tcp/9000` on boot. - -``` -$ ./beacon_node --libp2p-addresses /ip4/192.168.0.1/tcp/9000 testnet -f quick 8 1567222226 -``` - -### Specify a boot node by ENR - -You can specify a static list of Discv5 addresses when booting Lighthouse using -the `--boot-nodes` command. - -#### Example: - -Runs an 8 validator quick-start chain, peering with `-IW4QB2...` on boot. - -``` -$ ./beacon_node --boot-nodes -IW4QB2Hi8TPuEzQ41Cdf1r2AUU1FFVFDBJdJyOkWk2qXpZfFZQy2YnJIyoT_5fnbtrXUouoskmydZl4pIg90clIkYUDgmlwhH8AAAGDdGNwgiMog3VkcIIjKIlzZWNwMjU2azGhAjg0-DsTkQynhJCRnLLttBK1RS78lmUkLa-wgzAi-Ob5 testnet -f quick 8 1567222226 -``` - -### Avoid port clashes when starting nodes - -Starting a second Lighthouse node on the same machine will fail due to TCP/UDP -port collisions. Use the `-b` (`--port-bump`) flag to increase all listening -ports by some `n`. - -#### Example: - -Increase all ports by `10` (using multiples of `10` is recommended). - -``` -$ ./beacon_node -b 10 testnet -f quick 8 1567222226 -``` - -### Start a testnet with a custom slot time - -Lighthouse can run at quite low slot times when there are few validators (e.g., -`500 ms` slot times should be fine for 8 validators). - -#### Example - -The `-t` (`--slot-time`) flag specifies the milliseconds per slot. - -``` -$ ./beacon_node -b 10 testnet -t 500 -f quick 8 1567222226 -``` - -> Note: `bootstrap` loads the slot time via HTTP and therefore conflicts with -> this flag. - -## HTTP API - -Examples assume there is a Lighthouse node exposing a HTTP API on -`localhost:5052`. Responses are JSON. - -### Get the node's ENR - -``` -$ curl localhost:5052/network/enr - -"-IW4QFyf1VlY5pZs0xZuvKMRZ9_cdl9WMCDAAJXZiZiuGcfRYoU40VPrYDLQj5prneJIz3zcbTjHp9BbThc-yiymJO8HgmlwhH8AAAGDdGNwgiMog3VkcIIjKIlzZWNwMjU2azGhAjg0-DsTkQynhJCRnLLttBK1RS78lmUkLa-wgzAi-Ob5"% -``` - -### Get a list of connected peer ids - -``` -$ curl localhost:5052/network/peers - -["QmeMFRTWfo3KbVG7dEBXGhyRMa29yfmnJBXW84rKuGEhuL"]% -``` - -### Get the node's peer id - -``` -curl localhost:5052/network/peer_id - -"QmRD1qs2AqNNRdBcGHUGpUGkpih5cmdL32mhh22Sy79xsJ"% -``` - -### Get the list of listening libp2p addresses - -Lists all the libp2p multiaddrs that the node is listening on. - -``` -curl localhost:5052/network/listen_addresses - -["/ip4/127.0.0.1/tcp/9000","/ip4/192.168.1.121/tcp/9000","/ip4/172.17.0.1/tcp/9000","/ip4/172.42.0.1/tcp/9000","/ip6/::1/tcp/9000","/ip6/fdd3:c293:1bc::203/tcp/9000","/ip6/fdd3:c293:1bc:0:9aa9:b2ea:c610:44db/tcp/9000"]% -``` - -### Get the node's beacon chain head - -``` -curl localhost:5052/beacon/head - -{"slot":0,"block_root":"0x827bf71805540aa13f6d8c7d18b41b287b2094a4d7a28cbb8deb061dbf5df4f5","state_root":"0x90a78d73294bc9c7519a64e1912161be0e823eb472012ff54204e15a4d717fa5"}% -``` - -### Get the node's finalized checkpoint - -``` -curl localhost:5052/beacon/latest_finalized_checkpoint - -{"epoch":0,"root":"0x0000000000000000000000000000000000000000000000000000000000000000"}% -``` diff --git a/book/src/interop.md b/book/src/interop.md index a2f80584da..cb119d59da 100644 --- a/book/src/interop.md +++ b/book/src/interop.md @@ -3,134 +3,9 @@ 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.** +## Chapters -## 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. - -## CLI Overview - -The Lighthouse CLI has two primary tasks: - -- **Starting** a new testnet chain using `$ ./beacon_node testnet`. -- **Resuming** an existing chain with `$ ./beacon_node` (omit `testnet`). - -There are several methods for starting a new chain: - -- `quick`: using the `(validator_client, genesis_time)` tuple. -- `recent`: as above but `genesis_time` is set to the start of some recent time - window. -- `file`: loads the genesis file from disk in one of multiple formats. -- `bootstrap`: a Lighthouse-specific method where we connect to a running node - and download it's specification and genesis state via the HTTP API. - -See `$ ./beacon_node testnet --help` for more detail. - -Once a chain has been started, it can be resumed by running `$ ./beacon_node` -(potentially supplying the `--datadir`, if a non-default directory was used). - - -## Scenarios - -The following scenarios are documented here: - -- [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. - -All scenarios assume a working development environment and commands are based -in the `target/release` directory (this is the build dir for `cargo`). - - -#### 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 -``` -> Notes: -> -> - 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 - -Start the validator client with: - -``` -$ ./validator_client testnet -b insecure 0 8 -``` - -> Notes: -> -> - The `-b` flag means the validator client will "bootstrap" specs and config -> from the beacon node. -> - The `insecure` command dictates that the [interop keypairs](https://github.com/ethereum/eth2.0-pm/tree/6e41fcf383ebeb5125938850d8e9b4e9888389b4/interop/mocked_start#pubkeyprivkey-generation) -> will be used. -> - The `0 8` indicates that this validator client should manage 8 validators, -> starting at validator 0 (the first deposited validator). -> - The validator client will try to connect to the beacon node at `localhost`. -> See `--help` to configure that address and other features. -> - The validator client will operate very unsafely in `testnet` mode, happily -> swapping between chains and creating double-votes. - -#### Starting from a genesis file - -A genesis state can be read from file using the `testnet file` subcommand. -There are three supported formats: - -- `ssz` (default) -- `json` -- `yaml` - -Start a new node using `/tmp/genesis.ssz` as the genesis state: - -``` -$ ./beacon_node testnet --spec minimal -f file ssz /tmp/genesis.ssz -``` - -> Notes: -> -> - The `-f` flag ignores any existing database or configuration, backing them -> up before re-initializing. -> - See `$ ./beacon_node testnet file --help` for more configuration options. - -#### Exporting a genesis file - -Genesis states can downloaded from a running Lighthouse node via the HTTP API. Three content-types are supported: - -- `application/json` -- `application/yaml` -- `application/ssz` - -Using `curl`, a genesis state can be downloaded to `/tmp/genesis.ssz`: - -``` -$ curl --header "Content-Type: application/ssz" "localhost:5052/beacon/state/genesis" -o /tmp/genesis.ssz -``` +- Read about the required [development environment](./interop-environment.md). +- Get an [overview](./interop-cli.md) of the Lighthouse CLI. +- See how we expect to handle some [interop scenarios](./interop-scenarios.md). +- See the [interop cheat-sheet](./interop-cheat-sheet.md) for useful CLI tips. diff --git a/book/src/intro.md b/book/src/intro.md index e0e3cd6a0f..ccf867a54e 100644 --- a/book/src/intro.md +++ b/book/src/intro.md @@ -17,31 +17,11 @@ 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. +Documentation is presently targeted at **researchers and developers**. It +assumes significant prior knowledge of Ethereum 2.0. -- Get started with [development environment setup](setup.html). -- [Run a simple testnet](simple-testnet.html) in Only Three CLI Commands™. -- Read about our interop workflow. -- API? +Topics: -## 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. +- Get started with [development environment setup](./setup.md). +- See the [interop docs](./interop.md). +- [Run a simple testnet](./simple-testnet.md) in Only Three CLI Commands™.