Trait hotshot_types::traits::stake_table::StakeTableScheme

pub trait StakeTableScheme {
    type Key: Clone;
    type Amount: Clone + Copy;
    type Commitment;
    type LookupProof;
    type IntoIter: Iterator<Item = (Self::Key, Self::Amount, Self::Aux)>;
    type Aux: Clone;

    // Required methods
    fn register(
        &mut self,
        new_key: Self::Key,
        amount: Self::Amount,
        aux: Self::Aux
    ) -> Result<(), StakeTableError>;
    fn deregister(
        &mut self,
        existing_key: &Self::Key
    ) -> Result<(), StakeTableError>;
    fn commitment(
        &self,
        version: SnapshotVersion
    ) -> Result<Self::Commitment, StakeTableError>;
    fn total_stake(
        &self,
        version: SnapshotVersion
    ) -> Result<Self::Amount, StakeTableError>;
    fn len(&self, version: SnapshotVersion) -> Result<usize, StakeTableError>;
    fn contains_key(&self, key: &Self::Key) -> bool;
    fn lookup(
        &self,
        version: SnapshotVersion,
        key: &Self::Key
    ) -> Result<Self::Amount, StakeTableError>;
    fn lookup_with_proof(
        &self,
        version: SnapshotVersion,
        key: &Self::Key
    ) -> Result<(Self::Amount, Self::LookupProof), StakeTableError>;
    fn lookup_with_aux_and_proof(
        &self,
        version: SnapshotVersion,
        key: &Self::Key
    ) -> Result<(Self::Amount, Self::Aux, Self::LookupProof), StakeTableError>;
    fn update(
        &mut self,
        key: &Self::Key,
        delta: Self::Amount,
        negative: bool
    ) -> Result<Self::Amount, StakeTableError>;
    fn sample(
        &self,
        rng: &mut (impl SeedableRng + CryptoRngCore)
    ) -> Option<(&Self::Key, &Self::Amount)>;
    fn try_iter(
        &self,
        version: SnapshotVersion
    ) -> Result<Self::IntoIter, StakeTableError>;

    // Provided methods
    fn batch_register<I, J, K>(
        &mut self,
        new_keys: I,
        amounts: J,
        auxs: K
    ) -> Result<(), StakeTableError>
       where I: IntoIterator<Item = Self::Key>,
             J: IntoIterator<Item = Self::Amount>,
             K: IntoIterator<Item = Self::Aux> { ... }
    fn batch_deregister<'a, I>(
        &mut self,
        existing_keys: I
    ) -> Result<(), StakeTableError>
       where I: IntoIterator<Item = &'a <Self as StakeTableScheme>::Key>,
             <Self as StakeTableScheme>::Key: 'a { ... }
    fn batch_update(
        &mut self,
        keys: &[Self::Key],
        amounts: &[Self::Amount],
        negative_flags: Vec<bool>
    ) -> Result<Vec<Self::Amount>, StakeTableError> { ... }
}

Common interfaces required for a stake table used in HotShot System. APIs that doesn’t take version: SnapshotVersion as an input by default works on the head/latest version.

Required Associated Types

type Key: Clone

type for stake key

type Amount: Clone + Copy

type for the staked amount

type Commitment

type for the commitment to the current stake table

type LookupProof

type for the proof associated with the lookup result (if any)

type IntoIter: Iterator<Item = (Self::Key, Self::Amount, Self::Aux)>

type for the iterator over (key, value) entries

type Aux: Clone

Auxiliary information associated with the key

Required Methods

fn register( &mut self, new_key: Self::Key, amount: Self::Amount, aux: Self::Aux ) -> Result<(), StakeTableError>

Register a new key into the stake table.

Errors

Return err if key is already registered.

fn deregister( &mut self, existing_key: &Self::Key ) -> Result<(), StakeTableError>

Deregister an existing key from the stake table. Returns error if some keys are not found.

Errors

Return err if existing_key wasn’t registered.

fn commitment( &self, version: SnapshotVersion ) -> Result<Self::Commitment, StakeTableError>

Returns the commitment to the version of stake table.

Errors

Return err if the version is not supported.

fn total_stake( &self, version: SnapshotVersion ) -> Result<Self::Amount, StakeTableError>

Returns the accumulated stakes of all registered keys of the version of stake table.

Errors

Return err if the version is not supported.

fn len(&self, version: SnapshotVersion) -> Result<usize, StakeTableError>

Returns the number of keys in the version of the table.

Errors

Return err if the version is not supported.

fn contains_key(&self, key: &Self::Key) -> bool

Returns true if key is currently registered, else returns false.

fn lookup( &self, version: SnapshotVersion, key: &Self::Key ) -> Result<Self::Amount, StakeTableError>

Returns the stakes withhelded by a public key.

Errors

Return err if the version is not supported or key doesn’t exist.

fn lookup_with_proof( &self, version: SnapshotVersion, key: &Self::Key ) -> Result<(Self::Amount, Self::LookupProof), StakeTableError>

Returns the stakes withhelded by a public key along with a membership proof.

Errors

Return err if the version is not supported or key doesn’t exist.

fn lookup_with_aux_and_proof( &self, version: SnapshotVersion, key: &Self::Key ) -> Result<(Self::Amount, Self::Aux, Self::LookupProof), StakeTableError>

Return the associated stake amount and auxiliary information of a public key, along with a membership proof.

Errors

Return err if the version is not supported or key doesn’t exist.

fn update( &mut self, key: &Self::Key, delta: Self::Amount, negative: bool ) -> Result<Self::Amount, StakeTableError>

Update the stake of the key with (negative ? -1 : 1) * delta. Return the updated stake or error.

Errors

Return err if the key doesn’t exist of if the update overflow/underflow.

fn sample( &self, rng: &mut (impl SeedableRng + CryptoRngCore) ) -> Option<(&Self::Key, &Self::Amount)>

Randomly sample a (key, stake amount) pair proportional to the stake distributions, given a fixed seed for rng, this sampling should be deterministic.

fn try_iter( &self, version: SnapshotVersion ) -> Result<Self::IntoIter, StakeTableError>

Returns an iterator over all (key, value) entries of the version of the table

Errors

Return err if the version is not supported.

Provided Methods

fn batch_register<I, J, K>( &mut self, new_keys: I, amounts: J, auxs: K ) -> Result<(), StakeTableError>

where I: IntoIterator<Item = Self::Key>, J: IntoIterator<Item = Self::Amount>, K: IntoIterator<Item = Self::Aux>,

Batch register a list of new keys. A default implementation is provided w/o batch optimization.

Errors

Return err if any of new_keys fails to register.

fn batch_deregister<'a, I>( &mut self, existing_keys: I ) -> Result<(), StakeTableError>

where I: IntoIterator<Item = &'a <Self as StakeTableScheme>::Key>, <Self as StakeTableScheme>::Key: 'a,

Batch deregister a list of keys. A default implementation is provided w/o batch optimization.

Errors

Return err if any of existing_keys fail to deregister.

fn batch_update( &mut self, keys: &[Self::Key], amounts: &[Self::Amount], negative_flags: Vec<bool> ) -> Result<Vec<Self::Amount>, StakeTableError>

Batch update the stake balance of keys. Read documentation about Self::update(). By default, we call Self::update() on each (key, amount, negative) tuple.

Errors

Return err if any one of the update failed.

Object Safety

This trait is not object safe.

Implementors