docs(event): improve wallet event docs and tests

per suggestions from ValuedMammal:
1. re-export WalletEvent type
2. add comments to wallet_events function
3. rename ambiguous variable names in wallet_events from cp to pos
4. remove signing from wallet_event tests
5. change wallet_events function assert_eq to debug_asset_eq
6. update ADR 0003 decision outcome and add option 4 re: creating events only from Update

Author: notmandatory

docs/adr/0003_events.md

@@ -4,7 +4,7 @@
 * Authors: @notmandatory
 * Date: 2025-09-21
 * Targeted modules: wallet
-* Associated tickets/PRs: #6, #310
+* Associated tickets/PRs: #6, #310, #319
 
 ## Context and Problem Statement
 
@@ -89,10 +89,30 @@ return the list of `WalletEvent` enums.
 * Could be confusing to users which function to use, the original or new one.
 * If in a future breaking release we decide to always return events we'll need to deprecate `Wallet::apply_update_events`.
 
+#### Option 4: Create events directly from Wallet::Update
+
+The `wallet::Update` structure passed into the `Wallet::apply_update` function contains any new transaction or 
+blockchain data found in a `FullScanResponse` or `SyncResponse`. Events could be generated from only this data.
+
+**Pros:**
+
+* No further wallet lookups is required to create events, it would be more efficient.
+* Could be implemented as a function directly on the `wallet::Update` structure, a non-breaking API change.
+
+**Cons:**
+
+* A `wallet::Update` only contains the blocks, tx, and anchors found during a sync or full scan. It does not show how 
+  this data changes the canonical status of already known blocks and tx.
+
 ## Decision Outcome
 
-Chosen option: "Option 3", because it can be delivered to users in the next minor release. This option also lets us 
-get user feedback and see how the events are used before forcing all users to generate them during an update.
+Chosen option: 
+
+"Option 3" for the 2.2 release because it can be delivered to users as a minor release. This option also 
+lets us get user feedback and see how the events are used before forcing all users to generate them during an update.
+
+"Option 2" for the 3.0 release to simplify the API by only using one function `apply_update` that will now return
+events. 
 
 ### Positive Consequences
 

src/wallet/event.rs

