Fixes #28898 Users who import descriptors with incorrect birthdates may encounter inaccurate wallet balances. In such cases, the wallet may miss historical transactions that belong to it, resulting in underreported balances. Currently, the only way to correct this is to manually run rescanblockchain or reimport descriptors with proper metadata. However, users may not realize that their wallet balance is incomplete. This PR introduces a mechanism for wallets to verify their trusted balance against the UTXO set. By rescanning the current UTXO set, the wallet can detect discrepancies and suggest corrective actions to the user.
Features Adds a scan_utxoset argument to both getbalance and getbalances RPCs. When enabled: The wallet collects all scriptPubKeys from its descriptors. The node scans the chainstate UTXO set for matching outputs. A scanned balance is calculated independently of the wallet’s transaction history.
If the scanned balance differs from the wallet’s trusted balance: The result includes a utxo_discrepancy object with both balances and a suggested action. Users are advised to run rescanblockchain or reimport descriptors with correct birthdates.
Example usage
Normal trusted balance
$ bitcoin-cli getbalance
0.01000000
With UTXO set scan
0$ bitcoin-cli getbalance "* 0 false false true"
1{
2 "amount": 0.01000000,
3 "scanned_amount": 0.01500000,
4 "warnings": "Scanned UTXO balance (0.01500000 BTC) is larger than the wallet's trusted balance (0.01000000 BTC). If this is unexpected, consider running rescanblockchain or reimporting descriptors with correct birthdates to restore missing transaction history."
5}
6
7$ bitcoin-cli getbalances true
8{
9 "mine": {
10 "trusted": 0.01000000,
11 "untrusted_pending": 0.00000000,
12 "immature": 0.00000000
13 },
14 "utxo_scanned_balance": 0.01500000,
15 "utxo_discrepancy": {
16 "wallet_trusted_balance": 0.01000000,
17 "utxo_scanned_balance": 0.01500000,
18 "suggested_action": "If this is unexpected, consider running rescanblockchain or reimporting descriptors with correct birthdates to restore missing transaction history."
19 },
20 "lastprocessedblock": {
21 "height": 900000,
22 "hash": "000000000000000..."
23 }
24}
Implementation Notes
Introduces FindCoinsByScript to scan the chainstate UTXO set for a set of scripts.
ScanWalletUTXOSet aggregates spendable/watched outputs and tallies balances.
Results are merged into existing getbalance / getbalances RPCs behind a new scan_utxoset flag.
Coinbase maturity rules are applied consistently.
Review Notes This does not replace rescanblockchain; it only provides a diagnostic check. For large wallets, UTXO scans may be expensive but should complete faster than a full rescan. Maintains backwards compatibility by defaulting scan_utxoset=false. Adds optional result fields only when scan_utxoset is enabled.
