Creating and Importing Validators

The lighthouse validator-manager create command derives validators from a mnemonic and produces two files:

• validators.json: the keystores and passwords for the newly generated validators, in JSON format.
• deposits.json: a JSON file of the same format as ethstaker-deposit-cli which can be used for deposit submission via the Ethereum Staking Launchpad.

The lighthouse validator-manager import command accepts a validators.json file (from the create command) and submits those validators to a running Lighthouse Validator Client via the HTTP API.

These two commands enable a workflow of:

1. Creating the validators via the create command.
2. Importing the validators via the import command.
3. Depositing validators via the Ethereum Staking Launchpad.

The separation of the create and import commands allows for running the create command on an air-gapped host whilst performing the import command on an internet-connected host.

The create and import commands are recommended for advanced users who are familiar with command line tools and the practicalities of managing sensitive cryptographic material. We recommend that novice users follow the workflow on Ethereum Staking Launchpad rather than using the create and import commands.

Simple Example

Create validators from a mnemonic with:

lighthouse \
    validator-manager \
    create \
    --network mainnet \
    --first-index 0 \
    --count 2 \
    --eth1-withdrawal-address <ADDRESS> \
    --suggested-fee-recipient <ADDRESS> \
    --output-path ./

If the flag --first-index is not provided, it will default to using index 0. The --suggested-fee-recipient flag may be omitted to use whatever default value the VC uses. It does not necessarily need to be identical to --eth1-withdrawal-address. The command will create the deposits.json and validators.json in the present working directory. If you would like these files to be created in a different directory, change the value of output-path, for example --output-path /desired/directory. The directory will be created if the path does not exist.

Then, import the validators to a running VC with:

lighthouse \
    validator-manager \
    import \
    --validators-file validators.json \
    --vc-token <API-TOKEN-PATH>

This is assuming that validators.json is in the present working directory. If it is not, insert the directory of the file. Be sure to remove ./validators.json after the import is successful since it contains unencrypted validator keystores.

Note: To import validators with validator-manager using keystore files created using the ethstaker-deposit-cli, refer to Managing Validators.

Detailed Guide

This guide will create two validators and import them to a VC. For simplicity, the same host will be used to generate the keys and run the VC. In reality, users may want to perform the create command on an air-gapped machine and then move the validators.json and deposits.json files to an Internet-connected host. This would help protect the mnemonic from being exposed to the Internet.

1. Create the Validators

Run the create command, substituting <ADDRESS> for an execution address that you control. This is where all the staked ETH and rewards will ultimately reside, so it's very important that this address is secure, accessible and backed-up. The create command:

lighthouse \
    validator-manager \
    create \
    --first-index 0 \
    --count 2 \
    --eth1-withdrawal-address <ADDRESS> \
    --output-path ./

If successful, the command output will appear like below:

Running validator manager for mainnet network

Enter the mnemonic phrase:
<REDACTED>
Valid mnemonic provided.

Starting derivation of 2 keystores. Each keystore may take several seconds.
Completed 1/2: 0x8885c29b8f88ee9b9a37b480fd4384fed74bda33d85bc8171a904847e65688b6c9bb4362d6597fd30109fb2def6c3ae4
Completed 2/2: 0xa262dae3dcd2b2e280af534effa16bedb27c06f2959e114d53bd2a248ca324a018dc73179899a066149471a94a1bc92f
Keystore generation complete
Writing "./validators.json"
Writing "./deposits.json"

This command will create validators at indices 0, 1. The exact indices created can be influenced with the --first-index and --count flags. Use these flags with caution to prevent creating the same validator twice, this may result in a slashing!

The command will create two files:

• ./deposits.json: this file does not contain sensitive information and may be uploaded to the Ethereum Staking Launchpad.
• ./validators.json: this file contains sensitive unencrypted validator keys, do not share it with anyone or upload it to any website.

2. Import the validators

The VC which will receive the validators needs to have the following flags at a minimum:

• --http
• --enable-doppelganger-protection

Therefore, the VC command might look like:

lighthouse \
    vc \
    --http \
    --enable-doppelganger-protection

In order to import the validators, the location of the VC api-token.txt file must be known. The location of the file varies, but it is located in the "validator directory" of your data directory. For example: ~/.lighthouse/mainnet/validators/api-token.txt. We will use <API-TOKEN-PATH> to substitute this value. If you are unsure of the api-token.txt path, you can run curl http://localhost:5062/lighthouse/auth which will show the path.

Once the VC is running, use the import command to import the validators to the VC:

lighthouse \
    validator-manager \
    import \
    --validators-file validators.json \
    --vc-token <API-TOKEN-PATH>

If successful, the command output will appear like below:

Running validator manager for mainnet network
Validator client is reachable at http://localhost:5062/ and reports 0 validators
Starting to submit 2 validators to VC, each validator may take several seconds
Uploaded keystore 1 of 2 to the VC
Uploaded keystore 2 of 2 to the VC

The user should now securely delete the validators.json file (e.g., shred -u validators.json). The validators.json contains the unencrypted validator keys and must not be shared with anyone. At the same time, lighthouse vc will log:

INFO Importing keystores via standard HTTP API, count: 1
WARN No slashing protection data provided with keystores
INFO Enabled validator                       voting_pubkey: 0xab6e29f1b98fedfca878edce2b471f1b5ee58ee4c3bd216201f98254ef6f6eac40a53d74c8b7da54f51d3e85cacae92f, signing_method: local_keystore
INFO Modified key_cache saved successfully

The WARN message means that the validators.json file does not contain the slashing protection data. This is normal if you are starting a new validator. The flag --enable-doppelganger-protection will also protect users from potential slashing risk. The validators will now go through 2-3 epochs of doppelganger protection and will automatically start performing their duties when they are deposited and activated.

If the host VC contains the same public key as the validators.json file, an error will be shown and the import process will stop:

Duplicate validator   0xab6e29f1b98fedfca878edce2b471f1b5ee58ee4c3bd216201f98254ef6f6eac40a53d74c8b7da54f51d3e85cacae92f already exists on the destination validator client. This may indicate that some validators are running in two places at once, which can lead to slashing. If you are certain that there is no risk, add the --ignore-duplicates flag.
Err(DuplicateValidator(0xab6e29f1b98fedfca878edce2b471f1b5ee58ee4c3bd216201f98254ef6f6eac40a53d74c8b7da54f51d3e85cacae92f))

If you are certain that it is safe, you can add the flag --ignore-duplicates in the import command. The command becomes:

lighthouse \
    validator-manager \
    import \
    --validators-file validators.json \
    --vc-token <API-TOKEN-PATH> \
    --ignore-duplicates

and the output will be as follows:

Duplicate validators are ignored, ignoring 0xab6e29f1b98fedfca878edce2b471f1b5ee58ee4c3bd216201f98254ef6f6eac40a53d74c8b7da54f51d3e85cacae92f which exists on the destination validator client
Re-uploaded keystore 1 of 6 to the VC

The guide is complete.