@@ -0,0 +1,186 @@
+//! User facing wallet events.
+
+use crate::collections::BTreeMap;
+use crate::wallet::ChainPosition::{Confirmed, Unconfirmed};
+use crate::Wallet;
+use alloc::sync::Arc;
+use alloc::vec::Vec;
+use bitcoin::{Transaction, Txid};
+use chain::{BlockId, ChainPosition, ConfirmationBlockTime};
+
+/// Events representing changes to wallet transactions.
+///
+/// Returned after calling
+/// [`Wallet::apply_update_events`](crate::wallet::Wallet::apply_update_events).
+#[derive(Debug, Clone, PartialEq, Eq)]
+#[non_exhaustive]
+pub enum WalletEvent {
+    /// The latest chain tip known to the wallet changed.
+    ChainTipChanged {
+        /// Previous chain tip.
+        old_tip: BlockId,
+        /// New chain tip.
+        new_tip: BlockId,
+    },
+    /// A transaction is now confirmed.
+    ///
+    /// If the transaction was previously unconfirmed `old_block_time` will be `None`.
+    ///
+    /// 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.
+    TxConfirmed {
+        /// Transaction id.
+        txid: Txid,
+        /// Transaction.
+        tx: Arc<Transaction>,
+        /// Confirmation block time.
+        block_time: ConfirmationBlockTime,
+        /// Old confirmation block and time if previously confirmed in a different block.
+        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`.
+    ///
+    /// 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.
+    TxUnconfirmed {
+        /// Transaction id.
+        txid: Txid,
+        /// Transaction.
+        tx: Arc<Transaction>,
+        /// Old confirmation block and time, if previously confirmed.
+        old_block_time: Option<ConfirmationBlockTime>,
+    },
+    /// An unconfirmed transaction was 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.
+    ///
+    /// The conflicts field contains the txid and vin (in which it conflicts) of the conflicting
+    /// transactions.
+    TxReplaced {
+        /// Transaction id.
+        txid: Txid,
+        /// Transaction.
+        tx: Arc<Transaction>,
+        /// Conflicting transaction ids.
+        conflicts: Vec<(usize, Txid)>,
+    },
+    /// Unconfirmed transaction dropped.
+    ///
+    /// 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.
+    TxDropped {
+        /// Transaction id.
+        txid: Txid,
+        /// Transaction.
+        tx: Arc<Transaction>,
+    },
+}
+
+/// Generate events by comparing the chain tip and wallet transactions before and after applying
+/// `wallet::Update` to `Wallet`. Any changes are added to the list of returned `WalletEvent`s.
+pub(crate) fn wallet_events(
+    wallet: &mut Wallet,
+    chain_tip1: BlockId,
+    chain_tip2: BlockId,
+    wallet_txs1: BTreeMap<Txid, (Arc<Transaction>, ChainPosition<ConfirmationBlockTime>)>,
+    wallet_txs2: BTreeMap<Txid, (Arc<Transaction>, ChainPosition<ConfirmationBlockTime>)>,
+) -> Vec<WalletEvent> {
+    let mut events: Vec<WalletEvent> = Vec::new();
+
+    // find chain tip change
+    if chain_tip1 != chain_tip2 {
+        events.push(WalletEvent::ChainTipChanged {
+            old_tip: chain_tip1,
+            new_tip: chain_tip2,
+        });
+    }
+
+    // find transaction canonical status changes
+    wallet_txs2.iter().for_each(|(txid2, (tx2, pos2))| {
+        if let Some((tx1, pos1)) = wallet_txs1.get(txid2) {
+            debug_assert_eq!(tx1.compute_txid(), *txid2);
+            match (pos1, pos2) {
+                (Unconfirmed { .. }, Confirmed { anchor, .. }) => {
+                    events.push(WalletEvent::TxConfirmed {
+                        txid: *txid2,
+                        tx: tx2.clone(),
+                        block_time: *anchor,
+                        old_block_time: None,
+                    });
+                }
+                (Confirmed { anchor, .. }, Unconfirmed { .. }) => {
+                    events.push(WalletEvent::TxUnconfirmed {
+                        txid: *txid2,
+                        tx: tx2.clone(),
+                        old_block_time: Some(*anchor),
+                    });
+                }
+                (
+                    Confirmed {
+                        anchor: anchor1, ..
+                    },
+                    Confirmed {
+                        anchor: anchor2, ..
+                    },
+                ) => {
+                    if *anchor1 != *anchor2 {
+                        events.push(WalletEvent::TxConfirmed {
+                            txid: *txid2,
+                            tx: tx2.clone(),
+                            block_time: *anchor2,
+                            old_block_time: Some(*anchor1),
+                        });
+                    }
+                }
+                (Unconfirmed { .. }, Unconfirmed { .. }) => {
+                    // do nothing if still unconfirmed
+                }
+            }
+        } else {
+            match pos2 {
+                Confirmed { anchor, .. } => {
+                    events.push(WalletEvent::TxConfirmed {
+                        txid: *txid2,
+                        tx: tx2.clone(),
+                        block_time: *anchor,
+                        old_block_time: None,
+                    });
+                }
+                Unconfirmed { .. } => {
+                    events.push(WalletEvent::TxUnconfirmed {
+                        txid: *txid2,
+                        tx: tx2.clone(),
+                        old_block_time: None,
+                    });
+                }
+            }
+        }
+    });
+
+    // find tx that are no longer canonical
+    wallet_txs1.iter().for_each(|(txid1, (tx1, _))| {
+        if !wallet_txs2.contains_key(txid1) {
+            let conflicts = wallet.tx_graph().direct_conflicts(tx1).collect::<Vec<_>>();
+            if !conflicts.is_empty() {
+                events.push(WalletEvent::TxReplaced {
+                    txid: *txid1,
+                    tx: tx1.clone(),
+                    conflicts,
+                });
+            } else {
+                events.push(WalletEvent::TxDropped {
+                    txid: *txid1,
+                    tx: tx1.clone(),
+                });
+            }
+        }
+    });
+
+    events
+}

src/wallet/mod.rs

@@ -75,11 +75,12 @@ use crate::wallet::{
     tx_builder::{FeePolicy, TxBuilder, TxParams},
     utils::{check_nsequence_rbf, After, Older, SecpCtx},
 };
+use event::wallet_events;
 
 // re-exports
-use crate::event::{wallet_events, WalletEvent};
 pub use bdk_chain::Balance;
 pub use changeset::ChangeSet;
+pub use event::WalletEvent;
 pub use params::*;
 pub use persisted::*;
 pub use utils::IsDust;

tests/wallet_event.rs

@@ -1,7 +1,7 @@
 use bdk_chain::{BlockId, CheckPoint, ConfirmationBlockTime};
 use bdk_wallet::event::WalletEvent;
 use bdk_wallet::test_utils::{get_test_wpkh_and_change_desc, new_wallet_and_funding_update};
-use bdk_wallet::{SignOptions, Update};
+use bdk_wallet::Update;
 use bitcoin::hashes::Hash;
 use bitcoin::{Address, Amount, BlockHash, FeeRate};
 use core::str::FromStr;
@@ -76,8 +76,7 @@ fn test_tx_replaced_event() {
             .assume_checked(),
         Amount::from_sat(10_000),
     );
-    let mut psbt = builder.finish().unwrap();
-    wallet.sign(&mut psbt, SignOptions::default()).unwrap();
+    let psbt = builder.finish().unwrap();
     let orig_tx = Arc::new(psbt.extract_tx().unwrap());
     let orig_txid = orig_tx.compute_txid();
 
@@ -95,8 +94,7 @@ fn test_tx_replaced_event() {
     // create rbf tx
     let mut builder = wallet.build_fee_bump(orig_txid).unwrap();
     builder.fee_rate(FeeRate::from_sat_per_vb(10).unwrap());
-    let mut psbt = builder.finish().unwrap();
-    wallet.sign(&mut psbt, SignOptions::default()).unwrap();
+    let psbt = builder.finish().unwrap();
     let rbf_tx = Arc::new(psbt.extract_tx().unwrap());
     let rbf_txid = rbf_tx.compute_txid();
 
@@ -131,8 +129,7 @@ fn test_tx_confirmed_event() {
             .assume_checked(),
         Amount::from_sat(10_000),
     );
-    let mut psbt = builder.finish().unwrap();
-    wallet.sign(&mut psbt, SignOptions::default()).unwrap();
+    let psbt = builder.finish().unwrap();
     let new_tx = Arc::new(psbt.extract_tx().unwrap());
     let new_txid = new_tx.compute_txid();
 
@@ -189,8 +186,7 @@ fn test_tx_confirmed_new_block_event() {
             .assume_checked(),
         Amount::from_sat(10_000),
     );
-    let mut psbt = builder.finish().unwrap();
-    wallet.sign(&mut psbt, SignOptions::default()).unwrap();
+    let psbt = builder.finish().unwrap();
     let new_tx = Arc::new(psbt.extract_tx().unwrap());
     let new_txid = new_tx.compute_txid();
 
@@ -274,8 +270,7 @@ fn test_tx_dropped_event() {
             .assume_checked(),
         Amount::from_sat(10_000),
     );
-    let mut psbt = builder.finish().unwrap();
-    wallet.sign(&mut psbt, SignOptions::default()).unwrap();
+    let psbt = builder.finish().unwrap();
     let new_tx = Arc::new(psbt.extract_tx().unwrap());
     let new_txid = new_tx.compute_txid();