refactor(wallet): improve wallet event docs and extract helper method

- Enhanced WalletEvent documentation with clearer explanations
- Expanded apply_update() docs with examples and persistence warnings
- Extracted collect_wallet_txs() to reduce code duplication
- Fixed minor typos and improved code clarity

🤖 LLM-assisted changes

Author: notmandatory

src/wallet/event.rs

@@ -8,76 +8,82 @@ use alloc::vec::Vec;
 use bitcoin::{Transaction, Txid};
 use chain::{BlockId, ChainPosition, ConfirmationBlockTime};
 
-/// Events representing changes to wallet transactions.
+/// Events representing changes to the wallet state.
 ///
-/// Returned after calling
-/// [`Wallet::apply_update_events`](crate::wallet::Wallet::apply_update_events).
+/// Returned by [`Wallet::apply_update`], [`Wallet::apply_block`], and
+/// [`Wallet::apply_block_connected_to`] to track transaction status changes and chain
+/// tip changes due to new blocks or reorganizations.
 #[derive(Debug, Clone, PartialEq, Eq)]
 #[non_exhaustive]
 pub enum WalletEvent {
-    /// The latest chain tip known to the wallet changed.
+    /// The blockchain tip known to the wallet has changed.
+    ///
+    /// Emitted when the blockchain is extended or a chain reorganization occurs.
     ChainTipChanged {
-        /// Previous chain tip.
+        /// The previous blockchain tip.
         old_tip: BlockId,
-        /// New chain tip.
+        /// The new blockchain tip.
         new_tip: BlockId,
     },
-    /// A transaction is now confirmed.
-    ///
-    /// If the transaction was previously unconfirmed `old_block_time` will be `None`.
+
+    /// A transaction has been confirmed in a block.
     ///
-    /// If a confirmed transaction is now re-confirmed in a new block `old_block_time` will contain
-    /// the block id and the time it was previously confirmed. This can happen after a chain
-    /// reorg.
+    /// Emitted when a transaction is first confirmed or re-confirmed in a different block after
+    /// a chain reorganization. When `old_block_time` is `Some`, the transaction was previously
+    /// confirmed in a different block.
     TxConfirmed {
-        /// Transaction id.
+        /// The transaction id.
         txid: Txid,
-        /// Transaction.
+        /// The full transaction.
         tx: Arc<Transaction>,
-        /// Confirmation block time.
+        /// The block and timestamp where the transaction is confirmed.
         block_time: ConfirmationBlockTime,
-        /// Old confirmation block and time if previously confirmed in a different block.
+        /// Previous confirmation details if re-confirmed after a reorg, `None` for first
+        /// confirmation.
         old_block_time: Option<ConfirmationBlockTime>,
     },
-    /// A transaction is now unconfirmed.
-    ///
-    /// If the transaction is first seen in the mempool `old_block_time` will be `None`.
+
+    /// A transaction is now unconfirmed (in the mempool).
     ///
-    /// If a previously confirmed transaction is now seen in the mempool `old_block_time` will
-    /// contain the block id and the time it was previously confirmed. This can happen after a
-    /// chain reorg.
+    /// Emitted when a transaction first appears in the mempool or when a confirmed transaction
+    /// becomes unconfirmed due to a chain reorganization. When `old_block_time` is `Some`, the
+    /// transaction was previously confirmed but is now unconfirmed due to a reorg.
     TxUnconfirmed {
-        /// Transaction id.
+        /// The transaction id.
         txid: Txid,
-        /// Transaction.
+        /// The full transaction.
         tx: Arc<Transaction>,
-        /// Old confirmation block and time, if previously confirmed.
+        /// Previous confirmation details if unconfirmed due to reorg, `None` if first seen.
         old_block_time: Option<ConfirmationBlockTime>,
     },
-    /// An unconfirmed transaction was replaced.
+
+    /// One or more unconfirmed transactions were replaced.
     ///
-    /// This can happen after an RBF is broadcast or if a third party double spends an input of
-    /// a received payment transaction before it is confirmed.
+    /// Occurs when a transaction's inputs are spent by the replacement transaction, typically due
+    /// to Replace-By-Fee (RBF) or a double-spend attempt.
     ///
-    /// The 'conflicts' field contains the txid and vin (in which it conflicts) of the conflicting
-    /// transactions.
+    /// The `conflicts` field contains `(input_index, conflicting_txid)` pairs indicating which
+    /// inputs conflict. Only conflicting transactions known to the wallet are reported.
+    /// Conflicting transactions are usually added during a sync because they spend a UTXO tracked
+    /// by the wallet.
     TxReplaced {
-        /// Transaction id.
+        /// The replacement transaction id.
         txid: Txid,
-        /// Transaction.
+        /// The full replacement transaction.
         tx: Arc<Transaction>,
-        /// Conflicting transaction ids.
+        /// List of `(input_index, conflicting_txid)` pairs showing which inputs were double-spent.
         conflicts: Vec<(usize, Txid)>,
     },
-    /// Unconfirmed transaction dropped.
+
+    /// An unconfirmed transaction was dropped from the mempool.
     ///
-    /// The transaction was dropped from the local mempool. This is generally due to the fee rate
-    /// being too low. The transaction can still reappear in the mempool in the future resulting in
-    /// a [`WalletEvent::TxUnconfirmed`] event.
+    /// This typically occurs when a transaction's fee rate is too low and/or the mempool is full.
+    /// The transaction may reappear later if conditions change, which will emit a
+    /// [`WalletEvent::TxUnconfirmed`] event.
     TxDropped {
-        /// Transaction id.
+        /// The dropped transaction id.
         txid: Txid,
-        /// Transaction.
+        /// The full dropped transaction.
         tx: Arc<Transaction>,
     },
 }

