Trait hotshot_types::traits::election::Membership

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

    // Required methods
    fn new(
        stake_committee_members: Vec<PeerConfig<TYPES::SignatureKey>>,
        da_committee_members: Vec<PeerConfig<TYPES::SignatureKey>>,
    ) -> Self;
    fn stake_table(
        &self,
        epoch: Option<TYPES::Epoch>,
    ) -> Vec<<TYPES::SignatureKey as SignatureKey>::StakeTableEntry>;
    fn da_stake_table(
        &self,
        epoch: Option<TYPES::Epoch>,
    ) -> Vec<<TYPES::SignatureKey as SignatureKey>::StakeTableEntry>;
    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 committee_leaders(
        &self,
        view_number: TYPES::View,
        epoch: Option<TYPES::Epoch>,
    ) -> BTreeSet<TYPES::SignatureKey>;
    fn stake(
        &self,
        pub_key: &TYPES::SignatureKey,
        epoch: Option<TYPES::Epoch>,
    ) -> Option<<TYPES::SignatureKey as SignatureKey>::StakeTableEntry>;
    fn da_stake(
        &self,
        pub_key: &TYPES::SignatureKey,
        epoch: Option<TYPES::Epoch>,
    ) -> Option<<TYPES::SignatureKey as SignatureKey>::StakeTableEntry>;
    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>) -> NonZeroU64;
    fn da_success_threshold(&self, epoch: Option<TYPES::Epoch>) -> NonZeroU64;
    fn failure_threshold(&self, epoch: Option<TYPES::Epoch>) -> NonZeroU64;
    fn upgrade_threshold(&self, epoch: Option<TYPES::Epoch>) -> NonZeroU64;

    // Provided methods
    fn leader(
        &self,
        view: TYPES::View,
        epoch: Option<TYPES::Epoch>,
    ) -> Result<TYPES::SignatureKey> { ... }
    fn add_epoch_root<'life0, 'async_trait>(
        &'life0 self,
        _epoch: TYPES::Epoch,
        _block_header: TYPES::BlockHeader,
    ) -> Pin<Box<dyn Future<Output = Option<Box<dyn FnOnce(&mut Self) + Send>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn sync_l1<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Option<Box<dyn FnOnce(&mut Self) + Send>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
}

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::SignatureKey>>, da_committee_members: Vec<PeerConfig<TYPES::SignatureKey>>, ) -> Self

Create a committee

fn stake_table( &self, epoch: Option<TYPES::Epoch>, ) -> Vec<<TYPES::SignatureKey as SignatureKey>::StakeTableEntry>

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

fn da_stake_table( &self, epoch: Option<TYPES::Epoch>, ) -> Vec<<TYPES::SignatureKey as SignatureKey>::StakeTableEntry>

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 committee_leaders( &self, view_number: TYPES::View, epoch: Option<TYPES::Epoch>, ) -> BTreeSet<TYPES::SignatureKey>

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

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

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<<TYPES::SignatureKey as SignatureKey>::StakeTableEntry>

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>) -> NonZeroU64

Returns the threshold for a specific Membership implementation

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

Returns the DA threshold for a specific Membership implementation

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

Returns the threshold for a specific Membership implementation

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

Returns the threshold required to upgrade the network protocol

Provided Methods

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 add_epoch_root<'life0, 'async_trait>( &'life0 self, _epoch: TYPES::Epoch, _block_header: TYPES::BlockHeader, ) -> Pin<Box<dyn Future<Output = Option<Box<dyn FnOnce(&mut Self) + Send>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

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?

fn sync_l1<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Option<Box<dyn FnOnce(&mut Self) + Send>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Called after add_epoch_root runs and any callback has been invoked. Causes a read lock to be reacquired for this functionality.

Object Safety

This trait is not object safe.

Implementors