mark comments documenting functions as a whole as such (#1613)
This commit is contained in:
tersec
GitHub
parent
dde26f359f
commit
b3b578501a
|
|
@ -37,14 +37,14 @@ func is_valid_merkle_branch*(leaf: Eth2Digest, branch: openarray[Eth2Digest],
|
|||
# https://github.com/ethereum/eth2.0-specs/blob/v0.12.2/specs/phase0/beacon-chain.md#increase_balance
|
||||
func increase_balance*(
|
||||
state: var BeaconState, index: ValidatorIndex, delta: Gwei) =
|
||||
# Increase the validator balance at index ``index`` by ``delta``.
|
||||
## Increase the validator balance at index ``index`` by ``delta``.
|
||||
state.balances[index] += delta
|
||||
|
||||
# https://github.com/ethereum/eth2.0-specs/blob/v0.12.2/specs/phase0/beacon-chain.md#decrease_balance
|
||||
func decrease_balance*(
|
||||
state: var BeaconState, index: ValidatorIndex, delta: Gwei) =
|
||||
# Decrease the validator balance at index ``index`` by ``delta``, with
|
||||
# underflow protection.
|
||||
## Decrease the validator balance at index ``index`` by ``delta``, with
|
||||
## underflow protection.
|
||||
state.balances[index] =
|
||||
if delta > state.balances[index]:
|
||||
0'u64
|
||||
|
|
@ -73,7 +73,7 @@ proc process_deposit*(preset: RuntimePreset,
|
|||
state: var BeaconState,
|
||||
deposit: Deposit,
|
||||
flags: UpdateFlags = {}): Result[void, cstring] {.nbench.}=
|
||||
# Process an Eth1 deposit, registering a validator or increasing its balance.
|
||||
## Process an Eth1 deposit, registering a validator or increasing its balance.
|
||||
|
||||
# Verify the Merkle branch
|
||||
if not is_valid_merkle_branch(
|
||||
|
|
@ -129,7 +129,7 @@ func compute_activation_exit_epoch*(epoch: Epoch): Epoch =
|
|||
|
||||
# https://github.com/ethereum/eth2.0-specs/blob/v0.12.2/specs/phase0/beacon-chain.md#get_validator_churn_limit
|
||||
func get_validator_churn_limit(state: BeaconState, cache: var StateCache): uint64 =
|
||||
# Return the validator churn limit for the current epoch.
|
||||
## Return the validator churn limit for the current epoch.
|
||||
max(
|
||||
MIN_PER_EPOCH_CHURN_LIMIT,
|
||||
count_active_validators(
|
||||
|
|
@ -138,7 +138,7 @@ func get_validator_churn_limit(state: BeaconState, cache: var StateCache): uint6
|
|||
# https://github.com/ethereum/eth2.0-specs/blob/v0.12.2/specs/phase0/beacon-chain.md#initiate_validator_exit
|
||||
func initiate_validator_exit*(state: var BeaconState,
|
||||
index: ValidatorIndex, cache: var StateCache) =
|
||||
# Initiate the exit of the validator with index ``index``.
|
||||
## Initiate the exit of the validator with index ``index``.
|
||||
|
||||
# Return if validator already initiated exit
|
||||
let validator = addr state.validators[index]
|
||||
|
|
@ -167,7 +167,7 @@ func initiate_validator_exit*(state: var BeaconState,
|
|||
# https://github.com/ethereum/eth2.0-specs/blob/v0.12.2/specs/phase0/beacon-chain.md#slash_validator
|
||||
proc slash_validator*(state: var BeaconState, slashed_index: ValidatorIndex,
|
||||
cache: var StateCache) =
|
||||
# Slash the validator with index ``index``.
|
||||
## Slash the validator with index ``index``.
|
||||
let epoch = get_current_epoch(state)
|
||||
initiate_validator_exit(state, slashed_index, cache)
|
||||
let validator = addr state.validators[slashed_index]
|
||||
|
|
@ -320,7 +320,7 @@ func get_initial_beacon_block*(state: BeaconState): SignedBeaconBlock =
|
|||
# https://github.com/ethereum/eth2.0-specs/blob/v0.12.2/specs/phase0/beacon-chain.md#get_block_root_at_slot
|
||||
func get_block_root_at_slot*(state: BeaconState,
|
||||
slot: Slot): Eth2Digest =
|
||||
# Return the block root at a recent ``slot``.
|
||||
## Return the block root at a recent ``slot``.
|
||||
|
||||
# Potential overflow/wrap shouldn't occur, as get_block_root_at_slot() called
|
||||
# from internally controlled sources, but flag this explicitly, in case.
|
||||
|
|
@ -332,7 +332,7 @@ func get_block_root_at_slot*(state: BeaconState,
|
|||
|
||||
# https://github.com/ethereum/eth2.0-specs/blob/v0.12.2/specs/phase0/beacon-chain.md#get_block_root
|
||||
func get_block_root*(state: BeaconState, epoch: Epoch): Eth2Digest =
|
||||
# Return the block root at the start of a recent ``epoch``.
|
||||
## Return the block root at the start of a recent ``epoch``.
|
||||
get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch))
|
||||
|
||||
# https://github.com/ethereum/eth2.0-specs/blob/v0.12.2/specs/phase0/beacon-chain.md#get_total_balance
|
||||
|
|
@ -346,14 +346,14 @@ func get_total_balance*(state: BeaconState, validators: auto): Gwei =
|
|||
|
||||
# https://github.com/ethereum/eth2.0-specs/blob/v0.12.2/specs/phase0/beacon-chain.md#is_eligible_for_activation_queue
|
||||
func is_eligible_for_activation_queue(validator: Validator): bool =
|
||||
# Check if ``validator`` is eligible to be placed into the activation queue.
|
||||
## Check if ``validator`` is eligible to be placed into the activation queue.
|
||||
validator.activation_eligibility_epoch == FAR_FUTURE_EPOCH and
|
||||
validator.effective_balance == MAX_EFFECTIVE_BALANCE
|
||||
|
||||
# https://github.com/ethereum/eth2.0-specs/blob/v0.12.2/specs/phase0/beacon-chain.md#is_eligible_for_activation
|
||||
func is_eligible_for_activation(state: BeaconState, validator: Validator):
|
||||
bool =
|
||||
# Check if ``validator`` is eligible for activation.
|
||||
## Check if ``validator`` is eligible for activation.
|
||||
|
||||
# Placement in queue is finalized
|
||||
validator.activation_eligibility_epoch <= state.finalized_checkpoint.epoch and
|
||||
|
|
@ -423,8 +423,8 @@ proc process_registry_updates*(state: var BeaconState,
|
|||
proc is_valid_indexed_attestation*(
|
||||
state: BeaconState, indexed_attestation: SomeIndexedAttestation,
|
||||
flags: UpdateFlags): Result[void, cstring] =
|
||||
# Check if ``indexed_attestation`` is not empty, has sorted and unique
|
||||
# indices and has a valid aggregate signature.
|
||||
## Check if ``indexed_attestation`` is not empty, has sorted and unique
|
||||
## indices and has a valid aggregate signature.
|
||||
|
||||
template is_sorted_and_unique(s: untyped): bool =
|
||||
var res = true
|
||||
|
|
@ -491,7 +491,7 @@ func get_attesting_indices*(state: BeaconState,
|
|||
# https://github.com/ethereum/eth2.0-specs/blob/v0.12.2/specs/phase0/beacon-chain.md#get_indexed_attestation
|
||||
func get_indexed_attestation*(state: BeaconState, attestation: Attestation,
|
||||
cache: var StateCache): IndexedAttestation =
|
||||
# Return the indexed attestation corresponding to ``attestation``.
|
||||
## Return the indexed attestation corresponding to ``attestation``.
|
||||
let
|
||||
attesting_indices =
|
||||
get_attesting_indices(
|
||||
|
|
@ -507,7 +507,7 @@ func get_indexed_attestation*(state: BeaconState, attestation: Attestation,
|
|||
|
||||
func get_indexed_attestation*(state: BeaconState, attestation: TrustedAttestation,
|
||||
cache: var StateCache): TrustedIndexedAttestation =
|
||||
# Return the indexed attestation corresponding to ``attestation``.
|
||||
## Return the indexed attestation corresponding to ``attestation``.
|
||||
let
|
||||
attesting_indices =
|
||||
get_attesting_indices(
|
||||
|
|
|
|||
|
|
@ -24,7 +24,7 @@ type
|
|||
|
||||
# https://github.com/ethereum/eth2.0-specs/blob/v0.12.2/specs/phase0/beacon-chain.md#integer_squareroot
|
||||
func integer_squareroot*(n: SomeInteger): SomeInteger =
|
||||
# Return the largest integer ``x`` such that ``x**2 <= n``.
|
||||
## Return the largest integer ``x`` such that ``x**2 <= n``.
|
||||
doAssert n >= 0'u64
|
||||
|
||||
var
|
||||
|
|
@ -37,7 +37,7 @@ func integer_squareroot*(n: SomeInteger): SomeInteger =
|
|||
|
||||
# https://github.com/ethereum/eth2.0-specs/blob/v0.12.2/specs/phase0/beacon-chain.md#compute_epoch_at_slot
|
||||
func compute_epoch_at_slot*(slot: Slot|uint64): Epoch =
|
||||
# Return the epoch number at ``slot``.
|
||||
## Return the epoch number at ``slot``.
|
||||
(slot div SLOTS_PER_EPOCH).Epoch
|
||||
|
||||
template epoch*(slot: Slot): Epoch =
|
||||
|
|
@ -48,25 +48,25 @@ template isEpoch*(slot: Slot): bool =
|
|||
|
||||
# https://github.com/ethereum/eth2.0-specs/blob/v0.12.2/specs/phase0/beacon-chain.md#compute_start_slot_at_epoch
|
||||
func compute_start_slot_at_epoch*(epoch: Epoch): Slot =
|
||||
# Return the start slot of ``epoch``.
|
||||
## Return the start slot of ``epoch``.
|
||||
(epoch * SLOTS_PER_EPOCH).Slot
|
||||
|
||||
# https://github.com/ethereum/eth2.0-specs/blob/v0.12.2/specs/phase0/beacon-chain.md#is_active_validator
|
||||
func is_active_validator*(validator: Validator, epoch: Epoch): bool =
|
||||
### Check if ``validator`` is active
|
||||
## Check if ``validator`` is active
|
||||
validator.activation_epoch <= epoch and epoch < validator.exit_epoch
|
||||
|
||||
# https://github.com/ethereum/eth2.0-specs/blob/v0.12.2/specs/phase0/beacon-chain.md#get_active_validator_indices
|
||||
func get_active_validator_indices*(state: BeaconState, epoch: Epoch):
|
||||
seq[ValidatorIndex] =
|
||||
# Return the sequence of active validator indices at ``epoch``.
|
||||
## Return the sequence of active validator indices at ``epoch``.
|
||||
for idx, val in state.validators:
|
||||
if is_active_validator(val, epoch):
|
||||
result.add idx.ValidatorIndex
|
||||
|
||||
# https://github.com/ethereum/eth2.0-specs/blob/v0.12.2/specs/phase0/beacon-chain.md#get_current_epoch
|
||||
func get_current_epoch*(state: BeaconState): Epoch =
|
||||
# Return the current epoch.
|
||||
## Return the current epoch.
|
||||
doAssert state.slot >= GENESIS_SLOT, $state.slot
|
||||
compute_epoch_at_slot(state.slot)
|
||||
|
||||
|
|
@ -101,10 +101,10 @@ func uint_to_bytes4*(x: uint64): array[4, byte] =
|
|||
# https://github.com/ethereum/eth2.0-specs/blob/v0.12.2/specs/phase0/beacon-chain.md#compute_fork_data_root
|
||||
func compute_fork_data_root(current_version: Version,
|
||||
genesis_validators_root: Eth2Digest): Eth2Digest =
|
||||
# Return the 32-byte fork data root for the ``current_version`` and
|
||||
# ``genesis_validators_root``.
|
||||
# This is used primarily in signature domains to avoid collisions across
|
||||
# forks/chains.
|
||||
## Return the 32-byte fork data root for the ``current_version`` and
|
||||
## ``genesis_validators_root``.
|
||||
## This is used primarily in signature domains to avoid collisions across
|
||||
## forks/chains.
|
||||
hash_tree_root(ForkData(
|
||||
current_version: current_version,
|
||||
genesis_validators_root: genesis_validators_root
|
||||
|
|
@ -113,10 +113,10 @@ func compute_fork_data_root(current_version: Version,
|
|||
# https://github.com/ethereum/eth2.0-specs/blob/v0.12.2/specs/phase0/beacon-chain.md#compute_fork_digest
|
||||
func compute_fork_digest*(current_version: Version,
|
||||
genesis_validators_root: Eth2Digest): ForkDigest =
|
||||
# Return the 4-byte fork digest for the ``current_version`` and
|
||||
# ``genesis_validators_root``.
|
||||
# This is a digest primarily used for domain separation on the p2p layer.
|
||||
# 4-bytes suffices for practical separation of forks/chains.
|
||||
## Return the 4-byte fork digest for the ``current_version`` and
|
||||
## ``genesis_validators_root``.
|
||||
## This is a digest primarily used for domain separation on the p2p layer.
|
||||
## 4-bytes suffices for practical separation of forks/chains.
|
||||
array[4, byte](result)[0..3] =
|
||||
compute_fork_data_root(
|
||||
current_version, genesis_validators_root).data.toOpenArray(0, 3)
|
||||
|
|
@ -126,7 +126,7 @@ func compute_domain*(
|
|||
domain_type: DomainType,
|
||||
fork_version: Version,
|
||||
genesis_validators_root: Eth2Digest = ZERO_HASH): Domain =
|
||||
# Return the domain for the ``domain_type`` and ``fork_version``.
|
||||
## Return the domain for the ``domain_type`` and ``fork_version``.
|
||||
let fork_data_root =
|
||||
compute_fork_data_root(fork_version, genesis_validators_root)
|
||||
result[0..3] = uint_to_bytes4(domain_type.uint64)
|
||||
|
|
@ -152,8 +152,8 @@ func get_domain*(
|
|||
|
||||
# https://github.com/ethereum/eth2.0-specs/blob/v0.12.2/specs/phase0/beacon-chain.md#compute_signing_root
|
||||
func compute_signing_root*(ssz_object: auto, domain: Domain): Eth2Digest =
|
||||
# Return the signing root of an object by calculating the root of the
|
||||
# object-domain tree.
|
||||
## Return the signing root of an object by calculating the root of the
|
||||
## object-domain tree.
|
||||
let domain_wrapped_object = SigningData(
|
||||
object_root: hash_tree_root(ssz_object),
|
||||
domain: domain
|
||||
|
|
@ -162,7 +162,7 @@ func compute_signing_root*(ssz_object: auto, domain: Domain): Eth2Digest =
|
|||
|
||||
# https://github.com/ethereum/eth2.0-specs/blob/v0.12.2/specs/phase0/beacon-chain.md#get_seed
|
||||
func get_seed*(state: BeaconState, epoch: Epoch, domain_type: DomainType): Eth2Digest =
|
||||
# Return the seed at ``epoch``.
|
||||
## Return the seed at ``epoch``.
|
||||
|
||||
var seed_input : array[4+8+32, byte]
|
||||
|
||||
|
|
|
|||
|
|
@ -55,12 +55,11 @@ declareGauge beacon_current_epoch, "Current epoch"
|
|||
|
||||
# https://github.com/ethereum/eth2.0-specs/blob/v0.12.2/specs/phase0/beacon-chain.md#get_total_active_balance
|
||||
func get_total_active_balance*(state: BeaconState, cache: var StateCache): Gwei =
|
||||
# Return the combined effective balance of the active validators.
|
||||
## Return the combined effective balance of the active validators.
|
||||
# Note: ``get_total_balance`` returns ``EFFECTIVE_BALANCE_INCREMENT`` Gwei
|
||||
# minimum to avoid divisions by zero.
|
||||
|
||||
let
|
||||
epoch = state.get_current_epoch()
|
||||
let epoch = state.get_current_epoch()
|
||||
|
||||
get_total_balance(
|
||||
state, cache.get_shuffled_active_validator_indices(state, epoch))
|
||||
|
|
@ -92,8 +91,8 @@ func get_matching_head_attestations(state: BeaconState, epoch: Epoch):
|
|||
func get_attesting_balance(
|
||||
state: BeaconState, attestations: seq[PendingAttestation],
|
||||
stateCache: var StateCache): Gwei =
|
||||
# Return the combined effective balance of the set of unslashed validators
|
||||
# participating in ``attestations``.
|
||||
## Return the combined effective balance of the set of unslashed validators
|
||||
## participating in ``attestations``.
|
||||
# Note: ``get_total_balance`` returns ``EFFECTIVE_BALANCE_INCREMENT`` Gwei
|
||||
# minimum to avoid divisions by zero.
|
||||
get_total_balance(state, get_unslashed_attesting_indices(
|
||||
|
|
@ -308,7 +307,7 @@ func get_attestation_component_deltas(state: BeaconState,
|
|||
func get_source_deltas*(
|
||||
state: BeaconState, total_balance: Gwei, cache: var StateCache):
|
||||
tuple[a: seq[Gwei], b: seq[Gwei]] =
|
||||
# Return attester micro-rewards/penalties for source-vote for each validator.
|
||||
## Return attester micro-rewards/penalties for source-vote for each validator.
|
||||
|
||||
get_attestation_component_deltas(
|
||||
state,
|
||||
|
|
@ -318,7 +317,7 @@ func get_source_deltas*(
|
|||
func get_target_deltas*(
|
||||
state: BeaconState, total_balance: Gwei, cache: var StateCache):
|
||||
tuple[a: seq[Gwei], b: seq[Gwei]] =
|
||||
# Return attester micro-rewards/penalties for target-vote for each validator.
|
||||
## Return attester micro-rewards/penalties for target-vote for each validator.
|
||||
let matching_target_attestations =
|
||||
get_matching_target_attestations(state, get_previous_epoch(state))
|
||||
get_attestation_component_deltas(
|
||||
|
|
@ -327,7 +326,7 @@ func get_target_deltas*(
|
|||
func get_head_deltas*(
|
||||
state: BeaconState, total_balance: Gwei, cache: var StateCache):
|
||||
tuple[a: seq[Gwei], b: seq[Gwei]] =
|
||||
# Return attester micro-rewards/penalties for head-vote for each validator.
|
||||
## Return attester micro-rewards/penalties for head-vote for each validator.
|
||||
let matching_head_attestations =
|
||||
get_matching_head_attestations(state, get_previous_epoch(state))
|
||||
get_attestation_component_deltas(
|
||||
|
|
@ -336,7 +335,7 @@ func get_head_deltas*(
|
|||
func get_inclusion_delay_deltas*(
|
||||
state: BeaconState, total_balance: Gwei, cache: var StateCache):
|
||||
seq[Gwei] =
|
||||
# Return proposer and inclusion delay micro-rewards/penalties for each validator.
|
||||
## Return proposer and inclusion delay micro-rewards/penalties for each validator.
|
||||
var
|
||||
rewards = repeat(0'u64, len(state.validators))
|
||||
matching_source_attestations =
|
||||
|
|
@ -380,7 +379,7 @@ func get_inclusion_delay_deltas*(
|
|||
func get_inactivity_penalty_deltas*(
|
||||
state: BeaconState, total_balance: Gwei, cache: var StateCache):
|
||||
seq[Gwei] =
|
||||
# Return inactivity reward/penalty deltas for each validator.
|
||||
## Return inactivity reward/penalty deltas for each validator.
|
||||
var penalties = repeat(0'u64, len(state.validators))
|
||||
if is_in_inactivity_leak(state):
|
||||
let
|
||||
|
|
@ -408,7 +407,7 @@ func get_inactivity_penalty_deltas*(
|
|||
# https://github.com/ethereum/eth2.0-specs/blob/v0.12.2/specs/phase0/beacon-chain.md#get_attestation_deltas
|
||||
func get_attestation_deltas(state: BeaconState, cache: var StateCache):
|
||||
tuple[a: seq[Gwei], b: seq[Gwei]] =
|
||||
# Return attestation reward/penalty deltas for each validator.
|
||||
## Return attestation reward/penalty deltas for each validator.
|
||||
let
|
||||
total_balance = get_total_active_balance(state, cache)
|
||||
(source_rewards, source_penalties) =
|
||||
|
|
|
|||
|
|
@ -227,7 +227,7 @@ func compute_committee_len*(
|
|||
func get_beacon_committee*(
|
||||
state: BeaconState, slot: Slot, index: CommitteeIndex,
|
||||
cache: var StateCache): seq[ValidatorIndex] =
|
||||
# Return the beacon committee at ``slot`` for ``index``.
|
||||
## Return the beacon committee at ``slot`` for ``index``.
|
||||
let
|
||||
epoch = compute_epoch_at_slot(slot)
|
||||
committees_per_slot = get_committee_count_per_slot(state, epoch, cache)
|
||||
|
|
@ -257,7 +257,7 @@ func get_beacon_committee_len*(
|
|||
# https://github.com/ethereum/eth2.0-specs/blob/v0.12.2/specs/phase0/beacon-chain.md#compute_shuffled_index
|
||||
func compute_shuffled_index(
|
||||
index: uint64, index_count: uint64, seed: Eth2Digest): uint64 =
|
||||
# Return the shuffled index corresponding to ``seed`` (and ``index_count``).
|
||||
## Return the shuffled index corresponding to ``seed`` (and ``index_count``).
|
||||
doAssert index < index_count
|
||||
|
||||
var
|
||||
|
|
@ -295,7 +295,7 @@ func compute_shuffled_index(
|
|||
# https://github.com/ethereum/eth2.0-specs/blob/v0.12.2/specs/phase0/beacon-chain.md#compute_proposer_index
|
||||
func compute_proposer_index(state: BeaconState, indices: seq[ValidatorIndex],
|
||||
seed: Eth2Digest): Option[ValidatorIndex] =
|
||||
# Return from ``indices`` a random index sampled by effective balance.
|
||||
## Return from ``indices`` a random index sampled by effective balance.
|
||||
const MAX_RANDOM_BYTE = 255
|
||||
|
||||
if len(indices) == 0:
|
||||
|
|
@ -361,12 +361,12 @@ func get_committee_assignment*(
|
|||
state: BeaconState, epoch: Epoch,
|
||||
validator_index: ValidatorIndex):
|
||||
Option[tuple[a: seq[ValidatorIndex], b: CommitteeIndex, c: 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.
|
||||
## 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.
|
||||
let next_epoch = get_current_epoch(state) + 1
|
||||
doAssert epoch <= next_epoch
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue