feat(core)!: report missing heights from compute_mtp

Change `CheckPoint::compute_mtp` to return `Result<u32, MissingBlocks>`
instead of `Option<u32>`. On failure, `MissingBlocks` lists every
height in the MTP window (`h-10..=h`) that the chain is missing,
enabling callers to drive a fetch-retry loop against their chain
source.

This is motivated by light-client chain sources such as Electrum,
which do not expose MTP values directly. Callers need to know
precisely which block headers to fetch; a bare `None` forces either
eager full-chain prefetching or blind re-walking.

Author: evanlinjin

crates/core/src/checkpoint.rs

@@ -120,6 +120,25 @@ impl<D: ToBlockHash> ToBlockHash for WithMtp<D> {
     }
 }
 
+/// Error returned by [`CheckPoint::compute_mtp`] when one or more required ancestor
+/// checkpoints are missing from the chain.
+///
+/// The `heights` field lists every height in the MTP window (`h-10..=h`) that the caller
+/// needs to fetch and insert before `compute_mtp` can succeed.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct MissingBlocks {
+    /// Heights whose checkpoints were expected but not found in the chain.
+    pub heights: Vec<u32>,
+}
+
+impl fmt::Display for MissingBlocks {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "missing block data for heights {:?}", self.heights)
+    }
+}
+
+impl core::error::Error for MissingBlocks {}
+
 impl<D> PartialEq for CheckPoint<D> {
     fn eq(&self, other: &Self) -> bool {
         let self_cps = self.iter().map(|cp| cp.block_id());
@@ -257,31 +276,36 @@ where
     /// Note: This is a pseudo-median that takes the higher of the two middle values rather than
     /// averaging them. This matches the BIP-0113 specification.
     ///
-    /// Returns `None` if any of the 11 required ancestor checkpoints are missing from the chain.
+    /// Returns `Err(MissingBlocks)` listing every missing height when one or more ancestors in
+    /// the MTP window are not present in the chain. Callers can use this to drive a fetch-retry
+    /// loop against their chain source.
     ///
     /// If you want a compile-time guarantee that MTP is always available without walking the
     /// chain, store it directly on each checkpoint via [`WithMtp`] and use
     /// [`CheckPoint::mtp`] instead.
-    pub fn compute_mtp(&self) -> Option<u32>
+    pub fn compute_mtp(&self) -> Result<u32, MissingBlocks>
     where
         D: ToBlockTime,
     {
         let current_height = self.height();
         let earliest_height = current_height.saturating_sub(Self::MTP_BLOCK_COUNT - 1);
 
-        let mut timestamps = (earliest_height..=current_height)
-            .map(|height| {
-                // Return `None` for missing blocks or missing block times
-                let cp = self.get(height)?;
-                let block_time = cp.data_ref().to_blocktime();
-                Some(block_time)
-            })
-            .collect::<Option<Vec<u32>>>()?;
+        let mut timestamps = Vec::with_capacity(Self::MTP_BLOCK_COUNT as usize);
+        let mut missing = Vec::new();
+        for height in earliest_height..=current_height {
+            match self.get(height) {
+                Some(cp) => timestamps.push(cp.data_ref().to_blocktime()),
+                None => missing.push(height),
+            }
+        }
+        if !missing.is_empty() {
+            return Err(MissingBlocks { heights: missing });
+        }
         timestamps.sort_unstable();
 
         // If there are more than 1 middle values, use the higher middle value.
         // This is mathematically incorrect, but this is the BIP-0113 specification.
-        Some(timestamps[timestamps.len() / 2])
+        Ok(timestamps[timestamps.len() / 2])
     }
 
     /// Construct from an iterator of block data.

crates/core/tests/test_checkpoint.rs

@@ -1,4 +1,4 @@
-use bdk_core::{CheckPoint, ToBlockHash, ToBlockTime, WithMtp};
+use bdk_core::{CheckPoint, MissingBlocks, ToBlockHash, ToBlockTime, WithMtp};
 use bdk_testenv::{block_id, hash};
 use bitcoin::hashes::Hash;
 use bitcoin::BlockHash;
@@ -86,19 +86,19 @@ fn test_median_time_past_with_timestamps() {
     let cp = CheckPoint::from_blocks(blocks).expect("must construct valid chain");
 
     // Height 11: 11 previous blocks (11..=1), pseudo-median at index 6 = 1060
-    assert_eq!(cp.compute_mtp(), Some(1060));
+    assert_eq!(cp.compute_mtp(), Ok(1060));
 
     // Height 10: 11 previous blocks (10..=0), pseudo-median at index 5 = 1050
-    assert_eq!(cp.get(10).unwrap().compute_mtp(), Some(1050));
+    assert_eq!(cp.get(10).unwrap().compute_mtp(), Ok(1050));
 
     // Height 5: 6 previous blocks (5..=0), pseudo-median at index 3 = 1030
-    assert_eq!(cp.get(5).unwrap().compute_mtp(), Some(1030));
+    assert_eq!(cp.get(5).unwrap().compute_mtp(), Ok(1030));
 
     // Height 3: 4 previous blocks (3..=0), pseudo-median at index 2 = 1020
-    assert_eq!(cp.get(3).unwrap().compute_mtp(), Some(1020));
+    assert_eq!(cp.get(3).unwrap().compute_mtp(), Ok(1020));
 
     // Height 0: 1 block at index 0 = 1000
-    assert_eq!(cp.get(0).unwrap().compute_mtp(), Some(1000));
+    assert_eq!(cp.get(0).unwrap().compute_mtp(), Ok(1000));
 }
 
 #[test]
@@ -113,23 +113,28 @@ fn test_previous_median_time_past_edge_cases() {
     // At height 10: next_mtp uses all 11 blocks (0-10)
     // Times: [1000, 1100, 1200, 1300, 1400, 1500, 1600, 1700, 1800, 1900, 2000]
     // Median at index 5 = 1500
-    assert_eq!(cp.compute_mtp(), Some(1500));
+    assert_eq!(cp.compute_mtp(), Ok(1500));
 
     // At height 9: mtp uses blocks 0-9 (10 blocks)
     // Times: [1000, 1100, 1200, 1300, 1400, 1500, 1600, 1700, 1800, 1900]
     // Median at index 5 = 1400
-    assert_eq!(cp.get(9).unwrap().compute_mtp(), Some(1500));
+    assert_eq!(cp.get(9).unwrap().compute_mtp(), Ok(1500));
 
-    // Test sparse chain where next_mtp returns None due to missing blocks
+    // Test sparse chain where compute_mtp reports the missing heights
     let sparse = vec![
         (0, BlockWithTime(0, 1000)),
         (5, BlockWithTime(5, 1050)),
         (10, BlockWithTime(10, 1100)),
     ];
     let sparse_cp = CheckPoint::from_blocks(sparse).expect("must construct valid chain");
 
-    // At height 10: next_mtp needs blocks 0-10 but many are missing
-    assert_eq!(sparse_cp.compute_mtp(), None);
+    // At height 10: window is 0..=10; only 0, 5, 10 are present.
+    assert_eq!(
+        sparse_cp.compute_mtp(),
+        Err(MissingBlocks {
+            heights: vec![1, 2, 3, 4, 6, 7, 8, 9],
+        })
+    );
 }
 
 #[test]
@@ -155,18 +160,18 @@ fn test_mtp_with_non_monotonic_times() {
     // Height 10:
     // mtp uses blocks 0-10: sorted
     // [1000,1100,1200,1300,1400,1500,1600,1700,1800,1900,2000] Median at index 5 = 1500
-    assert_eq!(cp.get(10).unwrap().compute_mtp(), Some(1500));
+    assert_eq!(cp.get(10).unwrap().compute_mtp(), Ok(1500));
 
     // Height 11:
     // mtp uses blocks 1-11: sorted
     // [1000,1100,1200,1300,1400,1600,1650,1700,1800,1900,2000] Median at index 5 = 1600
-    assert_eq!(cp.compute_mtp(), Some(1600));
+    assert_eq!(cp.compute_mtp(), Ok(1600));
 
     // Test with smaller chain to verify sorting at different heights
     let cp3 = cp.get(3).unwrap();
     // Height 3: timestamps [1100, 1800, 1200, 1500] -> sorted [1100, 1200, 1500, 1800]
     // Pseudo-median at index 2 = 1500
-    assert_eq!(cp3.compute_mtp(), Some(1500));
+    assert_eq!(cp3.compute_mtp(), Ok(1500));
 }
 
 #[test]
@@ -182,9 +187,20 @@ fn test_mtp_sparse_chain() {
 
     let cp = CheckPoint::from_blocks(blocks).expect("must construct valid chain");
 
-    // All heights should return None due to missing sequential blocks
-    assert_eq!(cp.compute_mtp(), None);
-    assert_eq!(cp.get(11).unwrap().compute_mtp(), None);
+    // Tip is at height 15, window is 5..=15; present in window: 7, 11, 15.
+    assert_eq!(
+        cp.compute_mtp(),
+        Err(MissingBlocks {
+            heights: vec![5, 6, 8, 9, 10, 12, 13, 14],
+        })
+    );
+    // At height 11 the window is 1..=11; present in window: 3, 7, 11.
+    assert_eq!(
+        cp.get(11).unwrap().compute_mtp(),
+        Err(MissingBlocks {
+            heights: vec![1, 2, 4, 5, 6, 8, 9, 10],
+        })
+    );
 }
 
 #[test]