wallet: create and restore a recovery phrase (#96)

Adds -newphrase, -restorephrase, -restoredepth, -newaddress and -showderived, plus the window buttons that reach the same code. Restore derives forward in batches of 100 and rescans after each, stopping when a whole batch turns up nothing; the phrase is shown on the terminal only, never in debug.log. Proved end to end on a live wallet: paid a derived address, deleted wallet.dat, restored from the twelve words and recovered the coin. Coins on the pre-seed default address do not come back, and the command says so.

8 files changed, 610 insertions, 31 deletions

diff --git a/src/Makefile b/src/Makefile
index bbdc9e2..3eaf2ba 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -42,7 +42,7 @@ LIBS = -L$(SECP_LIB) -lsecp256k1 \
 HEADERS = headers_core.h headers.h util.h main.h serialize.h uint256.h \
           key.h bignum.h script.h db.h base58.h net.h nostr.h \
           randomx_pow.h btfaddr.h btfchan.h btfrv.h btftunnel.h market.h \
-          selftest.h compat.h
+          selftest.h walletcmd.h compat.h
 
 IMGUI_OBJS = obj/imgui.o obj/imgui_draw.o obj/imgui_tables.o \
              obj/imgui_widgets.o obj/imgui_impl_glfw.o obj/imgui_impl_opengl3.o
@@ -50,7 +50,7 @@ IMGUI_OBJS = obj/imgui.o obj/imgui_draw.o obj/imgui_tables.o \
 NODE_OBJS = obj/util.o obj/script.o obj/db.o obj/net.o obj/main.o \
             obj/market.o obj/sha.o obj/nostr.o obj/randomx_pow.o \
             obj/btfaddr.o obj/btfchan.o obj/btfrv.o obj/btftunnel.o obj/rpc.o \
-            obj/selftest.o obj/bip32.o
+            obj/selftest.o obj/bip32.o obj/walletcmd.o
 
 GUI_OBJS = obj/gui.o obj/main_gui.o
 
diff --git a/src/gui.cpp b/src/gui.cpp
index 51b5d5f..e800244 100644
--- a/src/gui.cpp
+++ b/src/gui.cpp
@@ -12,6 +12,11 @@
 #include <cstdio>
 #include <sstream>
 #include <iomanip>
+#include <atomic>
+#include <mutex>
+#include <thread>
+#include "bip32.h"
+#include "walletcmd.h"
 #include "font_roboto.h"
 
 // ---------------------------------------------------------------------------
@@ -910,6 +915,220 @@ static void DrawOptionsDialog()
 // ---------------------------------------------------------------------------
 // Wallet safety dialog
 // ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Recovery phrase
+//
+// The phrase is shown once, and the seed is installed only after the user says
+// they have written it down. Generating it and storing it in the same breath
+// would hand somebody a wallet whose only backup is twelve words they may have
+// closed the window on -- which is worse than no phrase at all, because they
+// would believe they had one.
+//
+// Nothing here writes the words to disk or to debug.log. They live in one
+// std::string that is cleared the moment the dialog closes.
+// ---------------------------------------------------------------------------
+static bool        g_showCreatePhrase   = false;
+static bool        g_showRestorePhrase  = false;
+static std::string g_pendingMnemonic;
+static bool        g_phraseWrittenDown  = false;
+static std::string g_phraseStatus;
+
+static char        g_restoreInput[600]  = {};
+static std::string g_restoreStatus;
+static std::atomic<bool> g_restoreRunning(false);
+static std::atomic<int>  g_restoreDerived(0);
+static std::atomic<int>  g_restoreRecovered(0);
+static std::string g_restoreResult;
+static std::mutex  g_restoreResultMutex;
+
+static void RestoreProgress(void*, int nDerived, int nRecovered)
+{
+    g_restoreDerived.store(nDerived);
+    g_restoreRecovered.store(nRecovered);
+}
+
+static void RestoreThread(std::string strPhrase)
+{
+    std::string strError;
+    int nRecovered = 0, nDerived = 0;
+    bool fOk = RestoreFromPhrase(strPhrase, 0, RestoreProgress, NULL,
+                                 strError, nRecovered, nDerived);
+    {
+        std::lock_guard<std::mutex> lock(g_restoreResultMutex);
+        if (!fOk)
+            g_restoreResult = "Nothing was changed. " + strError;
+        else if (nRecovered > 0)
+            g_restoreResult = strprintf(
+                "Restored %d transaction(s) across %d derived addresses. "
+                "Restart the node to see the balance.", nRecovered, nDerived);
+        else
+            g_restoreResult = strprintf(
+                "No transactions found for the first %d addresses of that phrase. "
+                "Check the words and their order.", nDerived);
+    }
+    g_restoreRunning.store(false);
+    g_needRefresh = true;
+}
+
+static void DrawCreatePhraseDialog()
+{
+    if (!g_showCreatePhrase) return;
+
+    ImGui::SetNextWindowSize(ImVec2(640.0f, 340.0f), ImGuiCond_Always);
+    ImGui::SetNextWindowPos(ImGui::GetMainViewport()->GetCenter(),
+                            ImGuiCond_Always, ImVec2(0.5f, 0.5f));
+    if (ImGui::Begin("Recovery Phrase", &g_showCreatePhrase,
+        ImGuiWindowFlags_NoResize | ImGuiWindowFlags_NoCollapse))
+    {
+        ImGui::TextColored(ImVec4(1.0f, 0.75f, 0.25f, 1.0f),
+                           "Write these twelve words down, in order, on paper.");
+        ImGui::TextWrapped(
+            "They are the only thing that can rebuild this wallet if the file is lost. "
+            "Anyone who reads them can spend your coins. They are not stored anywhere, "
+            "and this is the only time they will be shown.");
+        ImGui::Spacing();
+
+        ImGui::PushStyleColor(ImGuiCol_ChildBg, ImVec4(0.10f, 0.10f, 0.10f, 1.0f));
+        ImGui::BeginChild("##phrase", ImVec2(0.0f, 70.0f), true);
+        ImGui::PushTextWrapPos(0.0f);
+        ImGui::TextColored(ImVec4(0.55f, 1.0f, 0.6f, 1.0f), "%s", g_pendingMnemonic.c_str());
+        ImGui::PopTextWrapPos();
+        ImGui::EndChild();
+        ImGui::PopStyleColor();
+
+        ImGui::Spacing();
+        ImGui::TextWrapped(
+            "Keys already in this wallet are NOT covered by the phrase -- they existed "
+            "before it did. Keep your file backups as well.");
+        ImGui::Spacing();
+
+        ImGui::Checkbox("I have written these words down", &g_phraseWrittenDown);
+        ImGui::Spacing();
+
+        if (!g_phraseWrittenDown)
+            ImGui::BeginDisabled();
+        if (ImGui::Button("Finish", ImVec2(120.0f, 0.0f)))
+        {
+            std::string strError;
+            if (SetHDSeedFromMnemonic(g_pendingMnemonic, strError))
+            {
+                TopUpKeyPool();
+                g_phraseStatus = "Recovery phrase created. New addresses come from it.";
+            }
+            else
+            {
+                g_phraseStatus = "Could not install the seed: " + strError;
+            }
+            g_pendingMnemonic.clear();
+            g_phraseWrittenDown = false;
+            g_showCreatePhrase = false;
+            g_needRefresh = true;
+        }
+        if (!g_phraseWrittenDown)
+            ImGui::EndDisabled();
+
+        ImGui::SameLine();
+        if (ImGui::Button("Cancel", ImVec2(120.0f, 0.0f)))
+        {
+            // Nothing was installed, so there is nothing to undo. The words go
+            // away with the string.
+            g_pendingMnemonic.clear();
+            g_phraseWrittenDown = false;
+            g_showCreatePhrase = false;
+            g_phraseStatus = "Cancelled. No recovery phrase was created.";
+        }
+    }
+    ImGui::End();
+
+    // Closing with the window X is the same as cancelling.
+    if (!g_showCreatePhrase && !g_pendingMnemonic.empty())
+    {
+        g_pendingMnemonic.clear();
+        g_phraseWrittenDown = false;
+        g_phraseStatus = "Cancelled. No recovery phrase was created.";
+    }
+}
+
+static void DrawRestorePhraseDialog()
+{
+    if (!g_showRestorePhrase) return;
+
+    ImGui::SetNextWindowSize(ImVec2(640.0f, 330.0f), ImGuiCond_Always);
+    ImGui::SetNextWindowPos(ImGui::GetMainViewport()->GetCenter(),
+                            ImGuiCond_Always, ImVec2(0.5f, 0.5f));
+    if (ImGui::Begin("Restore From Phrase", &g_showRestorePhrase,
+        ImGuiWindowFlags_NoResize | ImGuiWindowFlags_NoCollapse))
+    {
+        ImGui::TextWrapped(
+            "Type the twelve words, in order, separated by spaces. The node will "
+            "derive the addresses they describe and search the chain for their coins.");
+        ImGui::Spacing();
+
+        if (HaveHDSeed())
+        {
+            ImGui::PushStyleColor(ImGuiCol_Text, ImVec4(1.0f, 0.75f, 0.25f, 1.0f));
+            ImGui::TextWrapped(
+                "This wallet already has a recovery phrase. Restoring replaces it: "
+                "coins on addresses from the current phrase would no longer come back "
+                "from the words you wrote down for it. Back up wallet.dat first.");
+            ImGui::PopStyleColor();
+            ImGui::Spacing();
+        }
+
+        ImGui::SetNextItemWidth(-1.0f);
+        ImGui::InputTextMultiline("##phrase-in", g_restoreInput, sizeof(g_restoreInput),
+                                  ImVec2(0.0f, 60.0f));
+
+        ImGui::Spacing();
+        bool fBusy = g_restoreRunning.load();
+        if (fBusy)
+            ImGui::BeginDisabled();
+        if (ImGui::Button("Restore", ImVec2(140.0f, 0.0f)))
+        {
+            std::string strWhy;
+            if (!CanScanWalletTransactions(strWhy))
+            {
+                std::lock_guard<std::mutex> lock(g_restoreResultMutex);
+                g_restoreResult = strWhy;
+            }
+            else
+            {
+                {
+                    std::lock_guard<std::mutex> lock(g_restoreResultMutex);
+                    g_restoreResult.clear();
+                }
+                g_restoreDerived.store(0);
+                g_restoreRecovered.store(0);
+                g_restoreRunning.store(true);
+                // On its own thread: a restore walks the whole chain once per
+                // batch and would otherwise freeze the window for as long as it
+                // takes.
+                std::thread(RestoreThread, std::string(g_restoreInput)).detach();
+            }
+        }
+        if (fBusy)
+            ImGui::EndDisabled();
+
+        ImGui::SameLine();
+        if (ImGui::Button("Close", ImVec2(100.0f, 0.0f)) && !fBusy)
+            g_showRestorePhrase = false;
+
+        ImGui::Spacing();
+        if (fBusy)
+        {
+            ImGui::Text("Searching: %d addresses checked, %d transaction(s) so far",
+                        g_restoreDerived.load(), g_restoreRecovered.load());
+        }
+        else
+        {
+            std::lock_guard<std::mutex> lock(g_restoreResultMutex);
+            if (!g_restoreResult.empty())
+                ImGui::TextWrapped("%s", g_restoreResult.c_str());
+        }
+    }
+    ImGui::End();
+}
+
 static void DrawWalletSafetyDialog()
 {
     if (!g_showWalletSafety) return;
@@ -994,6 +1213,43 @@ static void DrawWalletSafetyDialog()
         }
 
         ImGui::Spacing();
+        ImGui::SeparatorText("Recovery Phrase");
+        if (HaveHDSeed())
+            ImGui::TextColored(ImVec4(0.55f, 1.0f, 0.6f, 1.0f),
+                               "This wallet has a recovery phrase.");
+        else
+            ImGui::TextColored(ImVec4(1.0f, 0.75f, 0.25f, 1.0f),
+                               "No recovery phrase. Only a file backup can rebuild this wallet.");
+
+        if (!HaveHDSeed())
+        {
+            if (ImGui::Button("Create recovery phrase", ImVec2(200.0f, 0.0f)))
+            {
+                std::string strError;
+                if (bitflash::BIP39GenerateMnemonic(g_pendingMnemonic, strError))
+                {
+                    g_phraseWrittenDown = false;
+                    g_phraseStatus.clear();
+                    g_showCreatePhrase = true;
+                }
+                else
+                {
+                    g_phraseStatus = "Could not generate a phrase: " + strError;
+                }
+            }
+            ImGui::SameLine();
+        }
+        if (ImGui::Button("Restore from phrase", ImVec2(190.0f, 0.0f)))
+            g_showRestorePhrase = true;
+
+        if (!g_phraseStatus.empty())
+            ImGui::TextWrapped("%s", g_phraseStatus.c_str());
+
+        ImGui::TextWrapped(
+            "A phrase covers addresses created after it. Keys that already existed "
+            "are not derived from it, so keep the file backups above as well.");
+
+        ImGui::Spacing();
         ImGui::SeparatorText("Key Pool");
         int nPool = KeyPoolCount();
         ImGui::Text("Pre-generated keys ready: %d / %d", nPool, KEYPOOL_SIZE);
@@ -1157,6 +1413,8 @@ int RunGUI(int argc, char* argv[])
         DrawSendDialog();
         DrawOptionsDialog();
         DrawWalletSafetyDialog();
+        DrawCreatePhraseDialog();
+        DrawRestorePhraseDialog();
         DrawDiagnosticsDialog();
         DrawAboutDialog();
         DrawStatusBar();
diff --git a/src/main_gui.cpp b/src/main_gui.cpp
index aa9c23d..c9e7dee 100644
--- a/src/main_gui.cpp
+++ b/src/main_gui.cpp
@@ -2,6 +2,7 @@
 
 #include "headers_core.h"
 #include "selftest.h"
+#include "walletcmd.h"
 #include <thread>          // hardware_concurrency, to sanity-check /genproclimit
 #ifndef _WIN32
 #include <csignal>
@@ -78,6 +79,11 @@ static void PrintUsage()
     printf("  /dumpwallet=FILE           (export private keys as text -- readable by\n");
     printf("                              anyone, so guard it like cash)\n");
     printf("  /importwallet=FILE         (load keys from such a file back in)\n");
+    printf("  /newaddress                (print the next receiving address, then exit)\n");
+    printf("  /newphrase                 (create a twelve-word recovery phrase for a\n");
+    printf("                              wallet that has none, show it once, exit)\n");
+    printf("  /restorephrase=\"WORDS\"     (rebuild this wallet from a phrase and scan\n");
+    printf("                              the chain for its coins, then exit)\n");
     printf("  /rescan                    (walk the chain for coins this wallet owns\n");
     printf("                              but never recorded, then exit)\n");
     printf("\n");
@@ -347,6 +353,38 @@ int main(int argc, char* argv[])
     // /rescan -- walk the chain and pick up anything the wallet's keys own but
     // the wallet never recorded. Cheap to offer and the only recourse when a
     // balance is wrong for this reason.
+    string strShow = argval2(argc, argv, "/showderived", "-showderived");
+    if (!strShow.empty())
+    {
+        int nRet = CmdShowDerived(atoi(strShow.c_str()));
+        DBFlush(true);
+        return nRet;
+    }
+
+    if (arg(argc,argv,"/newaddress") || arg(argc,argv,"-newaddress"))
+    {
+        int nRet = CmdNewAddress();
+        DBFlush(true);
+        return nRet;
+    }
+
+    if (arg(argc,argv,"/newphrase") || arg(argc,argv,"-newphrase"))
+    {
+        int nRet = CmdNewPhrase();
+        DBFlush(true);
+        return nRet;
+    }
+
+    string strRestore = argval2(argc, argv, "/restorephrase", "-restorephrase");
+    if (!strRestore.empty())
+    {
+        string strDepth = argval2(argc, argv, "/restoredepth", "-restoredepth");
+        int nMinDepth = strDepth.empty() ? 0 : atoi(strDepth.c_str());
+        int nRet = CmdRestorePhrase(strRestore, nMinDepth);
+        DBFlush(true);
+        return nRet;
+    }
+
     if (arg(argc,argv,"/rescan") || arg(argc,argv,"-rescan"))
     {
         string strScanError;
diff --git a/src/makefile.mingw b/src/makefile.mingw
index 07ae034..94d2146 100644
--- a/src/makefile.mingw
+++ b/src/makefile.mingw
@@ -42,14 +42,14 @@ IMGUI_OBJS = obj/imgui.o obj/imgui_draw.o obj/imgui_tables.o \
 NODE_OBJS = obj/util.o obj/script.o obj/db.o obj/net.o obj/main.o \
             obj/market.o obj/sha.o obj/nostr.o obj/randomx_pow.o \
             obj/btfaddr.o obj/btfchan.o obj/btfrv.o obj/btftunnel.o obj/rpc.o \
-            obj/selftest.o obj/bip32.o
+            obj/selftest.o obj/bip32.o obj/walletcmd.o
 
 GUI_OBJS = obj/gui.o obj/main_gui.o obj/bitflash_res.o
 
 HEADERS = headers_core.h headers.h util.h main.h serialize.h uint256.h \
           key.h bignum.h script.h db.h base58.h net.h nostr.h \
           randomx_pow.h btfaddr.h btfchan.h btfrv.h btftunnel.h market.h \
-          selftest.h
+          selftest.h walletcmd.h
 
 all: bitflash.exe
 
diff --git a/src/selftest.cpp b/src/selftest.cpp
index 6792ae7..b733c60 100644
--- a/src/selftest.cpp
+++ b/src/selftest.cpp
@@ -286,33 +286,9 @@ static int RunWalletKeyPoolSelfTest()
     return nFail == 0 ? 0 : 1;
 }
 
-// A -mwindows binary starts with no console attached, so stdout goes nowhere
-// even when it was launched from a terminal. Borrow the caller's console for
-// the duration of the self-test. Nothing to do on Linux, where stdout is
-// already connected.
-static void AttachTerminal()
-{
-#ifdef _WIN32
-    // Only when there is nowhere for stdout to go. If the caller redirected it
-    // to a file or a pipe -- which is what `make tests > log` and any CI does --
-    // that handle is inherited and already works, and reopening it on CONOUT$
-    // would take the output away from the file and put it on the screen. That
-    // was the first version of this fix, and it broke the one case that
-    // mattered.
-    HANDLE hOut = GetStdHandle(STD_OUTPUT_HANDLE);
-    if (hOut != NULL && hOut != INVALID_HANDLE_VALUE)
-        return;
-
-    if (AttachConsole(ATTACH_PARENT_PROCESS))
-    {
-        // Return values ignored on purpose: if the reopen fails there is
-        // nowhere left to report it, and the exit status still carries the
-        // result.
-        freopen("CONOUT$", "w", stdout);
-        freopen("CONOUT$", "w", stderr);
-    }
-#endif
-}
+// AttachTerminal() moved to util.h: the wallet phrase commands need it too,
+// and two copies of a console-attach that must get its one condition right is
+// one copy too many.
 
 static int RunWalletHDSelfTest()
 {
diff --git a/src/util.h b/src/util.h
index 25ef118..d95d3ae 100644
--- a/src/util.h
+++ b/src/util.h
@@ -293,6 +293,33 @@ void PrintHex(const T pbegin, const T pend, const char* pszFormat="%s", bool fSp
 // Forward declaration -- defined in main.cpp
 string GetAppDir();
 
+// Give a command-line operation somewhere to print.
+//
+// The Windows binary is linked -mwindows and starts with no console, so stdout
+// goes nowhere even when it was launched from a terminal. Commands that report
+// to the person who typed them -- the self-tests, the wallet phrase commands --
+// call this first.
+//
+// Only when there is nowhere for stdout to go already: if the caller redirected
+// it to a file or a pipe, that handle is inherited and works, and reopening it
+// on CONOUT$ would take the output away from the file and put it on the screen.
+inline void AttachTerminal()
+{
+#ifdef _WIN32
+    HANDLE hOut = GetStdHandle(STD_OUTPUT_HANDLE);
+    if (hOut != NULL && hOut != INVALID_HANDLE_VALUE)
+        return;
+    if (AttachConsole(ATTACH_PARENT_PROCESS))
+    {
+        // Return values ignored on purpose: if the reopen fails there is
+        // nowhere left to report it, and the exit status still carries the
+        // result.
+        freopen("CONOUT$", "w", stdout);
+        freopen("CONOUT$", "w", stderr);
+    }
+#endif
+}
+
 inline int OutputDebugStringF(const char* pszFormat, ...) BF_FORMAT(1, 2);
 
 inline int OutputDebugStringF(const char* pszFormat, ...)
diff --git a/src/walletcmd.cpp b/src/walletcmd.cpp
new file mode 100644
index 0000000..94e9d72
--- /dev/null
+++ b/src/walletcmd.cpp
@@ -0,0 +1,237 @@
+// Copyright (c) 2026 Bitflash developers
+// Distributed under the MIT/X11 software license.
+//
+// Recovery-phrase commands, from the command line.
+//
+// The phrase reaches the person who typed the command and nowhere else. In this
+// tree printf is OutputDebugStringF, which writes into the data directory's
+// debug.log -- the file we routinely ask users to attach to issues. A wallet's
+// twelve words must never go there, so this file takes the real printf and
+// AttachTerminal() gives it somewhere to land on Windows.
+
+#include "headers_core.h"
+#include "bip32.h"
+#include "walletcmd.h"
+
+#undef printf
+
+// How far ahead to look for used addresses when restoring.
+//
+// A wallet is restored from a phrase alone, so the node has no idea how many
+// addresses the old one handed out. It derives forward in batches and stops
+// once a whole batch turns up unused. A fixed number would be simpler and wrong
+// for exactly this network: a miner burns an address per block, so a node that
+// mined for a week is thousands of keys deep, and stopping at a few hundred
+// would restore a wallet that looks empty.
+static const int RESTORE_BATCH   = 100;
+static const int RESTORE_MAX     = 10000;
+
+int CmdNewPhrase()
+{
+    AttachTerminal();
+
+    if (HaveHDSeed())
+    {
+        printf("This wallet already has a recovery phrase.\n");
+        printf("Creating another would replace it, and coins on addresses derived from\n");
+        printf("the current one would no longer come back from the phrase you write down.\n");
+        printf("Nothing was changed.\n");
+        return 1;
+    }
+
+    std::string strMnemonic, strError;
+    if (!bitflash::BIP39GenerateMnemonic(strMnemonic, strError))
+    {
+        fprintf(stderr, "Could not generate a phrase: %s\n", strError.c_str());
+        return 1;
+    }
+
+    if (!SetHDSeedFromMnemonic(strMnemonic, strError))
+    {
+        fprintf(stderr, "Could not install the seed: %s\n", strError.c_str());
+        return 1;
+    }
+
+    // Fill the pool from the new seed straight away, so the addresses this
+    // wallet hands out next are ones the phrase can reproduce.
+    TopUpKeyPool();
+
+    printf("\n");
+    printf("Write these twelve words down, in order, on paper.\n");
+    printf("They are the only thing that can rebuild this wallet if the file is lost.\n");
+    printf("Anyone who reads them can spend your coins. They are not stored anywhere,\n");
+    printf("and this is the only time they will be shown.\n");
+    printf("\n");
+    printf("    %s\n", strMnemonic.c_str());
+    printf("\n");
+    printf("Keys already in this wallet are NOT covered by the phrase -- they existed\n");
+    printf("before it did. Keep your file backups as well.\n");
+    fflush(stdout);
+    return 0;
+}
+
+bool RestoreFromPhrase(const std::string& strMnemonic,
+                       int nMinDepth,
+                       RestoreProgressFn fnProgress,
+                       void* pArg,
+                       std::string& strErrorRet,
+                       int& nRecoveredRet,
+                       int& nDerivedRet)
+{
+    strErrorRet.clear();
+    nRecoveredRet = 0;
+    nDerivedRet   = 0;
+
+    // Refuse before touching the wallet, not after.
+    //
+    // Without this, a restore on a node that has not synced derives the right
+    // keys, scans a chain that is not there, and reports "no transactions were
+    // found" -- which reads as "your coins are gone" to the one person least
+    // able to argue with it. Measured while testing: a copied data directory
+    // whose Berkeley DB environment failed to load left the node at height 0,
+    // the scan walked one block, and the message said nothing was found across
+    // 600 addresses.
+    if (!CanScanWalletTransactions(strErrorRet))
+        return false;
+
+    if (!SetHDSeedFromMnemonic(strMnemonic, strErrorRet))
+        return false;
+
+    // Derive forward in batches, scanning after each, until a whole batch turns
+    // up nothing. Every derived key is written to the wallet before the scan,
+    // because the scan asks the wallet what belongs to it.
+    int nTotalDerived = 0;
+    while (nTotalDerived < RESTORE_MAX)
+    {
+        // Count wallet transactions, not scan hits.
+        //
+        // ScanForWalletTransactions reports what it added *or updated*, and it
+        // walks the whole chain every time, so a transaction found in the first
+        // batch is reported again by every batch after it. Testing this against
+        // a real payment produced exactly +1 per batch and a loop that ran to
+        // the ceiling, deriving ten thousand addresses to rediscover one coin.
+        size_t nWalletBefore = 0;
+        CRITICAL_BLOCK(cs_mapWallet)
+            nWalletBefore = mapWallet.size();
+
+        std::string strDeriveError;
+        for (int i = 0; i < RESTORE_BATCH; i++)
+        {
+            CKey key;
+            if (!DeriveHDKey(nHDNext, key, strDeriveError))
+                break;
+            if (!AddKey(key))
+                break;
+            nHDNext++;
+            nTotalDerived++;
+        }
+        CWalletDB().WriteHDNext(nHDNext);
+
+        ScanForWalletTransactions(pindexGenesisBlock);
+
+        size_t nWalletAfter = 0;
+        CRITICAL_BLOCK(cs_mapWallet)
+            nWalletAfter = mapWallet.size();
+
+        if (fnProgress)
+            fnProgress(pArg, nTotalDerived, (int)nWalletAfter);
+
+        // A whole batch with nothing in it means far enough -- unless the
+        // caller asked to look deeper anyway.
+        if (nWalletAfter == nWalletBefore && nTotalDerived >= nMinDepth)
+            break;
+    }
+
+    // The pool is rebuilt from where derivation stopped, so the next address
+    // this wallet hands out is one the phrase can reproduce as well.
+    CRITICAL_BLOCK(cs_keyPool)
+        mapKeyPool.clear();
+    TopUpKeyPool();
+
+    CRITICAL_BLOCK(cs_mapWallet)
+        nRecoveredRet = (int)mapWallet.size();
+    nDerivedRet = nTotalDerived;
+    return true;
+}
+
+static void PrintRestoreProgress(void*, int nDerived, int nRecovered)
+{
+    printf("  %d addresses checked, %d transaction(s) recovered\n", nDerived, nRecovered);
+    fflush(stdout);
+}
+
+int CmdRestorePhrase(const std::string& strMnemonic, int nMinDepth)
+{
+    AttachTerminal();
+
+    printf("Checking the phrase and the chain.\n");
+    fflush(stdout);
+
+    std::string strError;
+    int nRecovered = 0, nDerived = 0;
+    if (!RestoreFromPhrase(strMnemonic, nMinDepth, PrintRestoreProgress, NULL,
+                           strError, nRecovered, nDerived))
+    {
+        fprintf(stderr, "Cannot restore: %s\n", strError.c_str());
+        fprintf(stderr, "Nothing was changed.\n");
+        return 1;
+    }
+
+    printf("\n");
+    if (nRecovered > 0)
+        printf("Restored: %d transaction(s) across %d derived addresses.\n",
+               nRecovered, nDerived);
+    else
+        printf("No transactions were found for the first %d addresses of that phrase.\n"
+               "If you expected coins, check the words and the order.\n", nDerived);
+    printf("Start the node normally to see the balance.\n");
+    fflush(stdout);
+    return 0;
+}
+
+int CmdNewAddress()
+{
+    AttachTerminal();
+
+    std::vector<unsigned char> vchPubKey = GetKeyFromPool();
+    if (vchPubKey.empty())
+    {
+        fprintf(stderr, "Could not get a key from the wallet.\n");
+        return 1;
+    }
+
+    printf("%s\n", PubKeyToAddress(vchPubKey).c_str());
+    if (!HaveHDSeed())
+        printf("(this wallet has no recovery phrase, so only a file backup covers this address)\n");
+    fflush(stdout);
+    return 0;
+}
+
+// Diagnostic: print the addresses a phrase produces, so "the restore found
+// nothing" can be told apart from "that address was never derived".
+int CmdShowDerived(int nCount)
+{
+    AttachTerminal();
+
+    if (!HaveHDSeed())
+    {
+        fprintf(stderr, "This wallet has no recovery phrase installed.\n");
+        return 1;
+    }
+    if (nCount <= 0)
+        nCount = 20;
+
+    std::string strError;
+    for (int i = 0; i < nCount; i++)
+    {
+        CKey key;
+        if (!DeriveHDKey((unsigned int)i, key, strError))
+        {
+            fprintf(stderr, "derivation failed at %d: %s\n", i, strError.c_str());
+            return 1;
+        }
+        printf("%6d  %s\n", i, PubKeyToAddress(key.GetPubKey()).c_str());
+    }
+    fflush(stdout);
+    return 0;
+}
diff --git a/src/walletcmd.h b/src/walletcmd.h
new file mode 100644
index 0000000..89834d8
--- /dev/null
+++ b/src/walletcmd.h
@@ -0,0 +1,43 @@
+// Copyright (c) 2026 Bitflash developers
+// Distributed under the MIT/X11 software license.
+//
+// Recovery-phrase commands. Both run against a loaded wallet and then exit;
+// neither starts the node.
+
+#ifndef BITFLASH_WALLETCMD_H
+#define BITFLASH_WALLETCMD_H
+
+#include <string>
+
+// Create a phrase for a wallet that does not have one, install the seed, and
+// show the words once. Refuses if a phrase already exists. Returns 0 on success.
+int CmdNewPhrase();
+
+// Install the seed a phrase describes, derive forward looking for used
+// addresses, and rescan the chain so their coins appear. Returns 0 on success.
+int CmdRestorePhrase(const std::string& strMnemonic, int nMinDepth = 0);
+
+// Called once per batch with how many addresses have been derived so far and
+// how many transactions the wallet now holds.
+typedef void (*RestoreProgressFn)(void* pArg, int nDerived, int nRecovered);
+
+// The restore itself, shared by the command and the GUI so the two cannot
+// drift apart. Returns false without touching the wallet if the chain is not
+// loaded or the phrase is not valid.
+bool RestoreFromPhrase(const std::string& strMnemonic,
+                       int nMinDepth,
+                       RestoreProgressFn fnProgress,
+                       void* pArg,
+                       std::string& strErrorRet,
+                       int& nRecoveredRet,
+                       int& nDerivedRet);
+
+// Take the next address from the key pool and print it. With a recovery phrase
+// installed the address is derived, so the phrase can bring back whatever is
+// paid to it.
+int CmdNewAddress();
+
+// Diagnostic: print the first nCount addresses this wallet's phrase derives.
+int CmdShowDerived(int nCount);
+
+#endif