Merge #72: refactor(selection)!: encapsulate Selection and fail-fast on mixed-unit locktimes

96b9f88 test(selector): cover mixed absolute-locktime-unit rejection (志宇)
5a6f34c refactor!: move locktime-unit check from create_psbt to selector (志宇)
d158cbf feat(selection): add sort/shuffle methods for inputs and outputs (志宇)
4ce801d refactor(selection)!: make fields private, add InputMut handle (志宇)
d43e81a feat: Add `fisher_yates_shuffle` method and refactor workspace (志宇)

Pull request description:

  ### Description

  Detects mixed-unit absolute timelock requirements at `Selector::new` instead of at PSBT creation, and prevents external code from constructing or rearranging a `Selection` in ways that would bypass the check.

  Closes #58

  ### Changes

  1. **Fail-fast in the selector.** `Selector::new` now returns `SelectorError::LockTypeMismatch` when candidate inputs mix height-based and time-based absolute timelocks. The corresponding `CreatePsbtError::LockTypeMismatch` is removed and `Selection::create_psbt`'s internal locktime accumulator becomes infallible (with a `debug_assert!` guarding the upstream invariant).

  2. **Encapsulate `Selection`.** `Selection.inputs` / `Selection.outputs` are now private. Access is via `inputs()` / `outputs()`. Per-input mutation goes through a new `InputMut<'_>` handle (returned by `input_mut(outpoint)` / `inputs_mut()`) which derefs to `&Input` for reads and exposes only `set_sequence`, preventing whole-input replacement that would silently break coin-selection invariants.

  3. **Reorder methods.** Adds `sort_inputs_by`, `shuffle_inputs`, `sort_outputs_by`, `shuffle_outputs` on `Selection` so callers can apply BIP-69 or chain-analysis-resistant ordering without raw mutable slice access.

  ### Scope creep

  Bundled in this PR (let me know if you'd prefer these split out):

  - **Workspace refactor.** `src/utils.rs` is split into `src/afs.rs` (AFS types) and `src/no_std_rand.rs` (no-std rand helpers). `no_std_rand` is now crate-private since it has no external consumers.
  - **`fisher_yates_shuffle` helper.** Added to `no_std_rand` and used to back `Selection::shuffle_inputs` / `shuffle_outputs`.

  ### Changelog Notice

  ```md
  Added:
  - `SelectorError::LockTypeMismatch` — raised by `Selector::new` when candidate inputs mix height-based and time-based absolute timelocks.
  - `Selection::inputs` / `Selection::outputs` accessors (replacing the public fields).
  - `Selection::input_mut` / `Selection::inputs_mut` returning a new `InputMut<'_>` handle that only permits `set_sequence`.
  - `Selection::sort_inputs_by`, `Selection::shuffle_inputs`, `Selection::sort_outputs_by`, `Selection::shuffle_outputs` for reordering without exposing raw mutable access.

  Removed:
  - `CreatePsbtError::LockTypeMismatch` — superseded by `SelectorError::LockTypeMismatch`.

  Changed:
  - `Selection.inputs` and `Selection.outputs` are no longer public fields. External construction of `Selection` is no longer possible; obtain one from `Selector::try_finalize`.
  ```

  ### Checklist

  - [x] I followed the [contribution guidelines](https://github.com/bitcoindevkit/bdk/blob/master/CONTRIBUTING.md)
  - [x] I ran `cargo fmt` and `cargo clippy` before committing
  - [x] I've added tests for the new feature
  - [x] I've added docs for the new feature
  - [x] I'm linking the issue being fixed by this PR

ACKs for top commit:
  nymius:
    ACK 96b9f88
  noahjoeris:
    ACK 96b9f88

Tree-SHA512: 013e0da33f2960841c74d89faa05aa4819507bdebbd279549ce09daf380abacbb6f5ec5437a9aa1893e42c30e7832e41097e160c04676b2afedfff43e513c268

Author: evanlinjin

examples/anti_fee_sniping.rs

@@ -88,7 +88,7 @@ fn main() -> anyhow::Result<()> {
                 },
             )?;
 
-        let selection_inputs = selection.inputs.clone();
+        let selection_inputs = selection.inputs().to_vec();
 
         let psbt = selection.create_psbt(PsbtParams {
             anti_fee_sniping: Some(tip_height),

examples/synopsis.rs

@@ -150,7 +150,7 @@ fn main() -> anyhow::Result<()> {
         println!(
             "selected inputs: {:?}",
             selection
-                .inputs
+                .inputs()
                 .iter()
                 .map(|input| input.prev_outpoint())
                 .collect::<Vec<_>>()

src/utils.rs src/afs.rssrc/utils.rs renamed to src/afs.rs

@@ -1,4 +1,7 @@
-use crate::Input;
+use crate::{
+    no_std_rand::{random_probability, random_range},
+    Input,
+};
 use alloc::vec::Vec;
 use miniscript::bitcoin::{
     absolute::{self, LockTime},
@@ -157,20 +160,3 @@ pub(crate) fn apply_anti_fee_sniping(
 
     Ok(())
 }
-
-/// Returns true with probability 1/n.
-fn random_probability(rng: &mut impl RngCore, n: u32) -> bool {
-    random_range(rng, n) == 0
-}
-
-/// Returns a random value in the range [0, n) using unbiased rejection sampling.
-fn random_range(rng: &mut impl RngCore, n: u32) -> u32 {
-    let threshold = n.wrapping_neg() % n;
-
-    loop {
-        let value = rng.next_u32();
-        if value >= threshold {
-            return value % n;
-        }
-    }
-}

src/finalizer.rs

@@ -27,7 +27,7 @@ use miniscript::{bitcoin, plan::Plan, psbt::PsbtInputSatisfier};
 /// # use bdk_tx::PsbtParams;
 /// # let secp = bitcoin::secp256k1::Secp256k1::new();
 /// # let keymap = std::collections::BTreeMap::new();
-/// # let selection = bdk_tx::Selection { inputs: vec![], outputs: vec![] };
+/// # let selection: bdk_tx::Selection = unimplemented!();
 /// // Create PSBT from a selection of inputs and outputs.
 /// let mut psbt = selection.create_psbt(PsbtParams::default())?;
 ///
@@ -217,10 +217,7 @@ mod tests {
     fn test_finalize_single_input() -> anyhow::Result<()> {
         let (input, keymap) = create_input_from_descriptor_at(TR_XPRV, 0)?;
         let output = Output::with_script(ScriptBuf::new(), Amount::from_sat(9_000));
-        let selection = Selection {
-            inputs: vec![input],
-            outputs: vec![output],
-        };
+        let selection = Selection::new(vec![input], vec![output]);
 
         let mut psbt = selection.create_psbt(PsbtParams::default())?;
         let finalizer = selection.into_finalizer();
@@ -240,10 +237,7 @@ mod tests {
     fn test_finalize_sets_final_script_sig() -> anyhow::Result<()> {
         let (input, keymap) = create_input_from_descriptor_at(PKH_XPRV, 0)?;
         let output = Output::with_script(ScriptBuf::new(), Amount::from_sat(9_000));
-        let selection = Selection {
-            inputs: vec![input],
-            outputs: vec![output],
-        };
+        let selection = Selection::new(vec![input], vec![output]);
 
         let mut psbt = selection.create_psbt(PsbtParams::default())?;
         let finalizer = selection.into_finalizer();
@@ -266,13 +260,13 @@ mod tests {
         let taproot_output_descriptor = derive_descriptor_at(TR_XPRV, 10)?;
         let wpkh_output_descriptor = derive_descriptor_at(WPKH_XPRV, 11)?;
 
-        let selection = Selection {
-            inputs: vec![input_0, input_1, input_2],
-            outputs: vec![
+        let selection = Selection::new(
+            vec![input_0, input_1, input_2],
+            vec![
                 Output::with_descriptor(taproot_output_descriptor, Amount::from_sat(20_000)),
                 Output::with_descriptor(wpkh_output_descriptor, Amount::from_sat(22_000)),
             ],
-        };
+        );
 
         let mut psbt = selection.create_psbt(PsbtParams::default())?;
         let finalizer = selection.into_finalizer();
@@ -321,13 +315,13 @@ mod tests {
             input_0.plan().cloned().expect("plan must exist"),
         )]);
 
-        let selection = Selection {
-            inputs: vec![input_0, input_1],
-            outputs: vec![
+        let selection = Selection::new(
+            vec![input_0, input_1],
+            vec![
                 Output::with_descriptor(taproot_output_descriptor, Amount::from_sat(20_000)),
                 Output::with_descriptor(wpkh_output_descriptor, Amount::from_sat(22_000)),
             ],
-        };
+        );
 
         let mut psbt = selection.create_psbt(PsbtParams::default())?;
 
@@ -361,13 +355,13 @@ mod tests {
         let (input, _) = create_input_from_descriptor_at(TR_XPRV, 0)?;
         let taproot_output_descriptor = derive_descriptor_at(TR_XPRV, 10)?;
         let wpkh_output_descriptor = derive_descriptor_at(WPKH_XPRV, 11)?;
-        let selection = Selection {
-            inputs: vec![input],
-            outputs: vec![
+        let selection = Selection::new(
+            vec![input],
+            vec![
                 Output::with_descriptor(taproot_output_descriptor, Amount::from_sat(20_000)),
                 Output::with_descriptor(wpkh_output_descriptor, Amount::from_sat(22_000)),
             ],
-        };
+        );
 
         let mut psbt = selection.create_psbt(PsbtParams::default())?;
         let finalizer = selection.into_finalizer();
@@ -395,10 +389,7 @@ mod tests {
     fn test_already_finalized_input() -> anyhow::Result<()> {
         let (input, keymap) = create_input_from_descriptor_at(TR_XPRV, 0)?;
         let output = Output::with_script(ScriptBuf::new(), Amount::from_sat(9_000));
-        let selection = Selection {
-            inputs: vec![input],
-            outputs: vec![output],
-        };
+        let selection = Selection::new(vec![input], vec![output]);
 
         let mut psbt = selection.create_psbt(PsbtParams::default())?;
         let finalizer = selection.into_finalizer();

src/input.rs

@@ -665,6 +665,39 @@ impl Input {
     }
 }
 
+/// Mutable handle to an [`Input`] held inside a [`Selection`].
+///
+/// Returned by [`Selection::input_mut`] and [`Selection::inputs_mut`]. This wrapper restricts
+/// mutation to operations that preserve [`Selection`]'s coin-selection invariants.
+///
+/// Read-only access to the underlying [`Input`] is available via [`Deref`].
+///
+/// [`Selection`]: crate::Selection
+/// [`Selection::input_mut`]: crate::Selection::input_mut
+/// [`Selection::inputs_mut`]: crate::Selection::inputs_mut
+/// [`Deref`]: core::ops::Deref
+#[derive(Debug)]
+pub struct InputMut<'a>(&'a mut Input);
+
+impl<'a> InputMut<'a> {
+    pub(crate) fn new(input: &'a mut Input) -> Self {
+        Self(input)
+    }
+
+    /// See [`Input::set_sequence`].
+    pub fn set_sequence(&mut self, sequence: Sequence) -> Result<(), SetSequenceError> {
+        self.0.set_sequence(sequence)
+    }
+}
+
+impl core::ops::Deref for InputMut<'_> {
+    type Target = Input;
+
+    fn deref(&self) -> &Input {
+        self.0
+    }
+}
+
 /// Input group. Cannot be empty.
 #[derive(Debug, Clone)]
 pub struct InputGroup(Vec<Input>);

src/lib.rs

@@ -9,30 +9,32 @@ extern crate alloc;
 #[cfg(feature = "std")]
 extern crate std;
 
+mod afs;
 mod canonical_unspents;
 mod finalizer;
 mod input;
 mod input_candidates;
+mod no_std_rand;
 mod output;
 mod rbf;
 mod selection;
 mod selector;
 mod signer;
-mod utils;
 
+pub use afs::*;
 pub use canonical_unspents::*;
 pub use finalizer::*;
 pub use input::*;
 pub use input_candidates::*;
 pub use miniscript;
 pub use miniscript::bitcoin;
 use miniscript::{DefiniteDescriptorKey, Descriptor};
+use no_std_rand::*;
 pub use output::*;
 pub use rbf::*;
 pub use selection::*;
 pub use selector::*;
 pub use signer::*;
-pub use utils::*;
 
 #[cfg(feature = "std")]
 pub(crate) mod collections {

src/no_std_rand.rs

@@ -0,0 +1,44 @@
+use rand_core::RngCore;
+
+/// Returns true with probability 1/n.
+pub(crate) fn random_probability(rng: &mut impl RngCore, n: u32) -> bool {
+    random_range(rng, n) == 0
+}
+
+/// Returns a random value in the range [0, n) using unbiased rejection sampling.
+pub(crate) fn random_range(rng: &mut impl RngCore, n: u32) -> u32 {
+    let threshold = n.wrapping_neg() % n;
+
+    loop {
+        let value = rng.next_u32();
+        if value >= threshold {
+            return value % n;
+        }
+    }
+}
+
+/// Fisher-Yates in-place shuffle using unbiased rejection sampling.
+pub(crate) fn fisher_yates_shuffle<T>(slice: &mut [T], rng: &mut impl RngCore) {
+    for i in (1..slice.len()).rev() {
+        // Unbiased index in [0, i+1) via rejection sampling.
+        let j = random_range(rng, (i + 1) as u32) as usize;
+        slice.swap(i, j);
+    }
+}
+
+#[cfg_attr(coverage_nightly, coverage(off))]
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use alloc::vec::Vec;
+    use rand_core::OsRng;
+
+    #[test]
+    fn test_fisher_yates_shuffle_preserves_multiset() {
+        let original: Vec<u32> = (0..32).collect();
+        let mut shuffled = original.clone();
+        fisher_yates_shuffle(&mut shuffled, &mut OsRng);
+        shuffled.sort();
+        assert_eq!(shuffled, original);
+    }
+}