Struct hotshot_stake_table::vec_based::StakeTable

pub struct StakeTable<K1, K2, F>
where
    K1: Eq + Hash + Clone + ToFields<F>,
    K2: Eq + Hash + Clone + Default + ToFields<F>,
    F: RescueParameter,
{
    capacity: usize,
    head: StakeTableSnapshot<K1, K2>,
    epoch_start: StakeTableSnapshot<K1, K2>,
    last_epoch_start: StakeTableSnapshot<K1, K2>,
    head_total_stake: U256,
    epoch_start_total_stake: U256,
    last_epoch_start_total_stake: U256,
    epoch_start_comm: (F, F, F),
    last_epoch_start_comm: (F, F, F),
    bls_mapping: HashMap<K1, usize>,
}

Locally maintained stake table, generic over public key type K. Whose commitment is a rescue hash of all key-value pairs over field F. NOTE: the commitment is only available for the finalized versions, and is computed only once when it’s finalized.

Fields

capacity: usize

upper bound on table size

head: StakeTableSnapshot<K1, K2>

The most up-to-date stake table, where the incoming transactions shall be performed on.

epoch_start: StakeTableSnapshot<K1, K2>

The snapshot of stake table at the beginning of the current epoch

last_epoch_start: StakeTableSnapshot<K1, K2>

The stake table used for leader election.

head_total_stake: U256

Total stakes in the most update-to-date stake table

epoch_start_total_stake: U256

Total stakes in the snapshot version EpochStart

last_epoch_start_total_stake: U256

Total stakes in the snapshot version LastEpochStart

epoch_start_comm: (F, F, F)

Commitment of the stake table snapshot version EpochStart We only support committing the finalized versions. Commitment for a finalized version is a triple where

• First item is the rescue hash of the bls keys
• Second item is the rescue hash of the Schnorr keys
• Third item is the rescue hash of all the stake amounts

last_epoch_start_comm: (F, F, F)

Commitment of the stake table snapshot version LastEpochStart

bls_mapping: HashMap<K1, usize>

The mapping from public keys to their location in the Merkle tree.

Implementations

impl<K1, K2, F> StakeTable<K1, K2, F>

where K1: Eq + Hash + Clone + ToFields<F>, K2: Eq + Hash + Clone + Default + ToFields<F>, F: RescueParameter,

pub fn new(capacity: usize) -> Self

Initiating an empty stake table.

Panics

If unable to evaluate a preimage

pub fn advance(&mut self)

Update the stake table when the epoch number advances, should be manually called.

pub fn set_value( &mut self, key: &K1, value: U256, ) -> Result<U256, StakeTableError>

Set the stake withheld by key to be value. Return the previous stake if succeed.

Errors

Errors if key is not in the stake table

fn compute_head_comm(&mut self) -> (F, F, F)

Helper function to recompute the stake table commitment for head version Commitment of a stake table is a triple (bls_keys_comm, schnorr_keys_comm, stake_amount_comm) TODO(Chengyu): The BLS verification keys doesn’t implement Default. Thus we directly pad with F::default().

fn lookup_pos(&self, key: &K1) -> Result<usize, StakeTableError>

Return the index of a given key. Err if the key doesn’t exists

fn version( &self, version: &SnapshotVersion, ) -> Result<&StakeTableSnapshot<K1, K2>, StakeTableError>

returns the snapshot version

Trait Implementations

impl<K1, K2, F> Clone for StakeTable<K1, K2, F>

where K1: Eq + Hash + Clone + ToFields<F> + Clone, K2: Eq + Hash + Clone + Default + ToFields<F> + Clone, F: RescueParameter + Clone,

fn clone(&self) -> StakeTable<K1, K2, F>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<K1, K2, F> Debug for StakeTable<K1, K2, F>

where K1: Eq + Hash + Clone + ToFields<F> + Debug, K2: Eq + Hash + Clone + Default + ToFields<F> + Debug, F: RescueParameter + Debug,

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

Formats the value using the given formatter.

impl<K1, K2, F> Default for StakeTable<K1, K2, F>

where K1: Eq + Hash + Clone + ToFields<F>, K2: Eq + Hash + Clone + Default + ToFields<F>, F: RescueParameter,

fn default() -> Self

Returns the “default value” for a type.

impl<'de, K1, K2, F> Deserialize<'de> for StakeTable<K1, K2, F>

where K1: Eq + Hash + Clone + ToFields<F> + Deserialize<'de> + Default, K2: Eq + Hash + Clone + Default + ToFields<F> + Deserialize<'de>, F: RescueParameter + Deserialize<'de>,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<K1, K2, F> PartialEq for StakeTable<K1, K2, F>

where K1: Eq + Hash + Clone + ToFields<F> + PartialEq, K2: Eq + Hash + Clone + Default + ToFields<F> + PartialEq, F: RescueParameter + PartialEq,

fn eq(&self, other: &StakeTable<K1, K2, F>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<K1, K2, F> Serialize for StakeTable<K1, K2, F>

where K1: Eq + Hash + Clone + ToFields<F> + Serialize, K2: Eq + Hash + Clone + Default + ToFields<F> + Serialize, F: RescueParameter + Serialize,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<K1, K2, F> StakeTableScheme for StakeTable<K1, K2, F>

where K1: Eq + Hash + Clone + ToFields<F>, K2: Eq + Hash + Clone + Default + ToFields<F>, F: RescueParameter,

type Key = K1

The stake table is indexed by BLS key

type Aux = K2

The auxiliary information is the associated Schnorr key

type Amount = U256

type for the staked amount

type Commitment = (F, F, F)

type for the commitment to the current stake table

type LookupProof = ()

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

type IntoIter = <Vec<(K1, U256, K2)> as IntoIterator>::IntoIter

type for the iterator over (key, value) entries

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

Register a new key into the stake table.

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.

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

Returns the commitment to the version of stake table.

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

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

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

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

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.

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.

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.

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.

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

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.

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

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

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

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.

impl<K1, K2, F> Eq for StakeTable<K1, K2, F>

where K1: Eq + Hash + Clone + ToFields<F> + Eq, K2: Eq + Hash + Clone + Default + ToFields<F> + Eq, F: RescueParameter + Eq,

impl<K1, K2, F> StructuralPartialEq for StakeTable<K1, K2, F>

where K1: Eq + Hash + Clone + ToFields<F>, K2: Eq + Hash + Clone + Default + ToFields<F>, F: RescueParameter,