feat(core): Introduce CheckPointEntry enum

Author: ValuedMammal

crates/core/src/checkpoint.rs

@@ -216,6 +216,31 @@ where
         }))
     }
 
+    /// Get the previous [`BlockId`] of this checkpoint.
+    ///
+    /// I.e. the height and hash of the block immediately preceding this one by consensus,
+    /// if it can be inferred from the [`prev_blockhash`](ToBlockHash::prev_blockhash) of the inner
+    /// block data.
+    ///
+    /// Will be `None` if this is the genesis checkpoint, or the
+    /// [`prev_blockhash`](ToBlockHash::prev_blockhash) returns `None`.
+    fn prev_block_id(&self) -> Option<BlockId> {
+        let prev_height = self.height().checked_sub(1)?;
+        let prev_hash = self.0.data.prev_blockhash()?;
+        Some(BlockId {
+            height: prev_height,
+            hash: prev_hash,
+        })
+    }
+
+    /// Get an iterator over the [`CheckPointEntry`] items of this [`CheckPoint`].
+    pub fn entries(&self) -> CheckPointEntryIter<D> {
+        CheckPointEntryIter {
+            current_cp: Some(self.clone()),
+            next_block_id: None,
+        }
+    }
+
     /// Construct from an iterator of block data.
     ///
     /// Returns `Err(None)` if `blocks` doesn't yield any data. If the blocks are not in ascending
@@ -371,9 +396,52 @@ impl<D> IntoIterator for CheckPoint<D> {
     }
 }
 
+/// [`CheckPointEntry`]
+#[derive(Debug, Clone, PartialEq)]
+pub enum CheckPointEntry<D> {
+    /// A node in the [`CheckPoint`] chain.
+    CheckPoint(CheckPoint<D>),
+    /// An entry which represents a checkpoint we know to exist but don't yet have data for.
+    BlockId(BlockId),
+}
+
+/// Iterator of [`CheckPointEntry`]s.
+pub struct CheckPointEntryIter<D> {
+    current_cp: Option<CheckPoint<D>>,
+    next_block_id: Option<BlockId>,
+}
+
+impl<D> Iterator for CheckPointEntryIter<D>
+where
+    D: ToBlockHash + fmt::Debug + Copy,
+{
+    type Item = CheckPointEntry<D>;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        // There's a next inferred entry, return it.
+        if let Some(block_id) = self.next_block_id.take() {
+            return Some(CheckPointEntry::BlockId(block_id));
+        }
+        // Get the current `CheckPoint` in the chain
+        let cp = self.current_cp.take()?;
+        // If a gap is detected (height_diff > 1), prepare the next `BlockId`.
+        if let Some(prev_cp) = cp.prev() {
+            if cp.height().saturating_sub(prev_cp.height()) > 1 {
+                self.next_block_id = cp.prev_block_id();
+            }
+            // Store the next `CheckPoint`.
+            self.current_cp = Some(prev_cp);
+        }
+
+        Some(CheckPointEntry::CheckPoint(cp))
+    }
+}
+
 #[cfg(test)]
