gnosis/lighthouse
1
0
Fork 0
mirror of https://github.com/sigp/lighthouse.git synced 2026-04-26 01:03:40 +00:00
Code Issues Packages Projects Releases Wiki Activity

Fix issues with testnet dir, update docs (#992)

Browse Source 
* Fix issues with testnet dir, update docs

* Remove "simple testnet" docs

* Tear out old "bn testnet" stuff

* Add back ClientGenesis::Interop

* Tidy

* Remove lighthouse-bootstrap module

* Fix bug with spec constant mismatch

* Ensure beacon-node.toml is written to correct dir

* Add -t alias for --testnet-dir

* Update book/src/local-testnets.md

Co-Authored-By: Age Manning <Age@AgeManning.com>

* Add --purge CLI flag

* Update purge docs

* Perform manual delete of files in purge

* Rename --purge to --purge-db

* Address Michael's comments

Co-authored-by: Age Manning <Age@AgeManning.com>
This commit is contained in:
Paul Hauner
2020-04-17 17:49:29 +10:00
committed by GitHub
parent a8ee3389c2
commit 1a3d1b3077
23 changed files with 280 additions and 1139 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
book/src/SUMMARY.md
View File

@@ -6,9 +6,7 @@
* [Building from Source](./become-a-validator-source.md)
* [Installation](./installation.md)
* [Docker](./docker.md)
* [CLI](./cli.md)
* [Simple Local Testnet](./simple-testnet.md)
* [Local Testnets](./local-testnets.md)
* [Local Testnets](./local-testnets.md)
* [API](./api.md)
* [HTTP (RESTful JSON)](./http.md)
* [/beacon](./http_beacon.md)

2
book/src/intro.md
View File

@@ -21,7 +21,7 @@ You may read this book from start to finish, or jump to some of these topics:
- Follow the [Installation Guide](./installation.md) to install Lighthouse.
- Get hacking with the [Development Environment Guide](./setup.md).
- Utilize the whole stack by starting a [simple local testnet](./simple-testnet.md).
- Utilize the whole stack by starting a [local testnet](./local-testnets.md).
- Query the [RESTful HTTP API](./http.md) using `curl`.
- Listen to events with the [JSON WebSocket API](./websockets.md).
- View the [Rust code docs](http://lighthouse-docs.sigmaprime.io/).

159
book/src/local-testnets.md
View File

@@ -3,143 +3,104 @@
> This section is about running your own private local testnets.
> - If you wish to join the ongoing public testnet, please read [become a validator](./become-a-validator.md).
The `beacon_node` and `validator` commands have a `testnet` sub-command to
allow creating or connecting to Eth2 beacon chain testnets.
It is possible to create local, short-lived Lighthouse testnets that _don't_
require a deposit contract and Eth1 connection. There are two components
required for this:
For detailed documentation, use the `--help` flag on the CLI:
1. Creating a "testnet directory", containing the configuration of your new
testnet.
1. Using the `--dummy-eth1` flag on your beacon node to avoid needing an Eth1
node for block production.
There is a TL;DR (too long; didn't read), followed by detailed steps if the
TL;DR isn't adequate.
## TL;DR
```bash
$ lighthouse bn testnet --help
lcli new-testnet
lcli interop-genesis 128
lighthouse bn --testnet-dir ~/.lighthouse/testnet --dummy-eth1 --http
lighthouse vc --testnet-dir ~/.lighthouse/testnet --allow-unsynced testnet insecure 0 128
```
Optionally update the genesis time to now:
```bash
$ lighthouse vc testnet --help
lcli change-genesis-time ~/.lighthouse/testnet/genesis.ssz $(date +%s)
```
## Examples
## 1. Creating a testnet directory
All examples assume a working [development environment](./setup.md) and
commands are based in the `target/release` directory (this is the build dir for
`cargo`).
### 1.1 Install `lcli`
### Start a beacon node given a validator count and genesis_time
This guide requires `lcli`, the "Lighthouse CLI tool". It is a development tool
used for starting testnets and debugging.
To start a brand-new beacon node (with no history) use:
Install `lcli` from the root directory of this repository with:
```bash
$ lighthouse bn testnet -f quick 8 <GENESIS_TIME>
cargo install --path lcli --force
```
Where `GENESIS_TIME` is in [unix time](https://duckduckgo.com/?q=unix+time&t=ffab&ia=answer).
### 1.2 Create a testnet directory
> 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 `$ lighthouse bn testnet quick --help` for more configuration options.
The default location for a testnet directory is `~/.lighthouse/testnet`. We'll
use this directory to keep the examples simple, however you can always specify
a different directory using the `--testnet-dir` flag.
### Start a 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:
Once you have `lcli` installed, create a new testnet directory with:
```bash
$ lighthouse bn testnet --spec minimal -f file ssz /tmp/genesis.ssz
lcli new-testnet
```
> Notes:
>
> - The `-f` flag ignores any existing database or configuration, backing them
> up before re-initializing.
> - See `$ lighthouse bn testnet file --help` for more configuration options.
> - The `--spec` flag is required to allow SSZ parsing of fixed-length lists.
> Here the `minimal` eth2 specification is chosen, allowing for lower
> validator counts. See
> [eth2.0-specs/configs](https://github.com/ethereum/eth2.0-specs/tree/dev/configs)
> for more info.
> - This will create a "mainnet" spec testnet. To create a minimal spec use `lcli --spec minim new-testnet`.
> - The `lcli new-testnet` command has many options, use `lcli new-testnet --help` to see them.
### Start an auto-configured validator client
### 1.3 Create a genesis state
To start a brand-new validator client (with no history) use:
Your new testnet directory at `~/.lighthouse/testnet` doesn't yet have a
genesis state (`genesis.ssz`). Since there's no deposit contract in this
testnet, there's no way for nodes to find genesis themselves.
Manually create an "interop" genesis state with `128` validators:
```bash
$ lighthouse vc testnet insecure 0 8
lcli interop-genesis 128
```
> Notes:
>
> - 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.
> - A custom genesis time can be provided with `-t`.
> - See `lcli interop-genesis --help` for more info.
### Exporting a genesis file
## 2. Start the beacon nodes and validator clients
Genesis states can downloaded from a running Lighthouse node via the HTTP API. Three content-types are supported:
Now the testnet has been specified in `~/.lighthouse/testnet`, it's time to
start a beacon node and validator client.
- `application/json`
- `application/yaml`
- `application/ssz`
### 2.1 Start a beacon node
Using `curl`, a genesis state can be downloaded to `/tmp/genesis.ssz`:
Start a beacon node:
```bash
$ curl --header "Content-Type: application/ssz" "localhost:5052/beacon/state/genesis" -o /tmp/genesis.ssz
lighthouse bn --testnet-dir ~/.lighthouse/testnet --dummy-eth1 --http
```
## Advanced
> - `--testnet-dir` instructs the beacon node to use the spec we generated earlier.
> - `--dummy-eth1` uses deterministic "junk data" for linking to the eth1 chain, avoiding the requirement for an eth1 node. The downside is that new validators cannot be on-boarded after genesis.
> - `--http` starts the REST API so the validator client can produce blocks.
Below are some CLI commands useful when working with testnets.
### 2.2 Start a validator client
### Specify a boot node by multiaddr
You can specify a static list of multiaddrs when booting Lighthouse using
the `--libp2p-addresses` command.
#### Example:
Once the beacon node has started and begun trying to sync, start a validator
client:
```bash
$ lighthouse bn --libp2p-addresses /ip4/192.168.0.1/tcp/9000
lighthouse vc --testnet-dir ~/.lighthouse/testnet --allow-unsynced testnet insecure 0 128
```
### Specify a boot node by ENR (Ethereum Name Record)
You can specify a static list of Discv5 addresses when booting Lighthouse using
the `--boot-nodes` command.
#### Example:
```bash
$ lighthouse bn --boot-nodes -IW4QB2Hi8TPuEzQ41Cdf1r2AUU1FFVFDBJdJyOkWk2qXpZfFZQy2YnJIyoT_5fnbtrXUouoskmydZl4pIg90clIkYUDgmlwhH8AAAGDdGNwgiMog3VkcIIjKIlzZWNwMjU2azGhAjg0-DsTkQynhJCRnLLttBK1RS78lmUkLa-wgzAi-Ob5
```
### 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.
```bash
$ lighthouse bn testnet -t 500 recent 8
```
> Note: `bootstrap` loads the slot time via HTTP and therefore conflicts with
> this flag.
> - `--testnet-dir` instructs the validator client to use the spec we generated earlier.
> - `--allow-unsynced` stops the validator client checking to see if the beacon node is synced prior to producing blocks.
> - `testnet insecure 0 128` instructs the validator client to use insecure
> testnet private keys and that it should control validators from `0` to
> `127` (inclusive).

70
book/src/simple-testnet.md
View File

@@ -1,70 +0,0 @@
# Simple Local Testnet
> This guide is about running your own private local testnet.
> - If you wish to join the ongoing public testnet, please read [become a validator](./become-a-validator.md).
This guide will help you setup your own private local testnet.
First, [install Lighthouse](./installation.md).
Then, get the current unix time in seconds; you can use
[epochconverter.com](https://www.epochconverter.com/) or `$ date +%s`. It
should look like this `1576803034` and you should use it wherever we put
`<time>`.
> If you choose a time that's more than several minutes in the past the
> validator client will refuse to produce blocks. We will loosen this
> restriction in the future, the issue is tracked
> [here](https://github.com/sigp/lighthouse/issues/714).
## Starting a beacon node
Start a new node with:
```bash
$ lighthouse bn --http testnet -r quick 8 <time>
```
> Notes:
>
> - The `--http` flag starts the API so the validator can produce blocks.
> - The `-r` flag creates a random data directory to avoid clashes with other
> nodes.
> - `8` is number of validators with deposits in the genesis state.
> - See `$ lighthouse bn testnet --help` for more configuration options,
> including `minimal`/`mainnet` specification.
## Starting a validator client
In a new terminal window, start the validator client with:
```bash
$ lighthouse vc testnet insecure 0 8
```
> Notes:
>
> - The `insecure` command uses predictable, well-known private keys. Since
> this is just a local testnet, these are fine.
> - 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.
## Adding another beacon node
You may connect another (non-validating) node to your local network by starting
a new terminal and running:
```bash
lighthouse bn -z --libp2p-addresses /ip4/127.0.0.1/tcp/9000 testnet -r quick 8 <time>
```
> Notes:
>
> - The `z` (or `--zero-ports`) flag sets all listening ports to be zero, which then
> means that the OS chooses random available ports. This avoids port
> collisions with the first node.
> - The `--libp2p-addresses` flag instructs the new node to connect to the
> first node.