From: merge-script <hello@evanlinjin.me>
Date: Thu, 15 Oct 2026 06:38:04 +0000 (+0000)
Subject: Merge bitcoindevkit/bdk#2231: refactor(testenv)!: make `wait_until_electrum_sees_bloc... 
X-Git-Url: http://internal-gitweb-vhost/-client-interface/src/example_cli/blockdata/script/sha512/index.html?a=commitdiff_plain;p=bdk

Merge bitcoindevkit/bdk#2231: refactor(testenv)!: make `wait_until_electrum_sees_block` concrete

a98cf7c48664c37a717c3160883ece6ceaed1684 refactor(testenv)!: make `wait_until_electrum_sees_block` concrete (Claude)

Pull request description:

  ### Description

  A from-scratch reimplementation of bitcoindevkit/bdk#1640 on top of the current `master`.

  `TestEnv::wait_until_electrum_sees_block` previously only took a `timeout` and returned as soon as Electrum emitted *any* new-block notification. That made it ambiguous which block was actually being waited for, and it could return before Electrum had caught up to the block the test cared about.

  This PR makes the wait concrete:

  - `wait_until_electrum_sees_block` now takes `block_height: usize` and `block_hash: Option<BlockHash>`, so callers state exactly which block Electrum must be aware of. If the notified tip has already advanced past `block_height`, the header at that height is fetched explicitly so the expected `block_hash` can still be verified.
  - A new convenience wrapper `wait_until_electrum_tip_syncs_with_bitcoind` waits until Electrum's tip matches bitcoind's chain tip (both height and hash). All existing call sites are migrated to it, since in every case the intent was "wait until Electrum catches up to the freshly mined/reorged tip".

  ### Notes to the reviewers

  - **Why subscribe instead of polling:** polling Electrs for the header at `block_height` and checking its hash does not guarantee the spk histories are current. Receiving a block-tip notification does, because of how Electrs indexes. This is captured in a `NOTE` in the code.
  - **Tip advanced past target:** the original PR's reviewers asked what happens when the method is called after the chain tip has moved past the target height. This is handled explicitly: when the notified height is greater than `block_height`, the header at `block_height` is fetched directly to verify the hash, rather than relying on the notification header.
  - **`trigger()` placement:** `electrsd.trigger()` is kept inside the polling loop (matching the previous `master` behaviour) so Electrs keeps getting nudged to re-index — this is important for reorgs, where the tip changes without a height change.
  - The previous WIP artefacts from #1640 (a `// TODO: Fails here.` marker and a struck-through doc comment) are intentionally left out.

  ### Changelog notice

  - Changed: `TestEnv::wait_until_electrum_sees_block` now takes a `block_height` and an optional `block_hash` (breaking change to `bdk_testenv`).
  - Added: `TestEnv::wait_until_electrum_tip_syncs_with_bitcoind`.

  ### Checklists

  #### All Submissions:

  * [x] I followed the [contribution guidelines](https://github.com/bitcoindevkit/bdk/blob/master/CONTRIBUTING.md)

  #### New Features:

  * [x] I've added docs for the new feature

  #### Bugfixes:

  * [x] This pull request breaks the existing API

  https://claude.ai/code/session_016gJvi98Q65QnanBFxe2UUn

  ---
  _Generated by [Claude Code](https://claude.ai/code/session_016gJvi98Q65QnanBFxe2UUn)_

ACKs for top commit:
  evanlinjin:
    ACK a98cf7c48664c37a717c3160883ece6ceaed1684

Tree-SHA512: 563934e0e1af7261facdb2b52fad15a45b1c364e143f99dee72d185b273ad716754313b069b8369cf09bfc22dab24fa187c7ffd0986285e546358b5ecd3e60ae
---

c503a7908e528e8b6e7c7b9b6d4446ab0fbaa11a