src/wallet/mod.rs

@@ -2341,101 +2341,121 @@ impl Wallet {
             .to_string()
     }
 
-    /// Applies an update to the wallet, stages the changes, and returns events.
+    /// Applies an update to the wallet, stages changes, and returns events describing what changed.
     ///
-    /// Usually you create an `update` by interacting with some blockchain data source and inserting
-    /// transactions related to your wallet into it. Staged changes are NOT persisted.
+    /// This is the primary method for updating wallet state with new blockchain data. It accepts
+    /// an [`Update`]
     ///
-    /// After applying updates, you should process the events in your app before persisting the
-    /// staged wallet changes. For an example of how to persist staged wallet changes, see
-    /// [`Wallet::reveal_next_address`].
+    /// **IMPORTANT**: Changes are staged but **NOT automatically persisted**. You must:
+    ///
+    /// 1. Process the returned events in your application
+    /// 2. Call [`take_staged`] to retrieve the [`ChangeSet`]
+    /// 3. Persist the changeset to your database/storage
+    ///
+    /// Failing to persist changes means they will be lost when the wallet is reloaded.
+    ///
+    /// # Example
+    ///
+    /// ## Basic usage with event handling
     ///
     /// ```rust,no_run
     /// # use bitcoin::*;
     /// # use bdk_wallet::*;
     /// use bdk_wallet::event::WalletEvent;
     /// # let wallet_update = Update::default();
     /// # let mut wallet = doctest_wallet!();
+    ///
+    /// // Apply the update and get events
     /// let events = wallet.apply_update(wallet_update)?;
-    /// // Handle wallet relevant events from this update.
-    /// events.iter().for_each(|event| {
+    ///
+    /// // Handle each event
+    /// for event in events {
     ///     match event {
-    ///         // The chain tip changed.
     ///         WalletEvent::ChainTipChanged { old_tip, new_tip } => {
-    ///             todo!() // handle event
+    ///             println!(
+    ///                 "Chain advanced from {} to {}",
+    ///                 old_tip.height, new_tip.height
+    ///             );
     ///         }
-    ///         // An unconfirmed tx is now confirmed in a block.
     ///         WalletEvent::TxConfirmed {
     ///             txid,
-    ///             tx,
     ///             block_time,
     ///             old_block_time: None,
+    ///             ..
     ///         } => {
