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

hotshot_types/
lib.rs
