docs: Improve docs for create_psbt and similar

Rename `*_with_aux_rand` methods to
`*_with_rng` instead.

Author: ValuedMammal

src/psbt/params.rs

@@ -1,4 +1,4 @@
-//! Parameters for PSBT building.
+//! Parameters for creating a PSBT.
 
 use alloc::sync::Arc;
 use alloc::vec::Vec;
@@ -78,8 +78,17 @@ impl PsbtParams {
     /// Add UTXOs by outpoint to fund the transaction.
     ///
     /// A single outpoint may appear at most once in the list of UTXOs to spend. The caller is
-    /// responsible for ensuring that elements of `outpoints` correspond to outputs of previous
+    /// responsible for ensuring that items of `outpoints` correspond to outputs of previous
     /// transactions and are currently unspent.
+    ///
+    /// If an outpoint doesn't correspond to an indexed script pubkey, a [`UnknownUtxo`]
+    /// will occur. See [`Wallet::create_psbt`] for more.
+    ///
+    /// To add a UTXO that did not originate from this wallet (i.e. a "foreign" UTXO), see
+    /// [`PsbtParams::add_planned_input`].
+    ///
+    /// [`UnknownUtxo`]: crate::wallet::error::CreatePsbtError::UnknownUtxo
+    /// [`Wallet::create_psbt`]: crate::Wallet::create_psbt
     pub fn add_utxos(&mut self, outpoints: &[OutPoint]) -> &mut Self {
         self.utxos
             .extend(outpoints.iter().copied().filter(|&op| self.set.insert(op)));
@@ -134,10 +143,10 @@ impl PsbtParams {
         self
     }
 
-    /// Add recipients.
+    /// Add outgoing recipients to the transaction.
     ///
-    /// - `recipients`: An iterator of `(S, Amount)` tuples where `S` can be a bitcoin [`Address`],
-    ///   a scriptPubKey, or anything that can be converted straight into a [`ScriptBuf`].
+    /// - `recipients`: An iterator of `(S, Amount)` tuples where `S` can be a [`bitcoin::Address`],
+    ///   a script pubkey, or anything that can be converted straight into a [`ScriptBuf`].
     pub fn add_recipients<I, S>(&mut self, recipients: I) -> &mut Self
     where
         I: IntoIterator<Item = (S, Amount)>,
@@ -201,7 +210,7 @@ impl PsbtParams {
     ///
     /// This merges all of the spends into a single transaction while retaining the parameters
     /// of `self`. Note however that any previously added UTXOs are removed. Call
-    /// [`replace_by_fee_with_aux_rand`](crate::Wallet::replace_by_fee_with_aux_rand) to finish
+    /// [`replace_by_fee_with_rng`](crate::Wallet::replace_by_fee_with_rng) to finish
     /// building the PSBT.
     ///
     /// ## Note
@@ -247,6 +256,35 @@ impl PsbtParams {
     /// Add a planned input.
     ///
     /// This can be used to add inputs that come with a [`Plan`] or [`psbt::Input`] provided.
+    /// See [`Input`] for more on how to create inputs manually. Be aware that creating inputs
+    /// in this manner relies on certain assumptions, like the UTXO validity, the satisfaction
+    /// weight, and so on. As such you should only use this method to add inputs you definitely
+    /// trust the values for.
+    ///
+    /// # Example
+    ///
+    /// ```rust,no_run
+    /// use bdk_tx::Input;
+    /// # use bdk_wallet::psbt::PsbtParams;
+    /// # use bitcoin::{psbt, OutPoint, Sequence, TxOut};
+    /// # let outpoint = OutPoint::null();
+    /// # let sequence = Sequence::ENABLE_LOCKTIME_NO_RBF;
+    /// # let psbt_input = psbt::Input::default();
+    /// # let satisfaction_weight = 0;
+    /// # let tx_status = None;
+    /// # let is_coinbase = false;
+    /// let mut params = PsbtParams::default();
+    /// let input = Input::from_psbt_input(
+    ///     outpoint,
+    ///     sequence,
+    ///     psbt_input,
+    ///     satisfaction_weight,
+    ///     tx_status,
+    ///     is_coinbase,
+    /// )?;
+    /// params.add_planned_input(input);
+    /// # Ok::<_, anyhow::Error>(())
+    /// ```
     ///
     /// [`Plan`]: miniscript::plan::Plan
     /// [`psbt::Input`]: bitcoin::psbt::Input
@@ -346,8 +384,8 @@ impl ReplaceParams {
         params
     }
 
-    /// Replace spends of the provided `txs`. This will internally set the internal list
-    /// of UTXOs to be spent.
+    /// Replace spends of the provided `txs`. This will internally set the list of UTXOs
+    /// to be spent.
     pub fn replace(&mut self, txs: &[Arc<Transaction>]) {
         self.inner.utxos.clear();
         let mut utxos = vec![];

src/wallet/error.rs

@@ -263,20 +263,20 @@ impl std::error::Error for BuildFeeBumpError {}
 pub enum CreatePsbtError {
     /// No Bnb solution.
     Bnb(bdk_coin_select::NoBnbSolution),
-    /// Non-sufficient funds
+    /// Non-sufficient funds.
     InsufficientFunds(bdk_coin_select::InsufficientFunds),
     /// In order to use the [`add_global_xpubs`] option, every extended key in the descriptor must
     /// either be a master key itself, having a depth of 0, or have an explicit origin provided.
     ///
     /// [`add_global_xpubs`]: crate::psbt::PsbtParams::add_global_xpubs
     MissingKeyOrigin(bitcoin::bip32::Xpub),
-    /// Failed to create a spend [`Plan`] for a manually selected output
+    /// Failed to create a spending plan for a manually selected output.
     Plan(OutPoint),
-    /// Failed to create PSBT
+    /// Failed to create PSBT.
     Psbt(bdk_tx::CreatePsbtError),
-    /// Selector error
+    /// Selector error.
     Selector(bdk_tx::SelectorError),
-    /// The UTXO of outpoint could not be found
+    /// The UTXO of outpoint could not be found.
     UnknownUtxo(OutPoint),
 }
 

src/wallet/mod.rs

@@ -2837,6 +2837,9 @@ impl Wallet {
     /// Creates a PSBT with the given `params` and returns the updated [`Psbt`] and
     /// [`Finalizer`].
     ///
+    /// This function uses the thread-local random number generator (RNG) to generate
+    /// randomness. To supply your own source of entropy see [`Wallet::create_psbt_with_rng`].
+    ///
     /// # Example
     ///
     /// ```rust,no_run
@@ -2857,21 +2860,31 @@ impl Wallet {
     /// let (psbt, finalizer) = wallet.create_psbt(params)?;
     /// # Ok::<_, anyhow::Error>(())
     /// ```
+    ///
+    /// # Errors
+    ///
+    /// A [`CreatePsbtError`] will be thrown if any of the following occurs
+    ///
+    /// - A manually selected input is missing from the wallet, or could not be planned
+    /// - The input value is insufficient to fund the outputs
+    /// - Failure to complete coin selection
+    /// - Failure to create or update the PSBT.
     #[cfg(feature = "std")]
     #[cfg_attr(docsrs, doc(cfg(feature = "std")))]
     pub fn create_psbt(&self, params: PsbtParams) -> Result<(Psbt, Finalizer), CreatePsbtError> {
-        self.create_psbt_with_aux_rand(params, &mut rand::thread_rng())
+        self.create_psbt_with_rng(params, &mut rand::thread_rng())
     }
 
-    /// Creates a PSBT with the given `params` and auxiliary randomness.
+    /// Creates a PSBT with the given `params` and random number generator (RNG).
     ///
-    /// ### Parameters:
+    /// Return the updated [`Psbt`] and [`Finalizer`].
     ///
-    /// - `params`: [`PsbtParams`]
-    /// - `rng`: Source of entropy, may be used during coin selection.
+    /// ## Parameters:
     ///
-    /// Returns the updated [`Psbt`] and [`Finalizer`].
-    pub fn create_psbt_with_aux_rand(
+    /// - `params`: [`PsbtParams`]
+    /// - `rng`: Source of entropy, may be used during coin selection and to sort inputs and outputs
+    ///   by the [`TxOrdering`](crate::wallet::tx_builder::TxOrdering).
+    pub fn create_psbt_with_rng(
         &self,
         params: PsbtParams,
         rng: &mut impl RngCore,
@@ -3020,7 +3033,7 @@ impl Wallet {
     /// [`Finalizer`].
     ///
     /// This is a convenience for getting a new [`ReplaceParams`], and updating the recipients
-    /// and feerate before calling [`replace_by_fee_with_aux_rand`]. If further configuration is
+    /// and feerate before calling [`Wallet::replace_by_fee_with_rng`]. If further configuration is
     /// desired, consider using [`PsbtParams::replace`] instead.
     ///
     /// # Example
@@ -3053,7 +3066,7 @@ impl Wallet {
         feerate: FeeRate,
         recipients: Vec<(ScriptBuf, Amount)>,
     ) -> Result<(Psbt, Finalizer), ReplaceByFeeError> {
-        self.replace_by_fee_with_aux_rand(
+        self.replace_by_fee_with_rng(
             ReplaceParams::new(
                 txs,
                 PsbtParams {
@@ -3069,25 +3082,35 @@ impl Wallet {
     /// Creates a Replace-By-Fee transaction (RBF) and returns the updated [`Psbt`] and
     /// [`Finalizer`].
     ///
-    /// ### Parameters:
+    /// This function uses the thread-local random number generator (RNG) to generate
+    /// randomness. To supply your own source of entropy see [`Wallet::replace_by_fee_with_rng`].
     ///
-    /// - `params`: [`ReplaceParams`]
+    /// # Errors
+    ///
+    /// A [`ReplaceByFeeError`] will be thrown if any of the following occurs
+    ///
+    /// - An original transaction is missing from the wallet
+    /// - Failure to calculate the [fee](Wallet::calculate_fee) of an original transaction
+    /// - Failure to complete coin selection
+    /// - Failure to create or update the PSBT.
     #[cfg(feature = "std")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "std")))]
     pub fn replace_by_fee(
         &self,
         params: ReplaceParams,
     ) -> Result<(Psbt, Finalizer), ReplaceByFeeError> {
-        self.replace_by_fee_with_aux_rand(params, &mut rand::thread_rng())
+        self.replace_by_fee_with_rng(params, &mut rand::thread_rng())
     }
 
     /// Creates a Replace-By-Fee transaction (RBF) and returns the updated [`Psbt`] and
     /// [`Finalizer`].
     ///
-    /// ### Parameters:
+    /// ## Parameters:
     ///
     /// - `params`: [`ReplaceParams`]
-    /// - `rng`: Source of entropy, may be used during coin selection.
-    pub fn replace_by_fee_with_aux_rand(
+    /// - `rng`: Source of entropy, may be used during coin selection and to sort inputs and outputs
+    ///   by the [`TxOrdering`](crate::wallet::tx_builder::TxOrdering).
+    pub fn replace_by_fee_with_rng(
         &self,
         params: ReplaceParams,
         rng: &mut impl RngCore,