zebra_consensus/checkpoint/
types.rs

Help
1//! Supporting types for checkpoint-based block verification
2
3use std::cmp::Ordering;
4
5use zebra_chain::block;
6
7use Progress::*;
8use TargetHeight::*;
9
10/// A `CheckpointVerifier`'s current progress verifying the chain.
11#[derive(Clone, Copy, Debug, Eq, PartialEq)]
12pub enum Progress<HeightOrHash> {
13    /// We have not verified any blocks yet.
14    BeforeGenesis,
15
16    /// We have verified up to and including this initial tip.
17    ///
18    /// Initial tips might not be one of our hard-coded checkpoints, because we
19    /// might have:
20    ///   - changed the checkpoint spacing, or
21    ///   - added new checkpoints above the initial tip.
22    InitialTip(HeightOrHash),
23
24    /// We have verified up to and including this checkpoint.
25    PreviousCheckpoint(HeightOrHash),
26
27    /// We have finished verifying.
28    ///
29    /// The final checkpoint is not included in this variant. The verifier has
30    /// finished, so the checkpoints aren't particularly useful.
31    /// To get the value of the final checkpoint, use `checkpoint_list.max_height()`.
32    FinalCheckpoint,
33}
34
35/// Block height progress, in chain order.
36impl Ord for Progress<block::Height> {
37    fn cmp(&self, other: &Self) -> Ordering {
38        if self == other {
39            return Ordering::Equal;
40        }
41        match (self, other) {
42            (BeforeGenesis, _) => Ordering::Less,
43            (_, BeforeGenesis) => Ordering::Greater,
44            (FinalCheckpoint, _) => Ordering::Greater,
45            (_, FinalCheckpoint) => Ordering::Less,
46            (InitialTip(self_height), InitialTip(other_height))
47            | (InitialTip(self_height), PreviousCheckpoint(other_height))
48            | (PreviousCheckpoint(self_height), InitialTip(other_height))
49            | (PreviousCheckpoint(self_height), PreviousCheckpoint(other_height)) => {
50                self_height.cmp(other_height)
51            }
52        }
53    }
54}
55
56/// Partial order for block height progress.
57///
58/// The partial order must match the total order.
59impl PartialOrd for Progress<block::Height> {
60    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
61        Some(self.cmp(other))
62    }
63}
64
65impl Progress<block::Height> {
66    /// Returns the contained height, or `None` if the progress has finished, or has not started.
67    pub fn height(&self) -> Option<block::Height> {
68        match self {
69            BeforeGenesis => None,
70            InitialTip(height) => Some(*height),
71            PreviousCheckpoint(height) => Some(*height),
72            FinalCheckpoint => None,
73        }
74    }
75}
76
77impl<HeightOrHash> Progress<HeightOrHash> {
78    /// Returns `true` if the progress is before the genesis block.
79    #[allow(dead_code)]
80    pub fn is_before_genesis(&self) -> bool {
81        matches!(self, BeforeGenesis)
82    }
83
84    /// Returns `true` if the progress is at or after the final checkpoint block.
85    pub fn is_final_checkpoint(&self) -> bool {
86        matches!(self, FinalCheckpoint)
87    }
88}
89
90/// A `CheckpointVerifier`'s target checkpoint height, based on the current
91/// queue.
92#[derive(Clone, Copy, Debug, Eq, PartialEq)]
93pub enum TargetHeight {
94    /// We need more blocks before we can choose a target checkpoint.
95    WaitingForBlocks,
96    /// We want to verify this checkpoint.
97    ///
98    /// The target checkpoint can be multiple checkpoints ahead of the previous
99    /// checkpoint.
100    Checkpoint(block::Height),
101    /// We have finished verifying, there will be no more targets.
102    FinishedVerifying,
103}
104
105/// Block height target, in chain order.
106///
107/// `WaitingForBlocks` is incomparable with itself and `Checkpoint(_)`.
108impl PartialOrd for TargetHeight {
109    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
110        match (self, other) {
111            // FinishedVerifying is the final state
112            (FinishedVerifying, FinishedVerifying) => Some(Ordering::Equal),
113            (FinishedVerifying, _) => Some(Ordering::Greater),
114            (_, FinishedVerifying) => Some(Ordering::Less),
115            // Checkpoints are comparable with each other by height
116            (Checkpoint(self_height), Checkpoint(other_height)) => {
117                self_height.partial_cmp(other_height)
118            }
119            // We can wait for blocks before or after any target checkpoint,
120            // so there is no ordering between checkpoint and waiting.
121            (WaitingForBlocks, Checkpoint(_)) => None,
122            (Checkpoint(_), WaitingForBlocks) => None,
123            // However, we consider waiting equal to itself.
124            (WaitingForBlocks, WaitingForBlocks) => Some(Ordering::Equal),
125        }
126    }
127}
zebra_consensus/checkpoint/types.rs

zebra_consensus/checkpoint/
types.rs
