#36236 wallet, rpc: add verify_balance option to importdescriptors

ReviewabilityReviewsAgreementSize
#36236 musaHaruna wallet, rpc: add verify_balance option to importdescriptorsNeeds rebase0Crickets320 + 250 tests
  • Prevent missed transactions and inaccurate balances when importing descriptors with too-recent timestamps
  • Let users verify imported wallet balances against the active chainstate UTXO set
  • Reviewable now, with no blockers or rebases required
  • No review verdicts recorded
  • No external review comments yet
  • 320 lines added or modified outside tests
  • 250 lines added or modified in tests
  • 46 lines removed in total
  • 11 files, 4 commits
Wallet#51 of 92
P3 · user request
  • P3 because it helps users who import descriptors avoid silent balance inaccuracies
  • Directly resolves a user-requested check against the active UTXO set
  • Ranking pass: Kept with the descriptor-import feature group.
Ranking notes
Reviewability: ReadyStalePaused
Agreement: StrongPositivePositive w/ caveatsNeutralMildDisputedBlockedCrickets
Reviews: current code-review ACKs, then (+stale ACKs) and -NACKs; greener = more ACKs.
Size: lines added or modified outside tests, then in tests; greener = smaller.

Goal

Adds an optional `verify_balance` parameter to the `importdescriptors` RPC that validates the wallet's confirmed UTXOs against the active chainstate. When enabled, it flushes and cursors through the chainstate UTXO database for outputs matching the wallet's scripts, automatically extends the rescan start height backward to the earliest missing UTXO if one is detected before the requested timestamp, and returns a verification report comparing wallet and chainstate UTXOs.

Problem: Users importing descriptors often specify a timestamp that is too recent (such as wallet creation time or "now" when receiving addresses were funded earlier), causing the rescan to miss transactions and leaving the wallet with an incomplete UTXO set and inaccurate balance.

Evidence of importance:

  • PR description: "When importing descriptors, users may provide a timestamp that is too recent. This causes the rescan to miss older payments, leaving the wallet with an incomplete balance."
  • Referenced issue #28898 ("wallet RPC to double-check the calculated balance") requests a mechanism to verify wallet balances against the node's UTXO set.

Scope: The implementation forces a flush of the in-memory coins cache to disk and scans the entire on-disk coins database with a `CCoinsViewCursor` to filter by scriptPubKey, which may have significant disk I/O implications on full nodes.

Reviewability

Ready · Needs rebase

Conflicts with master; review the logic now, the rebase is mechanical.

Agreement

Crickets

no substantive comment either way

Thread notes: Initial record. No external reviewers have commented yet.

Objections, suggestions, and questions: none recorded.

Files

250 lines under test/bench/ci.

  • test/functional/wallet_importdescriptors.py +250/-0
  • src/wallet/imports.cpp +148/-44
  • src/wallet/rpc/backup.cpp +55/-1
  • src/wallet/receive.cpp +35/-0
  • src/node/coin.cpp +31/-0
  • src/wallet/imports.h +14/-1
  • src/node/coin.h +14/-0
  • src/wallet/receive.h +11/-0
  • src/interfaces/chain.h +7/-0
  • src/node/interfaces.cpp +4/-0
  • src/rpc/client.cpp +1/-0

Card

The short text the ranking pass compares across PRs.

Adds an optional verify_balance argument to importdescriptors that checks wallet UTXOs against the chainstate database. If a user imports descriptors with a timestamp that is too recent, rescans miss historical payments and show an incomplete balance; this option checks on-disk UTXOs for wallet scripts, pulls the rescan backward to the earliest missing UTXO height, and validates matching outpoints. This addresses issue #28898 to help users verify and recover missing wallet funds during descriptor imports.

Data

dossier JSON · extract JSON · model ledger, generated 2026-09-18T03:48, confidence high, input hash 2bacaa740434ccdc
thread read through 2026-09-17 (1 statements), head 4da013f50b
Discussion read under schema 1 rules: suggestions and questions may be missing, and an objection may combine several harms (schema history).
labels: Needs rebase

Categories

Wallet

P3 · user request (ranking pass: Kept with the descriptor-import feature group.)

Prevents incomplete balances when importing descriptors with inaccurate timestamps by scanning chainstate UTXOs. Directly addresses user request issue #28898 for wallet balance verification.

Membership: Modifies descriptor import logic in `src/wallet/imports.cpp` and `src/wallet/rpc/backup.cpp` to verify balances and adjust rescan heights.

Factors: security/stability 0, bug 0, performance 0, user value 2, leverage 0