feat(chain)!: taint-aware CanonicalView::balance via canonical ancestor walk

[evanlinjin]

Warning

This PR — including this description — is currently entirely AI-generated.
It still needs proper human review (by me, @evanlinjin) before it should be taken seriously. Treat everything below as a draft proposal, not a vetted design.

Description

This is an alternative direction to #2221. Where #2221 makes CanonicalView::balance less restrictive by removing the min_confirmations parameter, this PR instead tries to make it more useful — handing control to the caller via closures, deriving trust from ancestry rather than a per-script heuristic, and exposing a per-output spend-eligibility classifier that's the building block for coin control.

The core new primitive is CanonicalView::classify_outpoints, built on a reusable, sans-TxGraph canonical ancestor walk. balance becomes a thin fold over it.

What's here (commit by commit)

1. Add CanonicalAncestors reverse-topological walk. Canonical::ancestors(seeds, map, should_walk) walks the canonical ancestors of a set of seed txids backwards (the seeds are the leaf-most txs, closer to the leaves of the ancestry DAG than its roots). Each tx is visited once in reverse-topological order, folding a Mergeable accumulator from descendants into ancestors (diamonds merge correctly). should_walk prunes per-tx with the ChainPosition available; the iterator is ExactSizeIterator.

2. Add Canonical::ancestors_inclusive. A variant that also yields the seeds (each with its own final accumulator), so a per-seed contribution can be folded uniformly with the ancestry.

3. Taint-aware CanonicalView::balance (breaking). Replaces trust_predicate + min_confirmations with two closures:

• does_taint(CanonicalTx) -> bool: a pending output is untrusted if it, or any of its unsettled ancestors, taints. The unsettled ancestry is walked once (deduped across outputs, stopping at settled txs) via ancestors_inclusive. This lets callers demote unconfirmed coins received from — or chained on top of — a third party. Trust is now derived from ancestry instead of a per-script heuristic.
• is_settled(&ChainPosition) -> bool: generalizes the numeric min_confirmations into a caller-defined "confident this won't be replaced" boundary, and is the sole authority on it — a settled output is never dropped or tainted (even an unconfirmed output a caller chooses to treat as settled is counted, not lost).
• balance also drops its O identifier generic and now takes bare OutPoints.

