feat!: depth-first branch and bound, and remove the Changeless metric

CHANGELOG.md

@@ -1,13 +1,15 @@
 # Unreleased
 
-- **Breaking:** `BnbMetric`'s `score`, `bound`, and `drain` take the `target: Target` as a parameter, and `CoinSelector::run_bnb`/`bnb_solutions` gain a leading `target` argument. Consequently `LowestFee` and `Changeless` no longer store a `target` field. This removes the target that `Changeless<M>` previously had to keep in sync with its inner metric, and aligns the metric API with the rest of `CoinSelector`, where `target` is always passed in.
+- **Breaking:** Replace `Candidate`'s `input_count` and `is_segwit` fields with `segwit_count` and `legacy_count`, fixing `CoinSelector::input_weight` undercounting candidates that group multiple inputs: in a segwit transaction every legacy input still serializes an empty witness (1 WU), which was previously paid once per candidate instead of once per legacy input, so a group of N legacy inputs came out N-1 WU short. Splitting the count by script type also means a single candidate may now mix legacy and segwit inputs and still be priced exactly. Branch and bound also stops treating candidates of equal value and weight as interchangeable when their segwit/legacy counts differ, which could make it skip a cheaper selection. Replaces `Candidate::new` with `Candidate::new_segwit` and `Candidate::new_legacy`.
+- **Breaking:** `CoinSelector` now owns its `Target`. `CoinSelector::new(candidates, target)` takes it and `CoinSelector::target()` returns it, and it is fixed for the life of the selector. Every method that took a `target: Target` argument no longer does, including `excess`, `missing`, `rate_excess`, `implied_fee`, `is_funded`, `is_within_max_weight`, `drain`, `select_until_target_met`, `select_srd`, `run_bnb`, and `bnb_solutions`. The same goes for arguments that merely restated part of the target: `weight` and `implied_feerate` no longer take `TargetOutputs`, `fee` no longer takes `target_value`, and `effective_value` and `select_all_effective` no longer take a `FeeRate`. `BnbMetric`'s methods read the target from the `CoinSelector` they are given — they are now `fn score(&mut self, cs: &CoinSelector<'_>) -> Option<Ordf32>`, `fn bound(&mut self, cs: &CoinSelector<'_>) -> Option<Ordf32>` and `fn drain(&mut self, cs: &CoinSelector<'_>) -> Drain` — so `LowestFee` no longer stores a `target` field. To measure a selection against a second target, use `CoinSelector::with_target(target)`, which copies the selection, the bans and the candidate order over to the new target; `CoinSelector::new` starts from an empty selection.
 - **Breaking:** `BnbMetric` metrics now decide the change output themselves. The trait gains a `drain(&mut self, cs) -> Drain` method; call it on a branch-and-bound solution (or the `LowestFee` metric directly) to get the change output the metric optimized against, instead of computing a separate `ChangePolicy`.
 - **Breaking:** `CoinSelector::run_bnb` now returns `(Ordf32, Drain)` instead of just `Ordf32`, handing back the change output the metric decided on for the winning selection.
 - **Breaking:** `LowestFee` no longer takes a `change_policy`. It now takes `dust_relay_feerate: FeeRate` and `drain_weights: DrainWeights`, and adds change only when doing so lowers the long-term fee and the change would not be dust.
 - Add `DrainWeights::dust_threshold(dust_relay_feerate)`, the minimum value a change output with these weights must have to not be dust.
 - Add `CoinSelector::select_srd`, a Single Random Draw selector (port of Bitcoin Core's `SelectCoinsSRD`) that adds candidates in random order until the change reaches `change_lower`, producing a healthy-sized (privacy-friendly) change output instead of minimizing fees. Adds the `CHANGE_LOWER` constant for Core's value.
-- **Breaking:** `Changeless` is now `Changeless<M>`, wrapping an inner metric it constrains to changeless solutions (e.g. `Changeless<LowestFee>`), replacing the previous tuple-composition approach.
-- **Breaking:** Removed the `BnbMetric` tuple implementations (`impl BnbMetric for ((A, f32), ...)`). Weighted composition of independent metrics is no longer supported; the only composition still provided is the changeless constraint, now expressed as `Changeless<M>`. If you relied on tuples to blend multiple objectives, there is no drop-in replacement.
+- Search branch and bound depth-first (better-bound child first, backtracking in place) instead of best-first over a heap of cloned branches. Only the current path is held in memory, and under a round cap it reaches complete selections on large pools where the old frontier often ran out of rounds first.
+- Seed branch and bound with the greedy selection, so a search that runs out of rounds returns the best selection it has instead of `NoBnbSolution::RoundLimit`. `RoundLimit` now means the round budget ran out before even the greedy selection was scored (e.g. `max_rounds` is 0), or the metric rejected it.
+- **Breaking:** Remove the `Changeless` metric and the `BnbMetric` tuple implementations (`impl BnbMetric for ((A, f32), ...)`). Generic metric composition is no longer supported. `LowestFee` decides for itself whether a selection should carry change (adding one only when it lowers the long-term fee, clears the dust threshold, and fits `Target::max_weight`), so a separate changeless objective duplicates that decision and then constrains it. Callers that required a changeless transaction should use `LowestFee` and inspect the returned `Drain`.
 - **Breaking:** `CoinSelector::selected_indices` and `CoinSelector::banned` now return `&Bitset` instead of `&BTreeSet<usize>`. `Bitset` exposes `contains`/`len`/`is_empty`/`iter` (#46)
 - Replace the internal `Cow<BTreeSet>`/`Cow<[usize]>` selection state with a `Bitset` and an `Arc`-shared candidate order, making the per-branch clones in branch-and-bound substantially cheaper (#46)
 - Fix compilation error when building with `--no-default-features` (#36)

README.md

@@ -33,34 +33,33 @@ let candidates = vec![
     Candidate {
         // How many inputs does this candidate represents. Needed so we can 
         // figure out the weight of the varint that encodes the number of inputs
-        input_count: 1,
+        // and whether segwit transaction fields need to be counted in.
+        segwit_count: 1,
+        legacy_count: 0,
         // the value of the input
         value: 1_000_000,
         // the total weight of the input(s) including their witness/scriptSig
         // you may need to use miniscript to figure out the correct value here.
         weight: TR_KEYSPEND_TXIN_WEIGHT,
-        // wether it's a segwit input. Needed so we know whether to include the
-        // segwit header in total weight calculations.
-        is_segwit: true
     },
     Candidate {
         // A candidate can represent multiple inputs in the case where you 
         // always want some inputs to be spent together.
-        input_count: 2,
+        segwit_count: 2,
+        legacy_count: 0,
         weight: 2*TR_KEYSPEND_TXIN_WEIGHT,
         value: 3_000_000,
-        is_segwit: true
     }
 ];
 
 // You can now select coins!
-let mut coin_selector = CoinSelector::new(&candidates);
+let mut coin_selector = CoinSelector::new(&candidates, target);
 coin_selector.select(0);
 
-assert!(!coin_selector.is_funded(target), "we didn't select enough");
-println!("we didn't select enough yet we're missing: {}", coin_selector.missing(target));
+assert!(!coin_selector.is_funded(), "we didn't select enough");
+println!("we didn't select enough yet we're missing: {}", coin_selector.missing());
 coin_selector.select(1);
-assert!(coin_selector.is_funded(target), "we should have enough now");
+assert!(coin_selector.is_funded(), "we should have enough now");
 
 // Now we need to know if we need a change output to drain the excess if we overshot too much
 //
@@ -69,7 +68,7 @@ assert!(coin_selector.is_funded(target), "we should have enough now");
 let drain_weights = DrainWeights::TR_KEYSPEND; 
 // Our policy is to only add a change output if the value is over 1_000 sats
 let change_policy = ChangePolicy::min_value(drain_weights, 1_000);
-let change = coin_selector.drain(target, change_policy);
+let change = coin_selector.drain(change_policy);
 if change.is_some() {
     println!("We need to add our change output to the transaction with {} value", change.value);
 } else {
@@ -105,36 +104,36 @@ let outputs = vec![TxOut {
 
 let candidates = [
     Candidate {
-        input_count: 1,
+        segwit_count: 1,
+        legacy_count: 0,
         value: 400_000,
         weight: TR_KEYSPEND_TXIN_WEIGHT,
-        is_segwit: true
     },
     Candidate {
-        input_count: 1,
+        segwit_count: 1,
+        legacy_count: 0,
         value: 200_000,
         weight: TR_KEYSPEND_TXIN_WEIGHT,
-        is_segwit: true
     },
     Candidate {
-        input_count: 1,
+        segwit_count: 1,
+        legacy_count: 0,
         value: 11_000,
         weight: TR_KEYSPEND_TXIN_WEIGHT,
-        is_segwit: true
     }
 ];
 let drain_weights = bdk_coin_select::DrainWeights::default();
 // You could determine this by looking at the user's transaction history and taking an average of the feerate.
 let long_term_feerate = FeeRate::from_sat_per_vb(10.0);
 
-let mut coin_selector = CoinSelector::new(&candidates);
-
 let target = Target {
     fee: TargetFee::from_feerate(FeeRate::from_sat_per_vb(15.0)),
     outputs: TargetOutputs::fund_outputs(outputs.iter().map(|output| (output.weight().to_wu(), output.value.to_sat()))),
     max_weight: None,
 };
 
+let mut coin_selector = CoinSelector::new(&candidates, target);
+
 // The feerate used to work out whether a change output would be dust (and so shouldn't be added).
 // The standard dust relay feerate is 3 sat/vb.
 let dust_relay_feerate = FeeRate::from_sat_per_vb(3.0);
@@ -150,13 +149,13 @@ let mut metric = LowestFee {
 
 // We run the branch and bound algorithm with a max round limit of 100,000.
 // On success it returns the score along with the change output the metric decided on.
-let change = match coin_selector.run_bnb(target, metric, 100_000) {
+let change = match coin_selector.run_bnb(metric, 100_000) {
     Err(err) => {
         println!("failed to find a solution: {}", err);
         // fall back to naive selection
-        coin_selector.select_until_target_met(target).expect("a selection was impossible!");
+        coin_selector.select_until_target_met().expect("a selection was impossible!");
         // the metric still decides the change output for whatever we end up selecting
-        metric.drain(&coin_selector, target)
+        metric.drain(&coin_selector)
     }
     Ok((score, change)) => {
         println!("we found a solution with score {}", score);

benches/coin_selector.rs

@@ -33,8 +33,8 @@ fn make_candidates(n: usize) -> Vec<Candidate> {
             Candidate {
                 value,
                 weight: TXIN_BASE_WEIGHT + P2WPKH_SAT_W,
-                input_count: 1,
-                is_segwit: true,
+                segwit_count: 1,
+                legacy_count: 0,
             }
         })
         .collect()
@@ -56,7 +56,8 @@ fn bench_coin_selector_clone(c: &mut Criterion) {
     let mut group = c.benchmark_group("clone");
     for &n in &[64usize, 256, 1024, 4096] {
         let candidates = make_candidates(n);
-        let mut selector = CoinSelector::new(&candidates);
+        let (target, _) = make_bnb_inputs(&candidates);
+        let mut selector = CoinSelector::new(&candidates, target);
         // Select ~10% of candidates so `selected` is non-trivial to copy.
         for i in (0..n).step_by(10) {
             selector.select(i);
@@ -74,8 +75,8 @@ fn bench_run_bnb_lowest_fee(c: &mut Criterion) {
     group.sample_size(20);
     for &n in &[20usize, 50, 100, 200] {
         let candidates = make_candidates(n);
-        let selector = CoinSelector::new(&candidates);
         let (target, long_term_feerate) = make_bnb_inputs(&candidates);
+        let selector = CoinSelector::new(&candidates, target);
         group.bench_with_input(BenchmarkId::from_parameter(n), &n, |b, _| {
             b.iter_batched(
                 || selector.clone(),
@@ -85,7 +86,7 @@ fn bench_run_bnb_lowest_fee(c: &mut Criterion) {
                         dust_relay_feerate: FeeRate::from_sat_per_vb(1.0),
                         drain_weights: DrainWeights::TR_KEYSPEND,
                     };
-                    let _ = sel.run_bnb(target, metric, black_box(100_000));
+                    let _ = sel.run_bnb(metric, black_box(100_000));
                     sel
                 },
                 BatchSize::SmallInput,