hotshot_types/traits/
election.rs

1// Copyright (c) 2021-2024 Espresso Systems (espressosys.com)
2// This file is part of the HotShot repository.
3
4// You should have received a copy of the MIT License
5// along with the HotShot repository. If not, see <https://mit-license.org/>.
6
7//! The election trait, used to decide which node is the leader and determine if a vote is valid.
8use std::{collections::BTreeSet, fmt::Debug, sync::Arc};
9
10use alloy::primitives::U256;
11use async_broadcast::Receiver;
12use async_lock::RwLock;
13use committable::{Commitment, Committable};
14use hotshot_utils::anytrace::Result;
15
16use super::node_implementation::NodeType;
17use crate::{
18    data::Leaf2,
19    drb::DrbResult,
20    event::Event,
21    stake_table::{supermajority_threshold, HSStakeTable},
22    traits::{node_implementation::NodeImplementation, signature_key::StakeTableEntryType},
23    PeerConfig,
24};
25
26pub struct NoStakeTableHash;
27
28impl Committable for NoStakeTableHash {
29    fn commit(&self) -> Commitment<Self> {
30        Commitment::from_raw([0u8; 32])
31    }
32}
33
34/// A protocol for determining membership in and participating in a committee.
35pub trait Membership<TYPES: NodeType>: Debug + Send + Sync {
36    /// The error type returned by methods like `lookup_leader`.
37    type Error: std::fmt::Display;
38
39    /// Storage type used by the underlying fetcher
40    type Storage;
41
42    type StakeTableHash: Committable;
43
44    /// Create a committee
45    fn new<I: NodeImplementation<TYPES>>(
46        // Note: eligible_leaders is currently a hack because the DA leader == the quorum leader
47        // but they should not have voting power.
48        stake_committee_members: Vec<PeerConfig<TYPES>>,
49        da_committee_members: Vec<PeerConfig<TYPES>>,
50        storage: Self::Storage,
51        network: Arc<<I as NodeImplementation<TYPES>>::Network>,
52        public_key: TYPES::SignatureKey,
53        epoch_height: u64,
54    ) -> Self;
55
56    fn set_external_channel(
57        &mut self,
58        _external_channel: Receiver<Event<TYPES>>,
59    ) -> impl std::future::Future<Output = ()> + Send {
60        async {}
61    }
62
63    fn total_stake(&self, epoch: Option<TYPES::Epoch>) -> U256 {
64        self.stake_table(epoch)
65            .iter()
66            .fold(U256::ZERO, |acc, entry| {
67                acc + entry.stake_table_entry.stake()
68            })
69    }
70
71    fn total_da_stake(&self, epoch: Option<TYPES::Epoch>) -> U256 {
72        self.da_stake_table(epoch)
73            .iter()
74            .fold(U256::ZERO, |acc, entry| {
75                acc + entry.stake_table_entry.stake()
76            })
77    }
78
79    /// Get all participants in the committee (including their stake) for a specific epoch
80    fn stake_table(&self, epoch: Option<TYPES::Epoch>) -> HSStakeTable<TYPES>;
81
82    /// Get all participants in the committee (including their stake) for a specific epoch
83    fn da_stake_table(&self, epoch: Option<TYPES::Epoch>) -> HSStakeTable<TYPES>;
84
85    /// Get all participants in the committee for a specific view for a specific epoch
86    fn committee_members(
87        &self,
88        view_number: TYPES::View,
89        epoch: Option<TYPES::Epoch>,
90    ) -> BTreeSet<TYPES::SignatureKey>;
91
92    /// Get all participants in the committee for a specific view for a specific epoch
93    fn da_committee_members(
94        &self,
95        view_number: TYPES::View,
96        epoch: Option<TYPES::Epoch>,
97    ) -> BTreeSet<TYPES::SignatureKey>;
98
99    /// Get the stake table entry for a public key, returns `None` if the
100    /// key is not in the table for a specific epoch
101    fn stake(
102        &self,
103        pub_key: &TYPES::SignatureKey,
104        epoch: Option<TYPES::Epoch>,
105    ) -> Option<PeerConfig<TYPES>>;
106
107    /// Get the DA stake table entry for a public key, returns `None` if the
108    /// key is not in the table for a specific epoch
109    fn da_stake(
110        &self,
111        pub_key: &TYPES::SignatureKey,
112        epoch: Option<TYPES::Epoch>,
113    ) -> Option<PeerConfig<TYPES>>;
114
115    /// See if a node has stake in the committee in a specific epoch
116    fn has_stake(&self, pub_key: &TYPES::SignatureKey, epoch: Option<TYPES::Epoch>) -> bool;
117
118    /// See if a node has stake in the committee in a specific epoch
119    fn has_da_stake(&self, pub_key: &TYPES::SignatureKey, epoch: Option<TYPES::Epoch>) -> bool;
120
121    /// The leader of the committee for view `view_number` in `epoch`.
122    ///
123    /// Note: this function uses a HotShot-internal error type.
124    /// You should implement `lookup_leader`, rather than implementing this function directly.
125    ///
126    /// # Errors
127    /// Returns an error if the leader cannot be calculated.
128    fn leader(
129        &self,
130        view: TYPES::View,
131        epoch: Option<TYPES::Epoch>,
132    ) -> Result<TYPES::SignatureKey> {
133        use hotshot_utils::anytrace::*;
134
135        self.lookup_leader(view, epoch).wrap().context(info!(
136            "Failed to get leader for view {view} in epoch {epoch:?}"
137        ))
138    }
139
140    /// The leader of the committee for view `view_number` in `epoch`.
141    ///
142    /// Note: There is no such thing as a DA leader, so any consumer
143    /// requiring a leader should call this.
144    ///
145    /// # Errors
146    /// Returns an error if the leader cannot be calculated
147    fn lookup_leader(
148        &self,
149        view: TYPES::View,
150        epoch: Option<TYPES::Epoch>,
151    ) -> std::result::Result<TYPES::SignatureKey, Self::Error>;
152
153    /// Returns the number of total nodes in the committee in an epoch `epoch`
154    fn total_nodes(&self, epoch: Option<TYPES::Epoch>) -> usize;
155
156    /// Returns the number of total DA nodes in the committee in an epoch `epoch`
157    fn da_total_nodes(&self, epoch: Option<TYPES::Epoch>) -> usize;
158
159    /// Returns the threshold for a specific `Membership` implementation
160    fn success_threshold(&self, epoch: Option<<TYPES as NodeType>::Epoch>) -> U256 {
161        let total_stake = self.total_stake(epoch);
162        supermajority_threshold(total_stake)
163    }
164
165    /// Returns the DA threshold for a specific `Membership` implementation
166    fn da_success_threshold(&self, epoch: Option<<TYPES as NodeType>::Epoch>) -> U256 {
167        let total_stake = self.total_da_stake(epoch);
168        let one = U256::ONE;
169        let two = U256::from(2);
170        let three = U256::from(3);
171
172        if total_stake < U256::MAX / two {
173            ((total_stake * two) / three) + one
174        } else {
175            ((total_stake / three) * two) + two
176        }
177    }
178
179    /// Returns the threshold for a specific `Membership` implementation
180    fn failure_threshold(&self, epoch: Option<<TYPES as NodeType>::Epoch>) -> U256 {
181        let total_stake = self.total_stake(epoch);
182        let one = U256::ONE;
183        let three = U256::from(3);
184
185        (total_stake / three) + one
186    }
187
188    /// Returns the threshold required to upgrade the network protocol
189    fn upgrade_threshold(&self, epoch: Option<<TYPES as NodeType>::Epoch>) -> U256 {
190        let total_stake = self.total_stake(epoch);
191        let nine = U256::from(9);
192        let ten = U256::from(10);
193
194        let normal_threshold = self.success_threshold(epoch);
195        let higher_threshold = if total_stake < U256::MAX / nine {
196            (total_stake * nine) / ten
197        } else {
198            (total_stake / ten) * nine
199        };
200
201        std::cmp::max(higher_threshold, normal_threshold)
202    }
203
204    /// Returns if the stake table is available for the given epoch
205    fn has_stake_table(&self, epoch: TYPES::Epoch) -> bool;
206
207    /// Returns if the randomized stake table is available for the given epoch
208    fn has_randomized_stake_table(&self, epoch: TYPES::Epoch) -> anyhow::Result<bool>;
209
210    /// Gets the validated block header and epoch number of the epoch root
211    /// at the given block height
212    fn get_epoch_root(
213        _membership: Arc<RwLock<Self>>,
214        _epoch: TYPES::Epoch,
215    ) -> impl std::future::Future<Output = anyhow::Result<Leaf2<TYPES>>> + Send;
216
217    /// Gets the DRB result for the given epoch
218    fn get_epoch_drb(
219        _membership: Arc<RwLock<Self>>,
220        _epoch: TYPES::Epoch,
221    ) -> impl std::future::Future<Output = anyhow::Result<DrbResult>> + Send;
222
223    /// Handles notifications that a new epoch root has been created.
224    fn add_epoch_root(
225        _membership: Arc<RwLock<Self>>,
226        _block_header: TYPES::BlockHeader,
227    ) -> impl std::future::Future<Output = anyhow::Result<()>> + Send;
228
229    /// Called to notify the Membership when a new DRB result has been calculated.
230    /// Observes the same semantics as add_epoch_root
231    fn add_drb_result(&mut self, _epoch: TYPES::Epoch, _drb_result: DrbResult);
232
233    /// Called to notify the Membership that Epochs are enabled.
234    /// Implementations should copy the pre-epoch stake table into epoch and epoch+1
235    /// when this is called. The value of initial_drb_result should be used for DRB
236    /// calculations for epochs (epoch+1) and earlier.
237    fn set_first_epoch(&mut self, _epoch: TYPES::Epoch, _initial_drb_result: DrbResult);
238
239    /// Get first epoch if epochs are enabled, `None` otherwise
240    fn first_epoch(&self) -> Option<TYPES::Epoch>;
241
242    /// Returns the commitment of the stake table for the given epoch,
243    /// Errors if the stake table is not available for the given epoch
244    fn stake_table_hash(&self, _epoch: TYPES::Epoch) -> Option<Commitment<Self::StakeTableHash>> {
245        None
246    }
247
248    fn add_da_committee(&mut self, _first_epoch: u64, _da_committee: Vec<PeerConfig<TYPES>>);
249}
hotshot_types/traits/election.rs

hotshot_types/traits/
election.rs