4. Rename Balance::confirmed to Balance::settled (breaking). The bucket is driven by is_settled (confidence a tx won't be replaced), not strictly confirmation status, so the field is renamed to match. Breaking serde key change (confirmed → settled, no alias).

5. Add classify_outpoints spend-eligibility classifier. CanonicalView::classify_outpoints pairs each unspent output with a chain-level Eligibility (Settled / Immature / TrustedPending / UntrustedPending) from is_settled + the does_taint walk. This is the primitive for coin selection / coin control (e.g. "prefer settled coins, fall back to trusted-pending"): the caller decides how to aggregate and can layer wallet-specific categories like "locked" on top, instead of being constrained to the fixed Balance buckets. balance is re-expressed as a thin fold over it.

Direction / open questions for human review

• The longer-term idea is that classify_outpoints is the real API and Balance is just one possible fold — wallets that want categories like "locked"/"reserved" aggregate themselves. This PR keeps Balance (as a fold) for now; a follow-up could move it down into bdk_wallet and drop it from bdk_chain.
• Is replacing trust_predicate with ancestry-based does_taint the right call, or should both coexist? (does_taint can't express per-output trust, but per-tx ancestry is arguably the more principled model.)
• Balance::confirmed → Balance::settled: worth the rename / serde break, or keep the conventional name?
• bdk_wallet will need its balance call updated (out of this repo's tree).

Notes to reviewers

• Tests: ancestor-walk tests (diamond merge / reverse-topo order / pruning / exact size), a balance + classify_outpoints ancestry-taint test, and a regression test that a settled-everything is_settled never drops an unconfirmed output. Existing balance tests were migrated (the old per-keychain trust test is recomputed for the new model, since none of its txs actually spend third-party coins).
• cargo fmt, clippy --all-features --all-targets -p bdk_chain, and RUSTDOCFLAGS="-D warnings" cargo doc are clean; the bdk_chain suite + doctests pass.

Changelog notice

Changed

• CanonicalView::balance now takes does_taint and is_settled closures instead of trust_predicate and min_confirmations, and accepts bare OutPoints.
• Renamed Balance::confirmed to Balance::settled.

Added

• CanonicalView::classify_outpoints + Eligibility: per-output spend-eligibility classification (the building block for coin control).
• Canonical::ancestors / Canonical::ancestors_inclusive: reverse-topological canonical ancestor walk with a Mergeable accumulator.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 92.52336% with 16 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.86%. Comparing base (6d03fc3) to head (71c35d9).

Files with missing lines	Patch %	Lines
crates/chain/src/canonical.rs	87.65%	10 Missing ⚠️
crates/chain/src/balance.rs	0.00%	3 Missing ⚠️
crates/chain/src/canonical_ancestors.rs	97.69%	1 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2235      +/-   ##
==========================================
+ Coverage   78.65%   78.86%   +0.20%     
==========================================
  Files          30       31       +1     
  Lines        5909     6076     +167     
  Branches      279      285       +6     
==========================================
+ Hits         4648     4792     +144     
- Misses       1185     1209      +24     
+ Partials       76       75       -1     

Flag	Coverage Δ
rust	78.86% <92.52%> (+0.20%)	⬆️

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.

[evanlinjin]

@oleonardolima It will be ideal if this can reuse logic from #2219.

[Dmenec]

Hey @evanlinjin thank you for pushing this.

As there are many things involved, I tried to go point-by-point on some thoughts I have in here.

Related to your questions:

The longer-term idea is that classify_outpoints is the real API and Balance is just one possible fold — wallets that want categories like "locked"/"reserved" aggregate themselves. This PR keeps Balance (as a fold) for now; a follow-up could move it down into bdk_wallet and drop it from bdk_chain.

Agree, classify_outpoints + Eligibility is a good primitive, Balance is just a convenience fold on top so it makes sense to me. I think moving Balance out of bdk_chain would be a breaking change for consumers calling it directly, so maybe the migration needs care.

Is replacing trust_predicate with ancestry-based does_taint the right call, or should both coexist? (does_taint can't express per-output trust, but per-tx ancestry is arguably the more principled model.)

As said in one comment below, trust_predicate had this identifier that provided specific assumptions per-output. I don't think that's a problem though, that policy was always wallet-specific. It makes more sense for bdk_wallet to handle it externally.

bdk_wallet will need its balance call updated (out of this repo's tree).

This is the part I'm least sure about, so I'll just lay out what I found and leave it open.

While looking into the walk I tried a different approach: a per-UTXO memoized DFS (one bool cached per tx, shared across UTXOs so each ancestor is visited once) instead of the topological accumulator pass. Same does_taint/is_settled contract, and I checked it gives the same Eligibility as classify_outpoints on a diamond. Benchmarked both across a few topologies:

topology	size	memoized	classify_outpoints	speedup
fan-in	10w×3d	9.0 µs	21.9 µs	2.4x
fan-in	50w×5d	77.7 µs	192.9 µs	2.5x
fan-in	100w×10d	300 µs	878 µs	2.9x
fan-in	500w×20d	3.3 ms	14.5 ms	4.4x
disjoint	10w×3d	9.9 µs	24.4 µs	2.5x
disjoint	50w×5d	83.9 µs	194.6 µs	2.3x
disjoint	100w×10d	311 µs	842 µs	2.7x
disjoint	500w×20d	3.3 ms	14.0 ms	4.2x
untrusted-fan-in	10w×3d	8.1 µs	24.2 µs	3.0x
untrusted-fan-in	50w×5d	73.2 µs	209.7 µs	2.9x
untrusted-fan-in	100w×10d	295 µs	940 µs	3.2x
untrusted-fan-in	500w×20d	3.2 ms	16.3 ms	5.1x
diamond	5s×20u	13.5 µs	39.2 µs	2.9x
diamond	10s×50u	49.2 µs	169.1 µs	3.4x
diamond	20s×100u	158 µs	627 µs	4.0x
diamond	50s×500u	1.8 ms	8.3 ms	4.6x

(w = number of parallel chains, d = depth of each chain; for diamond s = shared ancestor txs, u = UTXOs spending all of them.)

Both walk the same O(U+S) txs but the BTreeSet accumulator grows with the number of downstream UTXOs, while the memoized walk just stores one bool per tx and stops early once does_taint fires.

What I genuinely can't decide is where this belongs. It doesn't use CanonicalAncestors at all, just the public tx/txout, so it feels a bit out of place sitting next to classify_outpoints in bdk_chain, not really taking advantage of the ancestor-walk machinery this PR adds. It could just as easily live in bdk_wallet. But then direct bdk_chain consumers of balance() wouldn't benefit.

I'm not sure if it makes sense here, wallet-side, or not at all, some thoughts?

Code + bench: https://github.com/Dmenec/bdk/tree/bench/trust-classification

[Dmenec]

Agree, settled better reflects that the threshold is a wallet policy decision.

[Dmenec]

I like the taint concept more than saying some previous transaction is untrusted, what's actually untrusted is the pending UTXO, not the ancestor.

[Dmenec]

trust_predicate let callers express per-output trust by keychain. does_taint only sees the ancestor transaction, which does not allow for a "blind trust assumption" (i.e. this output belongs to my keychain so trust it).

Not sure if this policy now has to be layered on top of the Eligibility results.

[Dmenec]

does_taint is called eagerly for every unsettled ancestor here and before the returned iterator is built. So if a caller provides an expensive closure, we'd have to evaluate it against every walked ancestor upfront, even if we only end up needing a small part of the UTXOs.

[Dmenec]

Maybe checking with different topolgies would be useful to cover.

For instance: Disjoint seeds with no shared ancestry or a seed that is itself an ancestor of another seed.

[evanlinjin]

@Dmenec Thank you for the detailed review, analysis and experimentation on top. Would you like to take over this work?

I agree that trust_predicate can be implemented externally and I think classify_outpoints + Eligibility is the right shape. I don't mind keeping balance for now as a convenience method.