-    ///             todo!() // handle event
+    ///             println!(
+    ///                 "Transaction {} confirmed at height {}",
+    ///                 txid, block_time.block_id.height
+    ///             );
     ///         }
-    ///         // A confirmed tx is now confirmed in a new block (reorg).
     ///         WalletEvent::TxConfirmed {
     ///             txid,
-    ///             tx,
     ///             block_time,
-    ///             old_block_time: Some(old_block_time),
+    ///             old_block_time: Some(old),
+    ///             ..
     ///         } => {
-    ///             todo!() // handle event
+    ///             println!(
+    ///                 "Transaction {} re-confirmed due to reorg: {} -> {}",
+    ///                 txid, old.block_id.height, block_time.block_id.height
+    ///             );
     ///         }
-    ///         // A new unconfirmed tx was seen in the mempool.
     ///         WalletEvent::TxUnconfirmed {
     ///             txid,
-    ///             tx,
     ///             old_block_time: None,
+    ///             ..
     ///         } => {
-    ///             todo!() // handle event
+    ///             println!("New mempool transaction: {}", txid);
     ///         }
-    ///         // A previously confirmed tx in now unconfirmed in the mempool (reorg).
     ///         WalletEvent::TxUnconfirmed {
     ///             txid,
-    ///             tx,
-    ///             old_block_time: Some(old_block_time),
+    ///             old_block_time: Some(old),
+    ///             ..
     ///         } => {
-    ///             todo!() // handle event
+    ///             println!(
+    ///                 "Transaction {} unconfirmed due to reorg from height {}",
+    ///                 txid, old.block_id.height
+    ///             );
     ///         }
-    ///         // An unconfirmed tx was replaced in the mempool (RBF or double spent input).
     ///         WalletEvent::TxReplaced {
-    ///             txid,
-    ///             tx,
-    ///             conflicts,
+    ///             txid, conflicts, ..
     ///         } => {
-    ///             todo!() // handle event
+    ///             println!("Transaction {} replaced: {:?}", txid, conflicts);
     ///         }
-    ///         // An unconfirmed tx was dropped from the mempool (fee too low).
-    ///         WalletEvent::TxDropped { txid, tx } => {
-    ///             todo!() // handle event
+    ///         WalletEvent::TxDropped { txid, .. } => {
+    ///             println!("Transaction {} dropped from mempool", txid);
     ///         }
     ///         _ => {
-    ///             // unexpected event, do nothing
+    ///             debug_assert!(false, "unexpected event")
     ///         }
     ///     }
-    ///     // take staged wallet changes
-    ///     let staged = wallet.take_staged();
-    ///     // persist staged changes
-    /// });
+    /// }
+    ///
+    /// // IMPORTANT: Persist the changes
+    /// if let Some(changeset) = wallet.take_staged() {
+    ///     // Save changeset to your database
+    ///     // e.g., db.persist(&changeset)?;
+    /// }
     /// # Ok::<(), anyhow::Error>(())
     /// ```
