docs: Improve documentation

Author: ValuedMammal

wallet/src/psbt/params.rs

@@ -58,6 +58,10 @@ impl Default for PsbtParams {
 
 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
+    /// transactions and are currently unspent.
     pub fn add_utxos(&mut self, outpoints: &[OutPoint]) -> &mut Self {
         self.utxos.extend(outpoints);
         self
@@ -145,6 +149,8 @@ impl PsbtParams {
     }
 }
 
+// TODO: Bring back `TxOrdering`
+
 /// `ReplaceParams` provides a thin wrapper around [`PsbtParams`] and is intended for
 /// crafting Replace-By-Fee transactions (RBF).
 #[derive(Debug, Default)]
@@ -165,8 +171,8 @@ impl ReplaceParams {
         .replace(txs)
     }
 
-    /// Replace spends of the provided `txs`. This will internally set the inner
-    /// params UTXOs to be spent.
+    /// Replace spends of the provided `txs`. This will internally set the internal list
+    /// of UTXOs to be spent.
     pub fn replace(self, txs: &[Arc<Transaction>]) -> Self {
         let txs: Vec<Arc<Transaction>> = txs.to_vec();
         let mut txids: HashSet<Txid> = txs.iter().map(|tx| tx.compute_txid()).collect();
@@ -277,9 +283,9 @@ mod test {
 
     #[test]
     fn test_sanitize_rbf_set() {
-        // To replace: { [A, B], [C] } (where B spends from A)
-        // We can't replace the inputs of B, since we're already replacing A
-        // therefore the inputs should only include the spends of [A, C].
+        // To replace the set { [A, B], [C] }, where B is a descendant of A:
+        // We shouldn't try to replace the inputs of B, because replacing A will render A's outputs
+        // unspendable. Therefore the RBF inputs should only contain the inputs of A and C.
 
         // A is an ancestor
         let tx_a = Transaction {

wallet/src/test_utils.rs

@@ -317,7 +317,7 @@ pub fn insert_checkpoint(wallet: &mut Wallet, block: BlockId) {
         .unwrap();
 }
 
-/// Inserts a transaction with anchor (no last seen). This is useful for adding
+/// Inserts a transaction to be anchored by `block_id` (no last seen). This can be used to add
 /// a coinbase tx to the wallet for testing.
 ///
 /// This will also insert the anchor `block_id`. See [`insert_anchor`] for more.

wallet/src/wallet/mod.rs

@@ -1210,7 +1210,13 @@ impl Wallet {
         self.transactions_with_params(CanonicalizationParams::default())
     }
 
-    /// Transactions with params.
+    /// Iterate over relevant and canonical transactions in this wallet.
+    ///
+    /// - `params`: [`CanonicalizationParams`], modifies the wallet's internal logic for determining
+    ///   which transaction is canonical. This can be used to resolve conflicts, or to assert that a
+    ///   particular transaction should be treated as canonical.
+    ///
+    /// See [`Wallet::transactions`] for more.
     pub fn transactions_with_params<'a>(
         &'a self,
         params: CanonicalizationParams,
@@ -2486,19 +2492,20 @@ impl Wallet {
         Ok(())
     }
 
-    /// Inserts a transaction into the inner transaction graph with no additional metadata.
+    /// Inserts a transaction into the inner transaction graph, scanning for relevant txouts.
     ///
     /// This is used to inform the wallet of newly created txs before they are known to exist
-    /// on chain (or in mempool), which is useful for discovering wallet-owned outputs of
-    /// not-yet-canonical transactions.
+    /// on chain or in mempool, which is useful for discovering wallet-owned outputs of
+    /// not-yet-canonical transactions. The inserted transaction carries no additional metadata,
+    /// like the time it was seen or the confirmation height. To later retrieve it, refer to
+    /// [`Wallet::transactions_with_params`].
     ///
     /// The effect of insertion depends on the [relevance] of `tx` as determined by the indexer.
     /// If the transaction was newly inserted and a txout matches a derived SPK, then the index
-    /// is updated with the relevant outpoint. This means the output may be selected in
-    /// subsequent transactions (if selected manually), enabling chains of dependent spends to
-    /// occur prior to broadcast time. If none of the outputs are relevant, the transaction is
-    /// kept but the index remains unchanged. If the transaction was already present in-graph,
-    /// the effect is a no-op.
+    /// is updated with the relevant outpoint(s). If no outputs are relevant, the transaction is
+    /// kept but the index remains unchanged. There should be no change to the wallet balance until
+    /// the transaction is accepted by the network and the wallet is synced. If `tx` was already
+    /// present in-graph, then the effect is a no-op.
     ///
     /// **You must persist the change set staged as a result of this call.**
     ///

wallet/tests/psbt.rs

@@ -136,6 +136,8 @@ fn test_create_psbt_cltv() {
     }
 }
 
+// Test that replacing two unconfirmed txs A, B results in a transaction
+// that spends the inputs of both A and B.
 #[test]
 fn test_replace_by_fee() {
     use KeychainKind::*;
@@ -219,7 +221,7 @@ fn test_replace_by_fee() {
         .unwrap()
         .0;
 
-    // Expect re-select inputs of A, B
+    // Expect replace inputs of A, B
     assert_eq!(
         psbt.unsigned_tx.input.len(),
         2,