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.

    <!-- *** Please remove the following help text before submitting: *** Pull requests without a rationale and clear improvement may be closed immediately. GUI-related pull requests should be opened against https://github.com/bitcoin-core/gui first. See CONTRIBUTING.md -->

    <!-- Please provide clear motivation for your patch and explain how it improves Bitcoin Core user experience or Bitcoin Core developer experience significantly: * Any test improvements or new tests that improve coverage are always welcome. * All other changes should have accompanying unit tests (see `src/test/`) or functional tests (see `test/`). Contributors should note which tests cover modified code. If no tests exist for a region of modified code, new tests should accompany the change. * Bug fixes are most welcome when they come with steps to reproduce or an explanation of the potential issue as well as reasoning for the way the bug was fixed. * Features are welcome, but might be rejected due to design or scope issues. If a feature is based on a lot of dependencies, contributors should first consider building the system outside of Bitcoin Core, if possible. * Refactoring changes are only accepted if they are required for a feature or bug fix or otherwise improve developer experience significantly. For example, most "code style" refactoring changes require a thorough explanation why they are useful, what downsides they have and why they *significantly* improve developer experience or avoid serious programming bugs. Note that code style is often a subjective matter. Unless they are explicitly mentioned to be preferred in the [developer notes](/doc/developer-notes.md), stylistic code changes are usually rejected. -->

    <!-- Bitcoin Core has a thorough review process and even the most trivial change needs to pass a lot of eyes and requires non-zero or even substantial time effort to review. There is a huge lack of active reviewers on the project, so patches often sit for a long time. -->

  2. DrahtBot commented at 11:58 AM on June 16, 2025: contributor

    <!--e57a25ab6845829454e8d69fc972939a-->

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

    <!--006a51241073e994b41acfe9ec718e94-->

    Code Coverage & Benchmarks

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

    <!--021abf342d371248e50ceaed478a90ca-->

    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.

    <!--5faf32d7da4f0f540f40219e4f7537a3-->

  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.

    [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.
[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
  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

  19. achow101 commented at 10:11 PM on July 25, 2025: member

    I don't really think this change is necessary, especially with the removal of watch-only within a wallet.

  20. rkrux closed this on Jul 28, 2025
Contributors
rkruxDrahtBotluke-jrEunovomaflckoBrandonOdiwuorachow101
Labels
DocsWalletRPC/REST/ZMQ
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-05-03 21:12 UTC
This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me