---
# System prepended metadata

title: Applying updates returns list of events

---

# Applying Wallet Updates Returns A List of Events

* Lead Developer: [@notmandatory]
* Ticket: [#6]
* Pull Request: [#310]

<br>

## The Short Version

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

```rust=1
let events: Vec<WalletEvent> = wallet.apply_update(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.
```rust=
enum WalletEvent {
    ChainTipChanged {
        old_tip: BlockId,
        new_tip: BlockId,
    },
    TxConfirmed {
        txid: Txid,
        tx: Arc<Transaction>,
        block_time: ConfirmationBlockTime,
    },
    /// ...
}
```

<br>

## 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.

<br>

## 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.

<br>

## Deployment Path


The feature is currently explored as a non-breaking change through the `Wallet::apply_update_events` method which returns the list of events. There is a possibility of replacing the current `Wallet::apply_update` with this new one in the 3.0 release of bdk_wallet, which would be a breaking change.

<br>

[@notmandatory]: https://github.com/notmandatory
[#6]: https://github.com/bitcoindevkit/bdk_wallet/issues/6
[#310]: https://github.com/bitcoindevkit/bdk_wallet/issues/310
[Wallet::apply_update]: https://docs.rs/bdk_wallet/2.1.0/bdk_wallet/struct.Wallet.html#method.apply_update
