helpers

package
v0.2.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 24, 2019 License: GPL-3.0 Imports: 18 Imported by: 0

Documentation

Overview

Package helpers contains helper functions outlined in ETH2.0 spec beacon chain spec

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrAttestationDataSlotNilState is returned when a nil state argument
	// is provided to AttestationDataSlot.
	ErrAttestationDataSlotNilState = errors.New("nil state provided for AttestationDataSlot")
	// ErrAttestationDataSlotNilData is returned when a nil attestation data
	// argument is provided to AttestationDataSlot.
	ErrAttestationDataSlotNilData = errors.New("nil data provided for AttestationDataSlot")
	// ErrAttestationAggregationBitsOverlap is returned when two attestations aggregation
	// bits overlap with each other.
	ErrAttestationAggregationBitsOverlap = errors.New("overlapping aggregation bits")
)
View Source
var ErrInvalidStateLatestActiveIndexRoots = errors.New("state does not have correct number of latest active index roots")

ErrInvalidStateLatestActiveIndexRoots is returned when the state active index root count does not match the expected EpochsPerHistoricalVector.

Functions

func ActiveIndexRoot

func ActiveIndexRoot(state *pb.BeaconState, epoch uint64) []byte

ActiveIndexRoot returns the index root of a given epoch.

Spec pseudocode definition:

def get_active_index_root(state: BeaconState,
                       epoch: Epoch) -> Bytes32:
 """
 Return the index root at a recent ``epoch``.
 ``epoch`` expected to be between
 (current_epoch - LATEST_ACTIVE_INDEX_ROOTS_LENGTH + ACTIVATION_EXIT_DELAY, current_epoch + ACTIVATION_EXIT_DELAY].
 """
 return state.latest_active_index_roots[epoch % LATEST_ACTIVE_INDEX_ROOTS_LENGTH]

func ActiveIndicesKeys

func ActiveIndicesKeys() []string

ActiveIndicesKeys returns the keys of the active indices cache.

func ActiveValidatorCount

func ActiveValidatorCount(state *pb.BeaconState, epoch uint64) (uint64, error)

ActiveValidatorCount returns the number of active validators in the state at the given epoch.

func ActiveValidatorIndices

func ActiveValidatorIndices(state *pb.BeaconState, epoch uint64) ([]uint64, error)

ActiveValidatorIndices filters out active validators based on validator status and returns their indices in a list.

WARNING: This method allocates a new copy of the validator index set and is considered to be very memory expensive. Avoid using this unless you really need the active validator indices for some specific reason.

Spec pseudocode definition:

def get_active_validator_indices(state: BeaconState, epoch: Epoch) -> Sequence[ValidatorIndex]:
  """
  Return the sequence of active validator indices at ``epoch``.
  """
  return [ValidatorIndex(i) for i, v in enumerate(state.validators) if is_active_validator(v, epoch)]

func AggregateAttestation

func AggregateAttestation(a1 *ethpb.Attestation, a2 *ethpb.Attestation) (*ethpb.Attestation, error)

AggregateAttestation aggregates attestations a1 and a2 together.

func AggregateAttestations

func AggregateAttestations(atts []*ethpb.Attestation) ([]*ethpb.Attestation, error)

AggregateAttestations such that the minimal number of attestations are returned. Note: this is currently a naive implementation to the order of O(n^2).

func AttestationDataSlot

func AttestationDataSlot(state *pb.BeaconState, data *ethpb.AttestationData) (uint64, error)

AttestationDataSlot returns current slot of AttestationData for given state

Spec pseudocode definition:

