Add median-time-past (MTP) calculation to CheckPoint #2037

evanlinjin · 2025-09-18T05:42:13Z

Description

This PR adds the ability to calculate median-time-past (MTP) for CheckPoint structures, implementing the functionality described in #2036.

Notes to the reviewers

CheckPoint::median_time_past calculates the MTP value by looking at the previous 11 blocks (including the current block).

Changelog notice

Added

Introduced ToBlockTime trait for types that can return a block time.
Added median_time_past() method to CheckPoint for calculating MTP according to BIP113

Checklists

All Submissions:

I've signed all my commits
I followed the contribution guidelines
I ran cargo fmt and cargo clippy before committing

New Features:

I've added tests for the new feature
I've added docs for the new feature

Fixes #2036

oleonardolima

cACK 0f75c22

I'll just give it a try with some other test scenarios before final ACK.

oleonardolima · 2025-09-19T01:28:24Z

crates/core/src/checkpoint.rs

+    pub fn median_time_past(&self) -> Option<u32> {
+        let current_height = self.height();
+        let earliest_height = current_height.saturating_sub(Self::MTP_BLOCK_COUNT);
+        self._median_time_past(earliest_height..current_height)
+    }


I'm curious if these new APIs could output wrong/invalid values if the blocks inserted have a wrong/invalid time field e.g malicious block source.

Definitely. We are trusting the chain source here (and everywhere in BDK). Eventually, we should think about how to verify all consensus rules in BDK: difficulty, PoW, MTP, etc.

Why is it not inclusive of the current height?

nit: I want to avoid the temptation to resort to using these underscore methods.

Why is it not inclusive of the current height?

This method is asking "what's the MTP that was used to validate block 100".

However, if the caller is asking "what MTP should I use to validate a transaction going into the next block", next_median_time_past() can be used.

nit: I want to avoid the temptation to resort to using these underscore methods.

I renamed the private method to middle_timestamp_of_range.

Why is it not inclusive of the current height?

This method is asking "what's the MTP that was used to validate block 100".

However, if the caller is asking "what MTP should I use to validate a transaction going into the next block", next_median_time_past() can be used.

I imagine there would just be one function called median_time_past with a range that includes the current tip. If I wanted to know the last MTP, I would just call this function on the previous checkpoint, right?

I was wrong about the definition of MTP. MTP of block h includes the time of block h. However, when validating whether a tx can be included into a block at height x, consensus uses MTP(x-1).

I imagine there would just be one function called median_time_past with a range that includes the current tip.

Yes. This makes sense as MTP(spending_block - 1) is essentially MTP(tip).

If I wanted to know the last MTP, I would just call this function on the previous checkpoint, right?

~~This is true. However, a prev-MTP helper will be useful for relative-timelocked txs as we may need to get the confirmation block hash as well as MTP(conf_block - 1).~~

Edit: I agree with you. Less is more.

oleonardolima

cACK 74d30d8

I didn't really find other test vectors that we could use.

Another thing that should probably be handled in a future PR is updating the calculation of Balance for the immature category, we probably should update it to consider transactions that are not yet mature considering the Locktime and MTP for it.

ValuedMammal · 2026-01-09T18:24:08Z

crates/core/src/checkpoint.rs

+    fn block_time(&self) -> Option<u32> {
+        None
+    }


Hm but then the trait would need to be called ToBlockHashAndHeaderTime? Maybe just have a new impl where D is convertible to a Header (granted, the time is only a subset of the information contained in a header).

impl<D> CheckPoint<D> where D: Into<Header>, { /// Calculates the median time past (MTP) of this `CheckPoint`. pub fn median_time_past(&self) -> Option<u32> { ... } }

What do you think about a separate ToBlockTime trait?

Yes or maybe stay with 1 trait but redefine ToBlockHash to be a more general Header-like interface.

I think 2 traits is nicer otherwise the to_blocktime method needs to return an Option.

ValuedMammal · 2026-01-09T18:27:31Z

crates/core/src/checkpoint.rs

+    pub fn median_time_past(&self) -> Option<u32> {
+        let current_height = self.height();
+        let earliest_height = current_height.saturating_sub(Self::MTP_BLOCK_COUNT);
+        self._median_time_past(earliest_height..current_height)
+    }


nit: I want to avoid the temptation to resort to using these underscore methods.

luisschwab

ACK 00b0ca8

luisschwab · 2026-01-20T22:56:56Z

crates/core/src/checkpoint.rs

+            })
+            .collect::<Option<Vec<u32>>>()?;
+        timestamps.sort_unstable();
+        Some(timestamps[timestamps.len().checked_sub(1)? / 2])


super nit: BIP-0113 specifies len / 2. In the case of 11 blocks, both len / 2 and (len - 1)/2 yield 5, which is fine, but for even lengths, we get two elements. The median of an even number of elements is the average of the middle elements. Here we must choose one of the values, so perhaps remove the .checked_sub(1) to keep on par with the BIP?

Add MTP calculation methods for CheckPoint following Bitcoin's BIP113: - `median_time_past()`: calculates MTP for current block using 11 blocks starting from the current block - Returns None when required blocks are missing Includes comprehensive tests for all edge cases.

rustaceanrob · 2026-01-21T09:59:19Z

FYI in units = 1.0.0 there will be a median time past struct

evanlinjin · 2026-01-21T10:18:33Z

FYI in units = 1.0.0 there will be a median time past struct

Thanks! Unfortunately, I don't think we can use that here 😢

evanlinjin · 2026-01-21T10:19:01Z

CI is failing no_std builds. #2099 will fix this.

github-project-automation bot added this to BDK Chain Sep 18, 2025

evanlinjin force-pushed the feature/mtp branch from f97553f to 0f75c22 Compare September 18, 2025 05:45

evanlinjin self-assigned this Sep 18, 2025

evanlinjin added the new feature New feature or request label Sep 18, 2025

evanlinjin moved this to Needs Review in BDK Chain Sep 18, 2025

evanlinjin added this to the Wallet 3.0.0 milestone Sep 18, 2025

evanlinjin requested review from LagginTimes, ValuedMammal and oleonardolima September 18, 2025 05:48

oleonardolima reviewed Sep 18, 2025

View reviewed changes

evanlinjin force-pushed the feature/mtp branch 2 times, most recently from f97553f to 46e751f Compare September 19, 2025 01:00

oleonardolima reviewed Sep 19, 2025

View reviewed changes

evanlinjin force-pushed the feature/mtp branch from 46e751f to 74d30d8 Compare September 19, 2025 01:29

oleonardolima approved these changes Sep 19, 2025

View reviewed changes

evanlinjin mentioned this pull request Sep 19, 2025

Update Balance immature category calculation to consider MTP-based maturity #2040

Open

4 tasks

evanlinjin mentioned this pull request Jan 8, 2026

CheckPoint design issue #2076

Open

ValuedMammal reviewed Jan 9, 2026

View reviewed changes

evanlinjin force-pushed the feature/mtp branch 2 times, most recently from 6704eec to 00b0ca8 Compare January 15, 2026 01:19

evanlinjin mentioned this pull request Jan 15, 2026

refactor(chain)!: replace CanonicalIter with sans-io CanonicalizationTask #2038

Open

6 tasks

luisschwab requested review from luisschwab and removed request for LagginTimes January 20, 2026 21:19

luisschwab approved these changes Jan 20, 2026

View reviewed changes

evanlinjin force-pushed the feature/mtp branch from 00b0ca8 to 3d87a8c Compare January 21, 2026 09:04

Add median-time-past (MTP) calculation to CheckPoint #2037

Are you sure you want to change the base?

Add median-time-past (MTP) calculation to CheckPoint #2037

Conversation

evanlinjin commented Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Notes to the reviewers

Changelog notice

Added

Checklists

All Submissions:

New Features:

Uh oh!

oleonardolima left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

evanlinjin Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oleonardolima left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

luisschwab left a comment

Choose a reason for hiding this comment

Uh oh!

luisschwab Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rustaceanrob commented Jan 21, 2026

Uh oh!

evanlinjin commented Jan 21, 2026

Uh oh!

evanlinjin commented Jan 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

evanlinjin commented Sep 18, 2025 •

edited

Loading

evanlinjin Jan 21, 2026 •

edited

Loading

luisschwab Jan 20, 2026 •

edited

Loading