experiment: seed the search with an ancestry-aware greedy prefix too by evanlinjin · Pull Request #76 · bitcoindevkit/coin-select

evanlinjin · 2026-08-16T13:51:45Z

Draft, on top of #75 (which is on top of #73). One commit.

The problem

Branch and bound sorts candidates by descending value / weight, and LowestFee's bound depends on
that order. The key cannot see ancestry at all, so a candidate whose unconfirmed parents cost more to
bump than the next candidate is worth still sorts ahead of it.

On a pool the search can work through this is invisible — the search fixes it. On a pool it cannot,
it is the entire answer. Measured on a 200,000-candidate fixture at a 100 ms budget, coin-select's
returned score equals its greedy seed's score exactly, and stays byte-identical at a hundred times
the clock: 118,784 nodes of a tree over 200,000 candidates never beat the greedy prefix. At that
scale the ordering is the algorithm, and the blind order drags in parents it did not have to.

Against Bitcoin Core on the same fixture, that is worth the whole gap:

`shared_ancestry_200000`	inputs	with no unconfirmed parent	parents touched	union bump	child fee
coin-select	360	134	226	955,403	1,201,193
Bitcoin Core	360	141	219	923,621	1,169,084

The bump difference is 31,782 sat against a fee difference of 32,109 — 99% of Core's win is that it
dragged in seven fewer unconfirmed parents. Core gets there structurally: it charges each coin its
own bump inside effective value before the search, so parent-laden coins look worse and it drifts
off them.

What this does

Takes a second greedy prefix, ordered by (value - own bump) / weight, and keeps whichever of
the two the metric scores better.

It is deliberately not a change to the search order. local_bump overcounts a shared parent that
some other selected candidate would have dragged in anyway, so it is not a quantity the bound can be
built on — and the bound's admissibility rests on the value / weight ordering. Confining the
reprice to an incumbent keeps the bound untouched and the optimum reachable, and the reordered prefix
is adopted only when the metric actually scores it better.

Costs one greedy pass and one sort, and only when the problem has unconfirmed ancestors at all.

Measured

Every number from coinselect-benchmark, same
fixtures, same wall clock, against #75 unmodified.

The scale tier, 100 ms budget:

fixture	package fee		union bump		parents touched
	#75	+this	#75	+this	#75	+this
`shared_ancestry_200000`	1,366,750	1,331,840 (−2.55%)	955,403	926,237	226	220
`wallet_mixed_200000`	774,280	773,150 (−0.15%)	425,016	422,243	157	157
the other four	—	unchanged

On shared_ancestry_200000 that is a child fee of 1,201,193 → 1,172,027 against Core's 1,169,084:
91% of the gap closed, and 226 → 220 parents against Core's 219. Identical at a 1 s budget.

The 42-fixture matrix, up to 2,000 candidates — four budget regimes (100,000 rounds; 10 ms;
100 ms; 1 s):

regime	total package fee
100,000 rounds	+0.000% (42 of 42 selections identical)
10 ms	−0.041%
100 ms	+0.000% (42 of 42 identical)
1 s	+0.008%

The nonzero regimes are deadline noise, not the change, and the worst-looking entry is the proof.
wallet_mixed_200 appears to regress +6.3% at 10 ms — but it exhausts in 17,345 rounds and 9.8 ms,
right at the deadline. Both arms exhaust to the identical selection given a millisecond more, and it
is the unmodified arm that got the anomaly: truncated mid-search, it returned a selection that scores
better on the benchmark's package-fee model while scoring worse on LowestFee, which is what the
search is actually minimising. The two moves at 1 s are no_ancestry_2000 (+0.007%) and
wallet_mixed_2000 (+0.103%), both with a union bump of zero — no_ancestry_2000 has no
ancestors at all, so this code does not even run on it.

Cost, where the extra pass is not free: a few ms on the ancestry-heavy fixtures at 100,000 rounds
(shared_ancestry_2000 121 → 124 ms, subsidizing_ancestry_50 27 → 32 ms), with identical round
counts and identical scores.

Where it does nothing, and why

At 20,000 candidates it is byte-identical to #75 on every fixture, while Core still wins
shared_ancestry_20000 by 0.4% — by the same mechanism, one extra unconfirmed parent (204 against
203, worth 4,912 sat, against a 680 sat saving from one fewer input; that is the entire 4,252 sat
gap).