def get_attestation_data_slot(state: BeaconState, data: AttestationData) -> Slot:
 """
 Return the slot corresponding to the attestation ``data``.
 """
 committee_count = get_committee_count(state, data.target.epoch)
 offset = (data.crosslink.shard + SHARD_COUNT - get_start_shard(state, data.target.epoch)) % SHARD_COUNT
 return Slot(compute_start_slot_of_epoch(data.target.epoch) + offset // (committee_count // SLOTS_PER_EPOCH))

func AttestingIndices

func AttestingIndices(state *pb.BeaconState, data *ethpb.AttestationData, bf bitfield.Bitfield) ([]uint64, error)

AttestingIndices returns the attesting participants indices from the attestation data.

Spec pseudocode definition:

def get_attesting_indices(state: BeaconState,
                       data: AttestationData,
                       bits: Bitlist[MAX_VALIDATORS_PER_COMMITTEE]) -> Set[ValidatorIndex]:
 """
 Return the set of attesting indices corresponding to ``data`` and ``bits``.
 """
 committee = get_crosslink_committee(state, data.target.epoch, data.crosslink.shard)
 return set(index for i, index in enumerate(committee) if bits[i])

func BeaconProposerIndex

func BeaconProposerIndex(state *pb.BeaconState) (uint64, error)

BeaconProposerIndex returns proposer index of a current slot.

Spec pseudocode definition:

def get_beacon_proposer_index(state: BeaconState) -> ValidatorIndex:
  """
  Return the beacon proposer index at the current slot.
  """
  epoch = get_current_epoch(state)
  committees_per_slot = get_committee_count(state, epoch) // SLOTS_PER_EPOCH
  offset = committees_per_slot * (state.slot % SLOTS_PER_EPOCH)
  shard = Shard((get_start_shard(state, epoch) + offset) % SHARD_COUNT)
  first_committee = get_crosslink_committee(state, epoch, shard)
  MAX_RANDOM_BYTE = 2**8 - 1
  seed = get_seed(state, epoch)
  i = 0
  while True:
      candidate_index = first_committee[(epoch + i) % len(first_committee)]
      random_byte = hash(seed + int_to_bytes(i // 32, length=8))[i % 32]
      effective_balance = state.validators[candidate_index].effective_balance
      if effective_balance * MAX_RANDOM_BYTE >= MAX_EFFECTIVE_BALANCE * random_byte:
          return ValidatorIndex(candidate_index)
      i += 1

func BlockRoot

func BlockRoot(state *pb.BeaconState, epoch uint64) ([]byte, error)

BlockRoot returns the block root stored in the BeaconState for epoch start slot.

Spec pseudocode definition:

def get_block_root(state: BeaconState, epoch: Epoch) -> Hash:
  """
  Return the block root at the start of a recent ``epoch``.
  """
  return get_block_root_at_slot(state, compute_start_slot_of_epoch(epoch))

func BlockRootAtSlot

func BlockRootAtSlot(state *pb.BeaconState, slot uint64) ([]byte, error)

BlockRootAtSlot returns the block root stored in the BeaconState for a recent slot. It returns an error if the requested block root is not within the slot range.

Spec pseudocode definition:

def get_block_root_at_slot(state: BeaconState, slot: Slot) -> Hash:
  """
  Return the block root at a recent ``slot``.
  """
  assert slot < state.slot <= slot + SLOTS_PER_HISTORICAL_ROOT
  return state.block_roots[slot % SLOTS_PER_HISTORICAL_ROOT]

func ClearActiveCountCache

func ClearActiveCountCache()

ClearActiveCountCache restarts the active validator count cache from scratch.

func ClearActiveIndicesCache

func ClearActiveIndicesCache()

ClearActiveIndicesCache restarts the active validator indices cache from scratch.

func ClearAllCaches

func ClearAllCaches()

ClearAllCaches clears all the helpers caches from scratch.

func ClearShuffledValidatorCache

func ClearShuffledValidatorCache()

ClearShuffledValidatorCache clears the shuffled indices cache from scratch.

func CommitteeAssignment

func CommitteeAssignment(
	state *pb.BeaconState,
	epoch uint64,
	validatorIndex uint64) ([]uint64, uint64, uint64, bool, error)

CommitteeAssignment is used to query committee assignment from current and previous epoch.

Spec pseudocode definition:

def get_committee_assignment(state: BeaconState,
                          epoch: Epoch,
                          validator_index: ValidatorIndex) -> Optional[Tuple[Sequence[ValidatorIndex], Shard, Slot]]:
 """
 Return the committee assignment in the ``epoch`` for ``validator_index``.
 ``assignment`` returned is a tuple of the following form:
     * ``assignment[0]`` is the list of validators in the committee
     * ``assignment[1]`` is the shard to which the committee is assigned
     * ``assignment[2]`` is the slot at which the committee is assigned
 Return None if no assignment.
 """
 next_epoch = get_current_epoch(state) + 1
 assert epoch <= next_epoch

 committees_per_slot = get_committee_count(state, epoch) // SLOTS_PER_EPOCH
 start_slot = compute_start_slot_of_epoch(epoch)
 for slot in range(start_slot, start_slot + SLOTS_PER_EPOCH):
     offset = committees_per_slot * (slot % SLOTS_PER_EPOCH)
     slot_start_shard = (get_start_shard(state, epoch) + offset) % SHARD_COUNT
     for i in range(committees_per_slot):
         shard = Shard((slot_start_shard + i) % SHARD_COUNT)
         committee = get_crosslink_committee(state, epoch, shard)
         if validator_index in committee:
             return committee, shard, Slot(slot)
 return None

func CommitteeCount

func CommitteeCount(state *pb.BeaconState, epoch uint64) (uint64, error)

CommitteeCount returns the number of crosslink committees of an epoch.

Spec pseudocode definition:

def get_committee_count(state: BeaconState, epoch: Epoch) -> uint64:
 """
 Return the number of committees at ``epoch``.
 """
 committees_per_slot = max(1, min(
     SHARD_COUNT // SLOTS_PER_EPOCH,
     len(get_active_validator_indices(state, epoch)) // SLOTS_PER_EPOCH // TARGET_COMMITTEE_SIZE,
 ))
 return committees_per_slot * SLOTS_PER_EPOCH

func CompactCommitteesRoot

func CompactCommitteesRoot(state *pb.BeaconState, epoch uint64) ([32]byte, error)

CompactCommitteesRoot returns the index root of a given epoch.

Spec pseudocode definition:

def get_compact_committees_root(state: BeaconState, epoch: Epoch) -> Hash:
 """
 Return the compact committee root at ``epoch``.
 """
 committees = [CompactCommittee() for _ in range(SHARD_COUNT)]
 start_shard = get_epoch_start_shard(state, epoch)
 for committee_number in range(get_epoch_committee_count(state, epoch)):
     shard = Shard((start_shard + committee_number) % SHARD_COUNT)
     for index in get_crosslink_committee(state, epoch, shard):
         validator = state.validators[index]
         committees[shard].pubkeys.append(validator.pubkey)
         compact_balance = validator.effective_balance // EFFECTIVE_BALANCE_INCREMENT
         # `index` (top 6 bytes) + `slashed` (16th bit) + `compact_balance` (bottom 15 bits)
         compact_validator = uint64((index << 16) + (validator.slashed << 15) + compact_balance)
         committees[shard].compact_validators.append(compact_validator)
 return hash_tree_root(Vector[CompactCommittee, SHARD_COUNT](committees))

func ComputeCommittee

func ComputeCommittee(
	validatorIndices []uint64,
	seed [32]byte,
	indexShard uint64,
	totalCommittees uint64,
) ([]uint64, error)

ComputeCommittee returns the requested shuffled committee out of the total committees using validator indices and seed.

Spec pseudocode definition:

def compute_committee(indices: Sequence[ValidatorIndex],
                    seed: Hash,
                    index: uint64,
                    count: uint64) -> Sequence[ValidatorIndex]:
  """
  Return the committee corresponding to ``indices``, ``seed``, ``index``, and committee ``count``.
  """
  start = (len(indices) * index) // count
  end = (len(indices) * (index + 1)) // count
  return [indices[compute_shuffled_index(ValidatorIndex(i), len(indices), seed)] for i in range(start, end)

func CrosslinkCommittee

func CrosslinkCommittee(state *pb.BeaconState, epoch uint64, shard uint64) ([]uint64, error)

CrosslinkCommittee returns the crosslink committee of a given epoch.

Spec pseudocode definition:

def get_crosslink_committee(state: BeaconState, epoch: Epoch, shard: Shard) -> Sequence[ValidatorIndex]:
 """
 Return the crosslink committee at ``epoch`` for ``shard``.
 """
 return compute_committee(
     indices=get_active_validator_indices(state, epoch),
     seed=get_seed(state, epoch),
     index=(shard + SHARD_COUNT - get_start_shard(state, epoch)) % SHARD_COUNT,
     count=get_committee_count(state, epoch),
 )

func CurrentEpoch

func CurrentEpoch(state *pb.BeaconState) uint64

CurrentEpoch returns the current epoch number calculated from the slot number stored in beacon state.

Spec pseudocode definition:

def get_current_epoch(state: BeaconState) -> Epoch:
  """
  Return the current epoch.
  """
  return compute_epoch_of_slot(state.slot)

func DecreaseBalance

func DecreaseBalance(state *pb.BeaconState, idx uint64, delta uint64) *pb.BeaconState

DecreaseBalance decreases validator with the given 'index' balance by 'delta' in Gwei.

Spec pseudocode definition:

def decrease_balance(state: BeaconState, index: ValidatorIndex, delta: Gwei) -> None:
  """
  Decrease the validator balance at index ``index`` by ``delta``, with underflow protection.
  """
  state.balances[index] = 0 if delta > state.balances[index] else state.balances[index] - delta

func DelayedActivationExitEpoch

func DelayedActivationExitEpoch(epoch uint64) uint64

DelayedActivationExitEpoch takes in epoch number and returns when the validator is eligible for activation and exit.

Spec pseudocode definition:

def compute_activation_exit_epoch(epoch: Epoch) -> Epoch:
  """
  Return the epoch during which validator activations and exits initiated in ``epoch`` take effect.
  """
  return Epoch(epoch + 1 + ACTIVATION_EXIT_DELAY)

func Domain

func Domain(fork *pb.Fork, epoch uint64, domainType []byte) uint64

Domain returns the domain version for BLS private key to sign and verify.

Spec pseudocode definition:

def get_domain(state: BeaconState,
             domain_type: int,
             message_epoch: Epoch=None) -> int:
  """
  Return the signature domain (fork version concatenated with domain type) of a message.
  """
  epoch = get_current_epoch(state) if message_epoch is None else message_epoch
  fork_version = state.fork.previous_version if epoch < state.fork.epoch else state.fork.current_version
  return bls_domain(domain_type, fork_version)

func IncreaseBalance

func IncreaseBalance(state *pb.BeaconState, idx uint64, delta uint64) *pb.BeaconState

IncreaseBalance increases validator with the given 'index' balance by 'delta' in Gwei.

Spec pseudocode definition:

def increase_balance(state: BeaconState, index: ValidatorIndex, delta: Gwei) -> None:
  """
  Increase the validator balance at index ``index`` by ``delta``.
  """
  state.balances[index] += delta

func IsActiveValidator

func IsActiveValidator(validator *ethpb.Validator, epoch uint64) bool

IsActiveValidator returns the boolean value on whether the validator is active or not.

Spec pseudocode definition:

def is_active_validator(validator: Validator, epoch: Epoch) -> bool:
  """
  Check if ``validator`` is active.
  """
  return validator.activation_epoch <= epoch < validator.exit_epoch

func IsEpochEnd

func IsEpochEnd(slot uint64) bool

IsEpochEnd returns true if the given slot number is an epoch ending slot number.

func IsEpochStart

func IsEpochStart(slot uint64) bool

IsEpochStart returns true if the given slot number is an epoch starting slot number.

func IsSlashableValidator

func IsSlashableValidator(validator *ethpb.Validator, epoch uint64) bool

IsSlashableValidator returns the boolean value on whether the validator is slashable or not.

Spec pseudocode definition:

 def is_slashable_validator(validator: Validator, epoch: Epoch) -> bool:
   """
   Check if ``validator`` is slashable.
   """
   return (
       validator.activation_epoch <= epoch < validator.withdrawable_epoch and
       validator.slashed is False
		)

func NextEpoch

func NextEpoch(state *pb.BeaconState) uint64

NextEpoch returns the next epoch number calculated form the slot number stored in beacon state.

func PrevEpoch

func PrevEpoch(state *pb.BeaconState) uint64

PrevEpoch returns the previous epoch number calculated from the slot number stored in beacon state. It alswo checks for underflow condition.

Spec pseudocode definition:

def get_previous_epoch(state: BeaconState) -> Epoch:
  """`
  Return the previous epoch (unless the current epoch is ``GENESIS_EPOCH``).
  """
  current_epoch = get_current_epoch(state)
  return GENESIS_EPOCH if current_epoch == GENESIS_EPOCH else Epoch(current_epoch - 1)

func RandaoMix

func RandaoMix(state *pb.BeaconState, epoch uint64) []byte

RandaoMix returns the randao mix (xor'ed seed) of a given slot. It is used to shuffle validators.

Spec pseudocode definition:

def get_randao_mix(state: BeaconState, epoch: Epoch) -> Hash:
 """
 Return the randao mix at a recent ``epoch``.
 """
 return state.randao_mixes[epoch % EPOCHS_PER_HISTORICAL_VECTOR]

func Seed

func Seed(state *pb.BeaconState, epoch uint64) ([32]byte, error)

Seed returns the randao seed used for shuffling of a given epoch.

Spec pseudocode definition:

def get_seed(state: BeaconState, epoch: Epoch) -> Hash:
  """
  Return the seed at ``epoch``.
  """
  mix = get_randao_mix(state, Epoch(epoch + EPOCHS_PER_HISTORICAL_VECTOR - MIN_SEED_LOOKAHEAD - 1)) #Avoid underflow
  active_index_root = state.active_index_roots[epoch % EPOCHS_PER_HISTORICAL_VECTOR]
  return hash(mix + active_index_root + int_to_bytes(epoch, length=32))

func ShardDelta

func ShardDelta(beaconState *pb.BeaconState, epoch uint64) (uint64, error)

ShardDelta returns the minimum number of shards get processed in one epoch.

Note: if you already have the committee count, use shardDeltaFromCommitteeCount as CommitteeCount (specifically ActiveValidatorCount) iterates over the entire validator set.

Spec pseudocode definition:

def get_shard_delta(state: BeaconState, epoch: Epoch) -> uint64:
  """
  Return the number of shards to increment ``state.start_shard`` at ``epoch``.
  """
  return min(get_committee_count(state, epoch), SHARD_COUNT - SHARD_COUNT // SLOTS_PER_EPOCH)

func ShuffleList

func ShuffleList(input []uint64, seed [32]byte) ([]uint64, error)

ShuffleList returns list of shuffled indexes in a pseudorandom permutation `p` of `0...list_size - 1` with “seed“ as entropy. We utilize 'swap or not' shuffling in this implementation; we are allocating the memory with the seed that stays constant between iterations instead of reallocating it each iteration as in the spec. This implementation is based on the original implementation from protolambda, https://github.com/protolambda/eth2-shuffle

improvements:
 - seed is always the first 32 bytes of the hash input, we just copy it into the buffer one time.
 - add round byte to seed and hash that part of the buffer.
 - split up the for-loop in two:
  1. Handle the part from 0 (incl) to pivot (incl). This is mirrored around (pivot / 2).
  2. Handle the part from pivot (excl) to N (excl). This is mirrored around ((pivot / 2) + (size/2)).
 - hash source every 256 iterations.
 - change byteV every 8 iterations.
 - we start at the edges, and work back to the mirror point.
   this makes us process each pear exactly once (instead of unnecessarily twice, like in the spec).

func ShuffledIndex

func ShuffledIndex(index uint64, indexCount uint64, seed [32]byte) (uint64, error)

ShuffledIndex returns `p(index)` in a pseudorandom permutation `p` of `0...list_size - 1` with “seed“ as entropy. We utilize 'swap or not' shuffling in this implementation; we are allocating the memory with the seed that stays constant between iterations instead of reallocating it each iteration as in the spec. This implementation is based on the original implementation from protolambda, https://github.com/protolambda/eth2-shuffle

func ShuffledIndices

func ShuffledIndices(state *pb.BeaconState, epoch uint64) ([]uint64, error)

ShuffledIndices uses input beacon state and returns the shuffled indices of the input epoch, the shuffled indices then can be used to break up into committees.

func SlotToEpoch

func SlotToEpoch(slot uint64) uint64

SlotToEpoch returns the epoch number of the input slot.

Spec pseudocode definition:

def compute_epoch_of_slot(slot: Slot) -> Epoch:
  """
  Return the epoch number of ``slot``.
  """
  return Epoch(slot // SLOTS_PER_EPOCH)

func SplitIndices

func SplitIndices(l []uint64, n uint64) [][]uint64

SplitIndices splits a list into n pieces.

func StartShard

func StartShard(state *pb.BeaconState, epoch uint64) (uint64, error)

StartShard returns the start shard used to process crosslink of a given epoch. The start shard is cached using epoch as key, it gets rewritten where there's a reorg or a new finalized block.

Spec pseudocode definition:

def get_start_shard(state: BeaconState, epoch: Epoch) -> Shard:
 """
 Return the start shard of the 0th committee at ``epoch``.
 """
 assert epoch <= get_current_epoch(state) + 1
 check_epoch = Epoch(get_current_epoch(state) + 1)
 shard = Shard((state.start_shard + get_shard_delta(state, get_current_epoch(state))) % SHARD_COUNT)
 while check_epoch > epoch:
     check_epoch -= Epoch(1)
     shard = Shard((shard + SHARD_COUNT - get_shard_delta(state, check_epoch)) % SHARD_COUNT)
 return shard

func StartSlot

func StartSlot(epoch uint64) uint64

StartSlot returns the first slot number of the current epoch.

Spec pseudocode definition:

def compute_start_slot_of_epoch(epoch: Epoch) -> Slot:
  """
  Return the start slot of ``epoch``.
  """
  return Slot(epoch * SLOTS_PER_EPOCH

func TotalActiveBalance

func TotalActiveBalance(state *pb.BeaconState) (uint64, error)

TotalActiveBalance returns the total amount at stake in Gwei of active validators.

Spec pseudocode definition:

def get_total_active_balance(state: BeaconState) -> Gwei:
 """
 Return the combined effective balance of the active validators.
 """
 return get_total_balance(state, set(get_active_validator_indices(state, get_current_epoch(state))))

func TotalBalance

func TotalBalance(state *pb.BeaconState, indices []uint64) uint64

TotalBalance returns the total amount at stake in Gwei of input validators.

Spec pseudocode definition:

def get_total_balance(state: BeaconState, indices: Set[ValidatorIndex]) -> Gwei:
 """
 Return the combined effective balance of the ``indices``. (1 Gwei minimum to avoid divisions by zero.)
 """
 return Gwei(max(1, sum([state.validators[index].effective_balance for index in indices])))

func UnShuffledIndex

func UnShuffledIndex(index uint64, indexCount uint64, seed [32]byte) (uint64, error)

UnShuffledIndex returns the inverse of ShuffledIndex. This implementation is based on the original implementation from protolambda, https://github.com/protolambda/eth2-shuffle

func UnshuffleList

func UnshuffleList(input []uint64, seed [32]byte) ([]uint64, error)

UnshuffleList un-shuffles the list by running backwards through the round count.

func UpdateCommitteeCache

func UpdateCommitteeCache(state *pb.BeaconState) error

UpdateCommitteeCache gets called at the beginning of every epoch to cache the committee shuffled indices list with start shard and epoch number. It caches the shuffled indices for current epoch and next epoch.

func ValidatorChurnLimit

func ValidatorChurnLimit(state *pb.BeaconState) (uint64, error)

ValidatorChurnLimit returns the number of validators that are allowed to enter and exit validator pool for an epoch.

Spec pseudocode definition:

def get_validator_churn_limit(state: BeaconState) -> uint64:
 """
 Return the validator churn limit for the current epoch.
 """
 active_validator_indices = get_active_validator_indices(state, get_current_epoch(state))
 return max(MIN_PER_EPOCH_CHURN_LIMIT, len(active_validator_indices) // CHURN_LIMIT_QUOTIENT)

func VerifyAttestationBitfieldLengths

func VerifyAttestationBitfieldLengths(bState *pb.BeaconState, att *ethpb.Attestation) error

VerifyAttestationBitfieldLengths verifies that an attestations aggregation and custody bitfields are a valid length matching the size of the committee.

func VerifyBitfieldLength

func VerifyBitfieldLength(bf bitfield.Bitfield, committeeSize uint64) error

VerifyBitfieldLength verifies that a bitfield length matches the given committee size.

func VerifySlotTime

func VerifySlotTime(genesisTime uint64, slot uint64) error

VerifySlotTime validates the input slot is not from the future.

Types

This section is empty.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL