Skip to content

Have MTP in checkpoint data and report missing blocks#2186

Draft
evanlinjin wants to merge 2 commits intobitcoindevkit:masterfrom
evanlinjin:feature/cp_data_with_mtp
Draft

Have MTP in checkpoint data and report missing blocks#2186
evanlinjin wants to merge 2 commits intobitcoindevkit:masterfrom
evanlinjin:feature/cp_data_with_mtp

Conversation

@evanlinjin
Copy link
Copy Markdown
Member

@evanlinjin evanlinjin commented Apr 22, 2026

Description

Context: #2076 (comment)

Adds a way to carry a precomputed median-time-past (MTP) value on each checkpoint at the type level, and reworks compute_mtp so callers can drive fetch-retry loops when blocks are missing.

  • WithMtp<D> wrapper: CheckPoint<WithMtp<D>> gives a compile-time guarantee that MTP is available for every checkpoint, without walking 11 ancestor blocks per lookup. A new CheckPoint::mtp() method returns the stored value in O(1).
  • compute_mtp returns Result<u32, MissingBlocks> instead of Option<u32>. MissingBlocks lists every height in the MTP window (h-10..=h) that the chain is missing, so callers — especially light-client chain sources like Electrum that don't expose MTP directly — can batch-fetch exactly the headers they need and retry.
  • Rename median_time_pastcompute_mtp to make the chain-walk cost explicit and contrast with the O(1) mtp() accessor.

Notes to the reviewers

Breaking change, marked feat(core)!. Two API breaks:

  • median_time_pastcompute_mtp
  • compute_mtp returns Result<u32, MissingBlocks> (was Option<u32>)

Changelog notice

Added:
- `WithMtp<D>` wrapper for checkpoint data with precomputed MTP.
- `CheckPoint::mtp()` on `CheckPoint<WithMtp<D>>` — O(1) MTP accessor.
- `MissingBlocks` error type.

Changed:
- `CheckPoint::median_time_past` renamed to `CheckPoint::compute_mtp`; return type changed from `Option<u32>` to `Result<u32, MissingBlocks>`.

Checklists

All Submissions:

New Features:

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

Introduce `WithMtp<D>` so that `CheckPoint<WithMtp<D>>` carries a
compile-time guarantee that the median-time-past (BIP-0113) is
available at every checkpoint, without walking 11 ancestor blocks
per lookup. `CheckPoint::mtp()` returns the stored value.

Rename `median_time_past` to `compute_mtp` to make the chain-walking
cost explicit at the call site and to contrast it with the cheap
`mtp()` accessor on `CheckPoint<WithMtp<D>>`.
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.
@evanlinjin evanlinjin changed the title feat(core)!: carry MTP on checkpoints and report missing blocks Have MTP in checkpoint data and report missing blocks Apr 22, 2026
@evanlinjin evanlinjin marked this pull request as draft April 22, 2026 04:39
@evanlinjin evanlinjin self-assigned this Apr 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: No status

Development

Successfully merging this pull request may close these issues.

1 participant