Skip to content

feat: wrap wallet events API (apply_update_events)#33

Merged
darioAnongba merged 6 commits intomainfrom
feat/wallet-events
Feb 27, 2026
Merged

feat: wrap wallet events API (apply_update_events)#33
darioAnongba merged 6 commits intomainfrom
feat/wallet-events

Conversation

@darioAnongba
Copy link
Collaborator

Summary

Wrap BDK's WalletEvent type and add Wallet::apply_update_events so JS consumers can react to wallet state changes after syncing.

New API

WalletEvent type

JS-friendly wrapper with getters instead of Rust enum pattern matching:

Getter Type Description
kind string Event type: chain_tip_changed, tx_confirmed, tx_unconfirmed, tx_replaced, tx_dropped
txid Txid? Transaction id (tx events only)
tx Transaction? Full transaction (tx events only)
old_tip BlockId? Previous chain tip (chain_tip_changed only)
new_tip BlockId? New chain tip (chain_tip_changed only)
block_time ConfirmationBlockTime? Confirmation info (tx_confirmed only)
old_block_time ConfirmationBlockTime? Previous confirmation (reorgs)

Wallet.apply_update_events(update)

Like apply_update but returns WalletEvent[] describing what changed.

Example usage

const update = await esploraClient.full_scan(request, stopGap, parallelRequests);
const events = wallet.apply_update_events(update);
for (const event of events) {
  switch (event.kind) {
    case 'tx_confirmed':
      console.log(`TX ${event.txid} confirmed at block ${event.block_time.block_id.height}`);
      break;
    case 'chain_tip_changed':
      console.log(`Chain tip: ${event.old_tip.height}${event.new_tip.height}`);
      break;
  }
}

Closes #19

Add WalletEvent type wrapping BDK's WalletEvent enum with JS-friendly
getters:
- kind: event type string (chain_tip_changed, tx_confirmed,
  tx_unconfirmed, tx_replaced, tx_dropped)
- txid, tx: transaction data (where applicable)
- old_tip, new_tip: chain tip changes
- block_time, old_block_time: confirmation data

Add Wallet::apply_update_events method that returns Vec<WalletEvent>
describing what changed after applying an update.

Closes #19
@darioAnongba darioAnongba self-assigned this Feb 26, 2026
- Fix E0603: use bdk_wallet::event::WalletEvent (public) instead of
  bdk_wallet::wallet::event::WalletEvent (private)
- Fix E0282: explicit type in old_block_time getter to resolve inference
- Add WalletEventKind TS enum per review feedback, replacing String return
  type on kind() getter (follows KeychainKind pattern)
- Test apply_update_events on initial full scan (ChainTipChanged, TxConfirmed)
- Test TxConfirmed event after sending TX and mining blocks
- Test WalletEventKind enum values
- Test no spurious events on re-sync
- Uses docker exec for regtest block mining
- Only runs in regtest environment (skipped for signet)
- Update CI to include events test pattern
- WalletEventKind is a string literal union in TS, use string constants
- Use block_id.height instead of height on ConfirmationBlockTime
- Exclude events test from Node CI (requires regtest docker)
…ally

- Events test uses different descriptor to avoid UTXO conflicts with esplora test
- Self-funds wallet via docker exec in beforeAll
- Run regtest integration tests with --runInBand to prevent block mining
  side effects between test suites
@darioAnongba darioAnongba marked this pull request as ready for review February 26, 2026 16:21
@darioAnongba darioAnongba merged commit 297b275 into main Feb 27, 2026
12 checks passed
@darioAnongba darioAnongba deleted the feat/wallet-events branch February 27, 2026 11:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: wrap wallet events API (apply_update returning events)

1 participant