lighthouse vc command starts a validator client instance which connects
to a beacon node performs the duties of a staked validator.
This document provides information on how the validator client discovers the validators it will act for and how it should obtain their cryptographic signatures.
Users that create validators using the
lighthouse account tool in the
standard directories and do not start their
lighthouse vc with the
--disable-auto-discover flag should not need to understand the contents of
this document. However, users with more complex needs may find this document
validator_definitions.yml file is located in the
~/.lighthouse/validators. It is a
YAML encoded file defining exactly which
validators the validator client will (and won't) act for.
Here's an example file with two validators:
--- - enabled: true voting_public_key: "0x87a580d31d7bc69069b55f5a01995a610dd391a26dc9e36e81057a17211983a79266800ab8531f21f1083d7d84085007" type: local_keystore voting_keystore_path: /home/paul/.lighthouse/validators/0x87a580d31d7bc69069b55f5a01995a610dd391a26dc9e36e81057a17211983a79266800ab8531f21f1083d7d84085007/voting-keystore.json voting_keystore_password_path: /home/paul/.lighthouse/secrets/0x87a580d31d7bc69069b55f5a01995a610dd391a26dc9e36e81057a17211983a79266800ab8531f21f1083d7d84085007 - enabled: false voting_public_key: "0xa5566f9ec3c6e1fdf362634ebec9ef7aceb0e460e5079714808388e5d48f4ae1e12897fed1bea951c17fa389d511e477" type: local_keystore voting_keystore_path: /home/paul/.lighthouse/validators/0xa5566f9ec3c6e1fdf362634ebec9ef7aceb0e460e5079714808388e5d48f4ae1e12897fed1bea951c17fa389d511e477/voting-keystore.json voting_keystore_password: myStrongpa55word123&$
In this example we can see two validators:
- A validator identified by the
0x87a5...public key which is enabled.
- Another validator identified by the
0x0xa556...public key which is not enabled.
Each permitted field of the file is listed below for reference:
falseindicating if the validator client should consider this validator "enabled".
voting_public_key: A validator public key.
type: How the validator signs messages (currently restricted to
voting_keystore_path: The path to a EIP-2335 keystore.
voting_keystore_password_path: The path to the password for the EIP-2335 keystore.
voting_keystore_password: The password to the EIP-2335 keystore.
voting_keystore_passwordmust be supplied. If both are supplied,
When validator client starts and the
validator_definitions.yml file doesn't
exist, a new file will be created. If the
--disable-auto-discover flag is
provided, the new file will be empty and the validator client will not start
any validators. If the
--disable-auto-discover flag is not provided, an
automatic validator discovery routine will start (more on that later). To
lighthouse vc: validators are automatically discovered.
lighthouse vc --disable-auto-discover: validators are not automatically discovered.
--disable-auto-discover flag is not provided, the validator will search the
validator-dir for validators and add any new validators to the
The routine for this search begins in the
validator-dir, where it obtains a
list of all files in that directory and all sub-directories (i.e., recursive
directory-tree search). For each file named
voting-keystore.json it creates a
new validator definition by the following process:
pubkeyvalue from the
voting_keystore_pathto the full path of the discovered keystore.
voting_keystore_password_pathto be a file in the
secrets-dirwith a name identical to the
Lets assume the following directory structure:
~/.lighthouse/validators ├── john │ └── voting-keystore.json ├── sally │ ├── one │ │ └── voting-keystore.json │ ├── three │ │ └── my-voting-keystore.json │ └── two │ └── voting-keystore.json └── slashing_protection.sqlite
There is no
validator_definitions.yml file present, so we can run
lighthouse vc (without
--disable-auto-discover) and it will create the following
--- - enabled: true voting_public_key: "0xa5566f9ec3c6e1fdf362634ebec9ef7aceb0e460e5079714808388e5d48f4ae1e12897fed1bea951c17fa389d511e477" type: local_keystore voting_keystore_path: /home/paul/.lighthouse/validators/sally/one/voting-keystore.json voting_keystore_password_path: /home/paul/.lighthouse/secrets/0xa5566f9ec3c6e1fdf362634ebec9ef7aceb0e460e5079714808388e5d48f4ae1e12897fed1bea951c17fa389d511e477 - enabled: true voting_public_key: "0xaa440c566fcf34dedf233baf56cf5fb05bb420d9663b4208272545608c27c13d5b08174518c758ecd814f158f2b4a337" type: local_keystore voting_keystore_path: /home/paul/.lighthouse/validators/sally/two/voting-keystore.json voting_keystore_password_path: /home/paul/.lighthouse/secrets/0xaa440c566fcf34dedf233baf56cf5fb05bb420d9663b4208272545608c27c13d5b08174518c758ecd814f158f2b4a337 - enabled: true voting_public_key: "0x87a580d31d7bc69069b55f5a01995a610dd391a26dc9e36e81057a17211983a79266800ab8531f21f1083d7d84085007" type: local_keystore voting_keystore_path: /home/paul/.lighthouse/validators/john/voting-keystore.json voting_keystore_password_path: /home/paul/.lighthouse/secrets/0x87a580d31d7bc69069b55f5a01995a610dd391a26dc9e36e81057a17211983a79266800ab8531f21f1083d7d84085007
voting-keystore.json files have been detected and added to the file.
sally/three/my-voting-keystore.json file was not added to the
file, since the file name is not exactly
In order for the validator client to decrypt the validators, they will need to
secrets-dir is organised as below:
~/.lighthouse/secrets ├── 0xa5566f9ec3c6e1fdf362634ebec9ef7aceb0e460e5079714808388e5d48f4ae1e12897fed1bea951c17fa389d511e477 ├── 0xaa440c566fcf34dedf233baf56cf5fb05bb420d9663b4208272545608c27c13d5b08174518c758ecd814f158f2b4a337 └── 0x87a580d31d7bc69069b55f5a01995a610dd391a26dc9e36e81057a17211983a79266800ab8531f21f1083d7d84085007
The automatic validator discovery process works out-of-the-box with validators
that are created using the
lighthouse account validator new command. The
details of this process are only interesting to those who are using keystores
generated with another tool or have a non-standard requirements.
If you are one of these users, manually edit the
file to suit your requirements. If the file is poorly formatted or any one of
the validators is unable to be initialized, the validator client will refuse to
If a validator client were to start using the first example
validator_definitions.yml file it would print the following log,
acknowledging there there are two validators and one is disabled:
INFO Initialized validators enabled: 1, disabled: 1
The validator client will simply ignore the disabled validator. However, for the active validator, the validator client will:
- Load an EIP-2335 keystore from the
- If the
voting_keystore_passwordfield is present, use it as the keystore password. Otherwise, attempt to read the file at
voting_keystore_password_pathand use the contents as the keystore password.
- Use the keystore password to decrypt the keystore and obtain a BLS keypair.
- Verify that the decrypted BLS keypair matches the
- Create a
voting-keystore.json.lockfile adjacent to the
voting_keystore_path, indicating that the voting keystore is in-use and should not be opened by another process.
- Proceed to act for that validator, creating blocks and attestations if/when required.
If there is an error during any of these steps (e.g., a file is missing or corrupt) the validator client will log an error and continue to attempt to process other validators.
When the validator client exits (or the validator is deactivated) it will
voting-keystore.json.lock to indicate that the keystore is free for use again.