Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion doc/managing-wallets.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,9 @@ 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
through the use of the `migratewallet` RPC. Migration is experimental and must be enabled by starting
the node with `-walletmigration`, which also shows the `File` -> `Migrate Wallet` menu item in the GUI.

@knst knst Nov 3, 2026 •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

concept NACK, bitcoin core removing all command lines such as this -rescan, etc, I would not introduce it because it's quite abnormal and not justmatching with usptream but a step backwards

My agent says beyond that:

Concept NACK on the startup option. The goal (not exposing users to the failure-handling bugs before #8014 lands) is fine, the mechanism is not.

  1. It is not upstream, and upstream had the same situation. Bitcoin Core shipped migratewallet in v24.0 as an experimental RPC with no gate at all (doc/release-notes.md, "An 
  experimental RPC migratewallet has been added"), dropped the experimental warning in bitcoin#28037, and fixed the failure-handling bugs that #8014 backports only in bitcoin#34156 and
  its follow-ups, years later. They never added a startup gate for it. Our v24 ships the same code plus more fixes than their v24 had.

  2. Bitcoin Core has consistently removed one-shot wallet operations from the command line in favour of RPCs and tools, never the reverse:
  - bitcoin#15761 replaced -upgradewallet with the upgradewallet RPC
  - bitcoin#18918 moved -salvagewallet into the wallet tool
  - bitcoin#23123 removed -rescan in favour of rescanblockchain (we backported it in #7037, marked breaking)
  - bitcoin#28787 removed the last trace of -zapwallettxes (we backported it in #7074)
  Each of those removals was a breaking change that needed release notes. Adding a new startup flag for a wallet operation now means repeating one of those removals later.

  3. Removing it later is itself breaking. An unknown option on the command line makes dashd refuse to start ("Error parsing command line arguments"); only config-file entries are 
  merely warned about. So "flip the default or remove the option once #8014 lands" is not free: it needs its own deprecation cycle for a flag introduced for one release candidate.

  4. It does not fix anything. The gate only hides the RPC. A user who sets the flag hits exactly the bugs #8014 fixes. If migration is too broken to ship, the right call is to land 
  #8014 (about 300 lines in src, most of it wallet.cpp, plus tests) or to ship the RPC as experimental the way upstream did for two releases. Hiding it behind a Dash-only option is 
  neither.

  5. The GUI argument does not need an option. If File -> Migrate Wallet is the concern because the GUI drops the wallet model before calling in, hide or disable that menu item 
  unconditionally in bitcoingui.cpp for 24.0. That is a one-line GUI change with nothing to remove from init.cpp, wallet.cpp, dummywallet.cpp, the docs and the test harness later.

  6. Every file this touches is a wallet file we backport regularly: wallet.cpp, wallet/init.cpp, rpc/wallet.cpp, bitcoingui.cpp, dummywallet.cpp, wallet_migration.py. A Dash-only 
  option there is conflict surface for every future wallet backport, and AGENTS.md asks us to stay aligned with upstream absent a Dash-specific correctness reason. The only startup 
  option upstream labels experimental is -txreconciliation, a P2P protocol feature that is node-level by nature, not a gate on an 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,
Expand Down
3 changes: 2 additions & 1 deletion doc/release-notes-19602.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,5 +5,6 @@ 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
Descriptor wallets. It is disabled by default: start the node with `-walletmigration` to use it, which
also shows the `File` -> `Migrate Wallet` menu item in the GUI. More information about the migration process is available in the
[documentation](https://github.com/dashpay/dash/blob/master/doc/managing-wallets.md#migrating-legacy-wallets-to-descriptor-wallets).
1 change: 1 addition & 0 deletions src/dummywallet.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@ void DummyWalletInit::AddWalletOptions(ArgsManager& argsman) const
"-walletbackupsdir=<dir>",
"-walletbroadcast",
"-walletdir=<dir>",
"-walletmigration",
"-walletnotify=<cmd>",
"-discardfee=<amt>",
"-fallbackfee=<amt>",
Expand Down
3 changes: 3 additions & 0 deletions src/qt/bitcoingui.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,8 @@
#include <qt/walletframe.h>
#include <qt/walletmodel.h>
#include <qt/walletview.h>

#include <wallet/wallet.h>
#endif // ENABLE_WALLET

#ifdef Q_OS_MACOS
Expand Down Expand Up @@ -623,6 +625,7 @@ void BitcoinGUI::createActions()
connect(m_close_all_wallets_action, &QAction::triggered, [this] {
m_wallet_controller->closeAllWallets(this);
});
m_migrate_wallet_action->setVisible(gArgs.GetBoolArg("-walletmigration", wallet::DEFAULT_WALLET_MIGRATION));
connect(m_migrate_wallet_action, &QAction::triggered, [this] {
auto activity = new MigrateWalletActivity(m_wallet_controller, this);
connect(activity, &MigrateWalletActivity::migrated, this, &BitcoinGUI::setCurrentWallet);
Expand Down
1 change: 1 addition & 0 deletions src/wallet/init.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,7 @@ void WalletInit::AddWalletOptions(ArgsManager& argsman) const
argsman.AddArg("-walletbackupsdir=<dir>", "Specify full path to directory for automatic wallet backups (must exist)", ArgsManager::ALLOW_ANY, OptionsCategory::WALLET);
argsman.AddArg("-walletbroadcast", strprintf("Make the wallet broadcast transactions (default: %u)", DEFAULT_WALLETBROADCAST), ArgsManager::ALLOW_ANY, OptionsCategory::WALLET);
argsman.AddArg("-walletdir=<dir>", "Specify directory to hold wallets (default: <datadir>/wallets if it exists, otherwise <datadir>)", ArgsManager::ALLOW_ANY | ArgsManager::NETWORK_ONLY, OptionsCategory::WALLET);
argsman.AddArg("-walletmigration", strprintf("Allow migrating legacy wallets to descriptor wallets with the experimental migratewallet RPC and the GUI Migrate Wallet menu item (default: %u)", DEFAULT_WALLET_MIGRATION), ArgsManager::ALLOW_ANY, OptionsCategory::WALLET);
#if HAVE_SYSTEM
argsman.AddArg("-walletnotify=<cmd>", "Execute command when a wallet transaction changes. %s in cmd is replaced by TxID, %w is replaced by wallet name, %b is replaced by the hash of the block including the transaction (set to 'unconfirmed' if the transaction is not included) and %h is replaced by the block height (-1 if not included). %w is not currently implemented on windows. On systems where %w is supported, it should NOT be quoted because this would break shell escaping used to invoke the command.", ArgsManager::ALLOW_ANY, OptionsCategory::WALLET);
#endif
Expand Down
3 changes: 2 additions & 1 deletion src/wallet/rpc/wallet.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -1136,7 +1136,8 @@ static RPCHelpMan migratewallet()
"file will be named <wallet name>-<timestamp>.legacy.bak and can be found in the directory\n"
"for this wallet. In the event of an incorrect migration, the backup can be restored using restorewallet."
"\nEncrypted wallets must have the passphrase provided as an argument to this call.\n"
"\nThis RPC may take a long time to complete. Increasing the RPC client timeout is recommended.",
"\nThis RPC may take a long time to complete. Increasing the RPC client timeout is recommended.\n"
"\nThis RPC is experimental and requires the -walletmigration startup option.",
{
{"wallet_name", RPCArg::Type::STR, RPCArg::DefaultHint{"the wallet name from the RPC endpoint"}, "The name of the wallet to migrate. If provided both here and in the RPC endpoint, the two must be identical."},
{"passphrase", RPCArg::Type::STR, RPCArg::Optional::OMITTED, "The wallet passphrase"},
Expand Down
4 changes: 4 additions & 0 deletions src/wallet/wallet.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -5150,6 +5150,10 @@ bool DoMigration(CWallet& wallet, WalletContext& context, bilingual_str& error,

util::Result<MigrationResult> MigrateLegacyToDescriptor(const std::string& wallet_name, const SecureString& passphrase, WalletContext& context)
{
if (!context.args || !context.args->GetBoolArg("-walletmigration", DEFAULT_WALLET_MIGRATION)) {
return util::Error{Untranslated("Wallet migration is experimental and disabled by default. Restart with -walletmigration to enable it.")};
}

MigrationResult res;
bilingual_str error;
std::vector<bilingual_str> warnings;
Expand Down
2 changes: 2 additions & 0 deletions src/wallet/wallet.h
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,8 @@ static const unsigned int DEFAULT_TX_CONFIRM_TARGET = 6;
static const bool DEFAULT_WALLETBROADCAST = true;
static const bool DEFAULT_DISABLE_WALLET = false;
static const bool DEFAULT_WALLETCROSSCHAIN = false;
//! -walletmigration default
static constexpr bool DEFAULT_WALLET_MIGRATION{false};
//! -dustprotectionthreshold default (0 = disabled)
static constexpr CAmount DEFAULT_DUST_PROTECTION_THRESHOLD{0};
//! -dustprotectionthreshold maximum (matches GUI spinbox cap)
Expand Down
20 changes: 20 additions & 0 deletions test/functional/wallet_migration.py
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,25 @@ def check_address(self, wallet, addr, is_mine, is_change, label):
else:
assert_equal(addr_info['labels'], []),

def test_migration_requires_opt_in(self):
self.log.info("Test that migration is refused, leaving the wallet untouched, without -walletmigration")
wallet = self.create_legacy_wallet("optin")
wallet_dir = self.nodes[0].wallets_path / "optin"
files_before = sorted(os.listdir(wallet_dir))

assert_raises_rpc_error(-4, "Wallet migration is experimental and disabled by default", wallet.migratewallet)
assert_raises_rpc_error(-4, "Wallet migration is experimental and disabled by default", self.nodes[0].migratewallet, "optin")

assert "optin" in self.nodes[0].listwallets()
info = wallet.getwalletinfo()
assert_equal(info["descriptors"], False)
assert_equal(info["format"], "bdb")
assert_equal(sorted(os.listdir(wallet_dir)), files_before)

wallet.unloadwallet()
self.nodes[0].extra_args = ["-walletmigration"]
self.restart_node(0)

def test_basic(self):
default = self.nodes[0].get_wallet_rpc(self.default_wallet_name)

Expand Down Expand Up @@ -880,6 +899,7 @@ def check(info, node):
def run_test(self):
self.generate(self.nodes[0], 101)

self.test_migration_requires_opt_in()
# TODO: Test the actual records in the wallet for these tests too. The behavior may be correct, but the data written may not be what we actually want
self.test_basic()
self.test_multisig()
Expand Down
Loading