+#[allow(unused)]
 mod tests {
     use super::*;
+    use alloc::vec::Vec;
 
     /// Make sure that dropping checkpoints does not result in recursion and stack overflow.
     #[test]
@@ -500,4 +568,76 @@ mod tests {
         cp = cp.push(1, header_1).unwrap();
         let _cp = cp.insert(1, header_2a);
     }
+
+    #[test]
+    fn test_checkpoint_entries() {
+        // ```
+        // #!/bin/bash
+        // for n in $(seq 0 11); do bitcoin-cli -regtest getblockheader $(bitcoin-cli -regtest getblockhash $n) false
+        // done
+        //```
+        let headers: Vec<Header> = [
+            "0100000000000000000000000000000000000000000000000000000000000000000000003ba3edfd7a7b12b27ac72c3e67768f617fc81bc3888a51323a9fb8aa4b1e5e4adae5494dffff7f2002000000",
+            "0000002006226e46111a0b59caaf126043eb5bbf28c34f3a5e332a1fc7b2b73cf188910f23b4e61b625f26a50e33aa5a14cef81b92db912079dbdac9bce1dd5e6f02a20bae686069ffff7f2002000000",
+            "000000201f9b439e2274e1df4a70c3b3b28d6f1412a16aca043e8ddee1a561ba2483f70aeae2c2251894bcaa1b12e46bf72a0e3114a3d3c9d24c13439161b6c3afb236acaf686069ffff7f2000000000",
+            "000000202c070770b9033e3b76edafa29369774675f4efce93b6879fe732f6b7166e387a2ff70a22d5b7532e9bd509746f742c0004f3bd2c8664ea5a952f5ff851641dbdaf686069ffff7f2001000000",
+            "00000020e0c5f58ac674b56e87cf0234702b4a233df89d53a56092296ac7c085f9f0740cda05a8377da366739ae73895c9d6d6e5accce1529d421ff611f667c0fc192052b0686069ffff7f2001000000",
+            "00000020eba5058fdbffdab1c3643a0b0ac740657382ef1ff30a98e361fc2e17d84e745a671d728d09d3e55b88e544c9de3d79210738c0987b7cb26d32dd808ece338146b0686069ffff7f2001000000",
+            "00000020a949e23d8b64ccf0a1ea870ea37fdeb71451f5b1de0fa7615a16355b678fee492afb7b27b4ea020c786945e9d5e513aa300c03cf29b2abc70a1af6465caf2b65b0686069ffff7f2001000000",
+            "000000208d2ca4b8fcbffe858c4ad39dc57c60a32ec19eb5edfb74ede0da920b4388a631aab1f8ff0ab584ddfbd6c7da67693fe74a9badc2a6c78ad03ace46b1950700e5b0686069ffff7f2000000000",
+            "0000002087be4922d644dfcd43cf1f8de7138850b366111503229435b10c3fc4c24bf83ec9a3db521a416a01daa114bbafae98b92a70f0603e81a93e251cb7a48b8e90c2b1686069ffff7f2000000000",
+            "0000002064677da4c9971de66fc1a7d8284c460c61c8c2d399c2c3f8da52671f466f8070ed356a19b9507bdaba11145a11f4684d07c53dbf800c278511e63762f7b77724b1686069ffff7f2000000000",
+            "00000020f71012139fc64029711780370e8b2b29ad33fa073a74a6a2d0124013fdcce94f1ca1f097e0ca7991373a951543619c3a2130ca889b2fc498a83ddbb61d9fd3d5b1686069ffff7f2001000000",
+            "000000202ffc839d282fdc2a6f89f86ab63683e0e3f95d9fef3b0934a643864e4f7fd02087f71bec4c960d8f526022cbb02694ba4820af03f3087a1cd5e7958037dcca79b1686069ffff7f2002000000",
+        ]
+        .into_iter()
+        .map(|s| {
+            let header: Header = bitcoin::consensus::encode::deserialize_hex(s).unwrap();
+            header
+        })
+        .collect();
+
+        // A checkpoint chain of blocks
+        // 0--3--5--11
+        // Should yield entries with heights
+        // 11--10--5--4--3--2--0
+        // ..assuming the block data `D` has a `prev_blockhash`.
+        let header_0 = headers[0];
+        let header_3 = headers[3];
+        let header_5 = headers[5];
+        let header_11 = headers[11];
+        let mut cp = CheckPoint::new(0, header_0);
+        cp = cp.push(3, header_3).unwrap();
+        cp = cp.push(5, header_5).unwrap();
+        cp = cp.push(11, header_11).unwrap();
+
+        let cp_0 = cp.get(0).unwrap();
+        let cp_3 = cp.get(3).unwrap();
+        let cp_5 = cp.get(5).unwrap();
+        let cp_11 = cp.get(11).unwrap();
+
+        let entries: Vec<CheckPointEntry<Header>> = cp.entries().collect();
+        assert_eq!(entries.len(), 7);
+        assert_eq!(
+            entries,
+            vec![
+                CheckPointEntry::CheckPoint(cp_11),
+                CheckPointEntry::BlockId(BlockId {
+                    height: 10,
+                    hash: headers[11].prev_blockhash
+                }),
+                CheckPointEntry::CheckPoint(cp_5),
+                CheckPointEntry::BlockId(BlockId {
+                    height: 4,
+                    hash: headers[5].prev_blockhash
+                }),
+                CheckPointEntry::CheckPoint(cp_3),
+                CheckPointEntry::BlockId(BlockId {
+                    height: 2,
+                    hash: headers[3].prev_blockhash
+                }),
+                CheckPointEntry::CheckPoint(cp_0),
+            ]
+        );
+    }
 }