walletd: Log of balance changes

[sdbondi]

Bounty: walletd — Log of Balance Changes

Tier: L — 150,000 XTM

Description

Add a persistent, queryable log of account balance changes to the wallet daemon and surface it in the web UI. Every time a vault's balance changes (revealed and/or confidential), record a structured entry capturing the before/after balances, the signed delta, and an enumerated source — Transaction (linked to the transaction that caused it), Scan (funds discovered by re-reading on-chain state, e.g. inbound transfers the wallet didn't author), or Recovery (confidential UTXO recovery). All vault balance mutations already funnel through a single chokepoint (AccountScanner::refresh_vault), which is the place to record entries. The work spans a new additive SQLite migration, SDK models/reader/writer methods, a new accounts.get_balance_changes JSON-RPC method, regenerated TS bindings + JS client method, and a web UI surface (a per-vault "View changes" action plus an account-wide log).

Acceptance Criteria

• A finalized transaction that changes a vault's revealed and/or confidential balance persists a balance-change entry linked to that transaction; a single transaction affecting multiple vaults/accounts (e.g. self-transfer) produces one entry per affected vault, all sharing the same transaction_id.
• Each entry carries an enumerated source (Transaction { transaction_id }, Scan, or Recovery); non-transaction sources carry a null transaction_id. Each entry records before/after for both revealed and confidential balances plus the signed delta.
• Entries are idempotent: re-scanning or re-processing the same finalized transaction creates no duplicates, and only non-zero balance changes are logged.
• An additive diesel migration creates the account_balance_changes table with down.sql; schema.rs is regenerated; existing wallets upgrade without data loss or reset. SDK WalletStoreReader/WalletStoreWriter expose insert + paginated query methods, covered by storage tests.
• accounts.get_balance_changes returns an account's log newest-first with offset/limit pagination and optional resource_address / transaction_id filters; each entry includes vault, resource, before/after, delta, source, nullable transaction_id, and timestamp.
• Request/response types are exported via ts-rs into bindings/, a typed method is added to the JS WalletDaemonClient, and web_ui/dist is rebuilt/committed.
• The web UI provides a per-vault "View changes" action (scoped via the vault/resource filter) and an account-wide log showing timestamp, resource, signed delta, new balance, and source; Transaction entries link to the transaction detail page while Scan/Recovery (and unknown future variants) render a meaningful label with no broken link.
• Test coverage exists for: tx-driven change, multi-vault tx, non-tx (recovery) change, idempotent re-scan, and the JSON-RPC handler. cargo +nightly-2025-12-05 fmt --all is clean and the workspace builds.

Context

• Issue opened by @sdbondi
• Recording hook (single chokepoint): TransactionService (crates/wallet/sdk_services/src/transaction_service/service.rs) → AccountMonitor::on_event (crates/wallet/sdk_services/src/account_monitor/monitor.rs) → AccountScanner::process_result → AccountScanner::refresh_vault (crates/wallet/sdk_services/src/account_monitor/scanner.rs:156-268). The compare-and-write is at scanner.rs:252-265, which calls AccountsApi::update_vault_balance (crates/wallet/sdk/src/apis/accounts.rs:207-216) only when a balance changed.
• Threading the source: refresh_vault does not currently receive a transaction id — the tx_id known at process_result (scanner.rs:516/:590) must be threaded through as Transaction { tx_id }, and the account-scan path (scanner.rs:143) must pass Scan.
• Storage: crates/wallet/storage_sqlite/ (new migration, schema.rs, model, reader.rs/writer.rs). A generic wallet_events table already exists but is an unstructured event blob — a dedicated account_balance_changes table is recommended over overloading it.
• SDK: new BalanceChange model + internally-tagged BalanceChangeSource enum in crates/wallet/sdk/src/models/; reader/writer trait methods in crates/wallet/sdk/src/storage/.
• JSON-RPC: new method registered in applications/tari_walletd/src/server.rs (accounts.* arm) with a handler in src/handlers/accounts.rs; request/response types in clients/wallet_daemon_client/src/types.rs (with ts-rs derives, consistent with BalanceEntry).
• UI: applications/tari_walletd/web_ui/ (React 19 + Vite + MUI) — hook in src/services/api/hooks/useAccounts.ts; per-vault action in AssetVault/Components/MyAssets.tsx / AssetVault/Tokens/Tokens.tsx / AccountDetails.tsx; tx links to src/routes/Transactions/TransactionDetails.tsx.
• Full scope, code references, and open questions (granularity, confidential-amount semantics, retention, NFT vaults) are in the original issue body (preserved below on first sync).

