#36236 wallet, rpc: add verify_balance option to importdescriptors

full analysis

https://github.com/bitcoin/bitcoin/pull/36236 · musaHaruna · +584/-47 in 9 files, 4 commits · labels: Needs rebase

Goal

  • Prevent missing funds when importing descriptors by verifying balances against the UTXO set
  • Automatically extends rescan backwards if older unspent payments were missed due to a bad timestamp

Adds an optional `verify_balance` boolean argument to `importdescriptors`. When enabled, it scans the chainstate UTXO set for outputs matching the wallet's known scripts, automatically extends the rescan backwards to the earliest missing output if any are missing, and returns verification details comparing chainstate and wallet UTXOs.

Problem: When importing descriptors, users or external tools often supply a timestamp that is too recent, leading to a truncated rescan that omits older unspent payments and reports an incomplete wallet balance.

Category: Wallet (#63 of 84)

P3 · new feature

  • P3 because it offers a helpful usability safety check for users importing descriptors
  • Protects against bad import timestamps but users can already avoid this by scanning from genesis

Provides a clear usability improvement for a recognized pain point (#28898) where users miss UTXOs due to bad import timestamps. The problem can already be avoided by specifying an accurate timestamp or scanning from genesis, making this a worthwhile but deferrable optional enhancement.

Membership: Modifies descriptor import and rescan logic in src/wallet/rpc/backup.cpp and adds UTXO scanning helpers in src/wallet/receive.cpp.

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

Reviewability: Stale: Needs rebase

  • Review is blocked by merge conflicts against the base branch
  • Needs rebase before review can proceed

The PR has merge conflicts against the base branch and is marked with the Needs rebase label.

Author status: active

Agreement: Crickets

  • No reviews or feedback yet from any reviewers
  • Recently opened without concept comments

No reviews or comments yet

The PR was recently opened and has received no review comments or concept feedback.

Review verdicts (DrahtBot): 0

Files

250 lines under test/bench/ci.

  • src/wallet/rpc/backup.cpp +231/-47
  • test/functional/wallet_importdescriptors.py +250/-0
  • src/wallet/receive.cpp +35/-0
  • src/node/coin.cpp +31/-0
  • 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

This PR adds an optional verify_balance argument to the importdescriptors RPC to cross-check imported wallet outputs against a chainstate UTXO scan. If unspent coins are missing due to an overly recent import timestamp, it automatically extends the rescan back to the earliest missing coin's block height. It addresses issue #28898 regarding incorrect wallet balances after descriptor imports. The PR currently has merge conflicts and needs a rebase before review, with no reviewer feedback recorded yet.

Data

dossier JSON · extract JSON · model openrouter/google/gemini-3.8-flash, generated 2026-09-17T16:24, confidence high, input hash bf3000e416a60d78