rpc, doc: clarify watch-only wallets balances in RPCHelp #32761

1. 
   rkrux commented at 11:58 am on June 16, 2025: contributor

   The watch-only behaviour is per-wallet level in the descriptor wallets (the only kind of wallets now). The docs of the balance related RPCs seemed to be outdated to me. This patch adds a related note in both the balance related RPCS.
2. 
   DrahtBot commented at 11:58 am on June 16, 2025: contributor

   The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

   Code Coverage & Benchmarks

   For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/32761.

   Reviews

   See the guideline for information on the review process.

   Type	Reviewers
   ACK	Eunovo, BrandonOdiwuor

   If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.

3. 
   rkrux commented at 12:03 pm on June 16, 2025: contributor

   Essentially I want to convey the message that the watch-only wallets need not (read cannot) have corresponding private keys for the unspent outputs and thus they are not factored in the balance calculation.

   I’m open to changing the verbiage in the RPC docs if someone has a better suggestion.

4. 
   rkrux commented at 12:14 pm on June 16, 2025: contributor

   MSan, dependsFailing after 11s — Task Summary

   This failure seems unrelated to me as per the error messages from the CI run.

   0[07:58:31.196] Error: creating container storage: the container name "ci_native_msan" is already in use by a8395f5207b2bee3eff8c9392096e3e535820dcc96f5ced45dfe4256a1f6488b. You have to remove that container to be able to reuse that name: that name is already in use by an external entity, or use --replace to instruct Podman to do so.
   1[07:58:31.200] + CI_CONTAINER_ID=
   

5. DrahtBot added the label CI failed on Jun 17, 2025
6. DrahtBot removed the label CI failed on Jun 17, 2025
7. maflcko added the label Docs on Jun 17, 2025
8. maflcko added the label Wallet on Jun 17, 2025
9. maflcko added the label RPC/REST/ZMQ on Jun 17, 2025
10. 
    luke-jr commented at 6:20 pm on June 26, 2025: member

    I don’t get it. Watch-only wallets are treated the same as non-watch-only, aren’t they?
11. 
    Eunovo commented at 6:06 am on June 27, 2025: contributor

    @rkrux I think the include_watchonly param is also outdated and should be removed. Watch-only descriptor wallet balances are marked as spendable, so include_watchonly no longer serves any purpose.
12. in src/wallet/rpc/coins.cpp:171 in 220074ef09 outdated

    166@@ -167,7 +167,8 @@ RPCHelpMan getbalance()
    167         "getbalance",
    168         "Returns the total available balance.\n"
    169                 "The available balance is what the wallet considers currently spendable, and is\n"
    170-                "thus affected by options which limit spendability such as -spendzeroconfchange.\n",
    171+                "thus affected by options which limit spendability such as -spendzeroconfchange.\n"
    172+                "Note: For watch-only wallets, all the unspent outputs sent to wallet addresses are considered spendable.\n",
    

    ---

    ---

    

    Eunovo commented at 6:20 am on June 27, 2025:

    https://github.com/bitcoin/bitcoin/pull/32761/commits/220074ef094866386211db4d647d5ff1c93ba54e: Consider “Note: For watch-only wallets, this returns the balance of monitored addresses, but funds cannot actually be spent”

    ---

    

    rkrux commented at 12:36 pm on June 27, 2025:

    I have used this suggestion in the getbalances RPC, retained original (to some extent) in the getbalance one because it aligns closely with the current verbiage around the term “spendable”.
13. 
    maflcko commented at 6:28 am on June 27, 2025: member

    @rkrux I think the include_watchonly param is also outdated and should be removed. Watch-only descriptor wallet balances are marked as spendable, so include_watchonly no longer serves any purpose.

    See https://github.com/bitcoin/bitcoin/pull/32618

14. 
    rkrux commented at 11:42 am on June 27, 2025: contributor

    I don’t get it. Watch-only wallets are treated the same as non-watch-only, aren’t they?

    In a way, they are.

    The available balance is what the wallet considers currently spendable

    The current language^ in the RPC help made me curious regarding the balance shown for watch-only wallets because the watch-only wallets can’t technically spend them. I checked that the balance shown in the RPC response is correct for such wallets, and this prompted me to add a note specifically for these wallets.

15. rpc, doc: clarify watch-only wallets balances in RPCHelp

    The watch-only behaviour is per-wallet level in the descriptor
    wallets (the only kind of wallets now). The docs of the balance
    related RPCs seemed to be outdated to me. This patch adds a
    related note in both the balance related RPCS.

    cb44680db4
16. rkrux force-pushed on Jun 27, 2025
17. 
    Eunovo commented at 12:49 pm on June 27, 2025: contributor

    ACK https://github.com/bitcoin/bitcoin/pull/32761/commits/cb44680db40c85ba338f2a054511cd68ba6e89ba
18. 
    BrandonOdiwuor commented at 9:17 am on July 1, 2025: contributor

    Code Review ACK cb44680db40c85ba338f2a054511cd68ba6e89ba after reviewing https://github.com/bitcoin/bitcoin/pull/32618

Contributors
rkrux DrahtBot luke-jr Eunovo maflcko BrandonOdiwuor

Labels
Docs Wallet RPC/REST/ZMQ