6c769ed86c
## Issue Addressed Update Information in Lighthouse Book ## Proposed Changes - move Validator Graffiti from Advanced Usage to Validator Management - update API response and command - some items that aren't too sure I put it in comment, which can be seen in raw/review format but not live ## Additional Info Please provide any additional information. For example, future considerations or information useful for reviewers. Co-authored-by: chonghe <44791194+chong-he@users.noreply.github.com>
4.5 KiB
Validator Inclusion APIs
The /lighthouse/validator_inclusion API endpoints provide information on
results of the proof-of-stake voting process used for finality/justification
under Casper FFG.
These endpoints are not stable or included in the Ethereum consensus standard API. As such, they are subject to change or removal without a change in major release version.
In order to apply these APIs, you need to have historical states information in the database of your node. This means adding the flag --reconstruct-historic-states in the beacon node or using the /lighthouse/database/reconstruct API. Once the state reconstruction process is completed, you can apply these APIs to any epoch.
Endpoints
| HTTP Path | Description |
|---|---|
/lighthouse/validator_inclusion/{epoch}/global |
A global vote count for a given epoch. |
/lighthouse/validator_inclusion/{epoch}/{validator_id} |
A per-validator breakdown of votes in a given epoch. |
Global
Returns a global count of votes for some given epoch. The results are included
both for the current and previous (epoch - 1) epochs since both are required
by the beacon node whilst performing per-epoch-processing.
Generally, you should consider the "current" values to be incomplete and the "previous" values to be final. This is because validators can continue to include attestations from the current epoch in the next epoch, however this is not the case for attestations from the previous epoch.
`epoch` query parameter
|
| --------- values are calculated here
| |
v v
Epoch: |---previous---|---current---|---next---|
|-------------|
^
|
window for including "current" attestations
in a block
The votes are expressed in terms of staked effective Gwei (i.e., not the number of
individual validators). For example, if a validator has 32 ETH staked they will
increase the current_epoch_attesting_gwei figure by 32,000,000,000 if they
have an attestation included in a block during the current epoch. If this
validator has more than 32 ETH, that extra ETH will not count towards their
vote (that is why it is effective Gwei).
The following fields are returned:
current_epoch_active_gwei: the total staked gwei that was active (i.e., able to vote) during the current epoch.current_epoch_target_attesting_gwei: the total staked gwei that attested to the majority-elected Casper FFG target epoch during the current epoch.previous_epoch_active_gwei: as percurrent_epoch_active_gwei, but during the previous epoch.previous_epoch_target_attesting_gwei: seecurrent_epoch_target_attesting_gwei.previous_epoch_head_attesting_gwei: the total staked gwei that attested to a head beacon block that is in the canonical chain.
From this data you can calculate:
Justification/Finalization Rate
previous_epoch_target_attesting_gwei / previous_epoch_active_gwei
When this value is greater than or equal to 2/3 it is possible that the
beacon chain may justify and/or finalize the epoch.
HTTP Example
curl -X GET "http://localhost:5052/lighthouse/validator_inclusion/0/global" -H "accept: application/json" | jq
{
"data": {
"current_epoch_active_gwei": 642688000000000,
"previous_epoch_active_gwei": 642688000000000,
"current_epoch_target_attesting_gwei": 366208000000000,
"previous_epoch_target_attesting_gwei": 1000000000,
"previous_epoch_head_attesting_gwei": 1000000000
}
}
Individual
Returns a per-validator summary of how that validator performed during the current epoch.
The Global Votes endpoint is the summation of all of these individual values, please see it for definitions of terms like "current_epoch", "previous_epoch" and "target_attester".
HTTP Example
curl -X GET "http://localhost:5052/lighthouse/validator_inclusion/0/42" -H "accept: application/json" | jq
{
"data": {
"is_slashed": false,
"is_withdrawable_in_current_epoch": false,
"is_active_unslashed_in_current_epoch": true,
"is_active_unslashed_in_previous_epoch": true,
"current_epoch_effective_balance_gwei": 32000000000,
"is_current_epoch_target_attester": false,
"is_previous_epoch_target_attester": false,
"is_previous_epoch_head_attester": false
}
}