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

pull rkrux wants to merge 1 commits into bitcoin:master from rkrux:watchonly-balance changing 1 files +4 −2
  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. BrandonOdiwuor commented at 9:17 am on July 1, 2025: contributor
    Code Review ACK cb44680db40c85ba338f2a054511cd68ba6e89ba after reviewing https://github.com/bitcoin/bitcoin/pull/32618

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: 2025-07-08 12:13 UTC

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