solana_clock/lib.rs
1//! Information about the network's clock, ticks, slots, etc.
2//!
3//! Time in Solana is marked primarily by _slots_, which occur approximately every
4//! 400 milliseconds, and are numbered sequentially. For every slot, a leader is
5//! chosen from the validator set, and that leader is expected to produce a new
6//! block, though sometimes leaders may fail to do so. Blocks can be identified
7//! by their slot number, and some slots do not contain a block.
8//!
9//! An approximation of the passage of real-world time can be calculated by
10//! multiplying a number of slots by [`DEFAULT_MS_PER_SLOT`], which is a constant target
11//! time for the network to produce slots. Note though that this method suffers
12//! a variable amount of drift, as the network does not produce slots at exactly
13//! the target rate, and the greater number of slots being calculated for, the
14//! greater the drift. Epochs cannot be used this way as they contain variable
15//! numbers of slots.
16//!
17//! The network's current view of the real-world time can always be accessed via
18//! [`Clock::unix_timestamp`], which is produced by an [oracle derived from the
19//! validator set][oracle].
20//!
21//! [oracle]: https://docs.solanalabs.com/implemented-proposals/validator-timestamp-oracle
22#![no_std]
23#![cfg_attr(docsrs, feature(doc_cfg))]
24
25#[cfg(feature = "sysvar")]
26pub mod sysvar;
27
28#[cfg(feature = "serde")]
29use serde_derive::{Deserialize, Serialize};
30use solana_sdk_macro::CloneZeroed;
31
32/// The default tick rate that the cluster attempts to achieve (160 per second).
33///
34/// Note that the actual tick rate at any given time should be expected to drift.
35pub const DEFAULT_TICKS_PER_SECOND: u64 = 160;
36
37#[cfg(test)]
38static_assertions::const_assert_eq!(MS_PER_TICK, 6);
39
40/// The number of milliseconds per tick (6).
41pub const MS_PER_TICK: u64 = 1000 / DEFAULT_TICKS_PER_SECOND;
42
43// At 160 ticks/s, 64 ticks per slot implies that leader rotation and voting will happen
44// every 400 ms. A fast voting cadence ensures faster finality and convergence
45pub const DEFAULT_TICKS_PER_SLOT: u64 = 64;
46
47pub const DEFAULT_HASHES_PER_SECOND: u64 = 10_000_000;
48
49#[cfg(test)]
50static_assertions::const_assert_eq!(DEFAULT_HASHES_PER_TICK, 62_500);
51pub const DEFAULT_HASHES_PER_TICK: u64 = DEFAULT_HASHES_PER_SECOND / DEFAULT_TICKS_PER_SECOND;
52
53// 1 Dev Epoch = 400 ms * 8192 ~= 55 minutes
54pub const DEFAULT_DEV_SLOTS_PER_EPOCH: u64 = 8192;
55
56#[cfg(test)]
57static_assertions::const_assert_eq!(SECONDS_PER_DAY, 86_400);
58pub const SECONDS_PER_DAY: u64 = 24 * 60 * 60;
59
60#[cfg(test)]
61static_assertions::const_assert_eq!(TICKS_PER_DAY, 13_824_000);
62pub const TICKS_PER_DAY: u64 = DEFAULT_TICKS_PER_SECOND * SECONDS_PER_DAY;
63
64#[cfg(test)]
65static_assertions::const_assert_eq!(DEFAULT_SLOTS_PER_EPOCH, 432_000);
66
67/// The number of slots per epoch after initial network warmup.
68///
69/// 1 Epoch ~= 2 days.
70pub const DEFAULT_SLOTS_PER_EPOCH: u64 = 2 * TICKS_PER_DAY / DEFAULT_TICKS_PER_SLOT;
71
72// leader schedule is governed by this
73#[deprecated(since = "3.1.0", note = "Moved to solana-leader-schedule crate")]
74pub const NUM_CONSECUTIVE_LEADER_SLOTS: u64 = 4;
75
76#[cfg(test)]
77static_assertions::const_assert_eq!(DEFAULT_MS_PER_SLOT, 400);
78/// The expected duration of a slot (400 milliseconds).
79pub const DEFAULT_MS_PER_SLOT: u64 = 1_000 * DEFAULT_TICKS_PER_SLOT / DEFAULT_TICKS_PER_SECOND;
80pub const DEFAULT_S_PER_SLOT: f64 = DEFAULT_TICKS_PER_SLOT as f64 / DEFAULT_TICKS_PER_SECOND as f64;
81
82/// The time window of recent block hash values over which the bank will track
83/// signatures.
84///
85/// Once the bank discards a block hash, it will reject any transactions that
86/// use that `recent_blockhash` in a transaction. Lowering this value reduces
87/// memory consumption, but requires a client to update its `recent_blockhash`
88/// more frequently. Raising the value lengthens the time a client must wait to
89/// be certain a missing transaction will not be processed by the network.
90pub const MAX_HASH_AGE_IN_SECONDS: usize = 120;
91
92#[cfg(test)]
93static_assertions::const_assert_eq!(MAX_RECENT_BLOCKHASHES, 300);
94// Number of maximum recent blockhashes (one blockhash per non-skipped slot)
95pub const MAX_RECENT_BLOCKHASHES: usize =
96 MAX_HASH_AGE_IN_SECONDS * DEFAULT_TICKS_PER_SECOND as usize / DEFAULT_TICKS_PER_SLOT as usize;
97
98#[cfg(test)]
99static_assertions::const_assert_eq!(MAX_PROCESSING_AGE, 150);
100// The maximum age of a blockhash that will be accepted by the leader
101pub const MAX_PROCESSING_AGE: usize = MAX_RECENT_BLOCKHASHES / 2;
102
103/// This is maximum time consumed in forwarding a transaction from one node to next, before
104/// it can be processed in the target node
105pub const MAX_TRANSACTION_FORWARDING_DELAY_GPU: usize = 2;
106
107/// More delay is expected if CUDA is not enabled (as signature verification takes longer)
108pub const MAX_TRANSACTION_FORWARDING_DELAY: usize = 6;
109
110/// Transaction forwarding, which leader to forward to and how long to hold
111pub const FORWARD_TRANSACTIONS_TO_LEADER_AT_SLOT_OFFSET: u64 = 2;
112pub const HOLD_TRANSACTIONS_SLOT_OFFSET: u64 = 20;
113
114/// The unit of time given to a leader for encoding a block.
115///
116/// It is some number of _ticks_ long.
117pub type Slot = u64;
118
119/// Uniquely distinguishes every version of a slot.
120///
121/// The `BankId` is unique even if the slot number of two different slots is the
122/// same. This can happen in the case of e.g. duplicate slots.
123pub type BankId = u64;
124
125/// The unit of time a given leader schedule is honored.
126///
127/// It lasts for some number of [`Slot`]s.
128pub type Epoch = u64;
129
130pub const GENESIS_EPOCH: Epoch = 0;
131// must be sync with Account::rent_epoch::default()
132pub const INITIAL_RENT_EPOCH: Epoch = 0;
133
134/// An index to the slots of a epoch.
135pub type SlotIndex = u64;
136
137/// The number of slots in a epoch.
138pub type SlotCount = u64;
139
140/// An approximate measure of real-world time.
141///
142/// Expressed as Unix time (i.e. seconds since the Unix epoch).
143pub type UnixTimestamp = i64;
144
145/// A representation of network time.
146///
147/// All members of `Clock` start from 0 upon network boot.
148#[repr(C)]
149#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
150#[cfg_attr(feature = "wincode", derive(wincode::SchemaWrite, wincode::SchemaRead))]
151#[derive(Debug, CloneZeroed, Default, PartialEq, Eq)]
152pub struct Clock {
153 /// The current `Slot`.
154 pub slot: Slot,
155 /// The timestamp of the first `Slot` in this `Epoch`.
156 pub epoch_start_timestamp: UnixTimestamp,
157 /// The current `Epoch`.
158 pub epoch: Epoch,
159 /// The future `Epoch` for which the leader schedule has
160 /// most recently been calculated.
161 pub leader_schedule_epoch: Epoch,
162 /// The approximate real world time of the current slot.
163 ///
164 /// This value was originally computed from genesis creation time and
165 /// network time in slots, incurring a lot of drift. Following activation of
166 /// the [`timestamp_correction` and `timestamp_bounding`][tsc] features it
167 /// is calculated using a [validator timestamp oracle][oracle].
168 ///
169 /// [tsc]: https://docs.solanalabs.com/implemented-proposals/bank-timestamp-correction
170 /// [oracle]: https://docs.solanalabs.com/implemented-proposals/validator-timestamp-oracle
171 pub unix_timestamp: UnixTimestamp,
172}
173
174#[cfg(test)]
175mod tests {
176 use super::*;
177
178 #[test]
179 fn test_clone() {
180 let clock = Clock {
181 slot: 1,
182 epoch_start_timestamp: 2,
183 epoch: 3,
184 leader_schedule_epoch: 4,
185 unix_timestamp: 5,
186 };
187 let cloned_clock = clock.clone();
188 assert_eq!(cloned_clock, clock);
189 }
190}