Trait Membership

pub trait Membership<TYPES: NodeType>:
    Debug
    + Send
    + Sync {
    type Error: Display;

    // Required methods
    fn new(
        stake_committee_members: Vec<PeerConfig<TYPES>>,
        da_committee_members: Vec<PeerConfig<TYPES>>,
    ) -> Self;
    fn stake_table(&self, epoch: Option<TYPES::Epoch>) -> HSStakeTable<TYPES>;
    fn da_stake_table(&self, epoch: Option<TYPES::Epoch>) -> HSStakeTable<TYPES>;
    fn committee_members(
        &self,
        view_number: TYPES::View,
        epoch: Option<TYPES::Epoch>,
    ) -> BTreeSet<TYPES::SignatureKey>;
    fn da_committee_members(
        &self,
        view_number: TYPES::View,
        epoch: Option<TYPES::Epoch>,
    ) -> BTreeSet<TYPES::SignatureKey>;
    fn stake(
        &self,
        pub_key: &TYPES::SignatureKey,
        epoch: Option<TYPES::Epoch>,
    ) -> Option<PeerConfig<TYPES>>;
    fn da_stake(
        &self,
        pub_key: &TYPES::SignatureKey,
        epoch: Option<TYPES::Epoch>,
    ) -> Option<PeerConfig<TYPES>>;
    fn has_stake(
        &self,
        pub_key: &TYPES::SignatureKey,
        epoch: Option<TYPES::Epoch>,
    ) -> bool;
    fn has_da_stake(
        &self,
        pub_key: &TYPES::SignatureKey,
        epoch: Option<TYPES::Epoch>,
    ) -> bool;
    fn lookup_leader(
        &self,
        view: TYPES::View,
        epoch: Option<TYPES::Epoch>,
    ) -> Result<TYPES::SignatureKey, Self::Error>;
    fn total_nodes(&self, epoch: Option<TYPES::Epoch>) -> usize;
    fn da_total_nodes(&self, epoch: Option<TYPES::Epoch>) -> usize;
    fn success_threshold(&self, epoch: Option<TYPES::Epoch>) -> U256;
    fn da_success_threshold(&self, epoch: Option<TYPES::Epoch>) -> U256;
    fn failure_threshold(&self, epoch: Option<TYPES::Epoch>) -> U256;
    fn upgrade_threshold(&self, epoch: Option<TYPES::Epoch>) -> U256;
    fn has_stake_table(&self, epoch: TYPES::Epoch) -> bool;
    fn has_randomized_stake_table(&self, epoch: TYPES::Epoch) -> bool;
    fn add_drb_result(&mut self, _epoch: TYPES::Epoch, _drb_result: DrbResult);
    fn set_first_epoch(
        &mut self,
        _epoch: TYPES::Epoch,
        _initial_drb_result: DrbResult,
    );

    // Provided methods
    fn total_stake(&self, epoch: Option<TYPES::Epoch>) -> U256 { ... }
    fn total_da_stake(&self, epoch: Option<TYPES::Epoch>) -> U256 { ... }
    fn leader(
        &self,
        view: TYPES::View,
        epoch: Option<TYPES::Epoch>,
    ) -> Result<TYPES::SignatureKey> { ... }
    fn get_epoch_root(
        _membership: Arc<RwLock<Self>>,
        _block_height: u64,
        _epoch: TYPES::Epoch,
    ) -> impl Future<Output = Result<Leaf2<TYPES>>> + Send { ... }
    fn get_epoch_drb(
        _membership: Arc<RwLock<Self>>,
        _block_height: u64,
        _epoch: TYPES::Epoch,
    ) -> impl Future<Output = Result<DrbResult>> + Send { ... }
    fn add_epoch_root(
        &self,
        _epoch: TYPES::Epoch,
        _block_header: TYPES::BlockHeader,
    ) -> impl Future<Output = Option<Box<dyn FnOnce(&mut Self) + Send>>> + Send { ... }
}

A protocol for determining membership in and participating in a committee.

Required Associated Types

type Error: Display

The error type returned by methods like lookup_leader.

Required Methods

fn new( stake_committee_members: Vec<PeerConfig<TYPES>>, da_committee_members: Vec<PeerConfig<TYPES>>, ) -> Self

Create a committee

fn stake_table(&self, epoch: Option<TYPES::Epoch>) -> HSStakeTable<TYPES>

