feat(wallet): add WalletEvent and Wallet::apply_update_events

WalletEvent is a enum of user facing events that are
generated when a sync update is applied to a wallet using the
Wallet::apply_update_events function.

Author: notmandatory

src/test_utils.rs

@@ -4,7 +4,7 @@ use alloc::string::ToString;
 use alloc::sync::Arc;
 use core::str::FromStr;
 
-use bdk_chain::{BlockId, ConfirmationBlockTime, TxUpdate};
+use bdk_chain::{BlockId, CheckPoint, ConfirmationBlockTime, TxUpdate};
 use bitcoin::{
     absolute, hashes::Hash, transaction, Address, Amount, BlockHash, FeeRate, Network, OutPoint,
     Transaction, TxIn, TxOut, Txid,
@@ -22,13 +22,42 @@ pub fn get_funded_wallet(descriptor: &str, change_descriptor: &str) -> (Wallet,
 }
 
 fn new_funded_wallet(descriptor: &str, change_descriptor: Option<&str>) -> (Wallet, Txid) {
+    let (mut wallet, txid, update) = new_wallet_and_funding_update(descriptor, change_descriptor);
+    wallet.apply_update(update).unwrap();
+    (wallet, txid)
+}
+
+/// Return a fake wallet that appears to be funded for testing.
+///
+/// The funded wallet contains a tx with a 76_000 sats input and two outputs, one spending 25_000
+/// to a foreign address and one returning 50_000 back to the wallet. The remaining 1000
+/// sats are the transaction fee.
+pub fn get_funded_wallet_single(descriptor: &str) -> (Wallet, Txid) {
+    new_funded_wallet(descriptor, None)
+}
+
+/// Get funded segwit wallet
+pub fn get_funded_wallet_wpkh() -> (Wallet, Txid) {
+    let (desc, change_desc) = get_test_wpkh_and_change_desc();
+    get_funded_wallet(desc, change_desc)
+}
+
+/// Get unfunded wallet and wallet update that funds it
+///
+/// The funding update contains a tx with a 76_000 sats input and two outputs, one spending
+/// 25_000 to a foreign address and one returning 50_000 back to the wallet as
+/// change. The remaining 1000 sats are the transaction fee.
+pub fn new_wallet_and_funding_update(
+    descriptor: &str,
+    change_descriptor: Option<&str>,
+) -> (Wallet, Txid, Update) {
     let params = if let Some(change_desc) = change_descriptor {
         Wallet::create(descriptor.to_string(), change_desc.to_string())
     } else {
         Wallet::create_single(descriptor.to_string())
     };
 
-    let mut wallet = params
+    let wallet = params
         .network(Network::Regtest)
         .create_wallet_no_persist()
         .expect("descriptors must be valid");
@@ -39,6 +68,8 @@ fn new_funded_wallet(descriptor: &str, change_descriptor: Option<&str>) -> (Wall
         .require_network(Network::Regtest)
         .unwrap();
 
+    let mut update = Update::default();
+
     let tx0 = Transaction {
         output: vec![TxOut {
             value: Amount::from_sat(76_000),
@@ -67,71 +98,37 @@ fn new_funded_wallet(descriptor: &str, change_descriptor: Option<&str>) -> (Wall
         ],
         ..new_tx(0)
     };
+    let txid1 = tx1.compute_txid();
 
-    insert_checkpoint(
-        &mut wallet,
-        BlockId {
-            height: 42,
-            hash: BlockHash::all_zeros(),
-        },
-    );
-    insert_checkpoint(
-        &mut wallet,
-        BlockId {
-            height: 1_000,
-            hash: BlockHash::all_zeros(),
-        },
-    );
-    insert_checkpoint(
-        &mut wallet,
-        BlockId {
-            height: 2_000,
-            hash: BlockHash::all_zeros(),
-        },
-    );
-
-    insert_tx(&mut wallet, tx0.clone());
-    insert_anchor(
-        &mut wallet,
-        tx0.compute_txid(),
-        ConfirmationBlockTime {
-            block_id: BlockId {
-                height: 1_000,
-                hash: BlockHash::all_zeros(),
-            },
-            confirmation_time: 100,
-        },
-    );
-
-    insert_tx(&mut wallet, tx1.clone());
-    insert_anchor(
-        &mut wallet,
-        tx1.compute_txid(),
-        ConfirmationBlockTime {
-            block_id: BlockId {
-                height: 2_000,
-                hash: BlockHash::all_zeros(),
-            },
-            confirmation_time: 200,
-        },
-    );
-
-    (wallet, tx1.compute_txid())
-}
-
-/// Return a fake wallet that appears to be funded for testing.
-///
-/// The funded wallet contains a tx with a 76_000 sats input and two outputs, one spending 25_000
-/// to a foreign address and one returning 50_000 back to the wallet. The remaining 1000
-/// sats are the transaction fee.
-pub fn get_funded_wallet_single(descriptor: &str) -> (Wallet, Txid) {
-    new_funded_wallet(descriptor, None)
-}
+    let b0 = BlockId {
+        height: 0,
+        hash: BlockHash::from_slice(wallet.network().chain_hash().as_bytes()).unwrap(),
+    };
+    let b1 = BlockId {
+        height: 42,
+        hash: BlockHash::all_zeros(),
+    };
+    let b2 = BlockId {
+        height: 1000,
+        hash: BlockHash::all_zeros(),
+    };
+    let a2 = ConfirmationBlockTime {
+        block_id: b2,
+        confirmation_time: 100,
+    };
+    let b3 = BlockId {
+        height: 2000,
+        hash: BlockHash::all_zeros(),
+    };
+    let a3 = ConfirmationBlockTime {
+        block_id: b3,
+        confirmation_time: 200,
+    };
+    update.chain = CheckPoint::from_block_ids([b0, b1, b2, b3]).ok();
+    update.tx_update.anchors = [(a2, tx0.compute_txid()), (a3, tx1.compute_txid())].into();
+    update.tx_update.txs = [Arc::new(tx0), Arc::new(tx1)].into();
 
-/// Get funded segwit wallet
-pub fn get_funded_wallet_wpkh() -> (Wallet, Txid) {
-    let (desc, change_desc) = get_test_wpkh_and_change_desc();
-    get_funded_wallet(desc, change_desc)
+    (wallet, txid1, update)
 }
 
 /// `pkh` single key descriptor

src/wallet/mod.rs

@@ -52,6 +52,7 @@ use rand_core::RngCore;
 mod changeset;
 pub mod coin_selection;
 pub mod error;
+pub mod event;
 pub mod export;
 mod params;
 mod persisted;
@@ -76,6 +77,7 @@ use crate::wallet::{
 };
 
 // re-exports
+use crate::event::{wallet_events, WalletEvent};
 pub use bdk_chain::Balance;
 pub use changeset::ChangeSet;
 pub use params::*;
@@ -2374,6 +2376,54 @@ impl Wallet {
         Ok(())
     }
 
+    /// Applies an update to the wallet, stages the changes, and returns events.
+    ///
+    /// 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.
+    ///
+    /// 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`].
+    pub fn apply_update_events(
+        &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>)>>();
+
+        // apply update
+        self.apply_update(update)?;
+
+        // 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>)>>();
+
+        Ok(wallet_events(
+            self,
+            chain_tip1,
+            chain_tip2,
+            wallet_txs1,
+            wallet_txs2,
+        ))
+    }
+
     /// Get a reference of the staged [`ChangeSet`] that is yet to be committed (if any).
     pub fn staged(&self) -> Option<&ChangeSet> {
         if self.stage.is_empty() {