diff --git a/src/wallet/coin_selection.rs b/src/wallet/coin_selection.rs index 7a096a45..27262dd3 100644 --- a/src/wallet/coin_selection.rs +++ b/src/wallet/coin_selection.rs @@ -16,7 +16,8 @@ //! //! You can specify a custom coin selection algorithm through the [`coin_selection`] method on //! [`TxBuilder`]. [`DefaultCoinSelectionAlgorithm`] aliases the coin selection algorithm that will -//! be used if it is not explicitly set. +//! be used if it is not explicitly set: [`BranchAndBoundCoinSelection`] with a +//! [`SingleRandomDraw`] fallback. //! //! [`TxBuilder`]: super::tx_builder::TxBuilder //! [`coin_selection`]: super::tx_builder::TxBuilder::coin_selection @@ -117,7 +118,16 @@ use rand_core::RngCore; use super::utils::shuffle_slice; /// Default coin selection algorithm used by [`TxBuilder`](super::tx_builder::TxBuilder) if not -/// overridden +/// overridden. +/// +/// This is [`BranchAndBoundCoinSelection`] with [`SingleRandomDraw`] as the fallback algorithm. +/// Branch and bound first attempts to find an input set that exactly covers the payment target +/// plus fees, avoiding a change output (which reduces fees and improves privacy). If no exact +/// match is found within the search limit, selection falls back to [`SingleRandomDraw`], which +/// pulls UTXOs at random until the target is met. +/// +/// The default assumes a P2WPKH change output size (31 bytes) when evaluating whether creating +/// change is economical. pub type DefaultCoinSelectionAlgorithm = BranchAndBoundCoinSelection; /// Wallet's UTXO set is not enough to cover recipient's requested plus fee. diff --git a/src/wallet/mod.rs b/src/wallet/mod.rs index 5bd42ba7..17e52095 100644 --- a/src/wallet/mod.rs +++ b/src/wallet/mod.rs @@ -1193,6 +1193,9 @@ impl Wallet { /// This returns a blank [`TxBuilder`] from which you can specify the parameters for the /// transaction. /// + /// Coin selection uses [`DefaultCoinSelectionAlgorithm`] unless overridden via + /// [`TxBuilder::coin_selection`]. See [`TxBuilder`] for details on the default behavior. + /// /// ## Example /// /// ``` @@ -1555,6 +1558,9 @@ impl Wallet { /// *replace by fee* (RBF). If the transaction can be fee bumped then it returns a [`TxBuilder`] /// pre-populated with the inputs and outputs of the original transaction. /// + /// Coin selection uses [`DefaultCoinSelectionAlgorithm`] unless overridden via + /// [`TxBuilder::coin_selection`]. See [`TxBuilder`] for details on the default behavior. + /// /// ## Example /// /// ```no_run diff --git a/src/wallet/tx_builder.rs b/src/wallet/tx_builder.rs index ec50be9a..903e20cc 100644 --- a/src/wallet/tx_builder.rs +++ b/src/wallet/tx_builder.rs @@ -99,12 +99,25 @@ use crate::{KeychainKind, LocalOutput, Utxo, WeightedUtxo}; /// # Ok::<(), anyhow::Error>(()) /// ``` /// +/// ## Default Coin Selection +/// +/// If [`coin_selection`] is not called, [`DefaultCoinSelectionAlgorithm`] is used, which +/// is [`BranchAndBoundCoinSelection`] with [`SingleRandomDraw`] as the fallback algorithm. +/// Branch and bound attempts to find an input set that avoids creating a change output; +/// if no such combination is found within the search limit, it falls back to +/// [`SingleRandomDraw`], which pulls UTXOs at random until the target is met. +/// +/// To override this, call [`coin_selection`] on the builder before calling [`finish`]. +/// /// At the moment [`coin_selection`] is an exception to the rule as it consumes `self`. /// This means it is usually best to call [`coin_selection`] on the return value of `build_tx` /// before assigning it. /// /// For further examples see [this module](super::tx_builder)'s documentation; /// +/// [`DefaultCoinSelectionAlgorithm`]: crate::wallet::coin_selection::DefaultCoinSelectionAlgorithm +/// [`BranchAndBoundCoinSelection`]: crate::wallet::coin_selection::BranchAndBoundCoinSelection +/// [`SingleRandomDraw`]: crate::wallet::coin_selection::SingleRandomDraw /// [`build_tx`]: Wallet::build_tx /// [`build_fee_bump`]: Wallet::build_fee_bump /// [`finish`]: Self::finish @@ -613,10 +626,17 @@ impl<'a, Cs> TxBuilder<'a, Cs> { /// Choose the coin selection algorithm /// - /// Overrides the [`CoinSelectionAlgorithm`]. + /// Overrides the default [`CoinSelectionAlgorithm`], which is + /// [`DefaultCoinSelectionAlgorithm`] (i.e. [`BranchAndBoundCoinSelection`] with a + /// [`SingleRandomDraw`] fallback). See the [`TxBuilder`] struct-level docs for details on + /// the default behavior. /// /// Note that this function consumes the builder and returns it so it is usually best to put /// this as the first call on the builder. + /// + /// [`DefaultCoinSelectionAlgorithm`]: crate::wallet::coin_selection::DefaultCoinSelectionAlgorithm + /// [`BranchAndBoundCoinSelection`]: crate::wallet::coin_selection::BranchAndBoundCoinSelection + /// [`SingleRandomDraw`]: crate::wallet::coin_selection::SingleRandomDraw pub fn coin_selection(self, coin_selection: P) -> TxBuilder<'a, P> { TxBuilder { wallet: self.wallet,