feat: add CoinSelector::select_srd (Single Random Draw)

Port of Bitcoin Core's `SelectCoinsSRD`: add candidates in random order
until the change reaches a fixed `change_lower`, yielding a healthy-sized
(privacy-friendly) change output rather than minimizing fees. Like Core, the
threshold is fixed and the change amount comes out random from the draw
itself. The stop condition reuses `excess(target, drain_weights)`, so no new
fee math. RNG is a dependency-free `impl FnMut() -> u64`.

Adds the `CHANGE_LOWER` constant (Core's 50k).

Maximum-selection-weight handling is left as a TODO pending the max-weight PR.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: evanlinjin

CHANGELOG.md

@@ -4,6 +4,7 @@
 - **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.
 - **Breaking:** `CoinSelector::selected_indices` and `CoinSelector::banned` now return `&Bitset` instead of `&BTreeSet<usize>`. `Bitset` exposes `contains`/`len`/`is_empty`/`iter` (#46)

src/coin_selector.rs

@@ -4,6 +4,10 @@ use crate::float::FloatExt;
 use crate::{bitset::Bitset, bnb::BnbMetric, float::Ordf32, ChangePolicy, FeeRate, Target};
 use alloc::{sync::Arc, vec::Vec};
 
+/// The change amount Bitcoin Core's `SelectCoinsSRD` selects for; a sensible default for the
+/// `change_lower` argument of [`CoinSelector::select_srd`].
+pub const CHANGE_LOWER: u64 = 50_000;
+
 /// [`CoinSelector`] selects/deselects coins from a set of canididate coins.
 ///
 /// You can manually select coins using methods like [`select`], or automatically with methods such
@@ -548,6 +552,70 @@ impl<'a> CoinSelector<'a> {
         }
     }
 
+    /// Select candidates in random order ("Single Random Draw") until the change would be at least
+    /// `change_lower`.
+    ///
+    /// Unlike [`run_bnb`] with [`LowestFee`], this doesn't minimize fees — it deliberately produces
+    /// a healthy-sized (privacy-friendly) change output, avoiding tiny "toxic" change. It's a port
+    /// of Bitcoin Core's `SelectCoinsSRD`; pass [`CHANGE_LOWER`] for Core's value.
+    ///
+    /// The change *amount* comes out random on its own: because candidates are added in random order
+    /// and we stop as soon as the change reaches `change_lower`, the final change is wherever the
+    /// last (random) input pushed it — at or above `change_lower`. So, like Core, we use a fixed
+    /// lower bound rather than randomizing the target.
+    ///
+    /// On success it returns the [`Drain`] to attach, whose value is the achieved change (at least
+    /// `change_lower`). Returns [`InsufficientFunds`] if the target plus `change_lower` can't be met
+    /// with the available candidates.
+    ///
+    /// `rng` shuffles the candidates; it yields uniform `u64`s, e.g. `|| my_rng.next_u64()`. Any
+    /// already-selected candidates are kept and counted toward the target.
+    ///
+    /// [`run_bnb`]: Self::run_bnb
+    /// [`LowestFee`]: crate::metrics::LowestFee
+    // TODO: honor a maximum selection weight (evicting the least valuable inputs when exceeded),
+    // matching Core's `max_selection_weight`. Deferred until the max-weight PR lands.
+    pub fn select_srd(
+        &mut self,
+        target: Target,
+        drain_weights: DrainWeights,
+        change_lower: u64,
+        mut rng: impl FnMut() -> u64,
+    ) -> Result<Drain, InsufficientFunds> {
+        // `excess` with the drain weights (and zero value) is exactly the change this selection could
+        // give, net of the change output's own fee — so meeting `change_lower` here means the change
+        // output will be at least `change_lower`.
+        let drain = Drain {
+            weights: drain_weights,
+            value: 0,
+        };
+
+        // Shuffle the unselected candidates (Fisher-Yates) and add them until we have enough change.
+        let mut candidates: Vec<usize> = self.unselected_indices().collect();
+        for i in (1..candidates.len()).rev() {
+            let j = (rng() % (i as u64 + 1)) as usize;
+            candidates.swap(i, j);
+        }
+        for index in candidates {
+            if self.excess(target, drain) >= change_lower as i64 {
+                break;
+            }
+            self.select(index);
+        }
+
+        let change = self.excess(target, drain);
+        if change >= change_lower as i64 {
+            Ok(Drain {
+                weights: drain_weights,
+                value: change as u64,
+            })
+        } else {
+            Err(InsufficientFunds {
+                missing: (change_lower as i64 - change).unsigned_abs(),
+            })
+        }
+    }
+
     /// Return an iterator that can be used to select candidates.
     pub fn select_iter(self) -> SelectIter<'a> {
         SelectIter { cs: self.clone() }

tests/srd.rs

@@ -0,0 +1,186 @@
+#![allow(clippy::zero_prefixed_literal)]
+mod common;
+
+use bdk_coin_select::{
+    Candidate, CoinSelector, Drain, DrainWeights, FeeRate, Target, TargetFee, TargetOutputs,
+    CHANGE_LOWER, TR_SPK_WEIGHT, TXOUT_BASE_WEIGHT,
+};
+
+/// Deterministic, dependency-free `u64` source (SplitMix64) so we can drive `select_srd` without a
+/// `rand` dependency.
+fn splitmix64(mut state: u64) -> impl FnMut() -> u64 {
+    move || {
+        state = state.wrapping_add(0x9E37_79B9_7F4A_7C15);
+        let mut z = state;
+        z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
+        z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
+        z ^ (z >> 31)
+    }
+}
+
+fn target(value: u64, feerate: f32) -> Target {
+    Target {
+        fee: TargetFee::from_feerate(FeeRate::from_sat_per_vb(feerate)),
+        outputs: TargetOutputs::fund_outputs([(TXOUT_BASE_WEIGHT + TR_SPK_WEIGHT, value)]),
+    }
+}
+
+/// Whenever SRD succeeds, the change must be at least `change_lower` and the selection must actually
+/// meet the target with that drain.
+#[test]
+fn srd_success_yields_healthy_change_that_meets_target() {
+    let candidates = common::gen_candidates(60);
+    let target = target(200_000, 10.0);
+    let drain_weights = DrainWeights::TR_KEYSPEND;
+
+    let mut successes = 0;
+    for seed in 0..300u64 {
+        let mut cs = CoinSelector::new(&candidates);
+        let result = cs.select_srd(
+            target,
+            drain_weights,
+            CHANGE_LOWER,
+            splitmix64(seed),
+        );
+
+        if let Ok(drain) = result {
+            successes += 1;
+            assert!(
+                drain.value >= CHANGE_LOWER,
+                "seed {}: change {} is below CHANGE_LOWER",
+                seed,
+                drain.value
+            );
+            assert_eq!(drain.weights, drain_weights);
+            assert!(
+                cs.is_target_met_with_drain(target, drain),
+                "seed {}: target not met with the returned drain",
+                seed
+            );
+            // The reported change equals the actual excess available to the drain.
+            let excess = cs.excess(
+                target,
+                Drain {
+                    weights: drain_weights,
+                    value: 0,
+                },
+            );
+            assert_eq!(drain.value as i64, excess);
+        }
+    }
+    assert!(successes > 0, "expected SRD to succeed for some seeds");
+}
+
+/// A custom `change_lower` is honored: the change is at least the requested amount.
+#[test]
+fn srd_respects_custom_change_lower() {
+    let candidates = common::gen_candidates(60);
+    let target = target(200_000, 5.0);
+    let drain_weights = DrainWeights::TR_KEYSPEND;
+    let change_lower = 123_456;
+
+    let mut cs = CoinSelector::new(&candidates);
+    let drain = cs
+        .select_srd(target, drain_weights, change_lower, splitmix64(7))
+        .expect("plenty of funds");
+    assert!(
+        drain.value >= change_lower,
+        "change {} below change_lower",
+        drain.value
+    );
+}
+
+/// SRD errors when the candidates can't cover target + change_lower.
+#[test]
+fn srd_insufficient_funds() {
+    // 3 * 50_000 = 150_000 total, well below target (200_000) + CHANGE_LOWER (50_000) + fees.
+    let candidates = vec![
+        Candidate {
+            value: 50_000,
+            weight: 100,
+            input_count: 1,
+            is_segwit: true,
+        },
+        Candidate {
+            value: 50_000,
+            weight: 100,
+            input_count: 1,
+            is_segwit: true,
+        },
+        Candidate {
+            value: 50_000,
+            weight: 100,
+            input_count: 1,
+            is_segwit: true,
+        },
+    ];
+    let target = target(200_000, 5.0);
+    let drain_weights = DrainWeights::TR_KEYSPEND;
+
+    for seed in 0..50u64 {
+        let mut cs = CoinSelector::new(&candidates);
+        let result = cs.select_srd(
+            target,
+            drain_weights,
+            CHANGE_LOWER,
+            splitmix64(seed),
+        );
+        assert!(result.is_err(), "seed {}: expected InsufficientFunds", seed);
+    }
+}
+
+/// The same seed produces the same selection and drain.
+#[test]
+fn srd_is_deterministic_for_a_given_seed() {
+    let candidates = common::gen_candidates(60);
+    let target = target(200_000, 8.0);
+    let drain_weights = DrainWeights::TR_KEYSPEND;
+
+    let mut cs_a = CoinSelector::new(&candidates);
+    let a = cs_a.select_srd(
+        target,
+        drain_weights,
+        CHANGE_LOWER,
+        splitmix64(99),
+    );
+    let mut cs_b = CoinSelector::new(&candidates);
+    let b = cs_b.select_srd(
+        target,
+        drain_weights,
+        CHANGE_LOWER,
+        splitmix64(99),
+    );
+
+    assert_eq!(a, b);
+    assert_eq!(cs_a.selected_indices(), cs_b.selected_indices());
+}
+
+/// Already-selected candidates are kept and counted toward the target.
+#[test]
+fn srd_keeps_preselected_inputs() {
+    let candidates = common::gen_candidates(60);
+    let target = target(200_000, 6.0);
+    let drain_weights = DrainWeights::TR_KEYSPEND;
+
+    let mut cs = CoinSelector::new(&candidates);
+    cs.select(0);
+    cs.select(1);
+    let preselected: Vec<usize> = cs.selected_indices().iter().collect();
+
+    let _ = cs
+        .select_srd(
+            target,
+            drain_weights,
+            CHANGE_LOWER,
+            splitmix64(3),
+        )
+        .expect("plenty of funds");
+
+    for i in preselected {
+        assert!(
+            cs.selected_indices().contains(i),
+            "preselected {} was dropped",
+            i
+        );
+    }
+}