feat(core): add median-time-past calculation to CheckPoint

Add the ability to calculate median-time-past (MTP) for checkpoints,
following Bitcoin's BIP113 specification. MTP is the pseudo-median
of up to 11 previous block timestamps, used for time-based validations
in consensus rules.

- Extend `ToBlockHash` trait with optional `block_time()` method
- Add `median_time_past()` method to `CheckPoint`
- Return `None` when timestamps unavailable or blocks missing from sparse chain
- Include comprehensive tests for all edge cases

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: evanlinjin

crates/core/src/checkpoint.rs

@@ -2,6 +2,7 @@ use core::fmt;
 use core::ops::RangeBounds;
 
 use alloc::sync::Arc;
+use alloc::vec::Vec;
 use bitcoin::{block::Header, BlockHash};
 
 use crate::BlockId;
@@ -60,14 +61,22 @@ impl<D> Drop for CPInner<D> {
 
 /// Trait that converts [`CheckPoint`] `data` to [`BlockHash`].
 ///
-/// Implementations of [`ToBlockHash`] must always return the block’s consensus-defined hash. If
+/// Implementations of [`ToBlockHash`] must always return the block's consensus-defined hash. If
 /// your type contains extra fields (timestamps, metadata, etc.), these must be ignored. For
 /// example, [`BlockHash`] trivially returns itself, [`Header`] calls its `block_hash()`, and a
-/// wrapper type around a [`Header`] should delegate to the header’s hash rather than derive one
+/// wrapper type around a [`Header`] should delegate to the header's hash rather than derive one
 /// from other fields.
 pub trait ToBlockHash {
     /// Returns the [`BlockHash`] for the associated [`CheckPoint`] `data` type.
     fn to_blockhash(&self) -> BlockHash;
+
+    /// Returns the block time if available for the data type.
+    ///
+    /// Default implementation returns `None`. Data types that include timestamp information
+    /// (such as [`Header`]) should override this method.
+    fn block_time(&self) -> Option<u32> {
+        None
+    }
 }
 
 impl ToBlockHash for BlockHash {
@@ -80,6 +89,10 @@ impl ToBlockHash for Header {
     fn to_blockhash(&self) -> BlockHash {
         self.block_hash()
     }
+
+    fn block_time(&self) -> Option<u32> {
+        Some(self.time)
+    }
 }
 
 impl<D> PartialEq for CheckPoint<D> {
@@ -208,6 +221,38 @@ where
         }))
     }
 
+    /// Calculates the median-time-past (MTP) for this checkpoint.
+    ///
+    /// The MTP is defined as the pseudo-median timestamp of up to 11 previous blocks before this
+    /// current one. This is used in Bitcoin's consensus rules for time-based validations (BIP113).
+    ///
+    /// It is pseudo-median as it doesn't take the average of the two middle values and therefore
+    /// is not a true statistical median.
+    ///
+    /// Returns `None` if:
+    /// - The data type doesn't support block times
+    /// - Required sequential blocks are missing from the sparse chain (we need blocks at heights h,
+    ///   h-1, h-2, ..., h-10 where h is the current block's height)
+    pub fn median_time_past(&self) -> Option<u32> {
+        const MTP_BLOCK_COUNT: usize = 11;
+
+        let current_height = self.height();
+        let earliest_height = current_height.saturating_sub((MTP_BLOCK_COUNT) as u32);
+
+        // Calculate the pseudo-median (as defined in BIP113)
+        let mut timestamps = (earliest_height..current_height)
+            .rev()
+            .map(|height| {
+                // Return `None` for missing blocks or missing block times
+                let cp = self.get(height)?;
+                let block_time = cp.data_ref().block_time()?;
+                Some(block_time)
+            })
+            .collect::<Option<Vec<u32>>>()?;
+        timestamps.sort_unstable();
+        Some(timestamps[timestamps.len().checked_sub(1)? / 2])
+    }
+
     /// Construct from an iterator of block data.
     ///
     /// Returns `Err(None)` if `blocks` doesn't yield any data. If the blocks are not in ascending

crates/core/tests/test_checkpoint.rs

@@ -1,5 +1,6 @@
-use bdk_core::CheckPoint;
+use bdk_core::{CheckPoint, ToBlockHash};
 use bdk_testenv::{block_id, hash};
+use bitcoin::hashes::Hash;
 use bitcoin::BlockHash;
 
 /// Inserting a block that already exists in the checkpoint chain must always succeed.
@@ -55,3 +56,110 @@ fn checkpoint_destruction_is_sound() {
     }
     assert_eq!(cp.iter().count() as u32, end);
 }