Get all participants in the committee (including their stake) for a specific epoch

fn da_stake_table(&self, epoch: Option<TYPES::Epoch>) -> HSStakeTable<TYPES>

Get all participants in the committee (including their stake) for a specific epoch

fn committee_members( &self, view_number: TYPES::View, epoch: Option<TYPES::Epoch>, ) -> BTreeSet<TYPES::SignatureKey>

Get all participants in the committee for a specific view for a specific epoch

fn da_committee_members( &self, view_number: TYPES::View, epoch: Option<TYPES::Epoch>, ) -> BTreeSet<TYPES::SignatureKey>

Get all participants in the committee for a specific view for a specific epoch

fn stake( &self, pub_key: &TYPES::SignatureKey, epoch: Option<TYPES::Epoch>, ) -> Option<PeerConfig<TYPES>>

Get the stake table entry for a public key, returns None if the key is not in the table for a specific epoch

fn da_stake( &self, pub_key: &TYPES::SignatureKey, epoch: Option<TYPES::Epoch>, ) -> Option<PeerConfig<TYPES>>

Get the DA stake table entry for a public key, returns None if the key is not in the table for a specific epoch

fn has_stake( &self, pub_key: &TYPES::SignatureKey, epoch: Option<TYPES::Epoch>, ) -> bool

See if a node has stake in the committee in a specific epoch

fn has_da_stake( &self, pub_key: &TYPES::SignatureKey, epoch: Option<TYPES::Epoch>, ) -> bool

See if a node has stake in the committee in a specific epoch

fn lookup_leader( &self, view: TYPES::View, epoch: Option<TYPES::Epoch>, ) -> Result<TYPES::SignatureKey, Self::Error>

The leader of the committee for view view_number in epoch.

Note: There is no such thing as a DA leader, so any consumer requiring a leader should call this.

Errors

Returns an error if the leader cannot be calculated

fn total_nodes(&self, epoch: Option<TYPES::Epoch>) -> usize

Returns the number of total nodes in the committee in an epoch epoch

fn da_total_nodes(&self, epoch: Option<TYPES::Epoch>) -> usize

Returns the number of total DA nodes in the committee in an epoch epoch

fn success_threshold(&self, epoch: Option<TYPES::Epoch>) -> U256

Returns the threshold for a specific Membership implementation

fn da_success_threshold(&self, epoch: Option<TYPES::Epoch>) -> U256

Returns the DA threshold for a specific Membership implementation

fn failure_threshold(&self, epoch: Option<TYPES::Epoch>) -> U256

Returns the threshold for a specific Membership implementation

fn upgrade_threshold(&self, epoch: Option<TYPES::Epoch>) -> U256

Returns the threshold required to upgrade the network protocol

fn has_stake_table(&self, epoch: TYPES::Epoch) -> bool

Returns if the stake table is available for the given epoch

fn has_randomized_stake_table(&self, epoch: TYPES::Epoch) -> bool

Returns if the randomized stake table is available for the given epoch

fn add_drb_result(&mut self, _epoch: TYPES::Epoch, _drb_result: 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: TYPES::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.

Provided Methods

fn total_stake(&self, epoch: Option<TYPES::Epoch>) -> U256

fn total_da_stake(&self, epoch: Option<TYPES::Epoch>) -> U256

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

The leader of the committee for view view_number in epoch.

Note: this function uses a HotShot-internal error type. You should implement lookup_leader, rather than implementing this function directly.

Errors

Returns an error if the leader cannot be calculated.

fn get_epoch_root( _membership: Arc<RwLock<Self>>, _block_height: u64, _epoch: TYPES::Epoch, ) -> impl Future<Output = Result<Leaf2<TYPES>>> + Send

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

fn get_epoch_drb( _membership: Arc<RwLock<Self>>, _block_height: u64, _epoch: TYPES::Epoch, ) -> impl Future<Output = Result<DrbResult>> + Send

Gets the DRB result for the given epoch

fn add_epoch_root( &self, _epoch: TYPES::Epoch, _block_header: TYPES::BlockHeader, ) -> impl Future<Output = Option<Box<dyn FnOnce(&mut Self) + Send>>> + Send

Handles notifications that a new epoch root has been created Is called under a read lock to the Membership. Return a callback with Some to have that callback invoked under a write lock.

#3967 REVIEW NOTE: this is only called if epoch is Some. Is there any reason to do otherwise?

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors