wallet: checkpoint rescan progress when the scan is interrupted

An aborted or shutdown-interrupted rescan discarded all of its progress: nothing
advanced the on-disk best-block locator, so the next run started over. On a large
shielded wallet that is a multi-minute witness rebuild repeated from scratch.

Writes the locator ONCE, at the interrupt, rather than periodically through the
scan. That delivers the whole stated benefit -- "resume where it stopped" -- at
the cost of exactly one SetBestChain per interrupted scan. A periodic checkpoint
would additionally survive SIGKILL and power loss, a much weaker requirement, and
it is the part that carries all the cost: SetBestChainINTERNAL is O(whole wallet)
regardless of progress, so on the reported 5.3k-tx / 7.5k-note wallet a checkpoint
every 2500 blocks would plausibly cost more than the rebuild it was meant to save.
If someone later demonstrates a need for crash resilience mid-scan, add it then,
with a measured interval and fFlush=false -- not before.

Two guards, both necessary:

  - CONTIGUITY. The RPC entry points (rescan / importprivkey / z_importkey /
    z_importviewingkey) take a caller-supplied start height validated only against
    chainActive.Height(), never against the wallet's own persisted locator. A scan
    beginning above that locator must not checkpoint at all, or it would record
    the skipped range as scanned and hide any funds in it. Logged once when it
    applies, so an operator can see why an interrupt did not persist.

  - MONOTONICITY. A checkpoint may only advance the locator, never move it back.

The locator points at the last FULLY PROCESSED block -- the parent of the block we
were about to scan -- so resume restarts one block early. CChain::GetLocator pushes
its argument first and FindForkInGlobalIndex returns that same block, so resume
begins AT it; the one-block overlap is deliberate and idempotent, since AddToWallet
only takes its merge path when the transaction is already present.

No witness work is done at the interrupt, which answers the two "//TODO: should we
update witness caches?" comments this replaces: witnesses are re-derived from each
note's own witnessHeight independently of the locator, and witnessRootValidated is
never serialized, so every note is revalidated against hashFinalSaplingRoot on the
next start. A mid-scan checkpoint does capture notes at mixed witnessHeights -- the
in-loop BuildWitnessCache(pindex, true) returns before the extension phase and only
seeds new notes at their own transaction's height -- but that state is recoverable:
the post-loop BuildWitnessCache(tip, false) levels every note, and it now occurs at
most once per scan instead of hundreds of times.

Uses SetBestChainNoFlush so the checkpoint does not trigger a full BDB
txn_checkpoint over the whole cache, and reports failure rather than silently
leaving the operator to discover the replay.

Depends on the fLastRescanCompleted gate in the previous commit: without it
init.cpp would overwrite this checkpoint with a tip locator immediately after the
scan returns.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FU87LdsJZiZkfq1eXubpeo

src/wallet/wallet.cpp

@@ -3463,6 +3463,51 @@ int CWallet::ScanForWalletTransactions(CBlockIndex* pindexStart, bool fUpdate)
             pwalletMain->rescanHeight = pindex ? pindex->GetHeight() : 0;
         }
 
+        // --- interrupt checkpoint setup -------------------------------------------------------
+        // Where does the wallet currently believe it has scanned to? A checkpoint may only ever
+        // ADVANCE that point, and only if this scan is contiguous with it. The RPC entry points
+        // (rescan / importprivkey / z_importkey / z_importviewingkey) take a caller-supplied start
+        // height validated only against chainActive.Height(), so a scan can legitimately begin far
+        // ABOVE the persisted locator -- writing a checkpoint from such a scan would mark the
+        // skipped range as scanned and hide any funds in it.
+        CBlockIndex* pindexPersisted = NULL;
+        {
+            CWalletDB walletdb(strWalletFile, "r+", false);
+            CBlockLocator locPersisted;
+            if (walletdb.ReadBestBlock(locPersisted))
+                pindexPersisted = FindForkInGlobalIndex(chainActive, locPersisted);
+        }
+        const bool fMayCheckpoint = pindexPersisted != NULL &&
+            pindexStart->GetHeight() <= pindexPersisted->GetHeight() + 1;
+        if (!fMayCheckpoint) {
+            LogPrintf("%s: scan starts at %d but the wallet is persisted at %d; progress will NOT be "
+                      "checkpointed on interrupt (a non-contiguous scan cannot safely advance the locator)\n",
+                      __func__, pindexStart->GetHeight(),
+                      pindexPersisted ? pindexPersisted->GetHeight() : -1);
+        }
+
+        // Persist progress when the scan is cut short. `pindexStopped` is the block we were ABOUT to
+        // scan, so the last fully-processed block is its parent. Resume restarts AT the locator's own
+        // block (CChain::GetLocator pushes it first; FindForkInGlobalIndex returns it), giving one
+        // block of deliberate overlap -- idempotent, because AddToWallet only merges when the tx is
+        // already present. No witness work is needed: witnesses are re-derived from each note's own
+        // witnessHeight, and witnessRootValidated is in-memory-only so every note is revalidated
+        // against hashFinalSaplingRoot on the next start.
+        auto checkpointProgress = [&](const CBlockIndex* pindexStopped) {
+            if (!fMayCheckpoint || !pindexStopped || !pindexStopped->pprev)
+                return;
+            const CBlockIndex* pindexDone = pindexStopped->pprev;
+            if (pindexDone->GetHeight() <= pindexPersisted->GetHeight())
+                return;   // never move the locator backwards
+            if (SetBestChainNoFlush(chainActive.GetLocator(pindexDone))) {
+                LogPrintf("%s: checkpointed scan progress at height %d\n", __func__, pindexDone->GetHeight());
+            } else {
+                LogPrintf("%s: FAILED to checkpoint scan progress at height %d; the scan will replay "
+                          "from height %d on the next start\n", __func__, pindexDone->GetHeight(),
+                          pindexPersisted->GetHeight());
+            }
+        };
+
         ShowProgress(_("Rescanning..."), 0); // show rescan progress in GUI as dialog or on splashscreen, if -rescan on startup
         double dProgressStart = Checkpoints::GuessVerificationProgress(chainParams.Checkpoints(), pindex, false);
         double dProgressTip = Checkpoints::GuessVerificationProgress(chainParams.Checkpoints(), chainActive.LastTip(), false);
@@ -3478,11 +3523,13 @@ int CWallet::ScanForWalletTransactions(CBlockIndex* pindexStart, bool fUpdate)
                 pwalletMain->fRescanning  = false;
                 pwalletMain->fAbortRescan = false;   // consume it; see the note at scan entry
                 LogPrintf("%s: Rescan aborted at block %d\n", __func__, pwalletMain->rescanHeight);
+                checkpointProgress(pindex);
                 return ret;
             }
             if (ShutdownRequested()) {
                 pwalletMain->fRescanning = false;
                 LogPrintf("%s: Rescan interrupted by shutdown request at block %d\n", __func__, pwalletMain->rescanHeight);
+                checkpointProgress(pindex);
                 return ret;
             }