How It Works

1. Comment on this issue to signal intent (courtesy, not a lock)
2. Fork the repo and do the work
3. Submit a PR that references the issue with a closing keyword (e.g. Fixes #1949) so GitHub links your PR to the bounty automatically
4. Bounties are competitive. Multiple PRs may be submitted for the same bounty. Review comments are public, and contributors may borrow ideas from each other's work. The maintainer selects the PR that best solves the problem, considering code quality, completeness, and contributor behavior. In cases where multiple contributors made significant contributions, the maintainer may split the bounty. The maintainer's decision is final.
5. Earn XTM (processing may take up to a week; reach out to @Possum on Discord with your Tari address)

Notes

• This touches wallet balance-tracking code — PR will require thorough review
• AI-assisted development is expected and encouraged
• If you get stuck, ask in Discord

[sdbondi]

Original issue description (preserved before bounty rewrite)

For increased visibility, we should have a log of account balance changes and display these in the UI.

Each entry records a change to a vault's balance (revealed and/or confidential) for an account, linked — where applicable — to the transaction that caused it, and is queryable per account/vault over JSON-RPC and surfaced in the wallet web UI.

---

Scope

Where balance changes actually happen (the recording hook)

All vault balance mutations in the wallet funnel through a single chokepoint:

TransactionService (polls finalized txs, crates/wallet/sdk_services/src/transaction_service/service.rs) → emits WalletEvent::TransactionFinalized → AccountMonitor::on_event (crates/wallet/sdk_services/src/account_monitor/monitor.rs) extracts the SubstateDiff → AccountScanner::process_result(tx_id, diff, new_account) (crates/wallet/sdk_services/src/account_monitor/scanner.rs) → AccountScanner::refresh_vault(...) (scanner.rs:156-268).

The actual compare-and-write is at scanner.rs:252-265: it has the old vault balances (maybe_current_vault), the new revealed balance (latest_vault.balance()) and new confidential balance (outputs_api.get_unspent_balance(...)), and calls AccountsApi::update_vault_balance(vault_id, revealed, confidential) (crates/wallet/sdk/src/apis/accounts.rs:207-216) only when a balance actually changed. This is the single place to record a change entry.

Two distinct paths reach refresh_vault, and each is a different change source:

1. Transaction — AccountMonitor::on_event TransactionFinalized (monitor.rs:263) → process_result(tx_id, diff, …) → refresh_vault (scanner.rs:516, :590). A TransactionId is in hand.
2. Scan — the account-scan path (scanner.rs:143) that re-reads an account's vault substates from the indexer (e.g. funds received from a third party's transaction the wallet didn't author). No transaction id is available. Confidential-balance growth from UTXO recovery (verify_and_update_confidential_outputs inside refresh_vault, plus the UtxoRecovered events) is a candidate third variant.

Key constraint: refresh_vault does not currently receive a transaction id (signature: account_address, vault_id, latest_vault, updated_nft_data). The tx_id known at process_result must be threaded through, and the scan path must pass a non-transaction source. So the recorded change carries an enumerated source (see below), not just a nullable transaction_id. A single transaction can change multiple vaults across multiple accounts (e.g. self-transfer), so one transaction maps to many change rows.

1. Database — tari_ootle_wallet_storage_sqlite (crates/wallet/storage_sqlite/)

• New diesel migration dir (e.g. migrations/2026-06-XX-000000_account_balance_changes/{up,down}.sql) — additive only, no reset of existing wallet data; regenerate src/schema.rs.
• New table account_balance_changes:
  • id (PK, autoincrement)
  • account_id (FK → accounts)
  • vault_id (FK → vaults), resource_address
  • source_type (TEXT discriminator: transaction | scan | recovery)
  • transaction_id (nullable, FK/ref → transactions; set iff source_type = transaction)
  • revealed_before, revealed_after, confidential_before, confidential_after (Amount as TEXT, matching vaults)
  • revealed_delta, confidential_delta (stored for query/sort convenience; Amount is signed)
  • created_at
  • Indexes on account_id, vault_id, transaction_id, created_at.
• New diesel model under src/models/, plus reader/writer impls in src/reader.rs / src/writer.rs.
• Decision noted: a wallet_events table already exists (WalletEvent::TransactionFinalized stores the full FinalizeResult JSON). It's a generic event blob, not structured per-vault deltas — not efficiently queryable/filterable for this UI or for linking deltas to a transaction. A dedicated structured table is recommended over overloading wallet_events.

2. SDK — tari_ootle_wallet_sdk (crates/wallet/sdk/)

• New model BalanceChange in src/models/ (e.g. balance_change.rs) carrying an enumerated source:

  // internally tagged so it serialises to a discriminated union the UI can switch on:
  //   { type: "Transaction", transaction_id } | { type: "Scan" } | { type: "Recovery" }
  #[serde(tag = "type")]
  pub enum BalanceChangeSource {
      /// Balance changed by a transaction tracked by this wallet (process_result path).
      Transaction { transaction_id: TransactionId },
      /// Discovered while (re)scanning the account's on-chain state — e.g. funds received
      /// from a transaction this wallet did not author (scanner.rs:143 path).
      Scan,
      /// Attributed to confidential UTXO recovery (optional; only if we can distinguish it).
      Recovery,
  }

  The enum is reconstructed from the source_type + nullable transaction_id columns. Keep it #[non_exhaustive]-friendly so new sources can be added without breaking the UI's exhaustiveness.
• WalletStoreWriter (src/storage/writer.rs): balance_changes_insert(change).
• WalletStoreReader (src/storage/reader.rs): paginated reads, e.g. balance_changes_get_by_account(account, offset, limit), balance_changes_get_by_vault(...), balance_changes_get_by_transaction(tx_id).
• AccountsApi (src/apis/accounts.rs): record on write (extend/wrap update_vault_balance so the before/after + tx are captured atomically in the same write tx) and a read method get_balance_changes(...).

3. Recording integration — crates/wallet/sdk_services/

• Thread a BalanceChangeSource into refresh_vault: Transaction { tx_id } from process_result (scanner.rs:516/:590), Scan from the account-scan path (scanner.rs:143).
• At scanner.rs:252-265, capture before/after revealed + confidential balances and write a BalanceChange when (and only when) the balance changed, in the same write transaction as update_vault_balance (idempotent — re-processing the same finalized tx must not double-log; only non-zero deltas recorded).
• New-vault path (scanner.rs:183-204, old balance = 0) flows through the same recording point.

4. JSON-RPC — tari_ootle_walletd (applications/tari_walletd/)

• New method accounts.get_balance_changes registered in the dispatch in src/server.rs (under the accounts.* arm) with a handler in src/handlers/accounts.rs.
• Request: account (address or name), optional resource_address filter, optional transaction_id filter, optional source_type filter, pagination (offset/limit). Response: ordered list (newest first) of balance-change entries (vault, resource, before/after, delta, the discriminated source, timestamp).
• Request/response types in clients/wallet_daemon_client/src/types.rs with the #[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export, export_to = "wallet-types/"))] derives (consistent with BalanceEntry).
• (Optional) allow transactions.get to include associated balance changes, or rely on the transaction_id filter above for the tx-detail view.

5. TS bindings + JS client

• Regenerate/hand-edit committed bindings in bindings/src/types/wallet-types/, bump the bindings package version, rebuild dist (per repo convention for ts-rs binding changes — no full build.sh regen).
• Add a convenience method on WalletDaemonClient in clients/javascript/wallet_daemon_client/src/index.ts.

6. UI — applications/tari_walletd/web_ui/ (React 19 + Vite + MUI)

• New React Query hook (e.g. useAccountBalanceChanges) in src/services/api/hooks/useAccounts.ts, supporting the vault/resource_address filter so it can be scoped to a single vault.
• Entry point — per-vault action on the assets/vault table: add a "View changes" / history icon button to each row of the vault table (AssetVault/Components/MyAssets.tsx / AssetVault/Tokens/Tokens.tsx, and the balances table on AccountDetails.tsx). Clicking it opens the balance-change log filtered to that vault (drawer/dialog, or a /accounts/:id/changes?vault=… route). This reuses the existing resource_address/vault filter on accounts.get_balance_changes.
• Also expose an account-wide view (all vaults) — e.g. a tab/section near AssetVault/Components/AccountBalance.tsx. Both surfaces share the same component, differing only by whether a vault filter is applied.
• Columns: timestamp, resource (symbol), signed delta, new balance, and a source column.
• Render the source by switching on its discriminant: Transaction → label + link to the tx detail page (/transactions/:id, src/routes/Transactions/TransactionDetails.tsx); Scan → e.g. "Received / on-chain sync"; Recovery → e.g. "Recovered". A default arm keeps unknown future sources rendering gracefully.
• Commit the rebuilt web_ui/dist.

---

Acceptance Criteria

Behaviour

• When a finalized transaction changes an account's vault balance (revealed and/or confidential), a balance-change entry is persisted in the wallet DB linked to that transaction.
• A single transaction that changes multiple vaults/accounts (e.g. self-transfer) produces one entry per affected vault, all linked to the same transaction_id.
• Every entry carries an enumerated source: Transaction { transaction_id } for wallet-tracked transactions, Scan for changes discovered by re-reading on-chain state (e.g. inbound funds the wallet didn't author), Recovery for confidential UTXO recovery. Non-transaction sources carry a null transaction_id (no fabricated link).
• Each entry captures before/after for both revealed and confidential balances and the signed delta.
• Entries are idempotent: re-scanning or re-processing the same finalized transaction does not create duplicates; only non-zero balance changes are logged.

JSON-RPC

• accounts.get_balance_changes returns an account's balance-change log, ordered newest-first, with pagination (offset/limit) and optional resource_address / transaction_id filters.
• Each returned entry includes vault, resource (+ symbol/divisibility), before/after, delta, source, transaction_id (nullable), and timestamp.
• Request/response types are exported via ts-rs into bindings/ and a typed method is available on the JS WalletDaemonClient.

Persistence / migration

• A new additive diesel migration creates the table; schema.rs regenerated; existing wallets upgrade without data loss or reset (down.sql provided).
• SDK WalletStoreReader/WalletStoreWriter traits and the SQLite impl expose insert + paginated query methods, covered by storage tests.

UI

• Each row of the vault/assets table has a "View changes" action that opens the balance-change log scoped to that vault.
• An account-wide balance-change log (all vaults) is also reachable, showing timestamp, resource, signed delta, new balance, and source.
• The source column renders per variant: Transaction entries link to that transaction's detail page; Scan/Recovery (and any future variant) render a meaningful label without a broken link.
• Bindings + JS client + web_ui/dist are rebuilt/committed and the UI builds cleanly.

Quality

• Unit/integration coverage for: tx-driven change, multi-vault tx, non-tx (recovery) change, idempotent re-scan, and the JSON-RPC handler.
• cargo +nightly-2025-12-05 fmt --all clean; workspace builds.

---

Open questions / decisions

1. Granularity: record per-vault (per-resource) changes with an account reference (recommended), vs an aggregated per-account snapshot. Per-vault preserves the resource + transaction linkage the UI needs.
2. Confidential amounts: record the wallet's known unspent confidential balance delta (from confidential_outputs_api), matching how vaults.confidential_balance is already maintained — confirm this is the intended semantic vs on-chain commitment counts.
3. Retention: unbounded log vs pruning/cap per account — likely fine unbounded initially; flag if a cap is wanted.
4. NFT vaults: revealed/confidential Amount is meaningful for fungible/confidential resources; decide whether NFT vault membership changes should appear in this log or remain out of scope.

[BWM0223]

Interested in this bounty. I have read the CLAUDE.md, the full spec, and traced the code path through AccountScanner::refresh_vault. Will start with the SQLite migration + SDK models, then thread tx_id through refresh_vault, add the JSON-RPC handler, regenerate TS bindings, and build the UI component. Will submit incremental PRs. Happy to coordinate.