The wallet state and lifecycle

251    wallet->WalletLogPrintf("Releasing wallet %s..\n", name);
252    delete wallet;
253    // Wallet is now released, notify WaitForDeleteWallet, if any.
254    {
255        LOCK(g_wallet_release_mutex);
256        if (g_unloading_wallet_set.erase(name) == 0) {
257            // WaitForDeleteWallet was not called for this wallet, all done.
258            return;
259        }
260    }
261    g_wallet_release_cv.notify_all();
262}
263
264void WaitForDeleteWallet(std::shared_ptr<CWallet>&& wallet)
265{
266    // Mark wallet for unloading.
267    const std::string name = wallet->GetName();
268    {
269        LOCK(g_wallet_release_mutex);
270        g_unloading_wallet_set.insert(name);
271        // Do not expect to be the only one removing this wallet.
272        // Multiple threads could simultaneously be waiting for deletion.
273    }
274
275    // Time to ditch our shared_ptr and wait for FlushAndDeleteWallet call.
276    wallet.reset();
277    {
278        WAIT_LOCK(g_wallet_release_mutex, lock);
279        while (g_unloading_wallet_set.contains(name)) {
280            g_wallet_release_cv.wait(lock);
281        }
282    }
283}
284
285namespace {
286std::shared_ptr<CWallet> LoadWalletInternal(WalletContext& context, const std::string& name, std::optional<bool> load_on_start, const DatabaseOptions& options, DatabaseStatus& status, bilingual_str& error, std::vector<bilingual_str>& warnings)
287{
288    try {
289        std::unique_ptr<WalletDatabase> database = MakeWalletDatabase(name, options, status, error);
290        if (!database) {
291            error = Untranslated("Wallet file verification failed.") + Untranslated(" ") + error;
292            return nullptr;
293        }
294
295        context.chain->initMessage(_("Loading wallet…"));
296        std::shared_ptr<CWallet> wallet = CWallet::LoadExisting(context, name, std::move(database), error, warnings);
297        if (!wallet) {
298            error = Untranslated("Wallet loading failed.") + Untranslated(" ") + error;
299            status = DatabaseStatus::FAILED_LOAD;
300            return nullptr;
301        }
302
303        NotifyWalletLoaded(context, wallet);
304        AddWallet(context, wallet);
305        wallet->postInitProcess();
306
307        // Write the wallet setting
308        UpdateWalletSetting(*context.chain, name, load_on_start, warnings);
309
310        return wallet;
311    } catch (const std::runtime_error& e) {
312        error = Untranslated(e.what());
313        status = DatabaseStatus::FAILED_LOAD;
314        return nullptr;
315    }
316}
317
318class FastWalletRescanFilter
319{
320public:
321    FastWalletRescanFilter(const CWallet& wallet) : m_wallet(wallet)
322    {
323        // create initial filter with scripts from all ScriptPubKeyMans
324        for (auto spkm : m_wallet.GetAllScriptPubKeyMans()) {
325            auto desc_spkm{dynamic_cast<DescriptorScriptPubKeyMan*>(spkm)};
326            assert(desc_spkm != nullptr);
327            AddScriptPubKeys(desc_spkm);
328            // save each range descriptor's end for possible future filter updates
329            if (desc_spkm->IsHDEnabled()) {
330                m_last_range_ends.emplace(desc_spkm->GetID(), desc_spkm->GetEndRange());
331            }
332        }
333    }
334
335    void UpdateIfNeeded()
336    {
337        // repopulate filter with new scripts if top-up has happened since last iteration
338        for (const auto& [desc_spkm_id, last_range_end] : m_last_range_ends) {
339            auto desc_spkm{dynamic_cast<DescriptorScriptPubKeyMan*>(m_wallet.GetScriptPubKeyMan(desc_spkm_id))};
340            assert(desc_spkm != nullptr);
341            int32_t current_range_end{desc_spkm->GetEndRange()};
342            if (current_range_end > last_range_end) {
343                AddScriptPubKeys(desc_spkm, last_range_end);
344                m_last_range_ends.at(desc_spkm->GetID()) = current_range_end;
345            }
346        }
347    }
348
349    std::optional<bool> MatchesBlock(const uint256& block_hash) const
350    {
351        return m_wallet.chain().blockFilterMatchesAny(BlockFilterType::BASIC, block_hash, m_filter_set);
352    }
353
354private:
355    const CWallet& m_wallet;
356    /** Map for keeping track of each range descriptor's last seen end range.
357      * This information is used to detect whether new addresses were derived
358      * (that is, if the current end range is larger than the saved end range)
359      * after processing a block and hence a filter set update is needed to
360      * take possible keypool top-ups into account.
361      */
362    std::map<uint256, int32_t> m_last_range_ends;
363    GCSFilter::ElementSet m_filter_set;
364
365    void AddScriptPubKeys(const DescriptorScriptPubKeyMan* desc_spkm, int32_t last_range_end = 0)
366    {
367        for (const auto& script_pub_key : desc_spkm->GetScriptPubKeys(last_range_end)) {
368            m_filter_set.emplace(script_pub_key.begin(), script_pub_key.end());
369        }
370    }
371};
372} // namespace
373
374std::shared_ptr<CWallet> LoadWallet(WalletContext& context, const std::string& name, std::optional<bool> load_on_start, const DatabaseOptions& options, DatabaseStatus& status, bilingual_str& error, std::vector<bilingual_str>& warnings)
375{
376    auto result = WITH_LOCK(g_loading_wallet_mutex, return g_loading_wallet_set.insert(name));
377    if (!result.second) {
378        error = Untranslated("Wallet already loading.");
379        status = DatabaseStatus::FAILED_LOAD;
380        return nullptr;
381    }
382    auto wallet = LoadWalletInternal(context, name, load_on_start, options, status, error, warnings);
383    WITH_LOCK(g_loading_wallet_mutex, g_loading_wallet_set.erase(result.first));
384    return wallet;
385}
386
387std::shared_ptr<CWallet> CreateWallet(WalletContext& context, const std::string& name, std::optional<bool> load_on_start, DatabaseOptions& options, DatabaseStatus& status, bilingual_str& error, std::vector<bilingual_str>& warnings)
388{
389    // Wallet must have a non-empty name
390    if (name.empty()) {
391        error = Untranslated("Wallet name cannot be empty");
392        status = DatabaseStatus::FAILED_NEW_UNNAMED;
393        return nullptr;
394    }
395
396    uint64_t wallet_creation_flags = options.create_flags;
397    const SecureString& passphrase = options.create_passphrase;
398    bool born_encrypted = !passphrase.empty();
399
400    // Only descriptor wallets can be created
401    Assert(wallet_creation_flags & WALLET_FLAG_DESCRIPTORS);
402    options.require_format = DatabaseFormat::SQLITE;
403
404
405    // Private keys must be disabled for an external signer wallet
406    if ((wallet_creation_flags & WALLET_FLAG_EXTERNAL_SIGNER) && !(wallet_creation_flags & WALLET_FLAG_DISABLE_PRIVATE_KEYS)) {
407        error = Untranslated("Private keys must be disabled when using an external signer");
408        status = DatabaseStatus::FAILED_CREATE;
409        return nullptr;
410    }
411
412    // Do not allow a passphrase when private keys are disabled
413    if (born_encrypted && (wallet_creation_flags & WALLET_FLAG_DISABLE_PRIVATE_KEYS)) {
414        error = Untranslated("Passphrase provided but private keys are disabled. A passphrase is only used to encrypt private keys, so cannot be used for wallets with private keys disabled.");
415        status = DatabaseStatus::FAILED_CREATE;
416        return nullptr;
417    }
418
419    // Wallet::Verify will check if we're trying to create a wallet with a duplicate name.
420    std::unique_ptr<WalletDatabase> database = MakeWalletDatabase(name, options, status, error);
421    if (!database) {
422        error = Untranslated("Wallet file verification failed.") + Untranslated(" ") + error;
423        status = DatabaseStatus::FAILED_VERIFY;
424        return nullptr;
425    }
426
427    // Make the wallet
428    context.chain->initMessage(_("Creating wallet…"));
429    std::shared_ptr<CWallet> wallet = CWallet::CreateNew(context, name, std::move(database), wallet_creation_flags, born_encrypted, error, warnings);
430    if (!wallet) {
431        error = Untranslated("Wallet creation failed.") + Untranslated(" ") + error;
432        status = DatabaseStatus::FAILED_CREATE;
433        return nullptr;
434    }
435
436    // Encrypt the wallet
437    if (born_encrypted) {
438        if (!wallet->EncryptWallet(passphrase)) {
439            error = Untranslated("Error: Wallet created but failed to encrypt.");
440            status = DatabaseStatus::FAILED_ENCRYPT;
441            return nullptr;
442        }
443    }
444
445    WITH_LOCK(wallet->cs_wallet, wallet->LogStats());
446    NotifyWalletLoaded(context, wallet);
447    AddWallet(context, wallet);
448    wallet->postInitProcess();
449
450    // Write the wallet settings
451    UpdateWalletSetting(*context.chain, name, load_on_start, warnings);
452
453    status = DatabaseStatus::SUCCESS;
454    return wallet;
455}
456
457// Re-creates wallet from the backup file by renaming and moving it into the wallet's directory.
458// If 'load_after_restore=true', the wallet object will be fully initialized and appended to the context.
459std::shared_ptr<CWallet> RestoreWallet(WalletContext& context, const fs::path& backup_file, const std::string& wallet_name, std::optional<bool> load_on_start, DatabaseStatus& status, bilingual_str& error, std::vector<bilingual_str>& warnings, bool load_after_restore, bool allow_unnamed)
460{
461    // Error if the wallet name is empty and allow_unnamed == false
462    // allow_unnamed == true is only used by migration to migrate an unnamed wallet
463    if (!allow_unnamed && wallet_name.empty()) {
464        error = Untranslated("Wallet name cannot be empty");
465        status = DatabaseStatus::FAILED_NEW_UNNAMED;
466        return nullptr;
467    }
468
469    DatabaseOptions options;
470    ReadDatabaseArgs(*context.args, options);
471    options.require_existing = true;
472
473    const fs::path wallet_path = fsbridge::AbsPathJoin(GetWalletDir(), fs::u8path(wallet_name));
474    auto wallet_file = wallet_path / "wallet.dat";
475    std::shared_ptr<CWallet> wallet;
476    bool wallet_file_copied = false;
477    bool created_parent_dir = false;
478
479    try {
480        if (!fs::exists(backup_file)) {
481            error = Untranslated("Backup file does not exist");
482            status = DatabaseStatus::FAILED_INVALID_BACKUP_FILE;
483            return nullptr;
484        }
485
486        // Wallet directories are allowed to exist, but must not contain a .dat file.
487        // Any existing wallet database is treated as a hard failure to prevent overwriting.
488        if (fs::exists(wallet_path)) {
489            // If this is a file, it is the db and we don't want to overwrite it.
490            if (!fs::is_directory(wallet_path)) {
491                error = Untranslated(strprintf("Failed to restore wallet. Database file exists '%s'.", fs::PathToString(wallet_path)));
492                status = DatabaseStatus::FAILED_ALREADY_EXISTS;
493                return nullptr;
494            }
495
496            // Check we are not going to overwrite an existing db file
497            if (fs::exists(wallet_file)) {
498                error = Untranslated(strprintf("Failed to restore wallet. Database file exists in '%s'.", fs::PathToString(wallet_file)));
499                status = DatabaseStatus::FAILED_ALREADY_EXISTS;
500                return nullptr;