docs: 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. add option 4 to ADR 0003 re: creating events only from Update

Author: notmandatory

docs/adr/0003_events.md

@@ -89,6 +89,21 @@ 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 

wallet/src/wallet/event.rs

@@ -82,6 +82,8 @@ pub enum WalletEvent {
     },
 }
 
+/// 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,
@@ -91,17 +93,19 @@ pub(crate) fn wallet_events(
 ) -> 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,
         });
     }
 
-    wallet_txs2.iter().for_each(|(txid2, (tx2, cp2))| {
-        if let Some((tx1, cp1)) = wallet_txs1.get(txid2) {
-            assert_eq!(tx1.compute_txid(), *txid2);
-            match (cp1, cp2) {
+    // 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,
@@ -139,7 +143,7 @@ pub(crate) fn wallet_events(
                 }
             }
         } else {
-            match cp2 {
+            match pos2 {
                 Confirmed { anchor, .. } => {
                     events.push(WalletEvent::TxConfirmed {
                         txid: *txid2,

wallet/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;

wallet/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();