balances

Documentation

Overview

Package balances contains libraries to calculate reward and penalty quotients. It computes new validator balances for justifications, crosslinks and attestation inclusions. It also computes penalties for the inactive validators.

Index

• func AttestationInclusion(state *pb.BeaconState, totalBalance uint64, prevEpochAttesterIndices []uint64) (*pb.BeaconState, error)
• func Crosslinks(state *pb.BeaconState, thisEpochAttestations []*pb.PendingAttestationRecord, ...) (*pb.BeaconState, error)
• func ExpectedBeaconChainHead(state *pb.BeaconState, headAttesterIndices []uint64, ...) *pb.BeaconState
• func ExpectedFFGSource(state *pb.BeaconState, justifiedAttesterIndices []uint64, ...) *pb.BeaconState
• func ExpectedFFGTarget(state *pb.BeaconState, boundaryAttesterIndices []uint64, ...) *pb.BeaconState
• func InactivityChainHead(state *pb.BeaconState, headAttesterIndices []uint64, totalBalance uint64) *pb.BeaconState
• func InactivityExitedPenalties(state *pb.BeaconState, totalBalance uint64, epochsSinceFinality uint64) *pb.BeaconState
• func InactivityFFGSource(state *pb.BeaconState, justifiedAttesterIndices []uint64, totalBalance uint64, ...) *pb.BeaconState
• func InactivityFFGTarget(state *pb.BeaconState, boundaryAttesterIndices []uint64, totalBalance uint64, ...) *pb.BeaconState
• func InactivityInclusionDistance(state *pb.BeaconState, attesterIndices []uint64, totalBalance uint64) (*pb.BeaconState, error)
• func InclusionDistance(state *pb.BeaconState, attesterIndices []uint64, totalBalance uint64) (*pb.BeaconState, error)

Functions

func AttestationInclusion

func AttestationInclusion(
	state *pb.BeaconState,
	totalBalance uint64,
	prevEpochAttesterIndices []uint64) (*pb.BeaconState, error)

AttestationInclusion awards the the beacon proposers who included previous epoch attestations.

Spec pseudocode definition:

For each index in previous_epoch_attester_indices,
we determine the proposer proposer_index =
get_beacon_proposer_index(state, inclusion_slot(state, index))
and set state.validator_balances[proposer_index] +=
base_reward(state, index) // INCLUDER_REWARD_QUOTIENT

func Crosslinks

func Crosslinks(
	state *pb.BeaconState,
	thisEpochAttestations []*pb.PendingAttestationRecord,
	prevEpochAttestations []*pb.PendingAttestationRecord) (*pb.BeaconState, error)

Crosslinks awards or penalizes attesters for attesting shard cross links.

Spec pseudocode definition:

For slot in range(get_epoch_start_slot(previous_epoch), get_epoch_start_slot(current_epoch)),
	let crosslink_committees_at_slot = get_crosslink_committees_at_slot(slot).
	For every (crosslink_committee, shard) in crosslink_committee_at_slot, compute:

		Let shard_block_root be state.latest_crosslinks[shard].shard_block_root
		Let attesting_validator_indices(shard_committee, shard_block_root)
			be the union of the validator index sets given by [get_attestation_participants(
			state, a.data, a.participation_bitfield) for a in current_epoch_attestations +
			previous_epoch_attestations if a.shard == shard and a.shard_block_root == shard_block_root].
		Let winning_root(shard_committee)
			be equal to the value of shard_block_root such that sum([get_effective_balance(state, i)
			for i in attesting_validator_indices(shard_committee, shard_block_root)])
			is maximized (ties broken by favoring lower shard_block_root values).
		Let attesting_validators(shard_committee)
			be equal to attesting_validator_indices(
			shard_committee, winning_root(shard_committee)) for convenience.
		Let total_attesting_balance(shard_committee) =
			sum([get_effective_balance(state, i) for i in attesting_validators(shard_committee)]).
		Let total_balance(shard_committee) =
			sum([get_effective_balance(state, i) for i in shard_committee]).

func ExpectedBeaconChainHead

func ExpectedBeaconChainHead(
	state *pb.BeaconState,
	headAttesterIndices []uint64,
	headAttestingBalance uint64,
	totalBalance uint64) *pb.BeaconState

ExpectedBeaconChainHead applies rewards or penalties for an expected beacon chain head. It uses total head attesting balances, total validator balances and base reward quotient to calculate the reward amount. Validators who voted for the canonical head block will get a reward, everyone else will get a penalty.

Spec pseudocode definition:

Any validator index in previous_epoch_head_attester_indices gains
base_reward(state, index) * previous_epoch_head_attesting_balance // total_balance).
Any active validator index not in previous_epoch_head_attester_indices loses
base_reward(state, index).

func ExpectedFFGSource

func ExpectedFFGSource(
	state *pb.BeaconState,
	justifiedAttesterIndices []uint64,
	justifiedAttestingBalance uint64,
	totalBalance uint64) *pb.BeaconState

ExpectedFFGSource applies rewards or penalties for an expected FFG source. It uses total justified attesting balances, total validator balances and base reward quotient to calculate the reward amount. Validators who voted for previous justified hash will get a reward, everyone else will get a penalty.

Spec pseudocode definition:

   Any validator index in previous_epoch_justified_attester_indices
   gains base_reward(state, index) * previous_epoch_justified_attesting_balance // total_balance.
	  Any active validator v not in previous_epoch_justified_attester_indices
	  loses base_reward(state, index).

func ExpectedFFGTarget

func ExpectedFFGTarget(
	state *pb.BeaconState,
	boundaryAttesterIndices []uint64,
	boundaryAttestingBalance uint64,
	totalBalance uint64) *pb.BeaconState

ExpectedFFGTarget applies rewards or penalties for an expected FFG target. It uses total boundary attesting balances, total validator balances and base reward quotient to calculate the reward amount. Validators who voted for epoch boundary block will get a reward, everyone else will get a penalty.

Spec pseudocode definition:

   Any validator index in previous_epoch_boundary_attester_indices gains
   base_reward(state, index) * previous_epoch_boundary_attesting_balance // total_balance.
	  Any active validator index not in previous_epoch_boundary_attester_indices loses
	  base_reward(state, index).

func InactivityChainHead

func InactivityChainHead(
	state *pb.BeaconState,
	headAttesterIndices []uint64,
	totalBalance uint64) *pb.BeaconState

InactivityChainHead applies penalties to inactive validators that missed to vote on canonical head over an extended of time. (epochs_since_finality > 4)

Spec pseudocode definition:

   Any active validator index not in previous_epoch_head_attester_indices,
	  loses base_reward(state, index)

func InactivityExitedPenalties

func InactivityExitedPenalties(
	state *pb.BeaconState,
	totalBalance uint64,
	epochsSinceFinality uint64) *pb.BeaconState

InactivityExitedPenalties applies additional (2x) penalties to inactive validators with status EXITED_WITH_PENALTY.

Spec pseudocode definition:

Any active_validator index with validator.penalized_epoch <= current_epoch,
loses 2 * inactivity_penalty(state, index, epochs_since_finality) +
base_reward(state, index).

func InactivityFFGSource

func InactivityFFGSource(
	state *pb.BeaconState,
	justifiedAttesterIndices []uint64,
	totalBalance uint64,
	epochsSinceFinality uint64) *pb.BeaconState

InactivityFFGSource applies penalties to inactive validators that missed to vote FFG source over an extended of time. (epochs_since_finality > 4)

Spec pseudocode definition:

Any active validator index not in previous_epoch_justified_attester_indices,
loses inactivity_penalty(state, index, epochs_since_finality)

func InactivityFFGTarget

func InactivityFFGTarget(
	state *pb.BeaconState,
	boundaryAttesterIndices []uint64,
	totalBalance uint64,
	epochsSinceFinality uint64) *pb.BeaconState

InactivityFFGTarget applies penalties to inactive validators that missed to vote FFG target over an extended of time. (epochs_since_finality > 4)

Spec pseudocode definition:

   Any active validator index not in previous_epoch_boundary_attester_indices,
	  loses inactivity_penalty(state, index, epochs_since_finality)

func InactivityInclusionDistance

func InactivityInclusionDistance(
	state *pb.BeaconState,
	attesterIndices []uint64,
	totalBalance uint64) (*pb.BeaconState, error)

InactivityInclusionDistance applies penalties in relation with inclusion delay to inactive validators.

Spec pseudocode definition:

Any validator index in previous_epoch_attester_indices loses
base_reward(state, index) - base_reward(state, index) *
MIN_ATTESTATION_INCLUSION_DELAY // inclusion_distance(state, index)

func InclusionDistance

func InclusionDistance(
	state *pb.BeaconState,
	attesterIndices []uint64,
	totalBalance uint64) (*pb.BeaconState, error)

InclusionDistance applies rewards based on inclusion distance. It uses calculated inclusion distance and base reward quotient to calculate the reward amount.

Spec pseudocode definition:

Any validator index in previous_epoch_attester_indices gains
base_reward(state, index) * MIN_ATTESTATION_INCLUSION_DELAY //
inclusion_distance(state, index)