Allow chain sources to fetch blocks at caller-requested heights

[evanlinjin]

Context

Related to #2199. That issue covers continuous prev-11 emission during sync. This issue covers the underlying primitive: letting a caller ask a chain source for blocks at specific heights, on demand.

Use case

A wallet wants MTP only when it actually matters — e.g., when constructing a spend that uses relative timelocks, or surfacing confirmation timestamps in a UI. Paying for prev-11 fetches on every routine sync is wasteful when the wallet may go long stretches without needing MTP at all.

The desired flow:

1. Wallet syncs normally with no prev-11 emission. Local chain has confirmation blocks but no MTP windows.
2. When the wallet needs MTP (e.g., before a spend), it canonicalizes and discovers some confirmed txs (and/or the tip) have None MTPs because the surrounding heights aren't in the local chain.
3. Wallet asks the chain source to fetch a chain update covering those specific heights, passing its current local checkpoint chain as the baseline.
4. Wallet applies the update; canonicalization now yields Some(_) MTPs.

Goal

Each chain source exposes a way to request a chain update for a caller-supplied set of heights. The returned update is reorg-aware (anchored to the current best chain) and applies cleanly to a LocalChain<Header>.

Scope

• bdk_electrum
• bdk_esplora

Design notes

• Input shape. Two things: the caller's local checkpoint chain (its current CheckPoint) and the set/iterator of heights it wants. The checkpoint serves a dual purpose — it tells the source which heights the caller already has (so they aren't refetched) and provides the reorg anchor for building the update.
• Output shape. The same chain-update type each source already produces, so application is uniform.
• Reorg safety. Heights must be resolved against the source's current view of the best chain; if a requested height is below a reorg point relative to the caller's checkpoint, the update should reflect that.
• Composability with Optionally emit prev-11 block headers per confirmation block and chain tip (for MTP) #2199. If both this and Optionally emit prev-11 block headers per confirmation block and chain tip (for MTP) #2199 exist, the prev-11 builder flag can be implemented in terms of this primitive — or they can coexist as two entry points.

Acceptance criteria

• Each crate exposes a method that takes the caller's checkpoint and a set of heights, and returns a chain update.
• Returned update applies via the existing LocalChain apply path.
• Test covering: requesting heights [H1, H2, H3] yields an update whose checkpoint chain contains exactly those heights (plus whatever connecting tip is needed for application).
• Test covering: a height already represented in the caller's checkpoint chain does not trigger a fetch.
• Test covering: end-to-end MTP — sync without prev-11, canonicalize and find missing MTPs, fetch the missing heights, re-canonicalize, all MTPs present.

[ANAMASGARD]

Hi @evanlinjin — I've opened #2241 with an implementation of the on-demand fetch_headers_at_heights API for bdk_bitcoind_rpc, bdk_electrum, and bdk_esplora.

It returns a reorg-aware CheckPoint<Header> that applies via LocalChain::apply_update, with tests for exact requested heights, skip-already-known, and MTP recovery. #2199 is left out of scope as discussed.

Would appreciate a review when you have a moment. Thanks!

[ANAMASGARD]

Hi @evanlinjin - sorry for the delayed response, and thanks for the feedback.

For Electrum, I used "batch_block_header" because the API needs to fetch arbitrary sparse heights efficiently. But I agree that duplicating the existing fetching and reorg logic is not ideal. I’ll refactor it to reuse "fetch_tip_and_latest_blocks" with a provided "tip_height".

For "bdk_bitcoind_rpc", understood. I’ll remove those changes since "Emitter" and "FilterIter" already cover the required heights from the starting point.

I’m active again and ready to update the PR. Could you please reopen #2241, or would you prefer a new PR?