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

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

wallet/src/wallet/event.rs

@@ -0,0 +1,190 @@
+//! 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`](crate::wallet::Wallet::apply_update).
+#[derive(Debug, Clone, PartialEq, Eq)]
+#[non_exhaustive]
+pub enum WalletEvent {
+    /// The wallet's chain tip changed.
+    ChainTipChanged {
+        /// Previous chain tip.
+        old_tip: BlockId,
+        /// New chain tip.
+        new_tip: BlockId,
+    },
+    /// A new confirmed transaction was added to the wallet.
+    NewConfirmedTx {
+        /// Transaction id.
+        txid: Txid,
+        /// Transaction.
+        tx: Arc<Transaction>,
+        /// Confirmation block time.
+        block_time: ConfirmationBlockTime,
+    },
+    /// A new unconfirmed transaction was added to the wallet.
+    NewUnconfirmedTx {
+        /// Transaction id.
+        txid: Txid,
+        /// Transaction.
+        tx: Arc<Transaction>,
+    },
+    /// An unconfirmed transaction is now confirmed.
+    TxConfirmed {
+        /// Transaction id.
+        txid: Txid,
+        /// Transaction.
+        tx: Arc<Transaction>,
+        /// Confirmation block time.
+        block_time: ConfirmationBlockTime,
+    },
+    /// A confirmed transaction is now confirmed in a new block.
+    ///
+    /// This can happen after a chain reorg.
+    TxConfirmedNewBlock {
+        /// Transaction id.
+        txid: Txid,
+        /// Transaction.
+        tx: Arc<Transaction>,
+        /// Confirmation block time.
+        block_time: ConfirmationBlockTime,
+    },
+    /// A confirmed transaction is now unconfirmed.
+    ///
+    /// This can happen after a chain reorg.
+    TxUnconfirmed {
+        /// Transaction id.
+        txid: Txid,
+        /// Transaction.
+        tx: Arc<Transaction>,
+    },
+    /// An unconfirmed transaction was replaced.
+    ///
+    /// This can happen after an RBF or a third party double spending inputs prior to a transaction
+    /// being 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 be-appear in the mempool resulting in a
+    /// [`WalletEvent::NewUnconfirmedTx`] event.
+    TxDropped {
+        /// Transaction id.
+        txid: Txid,
+        /// Transaction.
+        tx: Arc<Transaction>,
+    },
+}
+
+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();
+
+    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) {
+                (Unconfirmed { .. }, Confirmed { anchor, .. }) => {
+                    events.push(WalletEvent::TxConfirmed {
+                        txid: *txid2,
+                        tx: tx2.clone(),
+                        block_time: *anchor,
+                    });
+                }
+                (Confirmed { .. }, Unconfirmed { .. }) => {
+                    events.push(WalletEvent::TxUnconfirmed {
+                        txid: *txid2,
+                        tx: tx2.clone(),
+                    });
+                }
+                (
+                    Confirmed {
+                        anchor: anchor1, ..
+                    },
+                    Confirmed {
+                        anchor: anchor2, ..
+                    },
+                ) => {
+                    if *anchor1 != *anchor2 {
+                        events.push(WalletEvent::TxConfirmedNewBlock {
+                            txid: *txid2,
+                            tx: tx2.clone(),
+                            block_time: *anchor2,
+                        });
+                    }
+                }
+                (Unconfirmed { .. }, Unconfirmed { .. }) => {
+                    // do nothing if still unconfirmed
+                }
+            }
+        } else {
+            match cp2 {
+                Confirmed { anchor, .. } => {
+                    events.push(WalletEvent::NewConfirmedTx {
+                        txid: *txid2,
+                        tx: tx2.clone(),
+                        block_time: *anchor,
+                    });
+                }
+                Unconfirmed { .. } => {
+                    events.push(WalletEvent::NewUnconfirmedTx {
+                        txid: *txid2,
+                        tx: tx2.clone(),
+                    });
+                }
+            }
+        }
+    });
+
+    // 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
+}
+
+// see tests in test/wallet_events.rs