Skip to content

Applying Wallet Updates Returns A List of Events

Overview

Overview

Applying updates to the Wallet would now return a list of events that were contained in this update on the wallet.

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 sync update is applied to a wallet using the existing Wallet::apply_update 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 canonical transactions.

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.