lighthouse/validator_client/README.md
Luke Anderson fba916a0d8
Updated validator config according to suggestions.
- Directory structure changed slightly
 - Uses a filter_map instead of a for loop.
 - All errors reading files does not prevent others from being read.
 - The accounts manager needs to generate files first, with the same structure.
2019-03-23 15:46:51 +11:00

88 lines
2.9 KiB
Markdown

# Lighthouse Validator Client
The Validator Client (VC) is a stand-alone binary which connects to a Beacon
Node (BN) and fulfils the roles of a validator.
## Roles
The VC is responsible for the following tasks:
- Requesting validator duties (a.k.a. shuffling) from the BN.
- Prompting the BN to produce a new block, when a validators block production
duties require.
- Completing all the fields on a new block (e.g., RANDAO reveal, signature) and
publishing the block to a BN.
- Prompting the BN to produce a new shard atteststation as per a validators
duties.
- Ensuring that no slashable messages are signed by a validator private key.
- Keeping track of the system clock and how it relates to slots/epochs.
The VC is capable of managing multiple validators in the same process tree.
## Implementation
_This section describes the present implementation of this VC binary._
### Services
Each validator is represented by two services, one which tracks the validator
duties and another which performs block production duties.
A separate thread is maintained for each service, for each validator. As such,
a single validator utilises three (3) threads (one for the base VC and two for
each service) and two validators utilise five (5) threads.
#### `DutiesManagerService`
Polls a BN and requests validator responsibilities, as well as a validator
index. The outcome of a successful poll is a `EpochDuties` struct:
```rust
EpochDuties {
validator_index: u64,
block_prodcution_slot: u64,
}
```
This is stored in the `EpochDutiesMap`, a `HashMap` mapping `epoch ->
EpochDuties`.
#### `BlockProducerService`
Polls the system clock and determines if a block needs to be produced. Reads
from the `EpochDutiesMap` maintained by the `DutiesManagerService`.
If block production is required, performs all the necessary duties to request,
complete and return a block from the BN.
### Configuration
Validator configurations are stored in a separate data directory from the main Beacon Node
binary. The validator data directory defaults to:
`$HOME/.lighthouse-validator`, however an alternative can be specified on the command line
with `--datadir`.
The configuration directory structure looks like:
```
~/.lighthouse-validator
├── 3cf4210d58ec
│   └── private.key
├── 9b5d8b5be4e7
│   └── private.key
└── cf6e07188f48
└── private.key
```
Where the hex value of the directory is a portion of the validator public key.
Validator keys must be generated using the separate `accounts_manager` binary, which will
place the keys into this directory structure in a format compatible with the validator client.
The chain specification (slot length, BLS domain, etc.) defaults to foundation
parameters, however is temporary and an upgrade will allow these parameters to be
read from a file (or initialized on first-boot).
## BN Communication
The VC communicates with the BN via a gRPC/protobuf connection.