The reprice cannot reach it there, and the reason is measurable. What the key buys is
(parent charge) / (gap between adjacent coins in the order):

	median solo bump	median neighbour gap	positions a parent moves a coin	coins crossing the prefix cutoff
20,000 candidates	4,185 sat	1,656 sat	2.5	0 (still 0 at top-1,000)
200,000 candidates	4,221 sat	148 sat	28.4	6

Ten times the coins drawn from the same value distribution means the top of the order is ten times
denser — the top 1,000 spans 4,998,053..2,792,317 sat at 20,000 candidates and 4,999,816..4,770,018
at 200,000 — so the same ~4,200 sat parent charge reorders ten times further. Below that threshold
the reprice shifts parent-laden coins without moving any of them across the cutoff, and the prefix
comes out the same set.

So this is not a general fix for ancestry blindness — it is worth exactly what an ancestor bump is
worth relative to the value gaps between adjacent coins. It happens to pay in the regime where the
search cannot help, which is the regime that needed it.

Test plan

cargo test, cargo clippy, and a --no-default-features build all pass. The behaviour is covered
by the benchmark numbers above rather than by a new unit test: the change is an incumbent that is
adopted only when it scores better, so it cannot make any existing assertion fail, and the fixtures
that exercise it are 30 MB apiece.

…y_count Fixes CoinSelector::input_weight undercounting candidates that group multiple legacy inputs in a segwit transaction (where each legacy input serializes a 1 WU empty witness). Tracking segwit and legacy input counts separately also allows a single Candidate to mix legacy and segwit inputs.

…legacy Replaces the boolean is_segwit parameter in Candidate::new with explicit new_segwit and new_legacy constructors. Clarifies in doc comments that satisfaction_weight is the additional weight required beyond TXIN_BASE_WEIGHT (which already accounts for a 1-byte scriptSigLen).