+
+/// Test helper: A block data type that includes timestamp
+/// Fields are (height, time)
+#[derive(Debug, Clone, Copy)]
+struct BlockWithTime(u32, u32);
+
+impl ToBlockHash for BlockWithTime {
+    fn to_blockhash(&self) -> BlockHash {
+        // Generate a deterministic hash from the height
+        let hash_bytes = bitcoin::hashes::sha256d::Hash::hash(&self.0.to_le_bytes());
+        BlockHash::from_raw_hash(hash_bytes)
+    }
+
+    fn block_time(&self) -> Option<u32> {
+        Some(self.1)
+    }
+}
+
+#[test]
+fn test_median_time_past_with_no_timestamps_available() {
+    // Test with BlockHash (no timestamps available)
+    let blocks = vec![
+        (0, hash!("genesis")),
+        (1, hash!("A")),
+        (2, hash!("B")),
+        (3, hash!("C")),
+    ];
+
+    let cp = CheckPoint::<BlockHash>::from_blocks(blocks).expect("must construct valid chain");
+    assert_eq!(cp.median_time_past(), None, "BlockHash has no timestamp");
+}
+
+#[test]
+fn test_median_time_past_with_timestamps() {
+    // Create a chain with 12 blocks (heights 0-11) with incrementing timestamps
+    let blocks: Vec<_> = (0..=11)
+        .map(|i| (i, BlockWithTime(i, 1000 + i * 10)))
+        .collect();
+
+    let cp = CheckPoint::from_blocks(blocks).expect("must construct valid chain");
+
+    // Height 11: 11 previous blocks (10..0), pseudo-median at index 5 = 1050
+    assert_eq!(cp.median_time_past(), Some(1050));
+
+    // Height 10: 10 previous blocks (9..0), pseudo-median at index 4 = 1040
+    assert_eq!(cp.get(10).unwrap().median_time_past(), Some(1040));
+
+    // Height 5: 5 previous blocks (4..0), pseudo-median at index 2 = 1020
+    assert_eq!(cp.get(5).unwrap().median_time_past(), Some(1020));
+
+    // Height 0: genesis has no previous blocks
+    assert_eq!(cp.get(0).unwrap().median_time_past(), None);
+}
+
+#[test]
+fn test_median_time_past_sparse_chain() {
+    // Sparse chain with gaps: only heights 0, 5, 10, 15, 20
+    let blocks = vec![
+        (0, BlockWithTime(0, 1000)),
+        (5, BlockWithTime(5, 1050)),
+        (10, BlockWithTime(10, 1100)),
+        (15, BlockWithTime(15, 1150)),
+        (20, BlockWithTime(20, 1200)),
+    ];
+
+    let cp = CheckPoint::from_blocks(blocks).expect("must construct valid chain");
+
+    // All non-genesis heights should return None due to missing sequential blocks
+    assert_eq!(cp.median_time_past(), None); // Height 20: missing 19..11
+    assert_eq!(cp.get(10).unwrap().median_time_past(), None); // Height 10: missing 9..1
+    assert_eq!(cp.get(5).unwrap().median_time_past(), None); // Height 5: missing 4..1
+    assert_eq!(cp.get(0).unwrap().median_time_past(), None); // Genesis: no previous blocks
+}
+
+#[test]
+fn test_median_time_past_with_sequential_blocks() {
+    // Complete sequential chain from 0 to 5
+    let blocks: Vec<_> = (0..=5)
+        .map(|i| (i, BlockWithTime(i, 1000 + i * 10)))
+        .collect();
+
+    let cp = CheckPoint::from_blocks(blocks).expect("must construct valid chain");
+
+    // Height 5: 5 previous blocks, pseudo-median at index 2 = 1020
+    assert_eq!(cp.median_time_past(), Some(1020));
+
+    // Height 3: 3 previous blocks, pseudo-median at index 1 = 1010
+    assert_eq!(cp.get(3).unwrap().median_time_past(), Some(1010));
+}
+
+#[test]
+fn test_median_time_past_unsorted_timestamps() {
+    // Non-monotonic timestamps to test sorting
+    let blocks = vec![
+        (0, BlockWithTime(0, 1000)),
+        (1, BlockWithTime(1, 1100)), // Jump forward
+        (2, BlockWithTime(2, 1050)), // Back
+        (3, BlockWithTime(3, 1150)), // Forward
+        (4, BlockWithTime(4, 1075)), // Back
+    ];
+
+    let cp = CheckPoint::from_blocks(blocks).expect("must construct valid chain");
+
+    // Height 4: previous times [1150, 1050, 1100, 1000] -> sorted [1000, 1050, 1100, 1150]
+    // Pseudo-median at index 1 = 1050
+    assert_eq!(cp.median_time_past(), Some(1050));
+}