The wallet state and lifecycle

4251                    throw std::runtime_error(util::ErrorString(spkm_res).original);
4252                }
4253            }
4254
4255            // Add the wallet to settings
4256            UpdateWalletSetting(*context.chain, wallet_name, load_on_startup, warnings);
4257        }
4258        if (data->solvable_descs.size() > 0) {
4259            wallet.WalletLogPrintf("Making a new watchonly wallet containing the unwatched solvable scripts\n");
4260
4261            DatabaseStatus status;
4262            std::vector<bilingual_str> warnings;
4263            std::string wallet_name = MigrationPrefixName(wallet) + "_solvables";
4264            std::unique_ptr<WalletDatabase> database = MakeWalletDatabase(wallet_name, options, status, error);
4265            if (!database) {
4266                error = strprintf(_("Wallet file creation failed: %s"), error);
4267                return false;
4268            }
4269
4270            data->solvable_wallet = CWallet::CreateNew(empty_context, wallet_name, std::move(database), options.create_flags, /*born_encrypted=*/false, error, warnings);
4271            if (!data->solvable_wallet) {
4272                error = _("Error: Failed to create new watchonly wallet");
4273                return false;
4274            }
4275            res.solvables_wallet = data->solvable_wallet;
4276            LOCK(data->solvable_wallet->cs_wallet);
4277
4278            // Parse the descriptors and add them to the new wallet
4279            for (const auto& [desc_str, creation_time] : data->solvable_descs) {
4280                // Parse the descriptor
4281                FlatSigningProvider keys;
4282                std::string parse_err;
4283                std::vector<std::unique_ptr<Descriptor>> descs = Parse(desc_str, keys, parse_err, /*require_checksum=*/ true);
4284                // LegacyDataSPKM should not produce invalid, multipath, or ranged watch-only descriptors.
4285                assert(descs.size() == 1);
4286                assert(!descs.at(0)->IsRange());
4287
4288                // Add to the wallet
4289                WalletDescriptor w_desc(std::move(descs.at(0)), creation_time, 0, 0, 0);
4290                if (auto spkm_res = data->solvable_wallet->AddWalletDescriptor(w_desc, keys, "", false); !spkm_res) {
4291                    throw std::runtime_error(util::ErrorString(spkm_res).original);
4292                }
4293            }
4294
4295            // Add the wallet to settings
4296            UpdateWalletSetting(*context.chain, wallet_name, load_on_startup, warnings);
4297        }
4298    }
4299
4300    // Add the descriptors to the wallet, remove the LegacyDataSPKM, and clean up transactions and address book data
4301    return RunWithinTxn(wallet.GetDatabase(), /*process_desc=*/"apply migration process", [&](WalletBatch& batch) EXCLUSIVE_LOCKS_REQUIRED(wallet.cs_wallet){
4302        if (auto res_migration = wallet.ApplyMigrationData(batch, *data); !res_migration) {
4303            error = util::ErrorString(res_migration);
4304            return false;
4305        }
4306        wallet.WalletLogPrintf("Wallet migration complete.\n");
4307        return true;
4308    });
4309}
4310
4311util::Result<MigrationResult> MigrateLegacyToDescriptor(const std::string& wallet_name, const SecureString& passphrase, WalletContext& context, bool load_wallet)
4312{
4313    std::vector<bilingual_str> warnings;
4314    bilingual_str error;
4315
4316    // The only kind of wallets that could be loaded are descriptor ones, which don't need to be migrated.
4317    if (auto wallet = GetWallet(context, wallet_name)) {
4318        assert(wallet->IsWalletFlagSet(WALLET_FLAG_DESCRIPTORS));
4319        return util::Error{_("Error: This wallet is already a descriptor wallet")};
4320    } else {
4321        // Check if the wallet is BDB
4322        const auto& wallet_path = GetWalletPath(wallet_name);
4323        if (!wallet_path) {
4324            return util::Error{util::ErrorString(wallet_path)};
4325        }
4326        if (!fs::exists(*wallet_path)) {
4327            return util::Error{_("Error: Wallet does not exist")};
4328        }
4329        if (!IsBDBFile(BDBDataFile(*wallet_path))) {
4330            return util::Error{_("Error: This wallet is already a descriptor wallet")};
4331        }
4332    }
4333
4334    // Load the wallet but only in the context of this function.
4335    // No signals should be connected nor should anything else be aware of this wallet
4336    WalletContext empty_context;
4337    empty_context.args = context.args;
4338    DatabaseOptions options;
4339    options.require_existing = true;
4340    options.require_format = DatabaseFormat::BERKELEY_RO;
4341    DatabaseStatus status;
4342    std::unique_ptr<WalletDatabase> database = MakeWalletDatabase(wallet_name, options, status, error);
4343    if (!database) {
4344        return util::Error{Untranslated("Wallet file verification failed.") + Untranslated(" ") + error};
4345    }
4346
4347    // Make the local wallet
4348    std::shared_ptr<CWallet> local_wallet = CWallet::LoadExisting(empty_context, wallet_name, std::move(database), error, warnings);
4349    if (!local_wallet) {
4350        return util::Error{Untranslated("Wallet loading failed.") + Untranslated(" ") + error};
4351    }
4352
4353    return MigrateLegacyToDescriptor(std::move(local_wallet), passphrase, context, load_wallet);
4354}
4355
4356util::Result<MigrationResult> MigrateLegacyToDescriptor(std::shared_ptr<CWallet> local_wallet, const SecureString& passphrase, WalletContext& context, bool load_wallet)
4357{
4358    MigrationResult res;
4359    bilingual_str error;
4360    std::vector<bilingual_str> warnings;
4361
4362    DatabaseOptions options;
4363    options.require_existing = true;
4364    DatabaseStatus status;
4365
4366    const std::string wallet_name = local_wallet->GetName();
4367
4368    // Before anything else, check if there is something to migrate.
4369    if (local_wallet->IsWalletFlagSet(WALLET_FLAG_DESCRIPTORS)) {
4370        return util::Error{_("Error: This wallet is already a descriptor wallet")};
4371    }
4372
4373    // Make a backup of the DB in the wallet's directory with a unique filename
4374    // using the wallet name and current timestamp. The backup filename is based
4375    // on the name of the parent directory containing the wallet data in most
4376    // cases, but in the case where the wallet name is a path to a data file,
4377    // the name of the data file is used, and in the case where the wallet name
4378    // is blank, "default_wallet" is used.
4379    const std::string backup_prefix = wallet_name.empty() ? MigrationPrefixName(*local_wallet) : [&] {
4380        // fs::weakly_canonical resolves relative specifiers and remove trailing slashes.
4381        const auto legacy_wallet_path = fs::weakly_canonical(GetWalletDir() / fs::PathFromString(wallet_name));
4382        return fs::PathToString(legacy_wallet_path.filename());
4383    }();
4384
4385    fs::path backup_filename = fs::PathFromString(strprintf("%s_%d.legacy.bak", backup_prefix, GetTime()));
4386    fs::path backup_path = fsbridge::AbsPathJoin(GetWalletDir(), backup_filename);
4387    if (!local_wallet->BackupWallet(fs::PathToString(backup_path))) {
4388        return util::Error{_("Error: Unable to make a backup of your wallet")};
4389    }
4390    res.backup_path = backup_path;
4391
4392    bool success = false;
4393
4394    // Unlock the wallet if needed
4395    if (local_wallet->IsLocked() && !local_wallet->Unlock(passphrase)) {
4396        if (passphrase.find('\0') == std::string::npos) {
4397            return util::Error{Untranslated("Error: Wallet decryption failed, the wallet passphrase was not provided or was incorrect.")};
4398        } else {
4399            return util::Error{Untranslated("Error: Wallet decryption failed, the wallet passphrase entered was incorrect. "
4400                                            "The passphrase contains a null character (ie - a zero byte). "
4401                                            "If this passphrase was set with a version of this software prior to 25.0, "
4402                                            "please try again with only the characters up to — but not including — "
4403                                            "the first null character.")};
4404        }
4405    }
4406
4407    // Indicates whether the current wallet is empty after migration.
4408    // Notes:
4409    // When non-empty: the local wallet becomes the main spendable wallet.
4410    // When empty: The local wallet is excluded from the result, as the
4411    //             user does not expect an empty spendable wallet after
4412    //             migrating only watch-only scripts.
4413    bool empty_local_wallet = false;
4414
4415    {
4416        LOCK(local_wallet->cs_wallet);
4417        // First change to using SQLite
4418        if (!local_wallet->MigrateToSQLite(error)) return util::Error{error};
4419
4420        // Do the migration of keys and scripts for non-empty wallets, and cleanup if it fails
4421        if (HasLegacyRecords(*local_wallet)) {
4422            success = DoMigration(*local_wallet, context, error, res, load_wallet);
4423            // No scripts mean empty wallet after migration
4424            empty_local_wallet = local_wallet->GetAllScriptPubKeyMans().empty();
4425        } else {
4426            // Make sure that descriptors flag is actually set
4427            local_wallet->SetWalletFlag(WALLET_FLAG_DESCRIPTORS);
4428            success = true;
4429        }
4430    }
4431
4432    // In case of loading failure, we need to remember the wallet files we have created to remove.
4433    // A `set` is used as it may be populated with the same wallet directory paths multiple times,
4434    // both before and after loading. This ensures the set is complete even if one of the wallets
4435    // fails to load.
4436    std::set<fs::path> wallet_files_to_remove;
4437    std::set<fs::path> wallet_empty_dirs_to_remove;
4438
4439    // Helper to track wallet files and directories for cleanup on failure.
4440    // Only directories of wallets created during migration (not the main wallet) are tracked.
4441    auto track_for_cleanup = [&](const CWallet& wallet) {
4442        const auto files = wallet.GetDatabase().Files();
4443        wallet_files_to_remove.insert(files.begin(), files.end());
4444        if (wallet.GetName() != wallet_name) {
4445            // If this isn’t the main wallet, mark its directory for removal.
4446            // This applies to the watch-only and solvable wallets.
4447            // Wallets stored directly as files in the top-level directory
4448            // (e.g. default unnamed wallets) don’t have a removable parent directory.
4449            wallet_empty_dirs_to_remove.insert(fs::PathFromString(wallet.GetDatabase().Filename()).parent_path());
4450        }
4451    };
4452
4453
4454    if (success) {
4455        Assume(!res.wallet); // We will set it here.
4456        // Check if the local wallet is empty after migration
4457        if (empty_local_wallet) {
4458            // This wallet has no records. We can safely remove it.
4459            std::vector<fs::path> paths_to_remove = local_wallet->GetDatabase().Files();
4460            local_wallet.reset();
4461            for (const auto& path_to_remove : paths_to_remove) fs::remove(path_to_remove);
4462        }
4463
4464        if (load_wallet) {
4465            LogInfo("Loading new wallets after migration...\n");
4466            /** We only override the load_on_startup setting in case the user explicitly said
4467             * that he does not want to load the wallet, otherwise keep the old wallet configuration */
4468        } else {
4469            UpdateWalletSetting(*context.chain, wallet_name, /*load_on_startup=*/false, warnings);
4470        }
4471        // Migration successful, if load_wallet is set load all the migrated wallets.
4472        bool main_wallet_set{false};
4473        for (std::shared_ptr<CWallet>* wallet_ptr : {&local_wallet, &res.watchonly_wallet, &res.solvables_wallet}) {
4474            if (success && *wallet_ptr) {
4475                std::shared_ptr<CWallet>& wallet = *wallet_ptr;
4476                // Track db path
4477                track_for_cleanup(*wallet);
4478                assert(wallet.use_count() == 1);
4479                std::string wallet_name = wallet->GetName();
4480                wallet.reset();
4481                if (load_wallet) {
4482                    wallet = LoadWallet(context, wallet_name, /*load_on_start=*/std::nullopt, options, status, error, warnings);
4483                    if (!wallet) {
4484                        LogError("Failed to load wallet '%s' after migration. Rolling back migration to preserve consistency. "
4485                                 "Error cause: %s\n", wallet_name, error.original);
4486                        success = false;
4487                        break;
4488                    }
4489                }
4490                // Set the first wallet as the main one.
4491                // The loop order is intentional and must always start with the local wallet.
4492                if (!main_wallet_set) {
4493                    res.wallet_name = wallet_name;
4494                    if (load_wallet) res.wallet = std::move(wallet);
4495                    main_wallet_set = true;
4496                }
4497                if (wallet_ptr == &res.watchonly_wallet) {
4498                    res.watchonly_wallet_name = wallet_name;
4499                } else if (wallet_ptr == &res.solvables_wallet) {
4500                    res.solvables_wallet_name = wallet_name;