From f949919b9bf7aedf79d095399fd2559c7954453e Mon Sep 17 00:00:00 2001 From: Paul Hauner Date: Tue, 12 Mar 2019 18:02:53 +1100 Subject: [PATCH] Add comments to epoch_processing --- .../beacon_chain/test_harness/src/gen_keys.rs | 1 + .../beacon_chain/test_harness/src/run_test.rs | 1 + .../src/per_epoch_processing.rs | 67 +++++++++++++++---- .../src/per_epoch_processing/attester_sets.rs | 35 ++++++++++ 4 files changed, 90 insertions(+), 14 deletions(-) diff --git a/beacon_node/beacon_chain/test_harness/src/gen_keys.rs b/beacon_node/beacon_chain/test_harness/src/gen_keys.rs index f2f81b393..abd512423 100644 --- a/beacon_node/beacon_chain/test_harness/src/gen_keys.rs +++ b/beacon_node/beacon_chain/test_harness/src/gen_keys.rs @@ -3,6 +3,7 @@ use log::debug; use std::path::Path; use types::test_utils::{generate_deterministic_keypairs, KeypairsFile}; +/// Creates a file containing BLS keypairs. pub fn gen_keys(matches: &ArgMatches) { let validator_count = value_t!(matches.value_of("validator_count"), usize) .expect("Validator count is required argument"); diff --git a/beacon_node/beacon_chain/test_harness/src/run_test.rs b/beacon_node/beacon_chain/test_harness/src/run_test.rs index 51a993bd7..d4e2e1cf2 100644 --- a/beacon_node/beacon_chain/test_harness/src/run_test.rs +++ b/beacon_node/beacon_chain/test_harness/src/run_test.rs @@ -4,6 +4,7 @@ use std::path::Path; use std::{fs::File, io::prelude::*}; use yaml_rust::YamlLoader; +/// Runs a YAML-specified test case. pub fn run_test(matches: &ArgMatches) { if let Some(yaml_file) = matches.value_of("yaml") { let docs = { diff --git a/eth2/state_processing/src/per_epoch_processing.rs b/eth2/state_processing/src/per_epoch_processing.rs index bb064ac34..4abbe012c 100644 --- a/eth2/state_processing/src/per_epoch_processing.rs +++ b/eth2/state_processing/src/per_epoch_processing.rs @@ -3,7 +3,6 @@ use errors::EpochProcessingError as Error; use fnv::FnvHashMap; use fnv::FnvHashSet; use integer_sqrt::IntegerSquareRoot; -use log::debug; use rayon::prelude::*; use ssz::TreeHash; use std::collections::HashMap; @@ -17,14 +16,20 @@ pub mod inclusion_distance; pub mod tests; pub mod winning_root; +/// Maps a shard to a winning root. +/// +/// It is generated during crosslink processing and later used to reward/penalize validators. +pub type WinningRootHashSet = HashMap; + +/// Performs per-epoch processing on some BeaconState. +/// +/// Mutates the given `BeaconState`, returning early if an error is encountered. If an error is +/// returned, a state might be "half-processed" and therefore in an invalid state. +/// +/// Spec v0.4.0 pub fn per_epoch_processing(state: &mut BeaconState, spec: &ChainSpec) -> Result<(), Error> { let previous_epoch = state.previous_epoch(spec); - debug!( - "Starting per-epoch processing on epoch {}...", - state.current_epoch(spec) - ); - // Ensure all of the caches are built. state.build_epoch_cache(RelativeEpoch::Previous, spec)?; state.build_epoch_cache(RelativeEpoch::Current, spec)?; @@ -79,11 +84,12 @@ pub fn per_epoch_processing(state: &mut BeaconState, spec: &ChainSpec) -> Result // Rotate the epoch caches to suit the epoch transition. state.advance_caches(); - debug!("Epoch transition complete."); - Ok(()) } +/// Returns a list of active validator indices for the state's current epoch. +/// +/// Spec v0.4.0 pub fn calculate_active_validator_indices(state: &BeaconState, spec: &ChainSpec) -> Vec { get_active_validator_indices( &state.validator_registry, @@ -91,6 +97,14 @@ pub fn calculate_active_validator_indices(state: &BeaconState, spec: &ChainSpec) ) } +/// Calculates various sets of attesters, including: +/// +/// - current epoch attesters +/// - current epoch boundary attesters +/// - previous epoch attesters +/// - etc. +/// +/// Spec v0.4.0 pub fn calculate_attester_sets( state: &BeaconState, spec: &ChainSpec, @@ -113,6 +127,13 @@ pub fn process_eth1_data(state: &mut BeaconState, spec: &ChainSpec) { } } +/// Update the following fields on the `BeaconState`: +/// +/// - `justification_bitfield`. +/// - `finalized_epoch` +/// - `justified_epoch` +/// - `previous_justified_epoch` +/// /// Spec v0.4.0 pub fn process_justification( state: &mut BeaconState, @@ -190,8 +211,13 @@ pub fn process_justification( state.justified_epoch = new_justified_epoch; } -pub type WinningRootHashSet = HashMap; - +/// Updates the following fields on the `BeaconState`: +/// +/// - `latest_crosslinks` +/// +/// Also returns a `WinningRootHashSet` for later use during epoch processing. +/// +/// Spec v0.4.0 pub fn process_crosslinks( state: &mut BeaconState, spec: &ChainSpec, @@ -250,6 +276,10 @@ pub fn process_crosslinks( Ok(winning_root_for_shards) } +/// Updates the following fields on the BeaconState: +/// +/// - `validator_balances` +/// /// Spec v0.4.0 pub fn process_rewards_and_penalities( state: &mut BeaconState, @@ -488,7 +518,9 @@ pub fn process_rewards_and_penalities( Ok(()) } -// Spec v0.4.0 +/// Peforms a validator registry update, if required. +/// +/// Spec v0.4.0 pub fn process_validator_registry(state: &mut BeaconState, spec: &ChainSpec) -> Result<(), Error> { let current_epoch = state.current_epoch(spec); let next_epoch = state.next_epoch(spec); @@ -535,7 +567,10 @@ pub fn process_validator_registry(state: &mut BeaconState, spec: &ChainSpec) -> Ok(()) } -// Spec v0.4.0 +/// Updates the state's `latest_active_index_roots` field with a tree hash the active validator +/// indices for the next epoch. +/// +/// Spec v0.4.0 pub fn update_active_tree_index_roots( state: &mut BeaconState, spec: &ChainSpec, @@ -555,7 +590,9 @@ pub fn update_active_tree_index_roots( Ok(()) } -// Spec v0.4.0 +/// Advances the state's `latest_slashed_balances` field. +/// +/// Spec v0.4.0 pub fn update_latest_slashed_balances(state: &mut BeaconState, spec: &ChainSpec) { let current_epoch = state.current_epoch(spec); let next_epoch = state.next_epoch(spec); @@ -564,7 +601,9 @@ pub fn update_latest_slashed_balances(state: &mut BeaconState, spec: &ChainSpec) state.latest_slashed_balances[current_epoch.as_usize() % spec.latest_slashed_exit_length]; } -// Spec v0.4.0 +/// Removes all pending attestations from the previous epoch. +/// +/// Spec v0.4.0 pub fn clean_attestations(state: &mut BeaconState, spec: &ChainSpec) { let current_epoch = state.current_epoch(spec); diff --git a/eth2/state_processing/src/per_epoch_processing/attester_sets.rs b/eth2/state_processing/src/per_epoch_processing/attester_sets.rs index d82774ac2..03f49c1d3 100644 --- a/eth2/state_processing/src/per_epoch_processing/attester_sets.rs +++ b/eth2/state_processing/src/per_epoch_processing/attester_sets.rs @@ -1,13 +1,17 @@ use fnv::FnvHashSet; use types::*; +/// A set of validator indices, along with the total balance of all those attesters. #[derive(Default)] pub struct Attesters { + /// A set of validator indices. pub indices: FnvHashSet, + /// The total balance of all validators in `self.indices`. pub balance: u64, } impl Attesters { + /// Add the given indices to the set, incrementing the sets balance by the provided balance. fn add(&mut self, additional_indices: &[usize], additional_balance: u64) { self.indices.reserve(additional_indices.len()); for i in additional_indices { @@ -17,15 +21,35 @@ impl Attesters { } } +/// A collection of `Attester` objects, representing set of attesters that are rewarded/penalized +/// during an epoch transition. pub struct AttesterSets { + /// All validators who attested during the state's current epoch. pub current_epoch: Attesters, + /// All validators who attested that the beacon block root of the first slot of the state's + /// current epoch is the same as the one stored in this state. + /// + /// In short validators who agreed with the state about the first slot of the current epoch. pub current_epoch_boundary: Attesters, + /// All validators who attested during the state's previous epoch. pub previous_epoch: Attesters, + /// All validators who attested that the beacon block root of the first slot of the state's + /// previous epoch is the same as the one stored in this state. + /// + /// In short, validators who agreed with the state about the first slot of the previous epoch. pub previous_epoch_boundary: Attesters, + /// All validators who attested that the beacon block root at the pending attestation's slot is + /// the same as the one stored in this state. + /// + /// In short, validators who agreed with the state about the current beacon block root when + /// they attested. pub previous_epoch_head: Attesters, } impl AttesterSets { + /// Loop through all attestations in the state and instantiate a complete `AttesterSets` struct. + /// + /// Spec v0.4.0 pub fn new(state: &BeaconState, spec: &ChainSpec) -> Result { let mut current_epoch = Attesters::default(); let mut current_epoch_boundary = Attesters::default(); @@ -67,10 +91,17 @@ impl AttesterSets { } } +/// Returns `true` if some `PendingAttestation` is from the supplied `epoch`. +/// +/// Spec v0.4.0 fn is_from_epoch(a: &PendingAttestation, epoch: Epoch, spec: &ChainSpec) -> bool { a.data.slot.epoch(spec.slots_per_epoch) == epoch } +/// Returns `true` if a `PendingAttestation` and `BeaconState` share the same beacon block hash for +/// the first slot of the given epoch. +/// +/// Spec v0.4.0 fn has_common_epoch_boundary_root( a: &PendingAttestation, state: &BeaconState, @@ -85,6 +116,10 @@ fn has_common_epoch_boundary_root( Ok(a.data.epoch_boundary_root == state_boundary_root) } +/// Returns `true` if a `PendingAttestation` and `BeaconState` share the same beacon block hash for +/// the current slot of the `PendingAttestation`. +/// +/// Spec v0.4.0 fn has_common_beacon_block_root( a: &PendingAttestation, state: &BeaconState,