helpers

package
v0.2.6 Latest Latest
Warning

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

 Go to latest Published: Nov 21, 2019 License: GPL-3.0 Imports: 16 Imported by: 231

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 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 AggregateSignature added in v0.2.5 

func AggregateSignature(attestations []*ethpb.Attestation) (*bls.Signature, error)

AggregateSignature returns the aggregated signature of the input attestations.

Spec pseudocode definition: 

def get_aggregate_signature(attestations: Sequence[Attestation]) -> BLSSignature:
 signatures = [attestation.signature for attestation in attestations]
 return bls_aggregate_signatures(signatures)

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_beacon_committee(state, data.slot, data.index)
 return set(index for i, index in enumerate(committee) if bits[i])

func BeaconCommittee added in v0.2.3 

func BeaconCommittee(state *pb.BeaconState, slot uint64, index uint64) ([]uint64, error)

BeaconCommittee returns the crosslink committee of a given epoch.

Spec pseudocode definition: 

def get_beacon_committee(state: BeaconState, slot: Slot, index: CommitteeIndex) -> Sequence[ValidatorIndex]:
 """
 Return the beacon committee at ``slot`` for ``index``.
 """
 epoch = compute_epoch_at_slot(slot)
 committees_per_slot = get_committee_count_at_slot(state, slot)
 epoch_offset = index + (slot % SLOTS_PER_EPOCH) * committees_per_slot
 return compute_committee(
     indices=get_active_validator_indices(state, epoch),
     seed=get_seed(state, epoch, DOMAIN_BEACON_ATTESTER),
     index=epoch_offset,
     count=committees_per_slot * SLOTS_PER_EPOCH,
 )

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)
  seed = hash(get_seed(state, epoch, DOMAIN_BEACON_PROPOSER) + int_to_bytes(state.slot, length=8))
  indices = get_active_validator_indices(state, epoch)
  return compute_proposer_index(state, indices, seed)

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 CommitteeAssignment 

func CommitteeAssignment(
	state *pb.BeaconState,
	epoch uint64,
	validatorIndex uint64,
) ([]uint64, uint64, uint64, uint64, 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], CommitteeIndex, 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 index 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

 start_slot = compute_start_slot_at_epoch(epoch)
 for slot in range(start_slot, start_slot + SLOTS_PER_EPOCH):
     for index in range(get_committee_count_at_slot(state, Slot(slot))):
         committee = get_beacon_committee(state, Slot(slot), CommitteeIndex(index))
         if validator_index in committee:
             return committee, CommitteeIndex(index), Slot(slot)
 return None

func CommitteeCountAtSlot added in v0.2.3 

func CommitteeCountAtSlot(state *pb.BeaconState, slot uint64) (uint64, error)

CommitteeCountAtSlot returns the number of crosslink committees of a slot.

Spec pseudocode definition: 

def get_committee_count_at_slot(state: BeaconState, slot: Slot) -> uint64:
 """
 Return the number of committees at ``slot``.
 """
 epoch = compute_epoch_at_slot(slot)
 return max(1, min(
     MAX_COMMITTEES_PER_SLOT,
     len(get_active_validator_indices(state, epoch)) // SLOTS_PER_EPOCH // TARGET_COMMITTEE_SIZE,
 ))

func ComputeCommittee 

func ComputeCommittee(
	indices []uint64,
	seed [32]byte,
	index uint64,
	count 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 ComputeProposerIndex added in v0.2.3 

func ComputeProposerIndex(state *pb.BeaconState, indices []uint64, seed [32]byte) (uint64, error)

ComputeProposerIndex returns the index sampled by effective balance, which is used to calculate proposer.

Spec pseudocode definition: 

def compute_proposer_index(state: BeaconState, indices: Sequence[ValidatorIndex], seed: Hash) -> ValidatorIndex:
  """
  Return from ``indices`` a random index sampled by effective balance.
  """
  assert len(indices) > 0
  MAX_RANDOM_BYTE = 2**8 - 1
  i = 0
  while True:
      candidate_index = indices[compute_shuffled_index(ValidatorIndex(i % len(indices)), len(indices), seed)]
      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 ComputeShuffledIndex added in v0.2.3 

func ComputeShuffledIndex(index uint64, indexCount uint64, seed [32]byte, shuffle bool) (uint64, error)

ComputeShuffledIndex returns the shuffled validator index corresponding to seed and index count. Spec pseudocode definition: 

def compute_shuffled_index(index: ValidatorIndex, index_count: uint64, seed: Hash) -> ValidatorIndex:
 """
 Return the shuffled validator index corresponding to ``seed`` (and ``index_count``).
 """
 assert index < index_count

 # Swap or not (https://link.springer.com/content/pdf/10.1007%2F978-3-642-32009-5_1.pdf)
 # See the 'generalized domain' algorithm on page 3
 for current_round in range(SHUFFLE_ROUND_COUNT):
     pivot = bytes_to_int(hash(seed + int_to_bytes(current_round, length=1))[0:8]) % index_count
     flip = ValidatorIndex((pivot + index_count - index) % index_count)
     position = max(index, flip)
     source = hash(seed + int_to_bytes(current_round, length=1) + int_to_bytes(position // 256, length=4))
     byte = source[(position % 256) // 8]
     bit = (byte >> (position % 8)) % 2
     index = flip if bit else index

 return ValidatorIndex(index)

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 IsAggregator added in v0.2.5 

func IsAggregator(state *pb.BeaconState, slot uint64, index uint64, slotSig *bls.Signature) (bool, error)

IsAggregator returns true if the signature is from the input validator.

Spec pseudocode definition: 

def is_aggregator(state: BeaconState, slot: Slot, index: CommitteeIndex, slot_signature: BLSSignature) -> bool:
 committee = get_beacon_committee(state, slot, index)
 modulo = max(1, len(committee) // TARGET_AGGREGATORS_PER_COMMITTEE)
 return bytes_to_int(hash(slot_signature)[0:8]) % modulo == 0

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, domain []byte) ([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, domain_type: DomainType) -> Hash:
  """
  Return the seed at ``epoch``.
  """
  mix = get_randao_mix(state, Epoch(epoch + EPOCHS_PER_HISTORICAL_VECTOR - MIN_SEED_LOOKAHEAD - 1))  # Avoid underflow
  return hash(domain_type + int_to_bytes(epoch, length=8) + mix)

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 SlotSignature added in v0.2.5 

func SlotSignature(state *pb.BeaconState, slot uint64, privKey *bls.SecretKey) (*bls.Signature, error)

SlotSignature returns the signed signature of the hash tree root of input slot.

Spec pseudocode definition: 

def slot_signature(state: BeaconState, slot: Slot, privkey: int) -> BLSSignature:
 domain = get_domain(state, DOMAIN_BEACON_ATTESTER, compute_epoch_at_slot(slot))
 return bls_sign(privkey, hash_tree_root(slot), domain)

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 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 committee index and epoch number. It caches the shuffled indices for current epoch and next epoch.

func ValidatorChurnLimit 

func ValidatorChurnLimit(activeValidatorCount uint64) (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.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.