Struct EpochCommittees

pub struct EpochCommittees {
    non_epoch_committee: NonEpochCommittee,
    state: HashMap<<SeqTypes as NodeType>::Epoch, EpochCommittee>,
    randomized_committees: BTreeMap<<SeqTypes as NodeType>::Epoch, RandomizedCommittee<StakeTableEntry<PubKey>>>,
    first_epoch: Option<<SeqTypes as NodeType>::Epoch>,
    epoch_height: u64,
    block_reward: Option<RewardAmount>,
    fetcher: Arc<Fetcher>,
}

Type to describe DA and Stake memberships

Fields

non_epoch_committee: NonEpochCommittee

Committee used when we’re in pre-epoch state

state: HashMap<<SeqTypes as NodeType>::Epoch, EpochCommittee>

Holds Stake table and da stake

randomized_committees: BTreeMap<<SeqTypes as NodeType>::Epoch, RandomizedCommittee<StakeTableEntry<PubKey>>>

Randomized committees, filled when we receive the DrbResult

first_epoch: Option<<SeqTypes as NodeType>::Epoch>

epoch_height: u64

block_reward: Option<RewardAmount>

fetcher: Arc<Fetcher>

Implementations

impl EpochCommittees

pub fn first_epoch(&self) -> Option<<SeqTypes as NodeType>::Epoch>

pub fn fetcher(&self) -> &Fetcher

async fn update_fixed_block_reward( membership: Arc<RwLock<Self>>, epoch: EpochNumber, ) -> Result<RewardAmount>

Fetch the block reward and update it if its None. We used a fixed block reward for version v3 Version v4 uses the dynamic block reward based Assumes the stake table contract proxy address does not change In the future, if we want to support updates to the stake table contract address via chain config, or allow the contract to handle additional block reward calculation parameters (e.g., inflation, block time), the fetch_block_reward logic can be updated to support per-epoch rewards. Initially, the block reward is zero if the node starts on pre-epoch version but it is updated on the first call to add_epoch_root()

pub fn compute_block_reward( epoch: &EpochNumber, total_supply: U256, total_stake: U256, avg_block_time_ms: u64, ) -> Result<RewardAmount>

async fn calculate_dynamic_block_reward( &self, epoch: &<SeqTypes as NodeType>::Epoch, header: Header, validators: &ValidatorMap, ) -> Result<RewardAmount>

Calculates the dynamic block reward for a given block header within an epoch.

The reward is based on a dynamic inflation rate computed from the current stake ratio (p), where p = total_stake / total_supply. The inflation function R(p) is defined piecewise:

• If p <= 0.01: R(p) = 0.03 / sqrt(2 * 0.01)
• Else: R(p) = 0.03 / sqrt(2 * p)

fn insert_committee( &mut self, epoch: EpochNumber, validators: ValidatorMap, block_reward: Option<RewardAmount>, hash: Option<StakeTableHash>, )

Updates Self.stake_table with stake_table for Self.contract_address at l1_block_height. This is intended to be called before calling self.stake() so that Self.stake_table only needs to be updated once in a given life-cycle but may be read from many times.

pub fn active_validators( &self, epoch: &<SeqTypes as NodeType>::Epoch, ) -> Result<ValidatorMap>

pub fn address( &self, epoch: &<SeqTypes as NodeType>::Epoch, bls_key: BLSPubKey, ) -> Result<Address>

pub fn get_validator_config( &self, epoch: &<SeqTypes as NodeType>::Epoch, key: BLSPubKey, ) -> Result<Validator<BLSPubKey>>

pub fn block_reward(&self, epoch: Option<EpochNumber>) -> Option<RewardAmount>

pub fn new_stake( committee_members: Vec<PeerConfig<SeqTypes>>, da_members: Vec<PeerConfig<SeqTypes>>, block_reward: Option<RewardAmount>, fetcher: Fetcher, epoch_height: u64, ) -> Self

pub async fn reload_stake(&mut self, limit: u64)

fn get_stake_table( &self, epoch: &Option<<SeqTypes as NodeType>::Epoch>, ) -> Option<Vec<PeerConfig<SeqTypes>>>

Trait Implementations

impl Clone for EpochCommittees

fn clone(&self) -> EpochCommittees

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for EpochCommittees

