feat: Add wallet event

Author: ItoroD

bdk-ffi/src/types.rs

@@ -23,6 +23,7 @@ use bdk_wallet::descriptor::policy::{
     Condition as BdkCondition, PkOrF as BdkPkOrF, Policy as BdkPolicy,
     Satisfaction as BdkSatisfaction, SatisfiableItem as BdkSatisfiableItem,
 };
+use bdk_wallet::event::WalletEvent as BdkWalletEvent;
 #[allow(deprecated)]
 use bdk_wallet::signer::{SignOptions as BdkSignOptions, TapLeavesOptions};
 use bdk_wallet::AddressInfo as BdkAddressInfo;
@@ -32,6 +33,7 @@ use bdk_wallet::Update as BdkUpdate;
 
 use std::collections::{BTreeMap, BTreeSet, HashMap};
 use std::convert::TryFrom;
+use std::fmt::Display;
 use std::sync::{Arc, Mutex};
 
 use crate::{impl_from_core_type, impl_into_core_type};
@@ -498,6 +500,157 @@ impl From<BdkSatisfiableItem> for SatisfiableItem {
     }
 }
 
+/// Events representing changes to wallet transactions.
+///
+/// Returned after calling
+/// [`Wallet::apply_update_events`](crate::wallet::Wallet::apply_update_events).
+#[derive(Debug, Clone, uniffi::Enum)]
+#[uniffi::export(Display)]
+#[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: Arc<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: Arc<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: Arc<Txid>,
+        /// Transaction.
+        tx: Arc<Transaction>,
+        /// Conflicting transactions.
+        conflicts: Vec<Conflict>,
+    },
+    /// 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: Arc<Txid>,
+        /// Transaction.
+        tx: Arc<Transaction>,
+    },
+}
+
+impl Display for WalletEvent {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{:?}", self)
+    }
+}
+
+/// Represent a conflict in a replacement transaction.
+#[uniffi::export(Display)]
+#[derive(Debug, Clone, uniffi::Record)]
+pub struct Conflict {
+    /// The index of the conflicting input.
+    pub vin: u32,
+    /// Conflicting transaction id.
+    pub txid: Arc<Txid>,
+}
+
+impl Display for Conflict {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{:?}", self)
+    }
+}
+
+impl From<BdkWalletEvent> for WalletEvent {
+    fn from(event: BdkWalletEvent) -> Self {
+        match event {
+            BdkWalletEvent::ChainTipChanged { old_tip, new_tip } => WalletEvent::ChainTipChanged {
+                old_tip: BlockId::from(old_tip),
+                new_tip: BlockId::from(new_tip),
+            },
+            BdkWalletEvent::TxConfirmed {
+                txid,
+                tx,
+                block_time,
+                old_block_time,
+            } => WalletEvent::TxConfirmed {
+                txid: Arc::new(Txid(txid)),
+                tx: Arc::new(tx.as_ref().clone().into()),
+                block_time: block_time.into(),
+                old_block_time: old_block_time.map(|v| v.into()),
+            },
+            BdkWalletEvent::TxUnconfirmed {
+                txid,
+                tx,
+                old_block_time,
+            } => WalletEvent::TxUnconfirmed {
+                txid: Arc::new(Txid(txid)),
+                tx: Arc::new(tx.as_ref().clone().into()),
+                old_block_time: old_block_time.map(|v| v.into()),
+            },
+            BdkWalletEvent::TxReplaced {
+                txid,
+                tx,
+                conflicts,
+            } => {
+                let conflict_list: Vec<Conflict> = conflicts
+                    .into_iter()
+                    .map(|(vin, conflict)| Conflict {
+                        vin: vin as u32,
+                        txid: Arc::new(Txid(conflict)),
+                    })
+                    .collect();
+                WalletEvent::TxReplaced {
+                    txid: Arc::new(Txid(txid)),
+                    tx: Arc::new(tx.as_ref().clone().into()),
+                    conflicts: conflict_list,
+                }
+            }
+            BdkWalletEvent::TxDropped { txid, tx } => WalletEvent::TxDropped {
+                txid: Arc::new(Txid(txid)),
+                tx: Arc::new(tx.as_ref().clone().into()),
+            },
+            _ => unreachable!("WalletEvent variant not covered in conversion"),
+        }
+    }
+}
+
 #[derive(Debug, Clone, uniffi::Enum)]
 pub enum PkOrF {
     Pubkey { value: String },

bdk-ffi/src/wallet.rs

@@ -8,7 +8,7 @@ use crate::store::{PersistenceType, Persister};
 use crate::types::{
     AddressInfo, Balance, BlockId, CanonicalTx, ChangeSet, EvictedTx, FullScanRequestBuilder,
     KeychainAndIndex, LocalOutput, Policy, SentAndReceivedValues, SignOptions, SyncRequestBuilder,
-    UnconfirmedTx, Update,
+    UnconfirmedTx, Update, WalletEvent,
 };
 
 use bdk_wallet::bitcoin::Network;
@@ -320,6 +320,24 @@ impl Wallet {
             .map_err(CannotConnectError::from)
     }
 
+    /// 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(
+        &self,
+        update: Arc<Update>,
+    ) -> Result<Vec<WalletEvent>, CannotConnectError> {
+        match self.get_wallet().apply_update_events(update.0.clone()) {
+            Ok(events) => Ok(events.into_iter().map(|e| e.into()).collect()),
+            Err(e) => Err(CannotConnectError::from(e)),
+        }
+    }
+
     /// Apply relevant unconfirmed transactions to the wallet.
     /// Transactions that are not relevant are filtered out.
     pub fn apply_unconfirmed_txs(&self, unconfirmed_txs: Vec<UnconfirmedTx>) {