Skip to content

feat(chain-sources): fetch headers at caller-requested heights (#2200)#2241

Open
ANAMASGARD wants to merge 1 commit into
bitcoindevkit:masterfrom
ANAMASGARD:feat/2200-fetch-requested-heights
Open

feat(chain-sources): fetch headers at caller-requested heights (#2200)#2241
ANAMASGARD wants to merge 1 commit into
bitcoindevkit:masterfrom
ANAMASGARD:feat/2200-fetch-requested-heights

Conversation

@ANAMASGARD

@ANAMASGARD ANAMASGARD commented Jul 9, 2026

Copy link
Copy Markdown

Closes #2200

Description

Adds fetch_headers_at_heights(local_tip, heights) -> CheckPoint<Header> to bdk_bitcoind_rpc, bdk_electrum, and bdk_esplora.

Wallets can fetch missing block headers on demand (for MTP, relative timelocks, confirmation timestamps) without paying for prev-11 fetches on every sync. The returned update is reorg-aware and applies via LocalChain::apply_update.

API contract:

  • Skips heights already in local_tip
  • No-op when all requested heights are known and no reorg → returns local_tip unchanged (empty ChangeSet)
  • Update may include bridge/reorg blocks beyond requested heights; no Esplora tip-suffix padding

Shared helpers in bdk_core: bridge_heights, build_fetch_headers_update

Notes to the reviewers

  • bdk_bitcoind_rpc: standalone fetch_headers_at_heights (not on Emitter::next_block)
  • bdk_electrum: BdkElectrumClient::fetch_headers_at_heights with batch_block_header
  • bdk_esplora: new headers_at_heights module; blocking + async trait methods
  • Esplora intentionally omits the ~10-block tip suffix used in normal sync/full_scan

Local verification : VERIFIED — all tests passed

cargo test -p bdk_bitcoind_rpc fetch_headers_at_heights
cargo test -p bdk_electrum fetch_headers_at_heights
cargo test -p bdk_esplora fetch_headers_at_heights
cargo clippy -p bdk_core -p bdk_bitcoind_rpc -p bdk_electrum -p bdk_esplora --all-targets -- -D warnings
image

Changelog notice

  • Added fetch_headers_at_heights to bdk_bitcoind_rpc, bdk_electrum, and bdk_esplora for on-demand CheckPoint<Header> fetches at caller-requested heights
  • Added bridge_heights and build_fetch_headers_update helpers in bdk_core

Checklists

All Submissions:

New Features:

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

Add a reorg-aware on-demand CheckPoint<Header> fetch API to
bitcoind_rpc, electrum, and esplora so wallets can obtain MTP
windows without paying for prev-11 on every sync (bitcoindevkit#2200).
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.

Allow chain sources to fetch blocks at caller-requested heights

1 participant