…call A selector was built for one target and evaluated against it throughout, but every method took the target as a parameter, so nothing stopped `cs.excess(target_a, drain)` being followed by `cs.is_funded(target_b)`. The correctness arguments in the metrics are all stated at a fixed target -- `LowestFee::bound`'s proof that a changeless superset always costs more, `Changeless::change_unavoidable`'s assumption that the drain decision is monotone in the excess -- and were held together by convention rather than by types. `CoinSelector::new` now takes the target and owns it. Twenty signatures *lose* a parameter rather than gaining one: fifteen public methods (`excess`, `implied_fee`, `is_funded`, `drain`, `select_until_target_met`, the four `*_excess`, ...), plus `bnb_solutions` and `run_bnb`, plus all three `BnbMetric` methods. The crate had already reached this conclusion one layer down: `BnbIter` stored the target as a field, took it once in `BnbIter::new`, and then re-passed it into `metric.score` and `metric.bound` at every node. That field and the re-threading are both gone. This is a breaking change, and it reaches `BnbMetric`, so metrics implemented outside this crate need their signatures updated: fn score(&mut self, cs: &CoinSelector<'_>) -> Option<Ordf32>; fn bound(&mut self, cs: &CoinSelector<'_>) -> Option<Ordf32>; fn drain(&mut self, cs: &CoinSelector<'_>) -> Drain; `CoinSelector::target()` exposes the target for metrics that need to read it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Move the fixed target, candidates, and optional ancestor graph into one immutable problem object. CoinSelector now borrows that object, keeping all calculations tied to the same inputs and allowing ancestry metadata to remain separate from Candidate. Provide new_no_ancestors for prebuilt candidates and new for constructing candidates from input groups and their unconfirmed transaction graph.

Selecting an unconfirmed coin means paying to bump its ancestors. The feerate obligation includes the shortfall of the union of ancestors the selected candidates drag in (each charged once; weight and fee netted; saturates at 0). Score is still the child fee — the bump is already inside it. With ancestors, LowestFee falls back to a loose but admissible fee floor; tightening is a follow-up. BnB only batch-bans look-alikes with the same drags_in; Changeless disables its prune when ancestors are present.

Precompute ancestors reachable through exactly one candidate as summed private packages. Keep bitset de-duplication only for ancestors shared by multiple candidates, preserving exact union accounting while reducing the common-path work in every fee calculation. Add Criterion coverage for private and shared ancestry at 20, 50, and 100 candidates, plus exhaustive regressions for the optimized representation.

For funded nodes, subtract the ancestor surplus still reachable by a descendant. For unfunded nodes, derive a minimum added child weight from independent fractional relaxations of the target-rate, absolute-fee, and RBF constraints, then evaluate the fee floor at that weight. Candidate ancestry is deliberately represented only by the global bump lower bound: package surplus can absorb a later private deficit, so a per-candidate ancestor cost is not admissible. Keep infeasibility prunes off because ancestor funding is non-monotone. Add regressions for package subsidy, absolute/RBF double counting, and large-float cancellation, plus the existing exhaustive proptests.

Maintain aggregate selection state per branch and expose it through SelectionView so metric evaluation avoids repeatedly walking selected candidates. Track each branch's candidate cursor to skip repeated scans, and extend benchmarks across wallet- and exchange-scale pools.

Keep SelectionView's hypothetical updates set-like and synchronize ancestor reachability when branches exclude candidates. Remove unsound funding and changeless assumptions exposed by non-monotone ancestor debt, and preserve conservative fee rounding in the bound. Add regressions for public view updates, exclusion transitions, weight caps, mixed serialization overhead, and floating-point edge cases.

Separate deterministic solution-finding cases from larger pools expected to exhaust the fixed round cap. Assert each fixture's expected search outcome before measuring it so benchmark comparisons cannot silently time different paths.

Store private ancestor totals directly and allocate shared reference tracking only when the problem actually has shared ancestry. Preserve an explicit precision allowance for large floating-point ancestor fees so the smaller cache does not tighten the admissible bound.

Replace generic metric composition with a changeless metric that reuses LowestFee's funding, weight-cap, dust, and change decisions. Add a monotone selected-value bound for pools up to 24 candidates while retaining LowestFee's ordering for larger pools to avoid finite-round starvation. Cover the constrained objective with exhaustive and serialization-edge regressions, and document the migration from Changeless and tuple metrics.

Replace the best-first BinaryHeap frontier with depth-first search that visits the better-bound child first and backtracks in place. This drops per-branch selector/cache clones and, under a round cap, finds complete solutions on large pools where the old frontier often exhausted the budget without a selection.

`LowestFeeChangeless` only applied its selected-value bound to pools of at most 24 candidates. The cap existed because best-first search treats a bound as a priority: a bound that grows with the selection pushed funded branches to the back of the heap, so on a big pool the frontier starved before it reached one. Depth-first search reads a bound as a cut instead of a ranking — it finishes a branch's descendants before its siblings — so the bound can be applied at every pool size, where it prunes inclusion branches that have already overshot the incumbent.

Yield the greedy selection before expanding the first node, and adopt its score as the incumbent. The search is otherwise not anytime: a caller whose round budget runs out before the first complete selection gets `NoBnbSolution::RoundLimit` and falls through to whatever fallback it has, which on a large pool is far worse than the selection a single greedy pass would have handed it for free. Only the incumbent changes, not the bound, so the optimum stays reachable and the improving-solutions contract is unaffected. Metrics that reject the greedy prefix outright — `LowestFeeChangeless`, which will not score a selection that overshoots — are unchanged, and `RoundLimit` still means what it did for them. The two round-count assertions in `tests/bnb.rs` each move by one: the seed is a round.

Bitcoin Core's `SelectCoinsBnB` computes `is_feerate_high` once and lets it decide whether a prune that is only sometimes valid may fire; it does not drop the prune because the general case is unsound. `bound_with_ancestors` took the other route — "never returns `None`" — on the grounds that a fat private deficit can un-fund a prefix a subset would have funded, so infeasibility is not something it may claim. That argument covers "select everything and it is still unfunded". It does not cover the case this relaxation can prove outright: a fee constraint whose deficit the best input still available cannot close at *any* weight. Descendants only add, the deficit is already computed against the branch-wide `ancestor_bump_lower_bound`, and the gain already ignores whatever ancestors those inputs would drag in — so the estimate is optimistic on every axis, and a deficit it still cannot close belongs to an empty subtree. The scan that finds the best value-per-weight candidate already runs, so the test is free. It also prunes the unfunded leaves that had nothing left to add, which the old path could only rank.

Port Bitcoin Core's `SelectCoinsBnB` lookahead. Core keeps a running `curr_available_value` over the coins it has not decided on yet and backtracks as soon as that total cannot close the gap to the target; the cut needs no incumbent, so it fires from the very first descent. We had the same idea only in `LowestFee::bound`'s no-ancestor path, as an O(n) rescan that ran after the relaxation had already been set up, and not at all when the problem has ancestors. `SelectionCache` now carries the value and weight of the undecided candidates worth selecting, maintained by the same add/sub/ban/unban hooks that already track reachable ancestor surplus, so the test is O(1). Two one-sided relaxations keep it from pruning a branch that holds a solution: only candidates with positive standalone effective value count toward the total, and the current ancestor bump is swapped for `ancestor_bump_lower_bound`, which holds for the whole subtree. That second one is what lets the prune run with ancestors present, where funding is not monotone and "select everything and it is still unfunded" would have been an unsound claim.

LowestFee already decides for itself whether a selection should carry a change output, adding one only when it lowers the long-term fee, clears the dust threshold and fits max_weight. A separate changeless objective duplicates that decision and constrains it, and nothing in the crate needs the constraint. Removes LowestFeeChangeless along with the Changeless wrapper the unreleased changelog already retired, plus their tests and proptest regressions. BREAKING CHANGE: LowestFeeChangeless and Changeless are gone. Callers that required a changeless transaction should use LowestFee and inspect the Drain it returns.

`bound_with_ancestors` scanned every undecided candidate at each unfunded node to find the greatest value-per-weight and to notice weightless value. Branch and bound asks for that bound at every unfunded node, so an O(n) scan there made per-node cost grow with the pool: measured on shared_ancestry_*, 2389 ns/round at n=500 rising to 9384 at n=2000, against 385-2056 for the no-ancestry fixtures. The metric already requires candidates in descending value-per-weight order, and that order is keyed on f32. The exact f64 maximum can therefore only lie inside the run sharing the first undecided candidate's f32 key, which is why the old code scanned in f64 rather than taking the first: two exact ratios can tie in f32 and be ordered either way. Scanning just that run keeps the exact answer without touching the tail. Weightless value becomes a counter kept where the undecided aggregates already are. 5.9x to 8.8x faster per round at n=500 to 2000, and byte-identical results: across all 42 benchmark fixtures the score, selection, round count and exhausted flag are unchanged. A debug assertion checks the tie-run result against a full scan, so the ordering assumption is verified on every node the test suite searches.

`SelectionView` overrides these with cache-backed versions, so every call site in the crate and its tests already resolved to the view; the `CoinSelector` copies recomputed the same answers by iterating and had no callers left. Removes `effective_value`, `implied_feerate`, `rate_excess_wu`, `replacement_excess_wu` and `waste`, plus the two private helpers they were the last users of. `missing` and `drain` are deliberately kept even though the view also has them: the crate's own front-page example calls them on a bare `CoinSelector`, which is the case they exist for. The same argument keeps the rest of the overlap -- `weight`, `excess`, `is_funded` and friends all have live callers holding a selector rather than a view, and routing those through `compute_view` would cost an O(n) cache build to replace an O(n) method. BREAKING CHANGE: obtain a `SelectionView` with `CoinSelector::compute_view` and call the removed methods there.

`SelectionView` answered every one of these from its cache while the `CoinSelector` copy recomputed the same figure by iterating the selection. Keeping both meant two implementations of the weight model, the excess model and the ancestor bump, and the slower one was the default a caller reached for. Removes `absolute_excess`, `ancestor_bump`, `ancestor_bump_lower_bound`, `drain`, `drain_value`, `excess`, `fee`, `implied_fee`, `input_weight`, `is_funded`, `is_funded_with_drain`, `is_within_max_weight`, `missing`, `rate_excess`, `replacement_excess`, `selected_value` and `weight` from `CoinSelector`, along with the two private helpers they were the last users of. `select_until` now hands its predicate a `&SelectionView` and maintains that view's cache incrementally, so the greedy pass behind `select_until_target_met` -- which seeds every branch-and-bound search -- costs one cache build plus O(1) per step instead of rescanning the selection on every iteration. The crate's own front-page example now goes through `compute_view` too, which is what the removed methods were kept for. BREAKING CHANGE: obtain a `SelectionView` with `CoinSelector::compute_view` and call the removed methods there. `CoinSelector::select_until` takes a predicate over `&SelectionView` rather than `&CoinSelector`. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HLiTkESMktypGJhFag2ZBM

`seed` carried `(CoinSelector, Ordf32)` while `best` separately held the same score. They are set together in `seed_greedy_incumbent` and nothing runs between construction and the first `next()`, so the score in the tuple was always exactly `best`. Store the selection alone and read the score from `best` when yielding. No behaviour change: identical score, selection, round count and exhausted flag on all 42 benchmark fixtures.

`drags_in` and `shared_drags_in` were one dense `Bitset` per candidate over every ancestor, costing candidates x ancestors bits. On a 200,000-candidate pool with 26,666 ancestors that is 667 MB per array of very nearly nothing: a candidate drags in its residing transactions and their unconfirmed parents, which measures mean 0.42 entries and never more than two, so the sets are 0.002% full. The cost is not only memory. Iterating a dense bitset is O(ancestors) per candidate however few bits are set, so building the selection cache — which walks every candidate's shared set — is O(candidates x ancestors) in time too. Setting up a search on 200,000 candidates took 464 ms before expanding a single node, which is enough to lose a wall-clock budget outright: the benchmark harness reported "no solution" on that fixture because the deadline expired during construction. Stored flat instead: one `Vec<u32>` of indices with per-candidate offsets. Every read of these sets is a full walk of one candidate's entries and they never change after construction, so a slice is all they need to be. Construction reuses one scratch bitset rather than allocating per candidate, so the old cost does not reappear while building. 200,000 candidates, 26,666 ancestors peak RSS setup dense bitset 1,332 MB 464 ms flat indices + offsets 58 MB 54 ms `Bitset` is unchanged where it is used over candidates — the selected and banned sets are dense and membership-tested constantly. Breaking: `drags_in` and `shared_drags_in` now return `&[u32]` rather than `&Bitset`. Byte-identical to the parent commit on all 42 benchmark fixtures — same selections, scores, round counts and exhausted flags. 80 tests green on `--all-features` and `--no-default-features`. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HLiTkESMktypGJhFag2ZBM

The search order is descending `value / weight`, which the `LowestFee` bound depends on and which cannot see ancestry at all: a candidate whose unconfirmed parents cost more to bump than the next candidate is worth still sorts ahead of it. On a pool the search can work through, that is invisible, because the search fixes it. On a pool it cannot — a few hundred thousand candidates, where branch and bound returns the greedy prefix it started from — the ordering *is* the answer, and the blind one drags in parents it did not have to. So take a second greedy prefix, ordered by `(value - own bump) / weight`, and keep whichever of the two the metric scores better. `local_bump` overcounts a shared parent that some other selected candidate would have dragged in anyway, which is why this is an incumbent rather than the order the search runs in: the ordering the bound relies on is untouched, the optimum stays reachable, and the reordered prefix is adopted only when it actually scores better. Costs one greedy pass and one sort, and only when the problem has unconfirmed ancestors at all. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HLiTkESMktypGJhFag2ZBM

evanlinjin and others added 26 commits August 14, 2026 04:52

bench: restore capped BnB frontier coverage

28c5455

Separate deterministic solution-finding cases from larger pools expected to exhaust the fixed round cap. Assert each fixture's expected search outcome before measuring it so benchmark comparisons cannot silently time different paths.

docs: polish ancestor-aware API guidance

7e965cf

fixup! perf: search branch and bound with in-place DFS

7d48f88

This was referenced Aug 17, 2026

perf: stop re-walking the decided prefix at every node evanlinjin/coin-select#4

Draft

perf: stop re-walking the decided prefix at every node #77

Draft

feat: repair a finished selection where ancestry is shared #79

Draft

Navigation Menu

Uh oh!

experiment: seed the search with an ancestry-aware greedy prefix too - #76

experiment: seed the search with an ancestry-aware greedy prefix too#76
evanlinjin wants to merge 26 commits into
bitcoindevkit:masterfrom
evanlinjin:experiment/ancestry-aware-seed

evanlinjin commented Aug 16, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

evanlinjin commented Aug 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

The problem

What this does

Measured

Where it does nothing, and why

Test plan

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

evanlinjin commented Aug 16, 2026 •

edited

Loading