From 45dd971955f11642ab5ce1006d850c23313ac946 Mon Sep 17 00:00:00 2001 From: tersec Date: Tue, 8 Sep 2020 08:54:55 +0000 Subject: [PATCH] mark comments documenting functions as a whole as such (#1613) --- beacon_chain/spec/beaconstate.nim | 30 ++++++++-------- beacon_chain/spec/helpers.nim | 36 ++++++++++---------- beacon_chain/spec/state_transition_epoch.nim | 21 ++++++------ beacon_chain/spec/validator.nim | 18 +++++----- 4 files changed, 52 insertions(+), 53 deletions(-) diff --git a/beacon_chain/spec/beaconstate.nim b/beacon_chain/spec/beaconstate.nim index bc76c8519..e92b9ab24 100644 --- a/beacon_chain/spec/beaconstate.nim +++ b/beacon_chain/spec/beaconstate.nim @@ -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( diff --git a/beacon_chain/spec/helpers.nim b/beacon_chain/spec/helpers.nim index e0deea219..f6ecc87fb 100644 --- a/beacon_chain/spec/helpers.nim +++ b/beacon_chain/spec/helpers.nim @@ -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] diff --git a/beacon_chain/spec/state_transition_epoch.nim b/beacon_chain/spec/state_transition_epoch.nim index 40834d1c9..47f9a8c40 100644 --- a/beacon_chain/spec/state_transition_epoch.nim +++ b/beacon_chain/spec/state_transition_epoch.nim @@ -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) = diff --git a/beacon_chain/spec/validator.nim b/beacon_chain/spec/validator.nim index d2e761079..d200ccd9b 100644 --- a/beacon_chain/spec/validator.nim +++ b/beacon_chain/spec/validator.nim @@ -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