Skip to content

Commit 53e7ed0

Browse files
committed
doc: Release notes and other docs for migration
1 parent 9c44bfe commit 53e7ed0

File tree

2 files changed

+35
-1
lines changed

2 files changed

+35
-1
lines changed

doc/managing-wallets.md

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -120,4 +120,29 @@ After that, `getwalletinfo` can be used to check if the wallet has been fully re
120120
$ bitcoin-cli -rpcwallet="restored-wallet" getwalletinfo
121121
```
122122

123-
The restored wallet can also be loaded in the GUI via `File` ->`Open wallet`.
123+
The restored wallet can also be loaded in the GUI via `File` ->`Open wallet`.
124+
125+
## Migrating Legacy Wallets to Descriptor Wallets
126+
127+
Legacy wallets (traditional non-descriptor wallets) can be migrated to become Descriptor wallets
128+
through the use of the `migratewallet` RPC. Migrated wallets will have all of their addresses and private keys added to
129+
a newly created Descriptor wallet that has the same name as the original wallet. Because Descriptor
130+
wallets do not support having private keys and watch-only scripts, there may be up to two
131+
additional wallets created after migration. In addition to a descriptor wallet of the same name,
132+
there may also be a wallet named `<name>_watchonly` and `<name>_solvables`. `<name>_watchonly`
133+
contains all of the watchonly scripts. `<name>_solvables` contains any scripts which the wallet
134+
knows but is not watching the corresponding P2(W)SH scripts.
135+
136+
Migrated wallets will also generate new addresses differently. While the same BIP 32 seed will be
137+
used, the BIP 44, 49, 84, and 86 standard derivation paths will be used. After migrating, a new
138+
backup of the wallet(s) will need to be created.
139+
140+
Given that there is an extremely large number of possible configurations for the scripts that
141+
Legacy wallets can know about, be watching for, and be able to sign for, `migratewallet` only
142+
makes a best effort attempt to capture all of these things into Descriptor wallets. There may be
143+
unforeseen configurations which result in some scripts being excluded. If a migration fails
144+
unexpectedly or otherwise misses any scripts, please create an issue on GitHub. A backup of the
145+
original wallet can be found in the wallet directory with the name `<name>-<timestamp>.legacy.bak`.
146+
147+
The backup can be restored using the `restorewallet` command as discussed in the
148+
[Restoring the Wallet From a Backup](#16-restoring-the-wallet-from-a-backup) section

doc/release-notes-19602.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
Wallet
2+
======
3+
4+
Migrating Legacy Wallets to Descriptor Wallets
5+
---------------------------------------------
6+
7+
An experimental RPC `migratewallet` has been added to migrate Legacy (non-descriptor) wallets to
8+
Descriptor wallets. More information about the migration process is available in the
9+
[documentation](https://github.com/bitcoin/bitcoin/blob/master/doc/managing-wallets.md#migrating-legacy-wallets-to-descriptor-wallets).

0 commit comments

Comments
 (0)