refactor!: collapse Selection into TxTemplate

Selection was a redundant intermediate: the Selection -> TxTemplate
transition was total (could not fail, was pure), so the type boundary
only existed to be crossed. Removing it shortens the pipeline:

  selector.try_finalize()?
      .apply_anti_fee_sniping(tip, &mut rng)?
      .create_psbt(PsbtBuildParams::default())?

TxTemplateParams disappears with it. Its two fields become methods on
the template itself, parallel to the existing set_locktime:

  TxTemplateParams::min_version       -> TxTemplate::set_version(v)?
  TxTemplateParams::fallback_sequence -> TxTemplate::set_fallback_sequence(s)

New TxTemplate::set_version validates against BIP-68
(SetVersionError::RelativeTimelockRequiresV2 if v < 2 and any input
has a relative timelock); set_fallback_sequence is infallible. Setters
keep the validation discoverable from the type without forcing every
caller to pass params.

API renames:
  Selector::try_finalize()        -> Option<TxTemplate>  (was Selection)
  InputCandidates::into_selection -> into_tx_template
  IntoSelectionError              -> IntoTxTemplateError

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

Author: evanlinjin

examples/anti_fee_sniping.rs

@@ -2,7 +2,7 @@
 use bdk_testenv::{bitcoincore_rpc::RpcApi, TestEnv};
 use bdk_tx::{
     filter_unspendable, group_by_spk, selection_algorithm_lowest_fee_bnb, Output, PsbtBuildParams,
-    SelectorParams, TxTemplateParams,
+    SelectorParams,
 };
 use bitcoin::{absolute::LockTime, key::Secp256k1, Amount, FeeRate};
 use miniscript::Descriptor;
