The highest tagged major version is
Documentation
¶
Overview ¶
Package performance implements RPIP-73 target-vote performance verification.
RPIP-73 measures attestation performance using the "target" timeliness flag from the Beacon State's previous_epoch_participation vector. The flag is defined to be set for validator v in epoch E iff some attestation by v with data.target.epoch == E was:
- included in a block (which implies source-checkpoint matching), AND
- voting for the correct target root, i.e. data.target.root equals the canonical block root at the first slot of epoch E, AND
- included within SLOTS_PER_EPOCH slots of data.slot.
Index ¶
- Constants
- func CheckEpochTargetVote(bc PerformanceBeaconClient, cfg beacon.Eth2Config, validatorIndex uint64, ...) (bool, error)
- func EncodeParticipationBitset(startEpoch, endEpoch uint64, missedEpochs []uint64) []*big.Int
- func ExceedsChallengeThreshold(resp *api.VerifyPerformanceResponse) bool
- func FindFirstTimelyTargetVote(bc PerformanceBeaconClient, cfg beacon.Eth2Config, validatorIndices []uint64, ...) (validatorIndex uint64, epoch uint64, found bool, err error)
- func GetPerformanceThresholdPct(rp *rocketpool.RocketPool) (float64, error)
- func IsChallengeable(params ChallengeParams, currentEpoch, startEpoch, endEpoch uint64) bool
- func IsRangeChallengeable(rp *rocketpool.RocketPool, bc challengeBeaconClient, ...) (bool, error)
- func VerifyPerformance(rp *rocketpool.RocketPool, bc pubkeyBeaconClient, ...) (*api.VerifyPerformanceResponse, error)
- type BatchValidatorResult
- type ChallengeParams
- type EpochPerformance
- type PerformanceBeaconClient
- type PerformanceSummary
Constants ¶
const ( TimelySourceFlagIndex = 0 TimelyTargetFlagIndex = 1 TimelyHeadFlagIndex = 2 )
Beacon participation flag indices, see the Ethereum consensus spec (Altair upgrade). previous_epoch_participation packs these as bit flags per validator in a single byte.
const DefaultPerformancePeriodEpochs uint64 = 44032
DefaultPerformancePeriodEpochs is used by verify-performance when Saturn 2 is not deployed and there is no on-chain performance_period to read.
Variables ¶
This section is empty.
Functions ¶
func CheckEpochTargetVote ¶
func CheckEpochTargetVote( bc PerformanceBeaconClient, cfg beacon.Eth2Config, validatorIndex uint64, epoch uint64, ) (bool, error)
CheckEpochTargetVote returns true if the validator made a timely target vote for the given epoch. Returns (false, nil) for missed-target epochs; errors are reserved for I/O / parsing failures. If the validator was not in a committee for this epoch, the result is (true, nil) — there was no duty to perform, so it is not exit-eligible under RPIP-73.
This is the lightweight single-epoch entry point intended for use by a challenge defender, who only needs to find one timely epoch within the challenged range.
func EncodeParticipationBitset ¶
EncodeParticipationBitset encodes the missed epochs of the inclusive range [startEpoch, endEpoch] as the uint256[] bitset expected by the challengeMegapool participation calldata: the words form a single bit stream starting at startEpoch, LSB-first within each word, with a 1 bit marking a not-timely target attestation.
func ExceedsChallengeThreshold ¶
func ExceedsChallengeThreshold(resp *api.VerifyPerformanceResponse) bool
ExceedsChallengeThreshold reports whether the validator missed enough target votes for a challenge to succeed: the missed share of the checked period must be higher than the allowed slack (100% - performance_threshold).
func FindFirstTimelyTargetVote ¶
func FindFirstTimelyTargetVote( bc PerformanceBeaconClient, cfg beacon.Eth2Config, validatorIndices []uint64, epochs []uint64, ) (validatorIndex uint64, epoch uint64, found bool, err error)
FindFirstTimelyTargetVote scans the supplied validator indices over the supplied epochs and returns the first validator index (and the epoch) that made a valid target vote
func GetPerformanceThresholdPct ¶
func GetPerformanceThresholdPct(rp *rocketpool.RocketPool) (float64, error)
func IsChallengeable ¶
func IsChallengeable(params ChallengeParams, currentEpoch, startEpoch, endEpoch uint64) bool
IsChallengeable reports whether a performance check over the inclusive range [startEpoch, endEpoch] could back an on-chain challenge: performance exits must be enabled, the range must cover exactly one performance period, and it must be recent enough that the proof buffer has not elapsed (startEpoch > currentEpoch - period - proofBuffer).
func IsRangeChallengeable ¶
func IsRangeChallengeable(rp *rocketpool.RocketPool, bc challengeBeaconClient, startEpoch, endEpoch uint64) (bool, error)
IsRangeChallengeable fetches the pDAO challenge settings and the beacon head, then reports whether a performance check over the inclusive range [startEpoch, endEpoch] could back an on-chain challenge. See IsChallengeable for the rules.
func VerifyPerformance ¶
func VerifyPerformance( rp *rocketpool.RocketPool, bc pubkeyBeaconClient, pubkey rptypes.ValidatorPubkey, startEpoch uint64, endEpoch uint64, ) (*api.VerifyPerformanceResponse, error)
VerifyPerformance is the end-to-end RPIP-73 target-vote verification flow for a single validator. It resolves the validator's beacon-chain index from the supplied pubkey, runs CheckTargetPerformance, and packages the result alongside the pDAO performance_threshold for pass/fail reporting.
To verify several validators in one run, prefer VerifyPerformanceBatch, which shares per-epoch beacon data across all of them.
Types ¶
type BatchValidatorResult ¶
type BatchValidatorResult struct {
Pubkey rptypes.ValidatorPubkey
// Active reports whether the validator is currently active on the beacon
// chain (activated and not yet exited) according to its live head status.
// Callers that target "all" validators use this to skip validators that are
// not actively attesting.
Active bool
Response *api.VerifyPerformanceResponse
Err error
}
BatchValidatorResult is one validator's outcome from VerifyPerformanceBatch. Exactly one of Response or Err is set: Response when the check succeeded, Err when that single validator could not be verified (the rest of the batch is unaffected). The slice returned by VerifyPerformanceBatch is aligned positionally with the input pubkeys, so callers can map results back to their own identifiers (minipool address, megapool validator id, etc).
func VerifyPerformanceBatch ¶
func VerifyPerformanceBatch( rp *rocketpool.RocketPool, bc pubkeyBeaconClient, pubkeys []rptypes.ValidatorPubkey, startEpoch uint64, endEpoch uint64, ) ([]BatchValidatorResult, error)
VerifyPerformanceBatch verifies the RPIP-73 target-vote performance of many validators over the same inclusive epoch range in a single pass. All per-epoch beacon data (target roots, committee assignments, inclusion-window blocks) is fetched once via a shared epochCache and reused for every validator, and the validators' indices and statuses are resolved in a single batched beacon call.
The returned slice is positionally aligned with pubkeys. A fatal error (returned as the second value) only occurs for failures that prevent the whole batch from running, such as being unable to read the beacon config or resolve any validator statuses; per-validator problems are reported in each entry's Err field instead.
type ChallengeParams ¶
ChallengeParams are the pDAO settings governing performance challenges.
func GetChallengeParams ¶
func GetChallengeParams(rp *rocketpool.RocketPool) (ChallengeParams, error)
GetChallengeParams fetches the pDAO performance-challenge settings.
type EpochPerformance ¶
type EpochPerformance struct {
Epoch uint64 `json:"epoch"`
TimelyTarget bool `json:"timelyTarget"`
}
EpochPerformance is the per-epoch result of a target-vote check.
type PerformanceBeaconClient ¶
type PerformanceBeaconClient interface {
GetEth2Config() (beacon.Eth2Config, error)
GetHistoricalCommitteesForEpoch(epoch uint64) (beacon.Committees, error)
GetBeaconBlock(blockId string) (beacon.BeaconBlock, bool, error)
GetBeaconBlockHeader(blockId string) (beacon.BeaconBlockHeader, bool, error)
GetValidatorStatusByIndex(index string, opts *beacon.ValidatorStatusOptions) (beacon.ValidatorStatus, error)
}
PerformanceBeaconClient is the minimal beacon client surface used by the block-based target-vote engine.
type PerformanceSummary ¶
type PerformanceSummary struct {
ValidatorIndex uint64 `json:"validatorIndex"`
StartEpoch uint64 `json:"startEpoch"`
EndEpoch uint64 `json:"endEpoch"`
TotalEpochs uint64 `json:"totalEpochs"`
TimelyEpochs uint64 `json:"timelyEpochs"`
MissedEpochs uint64 `json:"missedEpochs"`
InactiveEpochs uint64 `json:"inactiveEpochs"`
PerformancePct float64 `json:"performancePct"`
MissedEpochList []uint64 `json:"missedEpochList"`
TimelyEpochList []uint64 `json:"timelyEpochList"`
}
PerformanceSummary aggregates the per-epoch results of a target-vote check over the inclusive range [StartEpoch, EndEpoch]. Epochs in which the validator was not assigned to any committee (i.e. not yet active or already exited) are counted in InactiveEpochs and excluded from PerformancePct's denominator.
func CheckTargetPerformance ¶
func CheckTargetPerformance( bc PerformanceBeaconClient, cfg beacon.Eth2Config, validatorIndex uint64, startEpoch uint64, endEpoch uint64, ) (*PerformanceSummary, error)
CheckTargetPerformance evaluates a single validator's target-vote performance over the inclusive epoch range [startEpoch, endEpoch] by reading the canonical target root, the validator's committee assignment, and the attestations in the inclusion window per epoch.
Source Files