From 53e7ed075c49f853cc845afc7b2f058cabad0cb0 Mon Sep 17 00:00:00 2001 From: Andrew Chow Date: Thu, 11 Aug 2022 15:59:01 -0400 Subject: doc: Release notes and other docs for migration --- doc/managing-wallets.md | 27 ++++++++++++++++++++++++++- doc/release-notes-19602.md | 9 +++++++++ 2 files changed, 35 insertions(+), 1 deletion(-) create mode 100644 doc/release-notes-19602.md (limited to 'doc') diff --git a/doc/managing-wallets.md b/doc/managing-wallets.md index 6c1e13c503..366d7ec54b 100644 --- a/doc/managing-wallets.md +++ b/doc/managing-wallets.md @@ -120,4 +120,29 @@ After that, `getwalletinfo` can be used to check if the wallet has been fully re $ bitcoin-cli -rpcwallet="restored-wallet" getwalletinfo ``` -The restored wallet can also be loaded in the GUI via `File` ->`Open wallet`. \ No newline at end of file +The restored wallet can also be loaded in the GUI via `File` ->`Open wallet`. + +## Migrating Legacy Wallets to Descriptor Wallets + +Legacy wallets (traditional non-descriptor wallets) can be migrated to become Descriptor wallets +through the use of the `migratewallet` RPC. Migrated wallets will have all of their addresses and private keys added to +a newly created Descriptor wallet that has the same name as the original wallet. Because Descriptor +wallets do not support having private keys and watch-only scripts, there may be up to two +additional wallets created after migration. In addition to a descriptor wallet of the same name, +there may also be a wallet named `_watchonly` and `_solvables`. `_watchonly` +contains all of the watchonly scripts. `_solvables` contains any scripts which the wallet +knows but is not watching the corresponding P2(W)SH scripts. + +Migrated wallets will also generate new addresses differently. While the same BIP 32 seed will be +used, the BIP 44, 49, 84, and 86 standard derivation paths will be used. After migrating, a new +backup of the wallet(s) will need to be created. + +Given that there is an extremely large number of possible configurations for the scripts that +Legacy wallets can know about, be watching for, and be able to sign for, `migratewallet` only +makes a best effort attempt to capture all of these things into Descriptor wallets. There may be +unforeseen configurations which result in some scripts being excluded. If a migration fails +unexpectedly or otherwise misses any scripts, please create an issue on GitHub. A backup of the +original wallet can be found in the wallet directory with the name `-.legacy.bak`. + +The backup can be restored using the `restorewallet` command as discussed in the +[Restoring the Wallet From a Backup](#16-restoring-the-wallet-from-a-backup) section diff --git a/doc/release-notes-19602.md b/doc/release-notes-19602.md new file mode 100644 index 0000000000..61d6aa8ca9 --- /dev/null +++ b/doc/release-notes-19602.md @@ -0,0 +1,9 @@ +Wallet +====== + +Migrating Legacy Wallets to Descriptor Wallets +--------------------------------------------- + +An experimental RPC `migratewallet` has been added to migrate Legacy (non-descriptor) wallets to +Descriptor wallets. More information about the migration process is available in the +[documentation](https://github.com/bitcoin/bitcoin/blob/master/doc/managing-wallets.md#migrating-legacy-wallets-to-descriptor-wallets). -- cgit v1.2.3