doc: add note for watch-only wallet migration #32866

pull rkrux wants to merge 1 commits into bitcoin:master from rkrux:watchonly-migration changing 1 files +7 −4

rkrux commented at 11:57 AM on July 3, 2025: contributor

This was suggested in a previous PR #31423.
DrahtBot added the label Docs on Jul 3, 2025
DrahtBot commented at 11:57 AM on July 3, 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/32866.



Reviews

See the guideline for information on the review process.

Type Reviewers

ACK brunoerg, jonatack, achow101

Stale ACK furszy

If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.
Sammie05 commented at 2:47 AM on July 13, 2025: none

Checked this branch locally. the added note clarifies what happens if the legacy wallet only contains watch-only scripts. It helps make migration behavior clearer for users. it actually Looks good to me! Also noticed the LLM linter suggested rewording ‘which the wallet knows but is not watching…’ maybe worth considering for clarity. Thanks for adding this
furszy commented at 10:49 PM on July 15, 2025: member

ACK 9d25880bb720bc675a533098268b9e02f86e17ce
brunoerg approved
brunoerg commented at 8:03 PM on July 24, 2025: contributor

ACK 9d25880bb720bc675a533098268b9e02f86e17ce

Happy to re-ack if you touch it again to address the LLM linter suggestion.

Type	Reviewers
ACK	brunoerg, jonatack, achow101
Stale ACK	furszy

in doc/managing-wallets.md:155 in 9d25880bb7 outdated

 152 |  contains all of the watchonly scripts. `<name>_solvables` contains any scripts which the wallet
 153 | -knows but is not watching the corresponding P2(W)SH scripts.
 154 | +knows but is not watching the corresponding P2(W)SH scripts. In case, the legacy wallet doesn't
 155 | +contain the private key materials and contains only the watch-only scripts, then only the
 156 | +`<name>_watchonly` wallet will be created and the descriptor wallet with the same name will not
 157 | +be created. Additionally, the created watch-only descriptor wallet will not have private keys enabled.

achow101 commented at 10:17 PM on July 25, 2025:

The first sentences starts oddly to me. I would write it as

If the legacy wallet only contains watch-only scripts and no private keys, then only <name>_watchonly ...

rkrux commented at 9:29 AM on July 28, 2025:

Done

rkrux force-pushed on Jul 28, 2025
rkrux commented at 9:29 AM on July 28, 2025: contributor

ACK 9d25880

Happy to re-ack if you touch it again to address the LLM linter suggestion.

Done
brunoerg commented at 11:01 AM on July 28, 2025: contributor

reACK 3d7a0219a9819e67690ed5acfc1331703dd0eb3a
DrahtBot requested review from furszy on Jul 28, 2025

in doc/managing-wallets.md:148 in 3d7a0219a9 outdated

 144 | @@ -145,11 +145,14 @@ If the wallet passphrase is too complex and is subsequently forgotten or lost, t
 145 |  Legacy wallets (traditional non-descriptor wallets) can be migrated to become Descriptor wallets
 146 |  through the use of the `migratewallet` RPC. Migrated wallets will have all of their addresses and private keys added to
 147 |  a newly created Descriptor wallet that has the same name as the original wallet. Because Descriptor
 148 | -wallets do not support having private keys and watch-only scripts, there may be up to two
 149 | +wallets do not support having private keys and watch-only scripts together, there may be up to two

jonatack commented at 11:28 PM on July 28, 2025:

wallets do not support having both private keys and watch-only scripts, there may be up to two

also s/Because/As/ at the start of the sentence

in doc/managing-wallets.md:151 in 3d7a0219a9 outdated

 144 | @@ -145,11 +145,14 @@ If the wallet passphrase is too complex and is subsequently forgotten or lost, t
 145 |  Legacy wallets (traditional non-descriptor wallets) can be migrated to become Descriptor wallets
 146 |  through the use of the `migratewallet` RPC. Migrated wallets will have all of their addresses and private keys added to
 147 |  a newly created Descriptor wallet that has the same name as the original wallet. Because Descriptor
 148 | -wallets do not support having private keys and watch-only scripts, there may be up to two
 149 | +wallets do not support having private keys and watch-only scripts together, there may be up to two
 150 |  additional wallets created after migration. In addition to a descriptor wallet of the same name,
 151 |  there may also be a wallet named `<name>_watchonly` and `<name>_solvables`. `<name>_watchonly`
 152 |  contains all of the watchonly scripts. `<name>_solvables` contains any scripts which the wallet

jonatack commented at 11:28 PM on July 28, 2025:

contains all of the watchonly scripts. `<name>_solvables` contains any scripts that the wallet

jonatack commented at 11:30 PM on July 28, 2025: member

Approach ACK
rkrux force-pushed on Jul 29, 2025
doc: add note for watch-only wallet migration
This was suggested in a previous PR 31423.
5888b4a2a5
rkrux force-pushed on Jul 29, 2025
rkrux requested review from jonatack on Jul 29, 2025
brunoerg approved
brunoerg commented at 12:47 PM on July 29, 2025: contributor

reACK 5888b4a2a5566c64141b78a0e7660a166ec99775

minimal changes since my last review.
jonatack commented at 2:18 PM on July 29, 2025: member

ACK 5888b4a2a5566c64141b78a0e7660a166ec99775

(fwiw, it's unclear to me in this document why sometimes we write "Descriptor" and other times "descriptor")
achow101 commented at 6:06 PM on July 29, 2025: member

ACK 5888b4a2a5566c64141b78a0e7660a166ec99775
achow101 merged this on Jul 29, 2025
achow101 closed this on Jul 29, 2025

Contributors

Review Requested
furszy

Labels

Docs

Linked (view graph)

#31423 wallet: migration, avoid creating spendable wallet from a watch-only legacy wallet

doc: add note for watch-only wallet migration #32866

Code Coverage & Benchmarks

Reviews