-    /// [`TxBuilder`]: crate::TxBuilder
+    ///
+    /// # See Also
+    ///
+    /// - [`apply_block`] - Apply a single block to the wallet
+    /// - [`apply_block_connected_to`] - Apply a block with explicit connection point
+    /// - [`take_staged`] - Retrieve staged changes for persistence
+    /// - [`WalletEvent`] - Documentation for all event types
+    /// - [`Update`] - The update structure accepted by this method
+    ///
+    /// [`apply_block`]: Wallet::apply_block
+    /// [`apply_block_connected_to`]: Wallet::apply_block_connected_to
+    /// [`take_staged`]: Wallet::take_staged
     pub fn apply_update(
         &mut self,
         update: impl Into<Update>,
     ) -> Result<Vec<WalletEvent>, CannotConnectError> {
         // snapshot of chain tip and transactions before update
         let chain_tip1 = self.chain.tip().block_id();
-        let wallet_txs1 = self
-            .transactions()
-            .map(|wtx| {
-                (
-                    wtx.tx_node.txid,
-                    (wtx.tx_node.tx.clone(), wtx.chain_position),
-                )
-            })
-            .collect::<BTreeMap<Txid, (Arc<Transaction>, ChainPosition<ConfirmationBlockTime>)>>();
+        let wallet_txs1 = self.collect_wallet_txs();
 
         // apply update
         let update = update.into();
@@ -2454,15 +2474,7 @@ impl Wallet {
 
         // chain tip and transactions after update
         let chain_tip2 = self.chain.tip().block_id();
-        let wallet_txs2 = self
-            .transactions()
-            .map(|wtx| {
-                (
-                    wtx.tx_node.txid,
-                    (wtx.tx_node.tx.clone(), wtx.chain_position),
-                )
-            })
-            .collect::<BTreeMap<Txid, (Arc<Transaction>, ChainPosition<ConfirmationBlockTime>)>>();
+        let wallet_txs2 = self.collect_wallet_txs();
 
         Ok(wallet_events(
             self,
@@ -2557,7 +2569,9 @@ impl Wallet {
     /// if you need the inserted block data to be reloaded after closing the wallet.
     /// See [`Wallet::reveal_next_address`].
     ///
-    /// See [`apply_update_events`] for more information on the returned [`WalletEvent`]s.
+    /// See [`apply_update`] for more information on the returned [`WalletEvent`]s.
+    ///
+    /// [`apply_update`]: Wallet::apply_update
     pub fn apply_block_connected_to(
         &mut self,
         block: &Block,
@@ -2566,15 +2580,7 @@ impl Wallet {
     ) -> Result<Vec<WalletEvent>, ApplyHeaderError> {
         // snapshot of chain tip and transactions before update
         let chain_tip1 = self.chain.tip().block_id();
-        let wallet_txs1 = self
-            .transactions()
-            .map(|wtx| {
-                (
-                    wtx.tx_node.txid,
-                    (wtx.tx_node.tx.clone(), wtx.chain_position),
-                )
-            })
-            .collect::<BTreeMap<Txid, (Arc<Transaction>, ChainPosition<ConfirmationBlockTime>)>>();
+        let wallet_txs1 = self.collect_wallet_txs();
 
         // apply block to wallet
         let mut changeset = ChangeSet::default();
@@ -2592,15 +2598,7 @@ impl Wallet {
 
         // chain tip and transactions after update
         let chain_tip2 = self.chain.tip().block_id();
-        let wallet_txs2 = self
-            .transactions()
-            .map(|wtx| {
-                (
-                    wtx.tx_node.txid,
-                    (wtx.tx_node.tx.clone(), wtx.chain_position),
-                )
-            })
-            .collect::<BTreeMap<Txid, (Arc<Transaction>, ChainPosition<ConfirmationBlockTime>)>>();
+        let wallet_txs2 = self.collect_wallet_txs();
 
         Ok(wallet_events(
             self,
@@ -2611,13 +2609,30 @@ impl Wallet {
         ))
     }
 
+    /// Collects all canonical wallet transactions into a map.
+    ///
+    /// This method is primarily used internally to create before/after snapshots when applying
+    /// updates or blocks to the wallet.
+    fn collect_wallet_txs(
+        &self,
+    ) -> BTreeMap<Txid, (Arc<Transaction>, ChainPosition<ConfirmationBlockTime>)> {
+        self.transactions()
+            .map(|wtx| {
+                (
+                    wtx.tx_node.txid,
+                    (wtx.tx_node.tx.clone(), wtx.chain_position),
+                )
+            })
+            .collect()
+    }
+
     /// Apply relevant unconfirmed transactions to the wallet.
     ///
     /// Transactions that are not relevant are filtered out.
     ///
     /// This method takes in an iterator of `(tx, last_seen)` where `last_seen` is the timestamp of
     /// when the transaction was last seen in the mempool. This is used for conflict resolution
-    /// when there is conflicting unconfirmed transactions. The transaction with the later
+    /// when there are conflicting unconfirmed transactions. The transaction with the later
     /// `last_seen` is prioritized.
     ///
     /// **WARNING**: You must persist the changes resulting from one or more calls to this method