refactor(testenv)!: make wait_until_electrum_sees_block concrete

[evanlinjin]

Description

A from-scratch reimplementation of #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 Refactor TestEnv::wait_until_electrum_sees_block to be more concrete. #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:

• I followed the contribution guidelines

New Features:

• I've added docs for the new feature

Bugfixes:

• This pull request breaks the existing API

https://claude.ai/code/session_016gJvi98Q65QnanBFxe2UUn

---

Generated by Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.65%. Comparing base (47556ab) to head (f6a60a3).
⚠️ Report is 10 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2231      +/-   ##
==========================================
+ Coverage   77.69%   78.65%   +0.96%     
==========================================
  Files          29       30       +1     
  Lines        5801     5909     +108     
  Branches      271      279       +8     
==========================================
+ Hits         4507     4648     +141     
+ Misses       1223     1185      -38     
- Partials       71       76       +5     

Flag	Coverage Δ
rust	78.65% <ø> (+0.96%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.