feat(chain)!: add CheckPointEntry

LagginTimes · LagginTimes · commit 173cb46dd3ff · 2025-09-18T14:14:32.000Z
diff --git a/crates/chain/src/local_chain.rs b/crates/chain/src/local_chain.rs
@@ -6,8 +6,9 @@ use core::ops::RangeBounds;
 
 use crate::collections::BTreeMap;
 use crate::{BlockId, ChainOracle, Merge};
-use bdk_core::ToBlockHash;
+use alloc::vec::Vec;
 pub use bdk_core::{CheckPoint, CheckPointIter};
+use bdk_core::{CheckPointEntry, ToBlockHash};
 use bitcoin::block::Header;
 use bitcoin::BlockHash;
 
@@ -69,7 +70,10 @@ impl<D> PartialEq for LocalChain<D> {
     }
 }
 
-impl<D> ChainOracle for LocalChain<D> {
+impl<D> ChainOracle for LocalChain<D>
+where
+    D: ToBlockHash + Copy,
+{
     type Error = Infallible;
 
     fn is_block_in_chain(
@@ -83,10 +87,18 @@ impl<D> ChainOracle for LocalChain<D> {
             Some(cp) if cp.hash() == chain_tip.hash => cp,
             _ => return Ok(None),
         };
-        match chain_tip_cp.get(block.height) {
-            Some(cp) => Ok(Some(cp.hash() == block.hash)),
-            None => Ok(None),
+
+        if let Some(cp) = chain_tip_cp.get(block.height) {
+            return Ok(Some(cp.hash() == block.hash));
         }
+
+        if let Some(next_cp) = chain_tip_cp.get(block.height.saturating_add(1)) {
+            if let Some(prev_hash) = next_cp.prev_blockhash() {
+                return Ok(Some(prev_hash == block.hash));
+            }
+        }
+
+        Ok(None)
     }
 
     fn get_chain_tip(&self) -> Result<BlockId, Self::Error> {
@@ -576,6 +588,34 @@ impl core::fmt::Display for ApplyHeaderError {
 #[cfg(feature = "std")]
 impl std::error::Error for ApplyHeaderError {}
 
+/// Convert a `CheckPoint` to a `CheckPointEntry` representation that includes `prev_blockhash`.
+///
+/// NOTE: We store a block's prev_blockhash under its parent's height `(h - 1)`,  so a PrevBlockHash
+/// at height `h` and the hash at height `h` are the same.
+fn checkpoint_to_entries<D>(checkpoint: CheckPoint<D>) -> BTreeMap<u32, CheckPointEntry<D>>
+where
+    D: ToBlockHash + Copy,
+{
+    let mut entries = BTreeMap::new();
+
+    for cp in checkpoint.iter() {
+        // Add the actual `CheckPoint`.
+        entries.insert(cp.height(), CheckPointEntry::CheckPoint(cp.data()));
+
+        // Add prev_blockhash as a placeholder, if available.
+        if let Some(prev_hash) = cp.prev_blockhash() {
+            if let Some(prev_height) = cp.height().checked_sub(1) {
+                // Only add if we don't already have data at that height.
+                entries
+                    .entry(prev_height)
+                    .or_insert(CheckPointEntry::PrevBlockHash(prev_hash));
+            }
+        }
+    }
+
+    entries
+}
+
 /// Applies `update_tip` onto `original_tip`.
 ///
 /// On success, a tuple is returned ([`CheckPoint`], [`ChangeSet`]).
@@ -598,11 +638,16 @@ where
 {
     let mut changeset = ChangeSet::<D>::default();
 
-    let mut orig = original_tip.iter();
-    let mut update = update_tip.iter();
+    // Convert to internal representation that includes prev_blockhash information
+    let orig = checkpoint_to_entries(original_tip.clone());
+    let update = checkpoint_to_entries(update_tip.clone());
+
+    // Collect all heights from both chains to iterate through
+    let mut all_heights: Vec<u32> = orig.keys().chain(update.keys()).copied().collect();
 
-    let mut curr_orig = None;
-    let mut curr_update = None;
+    // Sort in descending order.
+    all_heights.sort_by(|a, b| b.cmp(a));
+    all_heights.dedup();
 
     let mut prev_orig: Option<CheckPoint<D>> = None;
     let mut prev_update: Option<CheckPoint<D>> = None;
@@ -617,43 +662,55 @@ where
     // in multiple locations to keep the same `Arc` pointers when they are being updated from each
     // other using this function. We can do this as long as the update contains every
     // block's height of the original chain.
-    let mut is_update_height_superset_of_original = true;
-
-    // To find the difference between the new chain and the original we iterate over both of them
-    // from the tip backwards in tandem. We are always dealing with the highest one from either
-    // chain first and move to the next highest. The crucial logic is applied when they have
-    // blocks at the same height.
-    loop {
-        if curr_orig.is_none() {
-            curr_orig = orig.next();
-        }
-        if curr_update.is_none() {
-            curr_update = update.next();
-        }
+    for height in all_heights {
+        let orig_entry = orig.get(&height);
+        let update_entry = update.get(&height);
 
-        match (curr_orig.as_ref(), curr_update.as_ref()) {
+        // Get actual `CheckPoint` references.
+        let curr_orig = original_tip.get(height);
+        let curr_update = update_tip.get(height);
+
+        match (orig_entry, update_entry) {
             // Update block that doesn't exist in the original chain
-            (o, Some(u)) if Some(u.height()) > o.map(|o| o.height()) => {
-                changeset.blocks.insert(u.height(), Some(u.data()));
-                prev_update = curr_update.take();
+            (None, Some(_u)) => {
+                // Only add actual checkpoint data, not placeholders.
+                if let Some(update_cp) = &curr_update {
+                    changeset.blocks.insert(height, Some(update_cp.data()));
+                }
+                prev_update = curr_update;
             }
             // Original block that isn't in the update
-            (Some(o), u) if Some(o.height()) > u.map(|u| u.height()) => {
-                // this block might be gone if an earlier block gets invalidated
-                potentially_invalidated_heights.push(o.height());
-                prev_orig_was_invalidated = false;
-                prev_orig = curr_orig.take();
-
-                is_update_height_superset_of_original = false;
-
-                // OPTIMIZATION: we have run out of update blocks so we don't need to continue
-                // iterating because there's no possibility of adding anything to changeset.
-                if u.is_none() {
-                    break;
+            (Some(o), None) => {
+                // Only consider real checkpoints for invalidation, not placeholders.
+                if let CheckPointEntry::CheckPoint(_) = o {
+                    // this block might be gone if an earlier block gets invalidated
+                    potentially_invalidated_heights.push(height);
+                    prev_orig_was_invalidated = false;
+                    prev_orig = curr_orig;
                 }
             }
+            // Both chains have entries at this height.
             (Some(o), Some(u)) => {
-                if o.hash() == u.hash() {
+                // Check for agreement considering both checkpoint data and prev_blockhash.
+                let entries_match = match (o, u) {
+                    // Both are actual checkpoints.
+                    (
+                        CheckPointEntry::CheckPoint(orig_data),
+                        CheckPointEntry::CheckPoint(update_data),
+                    ) => orig_data.to_blockhash() == update_data.to_blockhash(),
+                    // One is checkpoint, other is prev_blockhash: check if they match.
+                    (CheckPointEntry::CheckPoint(data), CheckPointEntry::PrevBlockHash(hash))
+                    | (CheckPointEntry::PrevBlockHash(hash), CheckPointEntry::CheckPoint(data)) => {
+                        data.to_blockhash() == *hash
+                    }
+                    // Both are prev_blockhash: check if they match.
+                    (
+                        CheckPointEntry::PrevBlockHash(hash1),
+                        CheckPointEntry::PrevBlockHash(hash2),
+                    ) => hash1 == hash2,
+                };
+
+                if entries_match {
                     // We have found our point of agreement 🎉 -- we require that the previous (i.e.
                     // higher because we are iterating backwards) block in the original chain was
                     // invalidated (if it exists). This ensures that there is an unambiguous point
@@ -671,34 +728,75 @@ where
                     prev_orig_was_invalidated = false;
                     // OPTIMIZATION 2 -- if we have the same underlying pointer at this point, we
                     // can guarantee that no older blocks are introduced.
-                    if o.eq_ptr(u) {
-                        if is_update_height_superset_of_original {
-                            return Ok((update_tip, changeset));
-                        } else {
-                            let new_tip = apply_changeset_to_checkpoint(original_tip, &changeset)
-                                .map_err(|_| CannotConnectError {
-                                try_include_height: 0,
-                            })?;
-                            return Ok((new_tip, changeset));
+                    if let (Some(o), Some(u)) = (&curr_orig, &curr_update) {
+                        if o.eq_ptr(u) {
+                            // Check if update contains every real checkpoint height from original.
+                            let is_update_height_superset_of_original = orig
+                                .iter()
+                                .filter(|(_, entry)| {
+                                    matches!(entry, CheckPointEntry::CheckPoint(_))
+                                })
+                                .all(|(height, _)| {
+                                    matches!(
+                                        update.get(height),
+                                        Some(CheckPointEntry::CheckPoint(_))
+                                    )
+                                });
+
+                            if is_update_height_superset_of_original {
+                                return Ok((update_tip, changeset));
+                            } else {
+                                let new_tip =
+                                    apply_changeset_to_checkpoint(original_tip, &changeset)
+                                        .map_err(|_| CannotConnectError {
+                                            try_include_height: 0,
+                                        })?;
+                                return Ok((new_tip, changeset));
+                            }
                         }
                     }
                 } else {
-                    // We have an invalidation height so we set the height to the updated hash and
-                    // also purge all the original chain block hashes above this block.
-                    changeset.blocks.insert(u.height(), Some(u.data()));
-                    for invalidated_height in potentially_invalidated_heights.drain(..) {
-                        changeset.blocks.insert(invalidated_height, None);
+                    // Entries differ: check for ambiguity cases.
+                    match (o, u) {
+                        // We have an invalidation height so we set the height to the updated hash
+                        // and also purge all the original chain block hashes above this block.
+                        (CheckPointEntry::CheckPoint(_), CheckPointEntry::CheckPoint(_)) => {
+                            if let Some(update_cp) = &curr_update {
+                                changeset.blocks.insert(height, Some(update_cp.data()));
+                            }
+                            for invalidated_height in potentially_invalidated_heights.drain(..) {
+                                changeset.blocks.insert(invalidated_height, None);
+                            }
+                            prev_orig_was_invalidated = true;
+                        }
+                        // Original has checkpoint, update only has prev_blockhash.
+                        (CheckPointEntry::CheckPoint(_), CheckPointEntry::PrevBlockHash(_)) => {
+                            return Err(CannotConnectError {
+                                try_include_height: height,
+                            });
+                        }
+                        // Both sides only have prev_blockhash but the two inferred predecessors
+                        // disagree.
+                        (CheckPointEntry::PrevBlockHash(_), CheckPointEntry::PrevBlockHash(_)) => {
+                            return Err(CannotConnectError {
+                                try_include_height: height,
+                            });
+                        }
+                        // Original only has prev_blockhash, update has checkpoint. Set the height
+                        // to the updated hash, but do not purge earlier heights since a
+                        // prev_blockhash is not a hard anchor.
+                        (CheckPointEntry::PrevBlockHash(_), CheckPointEntry::CheckPoint(_)) => {
+                            if let Some(update_cp) = &curr_update {
+                                changeset.blocks.insert(height, Some(update_cp.data()));
+                            }
+                        }
                     }
-                    prev_orig_was_invalidated = true;
                 }
-                prev_update = curr_update.take();
-                prev_orig = curr_orig.take();
+                prev_update = curr_update;
+                prev_orig = curr_orig;
             }
             (None, None) => {
-                break;
-            }
-            _ => {
-                unreachable!("compiler cannot tell that everything has been covered")
+                unreachable!("height should exist in at least one map")
             }
         }
     }
diff --git a/crates/core/src/checkpoint.rs b/crates/core/src/checkpoint.rs
@@ -6,6 +6,44 @@ use bitcoin::{block::Header, BlockHash};
 
 use crate::BlockId;
 
+/// Internal type to represent entries in `CheckPoint` that can handle both actual checkpoint data
+/// and placeholder entries for types that have `prev_blockhash`.
+#[derive(Debug, Clone, PartialEq)]
+pub enum CheckPointEntry<D> {
+    /// An actual `CheckPoint` entry with `data`.
+    CheckPoint(D),
+    /// A placeholder entry containing only a `prev_blockhash`.
+    PrevBlockHash(BlockHash),
+}
+
+impl<D> CheckPointEntry<D> {
+    /// Returns true if this entry is a placeholder entry.
+    pub fn is_prev_blockhash(&self) -> bool {
+        matches!(self, CheckPointEntry::PrevBlockHash(_))
+    }
+
+    /// Returns true if this entry contains actual `CheckPoint` data.
+    pub fn is_checkpoint(&self) -> bool {
+        matches!(self, CheckPointEntry::CheckPoint(_))
+    }
+
+    /// Return the `data` if this is a `CheckPoint` entry.
+    pub fn checkpoint_data(&self) -> Option<&D> {
+        match self {
+            CheckPointEntry::CheckPoint(data) => Some(data),
+            CheckPointEntry::PrevBlockHash(_) => None,
+        }
+    }
+
+    /// Return the `prev_blockhash` if this is a placeholder entry.
+    pub fn prev_blockhash(&self) -> Option<BlockHash> {
+        match self {
+            CheckPointEntry::CheckPoint(_) => None,
+            CheckPointEntry::PrevBlockHash(hash) => Some(*hash),
+        }
+    }
+}
+
 /// A checkpoint is a node of a reference-counted linked list of [`BlockId`]s.
 ///
 /// Checkpoints are cheaply cloneable and are useful to find the agreement point between two sparse
@@ -68,6 +106,11 @@ impl<D> Drop for CPInner<D> {
 pub trait ToBlockHash {
     /// Returns the [`BlockHash`] for the associated [`CheckPoint`] `data` type.
     fn to_blockhash(&self) -> BlockHash;
+
+    /// Returns `None` if the type has no knowledge of the previous [`BlockHash`].
+    fn prev_blockhash(&self) -> Option<BlockHash> {
+        None
+    }
 }
 
 impl ToBlockHash for BlockHash {
@@ -80,6 +123,26 @@ impl ToBlockHash for Header {
     fn to_blockhash(&self) -> BlockHash {
         self.block_hash()
     }
+
+    fn prev_blockhash(&self) -> Option<BlockHash> {
+        Some(self.prev_blockhash)
+    }
+}
+
+impl<D: ToBlockHash> ToBlockHash for CheckPointEntry<D> {
+    fn to_blockhash(&self) -> BlockHash {
+        match self {
+            CheckPointEntry::CheckPoint(data) => data.to_blockhash(),
+            CheckPointEntry::PrevBlockHash(hash) => *hash,
+        }
+    }
+
+    fn prev_blockhash(&self) -> Option<BlockHash> {
+        match self {
+            CheckPointEntry::CheckPoint(data) => data.prev_blockhash(),
+            CheckPointEntry::PrevBlockHash(_) => None,
+        }
+    }
 }
 
 impl<D> PartialEq for CheckPoint<D> {
@@ -188,6 +251,14 @@ impl<D> CheckPoint<D> {
     pub fn eq_ptr(&self, other: &Self) -> bool {
         Arc::as_ptr(&self.0) == Arc::as_ptr(&other.0)
     }
+
+    /// Return the `prev_blockhash` from the `CheckPoint`, if available.
+    pub fn prev_blockhash(&self) -> Option<BlockHash>
+    where
+        D: ToBlockHash,
+    {
+        self.0.data.prev_blockhash()
+    }
 }
 
 // Methods where `D: ToBlockHash`