@@ -72,7 +72,7 @@ fn main() -> anyhow::Result<()> {
             .all_candidates()
             .regroup(group_by_spk())
             .filter(filter_unspendable(tip_height, Some(tip_time)))
-            .into_selection(
+            .into_tx_template(
                 selection_algorithm_lowest_fee_bnb(longterm_feerate, 100_000),
                 SelectorParams {
                     // For waste optimization when deciding change.
@@ -91,7 +91,6 @@ fn main() -> anyhow::Result<()> {
         let selection_inputs = selection.inputs().to_vec();
 
         let (psbt, _) = selection
-            .into_tx_template(TxTemplateParams::default())
             .apply_anti_fee_sniping(tip_height, &mut rand::thread_rng())?
             .create_psbt(PsbtBuildParams::default())?;
 

examples/synopsis.rs

@@ -1,7 +1,7 @@
 use bdk_testenv::{bitcoincore_rpc::RpcApi, TestEnv};
 use bdk_tx::{
     filter_unspendable, group_by_spk, selection_algorithm_lowest_fee_bnb, Output, PsbtBuildParams,
-    SelectorParams, Signer, TxTemplateParams,
+    SelectorParams, Signer,
 };
 use bitcoin::{key::Secp256k1, Amount, FeeRate};
 use miniscript::Descriptor;
@@ -52,7 +52,7 @@ fn main() -> anyhow::Result<()> {
         .all_candidates()
         .regroup(group_by_spk())
         .filter(filter_unspendable(tip_height, Some(tip_mtp)))
-        .into_selection(
+        .into_tx_template(
             selection_algorithm_lowest_fee_bnb(longterm_feerate, 100_000),
             SelectorParams {
                 // For waste-optimization when deciding change.
@@ -67,7 +67,6 @@ fn main() -> anyhow::Result<()> {
                 )
             },
         )?
-        .into_tx_template(TxTemplateParams::default())
         .create_psbt(PsbtBuildParams::default())?;
 
     let _ = psbt.sign(&signer, &secp);
@@ -121,7 +120,7 @@ fn main() -> anyhow::Result<()> {
 
         let selection = rbf_candidates
             // Do coin selection.
-            .into_selection(
+            .into_tx_template(
                 // Coin selection algorithm.
                 selection_algorithm_lowest_fee_bnb(longterm_feerate, 100_000),
                 SelectorParams {
@@ -154,9 +153,7 @@ fn main() -> anyhow::Result<()> {
                 .collect::<Vec<_>>()
         );
 
-        let (mut psbt, finalizer) = selection
-            .into_tx_template(TxTemplateParams::default())
-            .create_psbt(PsbtBuildParams::default())?;
+        let (mut psbt, finalizer) = selection.create_psbt(PsbtBuildParams::default())?;
         psbt.sign(&signer, &secp).expect("failed to sign");
         assert!(
             finalizer.finalize(&mut psbt).is_finalized(),

src/finalizer.rs

@@ -23,13 +23,11 @@ use miniscript::{bitcoin, plan::Plan, psbt::PsbtInputSatisfier};
 /// # Example
 ///
 /// ```rust,no_run
-/// # use bdk_tx::{PsbtBuildParams, TxTemplateParams};
+/// # use bdk_tx::PsbtBuildParams;
 /// # let secp = bitcoin::secp256k1::Secp256k1::new();
 /// # let keymap = std::collections::BTreeMap::new();
-/// # let selection: bdk_tx::Selection = unimplemented!();
-/// let (mut psbt, finalizer) = selection
-///     .into_tx_template(TxTemplateParams::default())
-///     .create_psbt(PsbtBuildParams::default())?;
+/// # let template: bdk_tx::TxTemplate = unimplemented!();
+/// let (mut psbt, finalizer) = template.create_psbt(PsbtBuildParams::default())?;
 ///
 /// // Sign the PSBT using your preferred method.
 /// let signer = bdk_tx::Signer(keymap);
@@ -164,7 +162,7 @@ impl FinalizeMap {
 #[cfg_attr(coverage_nightly, coverage(off))]
 #[cfg(test)]
 mod tests {
-    use crate::{Finalizer, Output, PsbtBuildParams, Selection, Signer, TxTemplateParams};
+    use crate::{Finalizer, Output, PsbtBuildParams, Signer, TxTemplate};
     use bitcoin::secp256k1::Secp256k1;
     use bitcoin::{absolute, transaction, Amount, ScriptBuf, TxIn, TxOut};
     use miniscript::bitcoin;
@@ -216,11 +214,9 @@ 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::new(vec![input], vec![output]);
+        let selection = TxTemplate::from_parts(vec![input], vec![output]);
 
-        let (mut psbt, finalizer) = selection
-            .into_tx_template(TxTemplateParams::default())
-            .create_psbt(PsbtBuildParams::default())?;
+        let (mut psbt, finalizer) = selection.create_psbt(PsbtBuildParams::default())?;
 
         let secp = Secp256k1::new();
         let signer = Signer(keymap);
@@ -237,11 +233,9 @@ 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::new(vec![input], vec![output]);
+        let selection = TxTemplate::from_parts(vec![input], vec![output]);
 
-        let (mut psbt, finalizer) = selection
-            .into_tx_template(TxTemplateParams::default())
-            .create_psbt(PsbtBuildParams::default())?;
+        let (mut psbt, finalizer) = selection.create_psbt(PsbtBuildParams::default())?;
 
         let secp = Secp256k1::new();
         let signer = Signer(keymap);
@@ -261,17 +255,15 @@ 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::new(
+        let selection = TxTemplate::from_parts(
             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, finalizer) = selection
-            .into_tx_template(TxTemplateParams::default())
-            .create_psbt(PsbtBuildParams::default())?;
+        let (mut psbt, finalizer) = selection.create_psbt(PsbtBuildParams::default())?;
 
         assert!(!psbt.outputs[0].tap_key_origins.is_empty());
         assert!(psbt.outputs[0].tap_internal_key.is_some());
@@ -317,17 +309,15 @@ mod tests {
             input_0.plan().cloned().expect("plan must exist"),
         )]);
 
-        let selection = Selection::new(
+        let selection = TxTemplate::from_parts(
             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
-            .into_tx_template(TxTemplateParams::default())
-            .create_psbt(PsbtBuildParams::default())?;
+        let (mut psbt, _) = selection.create_psbt(PsbtBuildParams::default())?;
 
         let tap_key_origins = psbt.outputs[0].tap_key_origins.clone();
         let tap_internal_key = psbt.outputs[0].tap_internal_key;
@@ -359,17 +349,15 @@ 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::new(
+        let selection = TxTemplate::from_parts(
             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, finalizer) = selection
-            .into_tx_template(TxTemplateParams::default())
-            .create_psbt(PsbtBuildParams::default())?;
+        let (mut psbt, finalizer) = selection.create_psbt(PsbtBuildParams::default())?;
 
         let tap_key_origins = psbt.outputs[0].tap_key_origins.clone();
         let tap_internal_key = psbt.outputs[0].tap_internal_key;
@@ -394,11 +382,9 @@ 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::new(vec![input], vec![output]);
+        let selection = TxTemplate::from_parts(vec![input], vec![output]);
 
-        let (mut psbt, finalizer) = selection
-            .into_tx_template(TxTemplateParams::default())
-            .create_psbt(PsbtBuildParams::default())?;
+        let (mut psbt, finalizer) = selection.create_psbt(PsbtBuildParams::default())?;
 
         let secp = Secp256k1::new();
         let signer = Signer(keymap);

src/input_candidates.rs

@@ -7,8 +7,8 @@ use miniscript::bitcoin;
 
 use crate::collections::{BTreeMap, HashSet};
 use crate::{
-    CannotMeetTarget, FeeRateExt, Input, InputGroup, Selection, Selector, SelectorError,
-    SelectorParams,
+    CannotMeetTarget, FeeRateExt, Input, InputGroup, Selector, SelectorError, SelectorParams,
+    TxTemplate,
 };
 
 /// Input candidates.
@@ -191,30 +191,28 @@ impl InputCandidates {
         self
     }
 
-    /// Attempt to convert the input candidates into a valid [`Selection`] with a given
-    /// `algorithm` and selector `params`.
-    pub fn into_selection<A, E>(
+    /// Run coin selection with `algorithm` and selector `params`, returning a [`TxTemplate`].
+    pub fn into_tx_template<A, E>(
         self,
         algorithm: A,
         params: SelectorParams,
-    ) -> Result<Selection, IntoSelectionError<E>>
+    ) -> Result<TxTemplate, IntoTxTemplateError<E>>
     where
         A: FnMut(&mut Selector) -> Result<(), E>,
     {
-        let mut selector = Selector::new(&self, params).map_err(IntoSelectionError::Selector)?;
+        let mut selector = Selector::new(&self, params).map_err(IntoTxTemplateError::Selector)?;
         selector
             .select_with_algorithm(algorithm)
-            .map_err(IntoSelectionError::SelectionAlgorithm)?;
-        let selection = selector
+            .map_err(IntoTxTemplateError::SelectionAlgorithm)?;
+        selector
             .try_finalize()
-            .ok_or(IntoSelectionError::CannotMeetTarget(CannotMeetTarget))?;
-        Ok(selection)
+            .ok_or(IntoTxTemplateError::CannotMeetTarget(CannotMeetTarget))
     }
 }
 
 /// Occurs when we cannot find a solution for selection.
 #[derive(Debug)]
-pub enum IntoSelectionError<E> {
+pub enum IntoTxTemplateError<E> {
     /// Coin selector returned an error
     Selector(SelectorError),
     /// Selection algorithm failed.
@@ -223,22 +221,22 @@ pub enum IntoSelectionError<E> {
     CannotMeetTarget(CannotMeetTarget),
 }
 
-impl<E: fmt::Display> fmt::Display for IntoSelectionError<E> {
+impl<E: fmt::Display> fmt::Display for IntoTxTemplateError<E> {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
-            IntoSelectionError::Selector(error) => {
+            IntoTxTemplateError::Selector(error) => {
                 write!(f, "{error}")
             }
-            IntoSelectionError::SelectionAlgorithm(error) => {
+            IntoTxTemplateError::SelectionAlgorithm(error) => {
                 write!(f, "selection algorithm failed: {error}")
             }
-            IntoSelectionError::CannotMeetTarget(error) => write!(f, "{error}"),
+            IntoTxTemplateError::CannotMeetTarget(error) => write!(f, "{error}"),
         }
     }
 }
 
 #[cfg(feature = "std")]
-impl<E: fmt::Debug + fmt::Display> std::error::Error for IntoSelectionError<E> {}
+impl<E: fmt::Debug + fmt::Display> std::error::Error for IntoTxTemplateError<E> {}
 
 /// Select for lowest fee with bnb
 pub fn selection_algorithm_lowest_fee_bnb(

src/lib.rs

@@ -17,7 +17,6 @@ mod input_candidates;
 mod no_std_rand;
 mod output;
 mod rbf;
-mod selection;
 mod selector;
 mod signer;
 mod tx_template;
@@ -33,7 +32,6 @@ 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 tx_template::*;

src/selection.rs

@@ -4,7 +4,7 @@ use miniscript::bitcoin;
 
 use crate::{
     DefiniteDescriptor, FeeRateExt, Input, InputCandidates, InputGroup, Output, ScriptSource,
-    Selection,
+    TxTemplate,
 };
 use alloc::boxed::Box;
 use alloc::vec::Vec;
@@ -483,10 +483,10 @@ impl<'c> Selector<'c> {
         Some(has_drain)
     }
 
-    /// Try get final selection.
+    /// Try to finalize the selection into a [`TxTemplate`].
     ///
-    /// Return `None` if target is not met yet.
-    pub fn try_finalize(&self) -> Option<Selection> {
+    /// Returns `None` if the target is not yet met.
+    pub fn try_finalize(&self) -> Option<TxTemplate> {
         if !self.inner.is_target_met(self.target) {
             return None;
         }
@@ -506,7 +506,7 @@ impl<'c> Selector<'c> {
                 Amount::from_sat(maybe_change.value),
             )));
         }
-        Some(Selection::new(inputs, outputs))
+        Some(TxTemplate::from_parts(inputs, outputs))
     }
 }