docs: document TxBuilder default coin selection algorithm

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<SingleRandomDraw>;
 
 /// Wallet's UTXO set is not enough to cover recipient's requested plus fee.

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

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<P: CoinSelectionAlgorithm>(self, coin_selection: P) -> TxBuilder<'a, P> {
         TxBuilder {
             wallet: self.wallet,