Skip to content

Applying Updates to a Wallet Returns A List of Events

Overview

Overview

A new method is provided for applying a blockchain data update to the Wallet that returns a list of events the update generates.

1
let events: Vec<WalletEvent> = wallet.apply_update_events(update);

The WalletEvent is an enum with variants that signal things like a change in the blockchain tip, a new transaction confirmed, a transaction has been RBF'd, etc.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
enum WalletEvent {
    ChainTipChanged {
        old_tip: BlockId,
        new_tip: BlockId,
    },
    TxConfirmed {
        txid: Txid,
        tx: Arc<Transaction>,
        block_time: ConfirmationBlockTime,
    },
    /// ...
}

Why Do This?

When syncing a Wallet with new blockchain data using Wallet::apply_update, it does not return any value on success, and only a CannotConnectError if it fails.

Users have asked for a concise list of events that reflect if or how new blockchain data has changed the blockchain tip and the status of transactions relevant to the wallet's balance. This information is useful for downstream libraries who rely on these events for triggering their own work, as well as for applications who want to notify users of wallet changes after syncing.

Applying An Update to Wallet Now Returns Vec<WalletEvent>

This new feature adds a WalletEvent enum of user-facing events that are generated when a blockchain data update is applied to a wallet using the Wallet::apply_update_events function. The WalletEvent enum includes an event for changes in blockchain tip and events for changes to the status of transactions that are relevant to the wallet, including:

  1. Newly seen in the mempool
  2. Replaced in the mempool
  3. Dropped from the mempool
  4. Confirmed in a block
  5. Confirmed in a new block due to a reorg
  6. Unconfirmed due to a reorg

Chain tip change events are generated by comparing the wallet's chain tip before and after applying an update. Wallet transaction events are generated by comparing a snapshot of the wallet's canonical transactions before and after applying the update.

As long as updates to the wallet are not persisted until after all events are processed by the caller, then if the app crashes for some reason and the wallet is re-sync'd a new update will re-return the same events.

The WalletEvent enum is non-exhaustive.