Ancestor-aware CPFP: search on local bumps, report exact package pricing

[evanlinjin]

Note

Stacked on #59 (first commit). Review 5570dcc and d917ed8 here; the rest is #59.

Closes #24. Successor to #43 (closed), taking a different approach after measurement; alternative to #38 / #42.

Why

When spending unconfirmed UTXOs, miners evaluate the transaction as a package with its unconfirmed ancestors — if the ancestors paid below the target feerate, the child must cover the difference (CPFP). The bump is a property of the package: an ancestor shared by two candidates is paid for once, so it is not additive across candidates. That non-additivity is what broke every earlier design — per-candidate figures like Candidate::effective_value stop telling the truth, and every bound in branch and bound stops being a bound.

#43 answered that by banning ancestor-carrying candidates from automatic selection. Measured against brute force, the ban costs up to 3.07% in answer quality when parents mostly already pay the going rate, and reports insufficient funds against a wallet that can pay on up to 100% of instances once most candidates are unconfirmed. So this PR takes the split Bitcoin Core draws between calculateIndividualBumpFees and calculateCombinedBumpFee:

• the search ranks on each candidate's individual bump — additive, so every existing metric-correctness argument holds as written, and nothing is banned;
• everything reported (excess, implied_fee, is_funded, drain) uses the exact combined figure, which is what the transaction actually pays.

The individual sum never falls below the combined figure (pinned by proptest over 2000 generated clusters), so the search over-reserves and the difference lands in the change output, never missing from the fee.

API

let mut builder = ClusterBuilder::new(); // keyed by the caller's own ids (txids) -- no `bitcoin` dep, `Id` is generic
builder.tx(txid_a, /*weight*/ 1_000, /*fee*/ 500, /*parents*/ []);
builder.tx(txid_b, 400, 0, [txid_a]);
builder.spent_by(txid_b, /*candidate index*/ 3);
let cluster = builder.build()?; // errors name *your* ids, not positions

let mut cs = CoinSelector::new(&candidates, target).with_cluster(&cluster);

The caller supplies the mempool graph; transitive ancestor closures are computed internally, and a mock block template (Cluster::mine, the same greedy ancestor-feerate loop as Bitcoin Core's MiniMiner from bitcoin/bitcoin#27021) determines what still needs bumping at the target feerate — a parent already paying its way, or carried by an overpaying child in the cluster, correctly costs nothing. Because the selector owns its target (#59), the pricing is derived at the right feerate by construction; there is no way to inject figures computed at another rate.

Queries: ancestor_bump_fee_of / effective_value_of / value_pwu_of (per candidate, on CoinSelector because a bump is only meaningful at the feerate it was derived for), and selected_ancestor_bump_fee() for the package. No cap on how many candidates may carry ancestors, nothing banned, Candidate unchanged.

Measurements

src/ancestor_search_experiment.rs keeps them runnable (cargo test --release ancestor_search_experiment -- --ignored --nocapture). Sweeping how many of 12 candidates carry unconfirmed ancestors, optimum by brute force: answer gap ≤ 0.11% for k ≤ 8 (vs the ban's 0.07–0.46% plus its hard failures), search cost at or below the ancestor-free baseline. The module docs record the two designs this replaced and why: the ban, and repairing LowestFee::bound with a min_bump floor over the exact model (prunes almost nothing — the bound prices a greedy prefix, and the least bump reachable from the root is always zero).

Known residual: the prefix's stopping condition still uses the bump-aware is_funded, worth ~0.01% of bound calls; documented in the commit message, deliberately left for a follow-up.

---

Co-authored with @noahjoeris, who contributed the inverted ancestor→candidate edge the first iteration was built on.

🤖 Generated with Claude Code