fn fmt(&self, __derive_more_f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Membership<SeqTypes> for EpochCommittees

fn stake_table( &self, epoch: Option<<SeqTypes as NodeType>::Epoch>, ) -> HSStakeTable<SeqTypes>

Get the stake table for the current view

fn da_stake_table( &self, _epoch: Option<<SeqTypes as NodeType>::Epoch>, ) -> HSStakeTable<SeqTypes>

Get the stake table for the current view

fn committee_members( &self, _view_number: <SeqTypes as NodeType>::View, epoch: Option<<SeqTypes as NodeType>::Epoch>, ) -> BTreeSet<PubKey>

Get all members of the committee for the current view

fn da_committee_members( &self, _view_number: <SeqTypes as NodeType>::View, _epoch: Option<<SeqTypes as NodeType>::Epoch>, ) -> BTreeSet<PubKey>

Get all members of the committee for the current view

fn stake( &self, pub_key: &PubKey, epoch: Option<<SeqTypes as NodeType>::Epoch>, ) -> Option<PeerConfig<SeqTypes>>

Get the stake table entry for a public key

fn da_stake( &self, pub_key: &PubKey, _epoch: Option<<SeqTypes as NodeType>::Epoch>, ) -> Option<PeerConfig<SeqTypes>>

Get the DA stake table entry for a public key

fn has_stake( &self, pub_key: &PubKey, epoch: Option<<SeqTypes as NodeType>::Epoch>, ) -> bool

Check if a node has stake in the committee

fn has_da_stake( &self, pub_key: &PubKey, epoch: Option<<SeqTypes as NodeType>::Epoch>, ) -> bool

Check if a node has stake in the committee

fn lookup_leader( &self, view_number: <SeqTypes as NodeType>::View, epoch: Option<<SeqTypes as NodeType>::Epoch>, ) -> Result<PubKey, Self::Error>

Returns the leader’s public key for a given view number and epoch.

If an epoch is provided and a randomized committee exists for that epoch, the leader is selected from the randomized committee. Otherwise, the leader is selected from the non-epoch committee.

Arguments

• view_number - The view number to index into the committee.
• epoch - The epoch for which to determine the leader. If None, uses the non-epoch committee.

Errors

Returns LeaderLookupError if the epoch is before the first epoch or if the committee is missing.

fn total_nodes(&self, epoch: Option<<SeqTypes as NodeType>::Epoch>) -> usize

Get the total number of nodes in the committee

fn da_total_nodes(&self, epoch: Option<<SeqTypes as NodeType>::Epoch>) -> usize

Get the total number of DA nodes in the committee

fn success_threshold( &self, epoch: Option<<SeqTypes as NodeType>::Epoch>, ) -> U256

Get the voting success threshold for the committee

fn da_success_threshold( &self, epoch: Option<<SeqTypes as NodeType>::Epoch>, ) -> U256

Get the voting success threshold for the committee

fn failure_threshold( &self, epoch: Option<<SeqTypes as NodeType>::Epoch>, ) -> U256

Get the voting failure threshold for the committee

fn upgrade_threshold( &self, epoch: Option<<SeqTypes as NodeType>::Epoch>, ) -> U256

Get the voting upgrade threshold for the committee

async fn add_epoch_root( membership: Arc<RwLock<Self>>, epoch: <SeqTypes as NodeType>::Epoch, block_header: Header, ) -> Result<()>

Adds the epoch committee and block reward for a given epoch, either by fetching from L1 or using local state if available. It also calculates and stores the block reward based on header version.

fn has_randomized_stake_table( &self, epoch: <SeqTypes as NodeType>::Epoch, ) -> Result<bool>

Checks if the randomized stake table is available for the given epoch.

Returns Ok(true) if a randomized committee exists for the specified epoch and the epoch is not before the first epoch. Returns an error if first_epoch is None or if the provided epoch is before the first epoch.

Arguments

• epoch - The epoch for which to check the presence of a randomized stake table.

Errors

Returns an error if first_epoch is None or if epoch is before first_epoch.

type Error = LeaderLookupError

The error type returned by methods like lookup_leader.

type StakeTableHash = StakeTableState

fn new( _committee_members: Vec<PeerConfig<SeqTypes>>, _da_members: Vec<PeerConfig<SeqTypes>>, ) -> Self

Create a committee

fn has_stake_table(&self, epoch: <SeqTypes as NodeType>::Epoch) -> bool

Returns if the stake table is available for the given epoch

async fn get_epoch_root( membership: Arc<RwLock<Self>>, block_height: u64, epoch: <SeqTypes as NodeType>::Epoch, ) -> Result<Leaf2>

Gets the validated block header and epoch number of the epoch root at the given block height

async fn get_epoch_drb( membership: Arc<RwLock<Self>>, epoch: <SeqTypes as NodeType>::Epoch, ) -> Result<DrbResult>

Gets the DRB result for the given epoch

fn add_drb_result( &mut self, epoch: <SeqTypes as NodeType>::Epoch, drb: DrbResult, )

Called to notify the Membership when a new DRB result has been calculated. Observes the same semantics as add_epoch_root

fn set_first_epoch( &mut self, epoch: <SeqTypes as NodeType>::Epoch, initial_drb_result: DrbResult, )

Called to notify the Membership that Epochs are enabled. Implementations should copy the pre-epoch stake table into epoch and epoch+1 when this is called. The value of initial_drb_result should be used for DRB calculations for epochs (epoch+1) and earlier.

fn first_epoch(&self) -> Option<<SeqTypes as NodeType>::Epoch>

Get first epoch if epochs are enabled, None otherwise

fn stake_table_hash( &self, epoch: <SeqTypes as NodeType>::Epoch, ) -> Option<StakeTableHash>

Returns the commitment of the stake table for the given epoch, Errors if the stake table is not available for the given epoch

fn total_stake(&self, epoch: Option<<TYPES as NodeType>::Epoch>) -> Uint<256, 4>

fn total_da_stake( &self, epoch: Option<<TYPES as NodeType>::Epoch>, ) -> Uint<256, 4>

fn leader( &self, view: <TYPES as NodeType>::View, epoch: Option<<TYPES as NodeType>::Epoch>, ) -> Result<<TYPES as NodeType>::SignatureKey, Error>

The leader of the committee for view view_number in epoch.