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 branch of sigp/lighthouse 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. 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.
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 from a (validator_count, genesis) tuple.
Starting a validator client with n interop keypairs.
Starting a node from a genesis state file.
Exporting a genesis state 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" 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 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

TODO

Exporting a genesis file