hotshot_types/
lib.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//! Types and Traits for the `HotShot` consensus module
8use std::{fmt::Debug, future::Future, num::NonZeroUsize, pin::Pin, time::Duration};
9
10use alloy::primitives::U256;
11use bincode::Options;
12use displaydoc::Display;
13use stake_table::HSStakeTable;
14use tracing::error;
15use traits::{
16    node_implementation::NodeType,
17    signature_key::{SignatureKey, StateSignatureKey},
18};
19use url::Url;
20use vbs::version::Version;
21use vec1::Vec1;
22
23use crate::utils::bincode_opts;
24pub mod bundle;
25pub mod consensus;
26pub mod constants;
27pub mod data;
28/// Holds the types and functions for DRB computation.
29pub mod drb;
30/// Epoch Membership wrappers
31pub mod epoch_membership;
32pub mod error;
33pub mod event;
34/// Holds the configuration file specification for a HotShot node.
35pub mod hotshot_config_file;
36pub mod light_client;
37pub mod message;
38
39/// Holds the network configuration specification for HotShot nodes.
40pub mod network;
41pub mod qc;
42pub mod request_response;
43pub mod signature_key;
44pub mod simple_certificate;
45pub mod simple_vote;
46pub mod stake_table;
47pub mod traits;
48
49pub mod storage_metrics;
50/// Holds the upgrade configuration specification for HotShot nodes.
51pub mod upgrade_config;
52pub mod utils;
53pub mod vid;
54pub mod vote;
55
56/// Pinned future that is Send and Sync
57pub type BoxSyncFuture<'a, T> = Pin<Box<dyn Future<Output = T> + Send + Sync + 'a>>;
58
59/// yoinked from futures crate
60pub fn assert_future<T, F>(future: F) -> F
61where
62    F: Future<Output = T>,
63{
64    future
65}
66/// yoinked from futures crate, adds sync bound that we need
67pub fn boxed_sync<'a, F>(fut: F) -> BoxSyncFuture<'a, F::Output>
68where
69    F: Future + Sized + Send + Sync + 'a,
70{
71    assert_future::<F::Output, _>(Box::pin(fut))
72}
73
74#[derive(Clone, Debug, Display)]
75/// config for validator, including public key, private key, stake value
76pub struct ValidatorConfig<TYPES: NodeType> {
77    /// The validator's public key and stake value
78    pub public_key: TYPES::SignatureKey,
79    /// The validator's private key, should be in the mempool, not public
80    pub private_key: <TYPES::SignatureKey as SignatureKey>::PrivateKey,
81    /// The validator's stake
82    pub stake_value: U256,
83    /// the validator's key pairs for state verification
84    pub state_public_key: TYPES::StateSignatureKey,
85    /// the validator's key pairs for state verification
86    pub state_private_key: <TYPES::StateSignatureKey as StateSignatureKey>::StatePrivateKey,
87    /// Whether or not this validator is DA
88    pub is_da: bool,
89}
90
91impl<TYPES: NodeType> ValidatorConfig<TYPES> {
92    /// generate validator config from input seed, index, stake value, and whether it's DA
93    #[must_use]
94    pub fn generated_from_seed_indexed(
95        seed: [u8; 32],
96        index: u64,
97        stake_value: U256,
98        is_da: bool,
99    ) -> Self {
100        let (public_key, private_key) =
101            TYPES::SignatureKey::generated_from_seed_indexed(seed, index);
102        let (state_public_key, state_private_key) =
103            TYPES::StateSignatureKey::generated_from_seed_indexed(seed, index);
104        Self {
105            public_key,
106            private_key,
107            stake_value,
108            state_public_key,
109            state_private_key,
110            is_da,
111        }
112    }
113
114    /// get the public config of the validator
115    pub fn public_config(&self) -> PeerConfig<TYPES> {
116        PeerConfig {
117            stake_table_entry: self.public_key.stake_table_entry(self.stake_value),
118            state_ver_key: self.state_public_key.clone(),
119        }
120    }
121}
122
123impl<TYPES: NodeType> Default for ValidatorConfig<TYPES> {
124    fn default() -> Self {
125        Self::generated_from_seed_indexed([0u8; 32], 0, U256::from(1), true)
126    }
127}
128
129#[derive(serde::Serialize, serde::Deserialize, Clone, Display, PartialEq, Eq, Hash)]
130#[serde(bound(deserialize = ""))]
131/// structure of peers' config, including public key, stake value, and state key.
132pub struct PeerConfig<TYPES: NodeType> {
133    ////The peer's public key and stake value. The key is the BLS Public Key used to
134    /// verify Stake Holder in the application layer.
135    pub stake_table_entry: <TYPES::SignatureKey as SignatureKey>::StakeTableEntry,
136    //// The peer's state public key. This is the Schnorr Public Key used to
137    /// verify HotShot state in the state-prover.
138    pub state_ver_key: TYPES::StateSignatureKey,
139}
140
141impl<TYPES: NodeType> PeerConfig<TYPES> {
142    /// Serialize a peer's config to bytes
143    pub fn to_bytes(config: &Self) -> Vec<u8> {
144        let x = bincode_opts().serialize(config);
145        match x {
146            Ok(x) => x,
147            Err(e) => {
148                error!(?e, "Failed to serialize public key");
149                vec![]
150            },
151        }
152    }
153
154    /// Deserialize a peer's config from bytes
155    /// # Errors
156    /// Will return `None` if deserialization fails
157    pub fn from_bytes(bytes: &[u8]) -> Option<Self> {
158        let x: Result<PeerConfig<TYPES>, _> = bincode_opts().deserialize(bytes);
159        match x {
160            Ok(pub_key) => Some(pub_key),
161            Err(e) => {
162                error!(?e, "Failed to deserialize public key");
163                None
164            },
165        }
166    }
167}
168
169impl<TYPES: NodeType> Default for PeerConfig<TYPES> {
170    fn default() -> Self {
171        let default_validator_config = ValidatorConfig::<TYPES>::default();
172        default_validator_config.public_config()
173    }
174}
175
176impl<TYPES: NodeType> Debug for PeerConfig<TYPES> {
177    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
178        f.debug_struct("PeerConfig")
179            .field("stake_table_entry", &self.stake_table_entry)
180            .field("state_ver_key", &format_args!("{}", self.state_ver_key))
181            .finish()
182    }
183}
184
185#[derive(Clone, derive_more::Debug, serde::Serialize, serde::Deserialize)]
186#[serde(bound(deserialize = ""))]
187pub struct VersionedDaCommittee<TYPES: NodeType> {
188    #[serde(with = "version_ser")]
189    pub start_version: Version,
190    pub start_epoch: u64,
191    pub committee: Vec<PeerConfig<TYPES>>,
192}
193
194/// Holds configuration for a `HotShot`
195#[derive(Clone, derive_more::Debug, serde::Serialize, serde::Deserialize)]
196#[serde(bound(deserialize = ""))]
197pub struct HotShotConfig<TYPES: NodeType> {
198    /// The proportion of nodes required before the orchestrator issues the ready signal,
199    /// expressed as (numerator, denominator)
200    pub start_threshold: (u64, u64),
201    /// Total number of nodes in the network
202    // Earlier it was total_nodes
203    pub num_nodes_with_stake: NonZeroUsize,
204    /// List of known node's public keys and stake value for certificate aggregation, serving as public parameter
205    pub known_nodes_with_stake: Vec<PeerConfig<TYPES>>,
206    /// All public keys known to be DA nodes
207    pub known_da_nodes: Vec<PeerConfig<TYPES>>,
208    /// All public keys known to be DA nodes, by start epoch
209    pub da_committees: Vec<VersionedDaCommittee<TYPES>>,
210    /// List of DA committee (staking)nodes for static DA committee
211    pub da_staked_committee_size: usize,
212    /// Number of fixed leaders for GPU VID, normally it will be 0, it's only used when running GPU VID
213    pub fixed_leader_for_gpuvid: usize,
214    /// Base duration for next-view timeout, in milliseconds
215    pub next_view_timeout: u64,
216    /// Duration of view sync round timeouts
217    pub view_sync_timeout: Duration,
218    /// Number of network bootstrap nodes
219    pub num_bootstrap: usize,
220    /// The maximum amount of time a leader can wait to get a block from a builder
221    pub builder_timeout: Duration,
222    /// time to wait until we request data associated with a proposal
223    pub data_request_delay: Duration,
224    /// Builder API base URL
225    pub builder_urls: Vec1<Url>,
226    /// View to start proposing an upgrade
227    pub start_proposing_view: u64,
228    /// View to stop proposing an upgrade. To prevent proposing an upgrade, set stop_proposing_view <= start_proposing_view.
229    pub stop_proposing_view: u64,
230    /// View to start voting on an upgrade
231    pub start_voting_view: u64,
232    /// View to stop voting on an upgrade. To prevent voting on an upgrade, set stop_voting_view <= start_voting_view.
233    pub stop_voting_view: u64,
234    /// Unix time in seconds at which we start proposing an upgrade
235    pub start_proposing_time: u64,
236    /// Unix time in seconds at which we stop proposing an upgrade. To prevent proposing an upgrade, set stop_proposing_time <= start_proposing_time.
237    pub stop_proposing_time: u64,
238    /// Unix time in seconds at which we start voting on an upgrade
239    pub start_voting_time: u64,
240    /// Unix time in seconds at which we stop voting on an upgrade. To prevent voting on an upgrade, set stop_voting_time <= start_voting_time.
241    pub stop_voting_time: u64,
242    /// Number of blocks in an epoch, zero means there are no epochs
243    pub epoch_height: u64,
244    /// Epoch start block   
245    #[serde(default = "default_epoch_start_block")]
246    pub epoch_start_block: u64,
247    /// Stake table capacity for light client use
248    #[serde(default = "default_stake_table_capacity")]
249    pub stake_table_capacity: usize,
250    /// number of iterations in the DRB calculation
251    pub drb_difficulty: u64,
252    /// number of iterations in the DRB calculation
253    pub drb_upgrade_difficulty: u64,
254}
255
256fn default_epoch_start_block() -> u64 {
257    1
258}
259
260fn default_stake_table_capacity() -> usize {
261    crate::light_client::DEFAULT_STAKE_TABLE_CAPACITY
262}
263
264impl<TYPES: NodeType> HotShotConfig<TYPES> {
265    /// Update a hotshot config to have a view-based upgrade.
266    pub fn set_view_upgrade(&mut self, view: u64) {
267        self.start_proposing_view = view;
268        self.stop_proposing_view = view + 1;
269        self.start_voting_view = view.saturating_sub(1);
270        self.stop_voting_view = view + 10;
271        self.start_proposing_time = 0;
272        self.stop_proposing_time = u64::MAX;
273        self.start_voting_time = 0;
274        self.stop_voting_time = u64::MAX;
275    }
276
277    /// Return the `known_nodes_with_stake` as a `HSStakeTable`
278    pub fn hotshot_stake_table(&self) -> HSStakeTable<TYPES> {
279        self.known_nodes_with_stake.clone().into()
280    }
281}
282
283pub mod version_ser {
284
285    use serde::{de, Deserialize, Deserializer, Serializer};
286    use vbs::version::Version;
287
288    pub fn serialize<S>(ver: &Version, serializer: S) -> Result<S::Ok, S::Error>
289    where
290        S: Serializer,
291    {
292        serializer.serialize_str(&ver.to_string())
293    }
294
295    pub fn deserialize<'de, D>(deserializer: D) -> Result<Version, D::Error>
296    where
297        D: Deserializer<'de>,
298    {
299        let version_str = String::deserialize(deserializer)?;
300
301        let version: Vec<_> = version_str.split('.').collect();
302
303        let version = Version {
304            major: version[0]
305                .parse()
306                .map_err(|_| de::Error::custom("invalid version format"))?,
307            minor: version[1]
308                .parse()
309                .map_err(|_| de::Error::custom("invalid version format"))?,
310        };
311
312        Ok(version)
313    }
314}
hotshot_types/lib.rs

hotshot_types/
lib.rs
