mirror of
https://github.com/sigp/lighthouse.git
synced 2026-05-09 03:17:55 +00:00
6e3ca48cb9
## Issue Addressed NA ## Proposed Changes This PR addresses two things: 1. Allows the `ValidatorMonitor` to work with Altair states. 1. Optimizes `altair::process_epoch` (see [code](https://github.com/paulhauner/lighthouse/blob/participation-cache/consensus/state_processing/src/per_epoch_processing/altair/participation_cache.rs) for description) ## Breaking Changes The breaking changes in this PR revolve around one premise: *After the Altair fork, it's not longer possible (given only a `BeaconState`) to identify if a validator had *any* attestation included during some epoch. The best we can do is see if that validator made the "timely" source/target/head flags.* Whilst this seems annoying, it's not actually too bad. Finalization is based upon "timely target" attestations, so that's really the most important thing. Although there's *some* value in knowing if a validator had *any* attestation included, it's far more important to know about "timely target" participation, since this is what affects finality and justification. For simplicity and consistency, I've also removed the ability to determine if *any* attestation was included from metrics and API endpoints. Now, all Altair and non-Altair states will simply report on the head/target attestations. The following section details where we've removed fields and provides replacement values. ### Breaking Changes: Prometheus Metrics Some participation metrics have been removed and replaced. Some were removed since they are no longer relevant to Altair (e.g., total attesting balance) and others replaced with gwei values instead of pre-computed values. This provides more flexibility at display-time (e.g., Grafana). The following metrics were added as replacements: - `beacon_participation_prev_epoch_head_attesting_gwei_total` - `beacon_participation_prev_epoch_target_attesting_gwei_total` - `beacon_participation_prev_epoch_source_attesting_gwei_total` - `beacon_participation_prev_epoch_active_gwei_total` The following metrics were removed: - `beacon_participation_prev_epoch_attester` - instead use `beacon_participation_prev_epoch_source_attesting_gwei_total / beacon_participation_prev_epoch_active_gwei_total`. - `beacon_participation_prev_epoch_target_attester` - instead use `beacon_participation_prev_epoch_target_attesting_gwei_total / beacon_participation_prev_epoch_active_gwei_total`. - `beacon_participation_prev_epoch_head_attester` - instead use `beacon_participation_prev_epoch_head_attesting_gwei_total / beacon_participation_prev_epoch_active_gwei_total`. The `beacon_participation_prev_epoch_attester` endpoint has been removed. Users should instead use the pre-existing `beacon_participation_prev_epoch_target_attester`. ### Breaking Changes: HTTP API The `/lighthouse/validator_inclusion/{epoch}/{validator_id}` endpoint loses the following fields: - `current_epoch_attesting_gwei` (use `current_epoch_target_attesting_gwei` instead) - `previous_epoch_attesting_gwei` (use `previous_epoch_target_attesting_gwei` instead) The `/lighthouse/validator_inclusion/{epoch}/{validator_id}` endpoint lose the following fields: - `is_current_epoch_attester` (use `is_current_epoch_target_attester` instead) - `is_previous_epoch_attester` (use `is_previous_epoch_target_attester` instead) - `is_active_in_current_epoch` becomes `is_active_unslashed_in_current_epoch`. - `is_active_in_previous_epoch` becomes `is_active_unslashed_in_previous_epoch`. ## Additional Info NA ## TODO - [x] Deal with total balances - [x] Update validator_inclusion API - [ ] Ensure `beacon_participation_prev_epoch_target_attester` and `beacon_participation_prev_epoch_head_attester` work before Altair Co-authored-by: realbigsean <seananderson33@gmail.com>
126 lines
4.3 KiB
Markdown
126 lines
4.3 KiB
Markdown
# 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 Eth2 standard API. As such,
|
|
they are subject to change or removal without a change in major release
|
|
version.
|
|
|
|
## Endpoints
|
|
|
|
HTTP Path | Description |
|
|
| --- | -- |
|
|
[`/lighthouse/validator_inclusion/{epoch}/global`](#global) | A global vote count for a given epoch.
|
|
[`/lighthouse/validator_inclusion/{epoch}/{validator_id}`](#individual) | 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 calcuated 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 per `current_epoch_active_gwei`, but during the previous epoch.
|
|
- `previous_epoch_target_attesting_gwei`: see `current_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 some interesting figures:
|
|
|
|
#### Participation Rate
|
|
|
|
`previous_epoch_attesting_gwei / previous_epoch_active_gwei`
|
|
|
|
Expresses the ratio of validators that managed to have an attestation
|
|
voting upon the previous epoch included in a block.
|
|
|
|
#### 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
|
|
|
|
```bash
|
|
curl -X GET "http://localhost:5052/lighthouse/validator_inclusion/0/global" -H "accept: application/json" | jq
|
|
```
|
|
|
|
```json
|
|
{
|
|
"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](#consensusglobal_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
|
|
|
|
```bash
|
|
curl -X GET "http://localhost:5052/lighthouse/validator_inclusion/0/42" -H "accept: application/json" | jq
|
|
```
|
|
|
|
```json
|
|
{
|
|
"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
|
|
}
|
|
}
|
|
```
|