ab_client_consensus_common/
lib.rs

1#![feature(option_into_flat_iter)]
2
3pub mod consensus_parameters;
4pub mod state;
5#[cfg(test)]
6mod test_utils;
7
8use ab_core_primitives::block::{BlockNumber, BlockTimestamp};
9use ab_core_primitives::pot::{SlotDuration, SlotNumber};
10use ab_core_primitives::segments::HistorySize;
11use futures::channel::mpsc;
12
13/// Proof-of-time consensus constants
14#[derive(Debug, PartialEq, Eq, Clone, Copy)]
15pub struct PotConsensusConstants {
16    /// Interval, in blocks, between blockchain entropy injection into the proof of time chain
17    pub entropy_injection_interval: BlockNumber,
18    /// Interval, in entropy injection intervals, where to take entropy for injection from
19    pub entropy_injection_lookback_depth: u8,
20    /// Delay after block, in slots, when entropy injection takes effect
21    pub entropy_injection_delay: SlotNumber,
22}
23
24/// Consensus constants
25#[derive(Debug, PartialEq, Eq, Clone, Copy)]
26pub struct ConsensusConstants {
27    /// Depth at which a block is confirmed and enters the recorded history.
28    ///
29    /// When block `n` is built, the block at `n - block_confirmation_depth` is confirmed, so the
30    /// largest possible reorg is `block_confirmation_depth - 1` blocks. Importing the next best
31    /// block (block number `best_number + 1`) confirms the block at
32    /// `best_number + 1 - block_confirmation_depth`, so fork blocks must be above it, and blocks
33    /// up to it are the same on every chain that can still be extended. This is why they can
34    /// be referenced by block number alone.
35    ///
36    /// With `block_confirmation_depth = 5` and `shard_confirmation_depth = 2`:
37    ///
38    /// ```text
39    /// block number
40    /// best_number + 1  next best block
41    /// best_number      best block
42    /// best_number - 3  deepest fork blocks
43    /// best_number - 4  confirmed once the next best block is imported  -+ read by the super
44    /// best_number - 5  confirmed                                        | segment derivation of
45    /// best_number - 6  confirmed                                       -+ the next best block
46    /// ```
47    ///
48    /// The block lifecycle in the database is shown on `ClientDatabaseOptions` in
49    /// `ab-client-database`.
50    ///
51    /// This is from the perspective of the individual shard, with additional confirmation on the
52    /// beacon chain required for intermediate and leaf shards (see `shard_confirmation_depth`).
53    pub block_confirmation_depth: BlockNumber,
54    /// Depth on the beacon chain in addition to `block_confirmation_depth` after intermediate or
55    /// leaf shard information on the beacon chain is confirmed and corresponding segment roots
56    /// become a part of the super segment.
57    ///
58    /// Segment roots included in the beacon chain block at
59    /// `n - block_confirmation_depth - shard_confirmation_depth` become a part of the super
60    /// segment of block `n` unless later beacon chain blocks up to `n - block_confirmation_depth`
61    /// show that their shard reorged them (see the diagram on `block_confirmation_depth`).
62    ///
63    /// This is separate from the block confirmation on the corresponding shard itself, which
64    /// happens much sooner (see `block_confirmation_depth`), but can't be immediately trusted by
65    /// the beacon chain.
66    pub shard_confirmation_depth: BlockNumber,
67    /// Number of slots between slot arrival and when the corresponding block can be produced
68    pub block_authoring_delay: SlotNumber,
69    /// Proof-of-time consensus constants
70    pub pot: PotConsensusConstants,
71    // TODO: Non-zero block number would be nice
72    /// Period of time in blocks after which the solution range is adjusted
73    pub retarget_interval: BlockNumber,
74    /// Slot probability
75    pub slot_probability: (u64, u64),
76    /// The slot duration in milliseconds
77    pub slot_duration: SlotDuration,
78    /// Number of latest archived segments that are considered "recent history"
79    pub recent_segments: HistorySize,
80    /// Fraction of pieces from the "recent history" (`recent_segments`) in each sector
81    pub recent_history_fraction: (HistorySize, HistorySize),
82    /// Minimum lifetime of a plotted sector, measured in archived segments
83    pub min_sector_lifetime: HistorySize,
84    /// Max block timestamp drift allowed
85    pub max_block_timestamp_drift: BlockTimestamp,
86    // TODO: Non-zero block number would be nice
87    /// Number of beacon chain blocks between shard rotations.
88    ///
89    /// Every this number of beacon chain blocks PoT entropy is taken to calculate the next shard
90    /// assignment.
91    pub shard_rotation_interval: BlockNumber,
92    /// Delay in beacon chain blocks for the next shard rotation.
93    ///
94    /// Delay after shard assignment is revealed before it actually takes effect (essentially the
95    /// amount of time for a node to sync the corresponding shard).
96    pub shard_rotation_delay: BlockNumber,
97}
98
99/// Notification with information about the block that is about to be imported and acknowledgement
100/// sender that can be used to pause block production if necessary
101#[derive(Debug, Clone)]
102pub struct BlockImportingNotification {
103    /// Block number
104    pub block_number: BlockNumber,
105    /// Sender for pausing the block import for archiving purposes is not fast enough to process
106    /// the consensus block
107    pub acknowledgement_sender: mpsc::Sender<()>,
108}
ab_client_consensus_common/lib.rs

ab_client_consensus_common/
lib.rs
