wallet RPC to double-check the calculated balance #28898

issue maflcko opened this issue on November 17, 2023
  1. maflcko commented at 8:58 AM on November 17, 2023: member

    Please describe the feature you'd like to see added.

    Sometimes a user may put in the wrong birthdate when calling importdescriptors.

    Adding a checkbalance RPC (or a check argument to the getbalances RPC) to check that the calculated balance is correct by re-calculating it in a different way may be a solution. It could iterate over the utxo set for the check and then instruct for a rescan to restore missing transaction history and balance, if two different balances were calculated.

    Is your feature related to a problem, if so please describe it.

    #28897

    Describe the solution you'd like

    No response

    Describe any alternatives you've considered

    No response

    Please leave any additional context

    No response

  2. maflcko added the label Feature on Nov 17, 2023
  3. maflcko added the label Wallet on Nov 17, 2023
  4. maflcko added the label RPC/REST/ZMQ on Nov 17, 2023
  5. fjahr commented at 5:37 PM on November 23, 2023: contributor

    Allowing to call importdescriptors with the same descriptor but a different birthdate may also be a solution? Are users only interested in spendable outputs or may they also be interested in their transaction history in general?

  6. furszy commented at 9:17 PM on November 23, 2023: member

    An alternative/parallel course of action could be making rescanblockchain much faster. Removing the need for additional RPC calls to identify any missing tx. <start_shill> The user can build the block filter index in 5-10 minutes using #26966 (per Sjors's benchmark). And, with it, rescanblockchain performs at a completely different speed level. <end_shill>

  7. maflcko commented at 8:56 AM on November 24, 2023: member

    An alternative/parallel course of action could be making rescanblockchain much faster. Removing the need for additional RPC calls to identify any missing tx.

    I don't think this is an alternative, because the rescan won't find the txs if the birthdate is wrong, see also #28897? Moreover, on hardware without parallel cores, building the block filter index is not going to be sped up. Finally, on wallets with a sufficient number of keys, the blockfilter rescan may take longer than a "traditional" rescan, or at least time in the same magnitude.

  8. furszy commented at 2:23 PM on November 24, 2023: member

    the rescan won't find the txs if the birthdate is wrong

    The birth time check resides on the 'block connected' event handler. It does not affect the rescanblockchain functionality. Users can utilize it to identify missing transactions.

    see also #28897

    Fixed it few days ago, see #28920.

    Moreover, on hardware without parallel cores, building the block filter index is not going to be sped up

    That's true, but it's not a reason not to do it. The entire node is multi-threaded, and the user will need to call rescanblockchain sooner or later to obtain the latest wallet state (use missing tx outputs, see the final balance, etc.)

    I'm not going against your proposed changes (the getbalances scan_utxoset=true sounds good for me). But, just as a clarification; the user will still need to call rescanblockchain after calling getbalances to detect the transaction(s) history and any other possible branches of it. For instance, could be a case where the spendable utxo is part of a chain of transactions, so the wallet will need to scan the chain backwards. Which could also cause the wallet to surpass the look-ahead window (the 1k key pool), which could make the wallet identify other transactions along the way.

  9. S3RK commented at 3:43 PM on November 25, 2023: contributor

    Allowing to call importdescriptors with the same descriptor but a different birthdate may also be a solution? Are users only interested in spendable outputs or may they also be interested in their transaction history in general?

    This is already possible btw.

    Can we always double-check balance after importdescriptors? Why ask users to call a second RPC manually if we can do it automatically for them?

  10. musaHaruna commented at 7:51 AM on September 16, 2025: contributor

    Hi everyone,

    I’ve opened PR #28930 that attempts to resolve the issue.

    The PR extends the importdescriptors RPC with a new optional argument called scan_utxoset. When enabled, the wallet generates its scriptPubKeys and compares them against the chain’s UTXO set to compute UTXO set based balance. This balance is then compared with the wallet’s trusted balance. If the two match, the import proceeds as normal. If a discrepancy is found, the wallet automatically attempts incremental rescans in chunks of recent blocks until the missing history is located. On pruned nodes, these rescans do not go earlier than the prune boundary. The RPC also returns additional diagnostic information when scan_utxoset is used, under a new info object. This includes whether the UTXO set matched the wallet balance (utxo_check), the number of incremental rescans attempted (scanned_chunks), and the approximate number of blocks scanned during incremental rescans (scanned_blocks).

  11. sedited commented at 4:22 PM on October 30, 2026: contributor
  12. polespinasa commented at 10:40 AM on November 2, 2026: member

    I agree with what furszy says in #28898 (comment) and #28898 (comment). I don't see it worth to add another RPC call/argument for it. Users can always re-scan the chain in case they think they are missing transactions.

    #36236 adds an argument to importdescriptors to double check the balance in case the user is not secure of the birth time set. If that is the case, where the user knows that the birth time might be wrong, probably he should just set an obviously too-old birth time or just use 0. I don't see it worth the complexity when that situation can already be fixed with what we have now.

  13. maflcko commented at 10:45 AM on November 2, 2026: member

    ok, closing for now. Can be re-opened later, or discussion can continue in a new issue.

  14. maflcko closed this on Nov 2, 2026

  15. maflcko commented at 4:42 PM on November 10, 2026: member

    Users can always re-scan the chain in case they think they are missing transactions.

    I think the problem is that they may not know they are missing transactions. And rescanning to find out can be tedious (with or even without pruning).

    Sure, the birthdate issue was fixed, but that doesn't mean the other code is completely bug free. See e.g. #36828

    An option to scan the utxo set could act as a sanity check.

  16. polespinasa commented at 10:43 AM on November 13, 2026: member

    An option to scan the utxo set could act as a sanity check.

    Would be nice to benchmark how fast can we scan it, because if it is fast, we could do it by default and not set it as an option. Obviously it has to be really fast, but maybe there is some way of doing it with some bloom filters or similar, at the end we only need to know if the number of outputs mismatch, the value of them does not matter.

    I will try think a bit about it.

  17. musaHaruna commented at 8:03 PM on November 13, 2026: contributor

    Would be nice to benchmark how fast can we scan it, because if it is fast, we could do it by default and not set it as an option. Obviously it has to be really fast, but maybe there is some way of doing it with some bloom filters or similar, at the end we only need to know if the number of outputs mismatch, the value of them does not matter. @polespinasa I tried benchmarking (benchmark code) this with FindCoinsByScript on my branch to see how much time the scan takes. I used generated UTXOs in a database stored on disk, and changed the number of scripts, matching outputs and dirty coins.

    I ran it on my Apple M5 with 16 GiB RAM, macOS 26, using a Release build. Each number is the median of 11 full scans.

    Case 10,000 UTXOs 100,000 UTXOs 1,000,000 UTXOs
    1 script, no matches 5.81 ms 36.22 ms 336.29 ms
    1,000 scripts, no matches 5.93 ms 44.20 ms 404.68 ms
    10,000 scripts, no matches 7.22 ms 49.35 ms 438.62 ms
    1,000 scripts, 10 matching outputs 6.27 ms 43.59 ms 407.79 ms
    1,000 scripts, 10% matching outputs 6.14 ms 45.51 ms 430.62 ms
    1,000 scripts, 10,000 dirty coins, no matches 21.55 ms 59.81 ms 410.82 ms

    To put the size into perspective, if the time per UTXO stayed the same, scanning 164 million UTXOs would take roughly 55–72 seconds based on the no-match cases. For example, the 1,000-script case gives 0.40468 seconds × 164 ≈ 66.37 seconds. That is just scaling the numbers above; I haven’t run the benchmark at that size, and cache behaviour could change.

    I haven’t tried a Bloom filter or changed the scan to only count matches yet. These give us some numbers to start with, but I'm not sure if this alone tells us whether we should do UTXO scan by default.

  18. polespinasa commented at 8:46 PM on November 13, 2026: member

    scanning 164 million UTXOs would take roughly 55–72 seconds based on the no-match cases

    Yeah this is too slow to do it by default, we cannot let users with a 1min delay response in an RPC call.


github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin/bitcoin. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2026-11-21 11:52 UTC

This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me