refactor(chain)!: drop the bound framing from confirmation APIs

[evanlinjin]

Description

Fixes #2298.

The Anchor trait previously said an anchor block might be a descendant of the block that actually confirmed a transaction. Nothing in this repo ever produces that kind of anchor:

• Electrum validates a merkle proof before building one
• Esplora uses the confirming block from TxStatus
• TxPosInBlock carries the transaction’s index inside that block

So the height is exact, not an upper bound. This PR removes that framing and renames:

• confirmation_height_upper_bound → confirmation_height (on both Anchor and ChainPosition)
• confirmations_lower_bound → confirmations

The second rename follows for the same reason: a higher height produces fewer confirmations, so an upper-bounded height used to yield a lower-bounded count. With an exact height the count is exact.

Notes to reviewers

No behaviour change. Every implementation already returned anchor_block().height. The override on ConfirmationBlockTime is removed because it was identical to the trait default.

Hard renames, no deprecated shims. The next bdk_chain release is already breaking, so a downstream impl that still overrides the old name should fail to compile rather than be silently ignored.

Changelog notice

bdk_chain

• Renamed Anchor::confirmation_height_upper_bound and ChainPosition::confirmation_height_upper_bound to confirmation_height. An anchor names the confirming block, so the height is exact. No deprecated alias.
• Renamed ChainPosition::confirmations_lower_bound to ChainPosition::confirmations (the derived count is now exact).
• Updated Anchor trait docs: they no longer claim an anchor block may be a descendant of the confirming block.

Checklists

All Submissions:

• I followed the contribution guidelines

Bugfixes:

• This pull request breaks the existing API
• I'm linking the issue being fixed by this PR

[codecov]

Codecov Report

❌ Patch coverage is 85.71429% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.72%. Comparing base (38b52d9) to head (40cb3d1).

Files with missing lines	Patch %	Lines
crates/chain/src/tx_data_traits.rs	33.33%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2299      +/-   ##
==========================================
- Coverage   78.75%   78.72%   -0.03%     
==========================================
  Files          31       31              
  Lines        5974     5966       -8     
  Branches      284      284              
==========================================
- Hits         4705     4697       -8     
  Misses       1193     1193              
  Partials       76       76              

Flag	Coverage Δ
rust	78.72% <85.71%> (-0.03%)	⬇️

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.

[nymius]

cACK 40cb3d1

For now, if we have no use for the probabilistic case, I agree with removing it. If we need it in the future (e.g., Utreexo?), I would reintroduce it under a different name to avoid colliding with previous versions.

[nymius]

I don't know the best way to word this, but a coin is mature if it's eligible to be included in the next block. The minimum such height is COINBASE_MATURITY - 1 , so this should say something like:

/// A coinbase output is mature once it can be included in the next block after
/// [`COINBASE_MATURITY`] blocks have been mined after its confirmation

[evanlinjin]

@nymius Thank you for the review. How do you envision UTreexo potentially using this feature?