@tokamak-private-dapps/private-state-cli 2.1.0 → 2.1.1

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+## 2.1.1 - 2026-05-14
+
+- Changed `channel recover-workspace --from-genesis` to move any existing local channel workspace
+  to `workspace-rebuild-backups/` before writing the current-format workspace. The clean rebuild
+  path is limited to workspace files and preserves local account and wallet key secrets under
+  `secrets/`.
+- Added channel workspace recovery checkpointing at the existing RPC log chunk boundary so
+  interrupted RPC recovery can resume from the last completed chunk.
+- Changed mirror recovery to fall back to a newer verified full mirror checkpoint when no matching
+  delta bundle exists for the local recovery index.
+- Changed `wallet recover-workspace` to use the same bounded channel-workspace freshness preflight
+  as other wallet commands. `wallet recover-workspace --from-genesis` now restarts received-note
+  scanning from channel genesis but does not rebuild the channel workspace from genesis.
+- Added received-note recovery checkpointing at the existing RPC log chunk boundary so ordinary
+  `wallet recover-workspace` resumes from the last completed chunk after an interruption.
+
 ## 2.1.0 - 2026-05-14
 
 - Required current epoch-aware wallet workspaces for wallet commands and backup imports. Local

package/README.md

@@ -151,16 +151,25 @@ Static warning scope:
 centralized-exchange controlled address as a self-custody bridge source or as the direct bridge withdrawal target
 unless the user explicitly understands the compliance implications. Prefer a self-custody L1 wallet.
 
-Workspace recovery commands use the saved recovery index by default. If the local workspace is missing, corrupted, or
-does not contain a usable index, `channel recover-workspace` and `wallet recover-workspace` stop with an explicit error instead of
-silently replaying logs from channel genesis. Use `--source rpc --from-genesis` only when you intentionally want to
-rebuild channel workspace state from the channel creation block:
+Workspace recovery commands use saved recovery indexes by default. If the local channel workspace is missing,
+corrupted, or does not contain a usable index, `channel recover-workspace` stops with an explicit error instead of
+silently replaying logs from channel genesis. Use `channel recover-workspace --source rpc --from-genesis` only when
+you intentionally want to rebuild channel workspace state from the channel creation block:
 
 ```bash
 private-state-cli channel recover-workspace --channel-name <CHANNEL> --network mainnet --source rpc --from-genesis
-private-state-cli wallet recover-workspace --channel-name <CHANNEL> --network mainnet --account <ACCOUNT> --from-genesis
 ```
 
+When `channel recover-workspace --from-genesis` is used, the CLI treats the local channel workspace as a clean rebuild target.
+If `~/tokamak-private-channels/workspace/<network>/<channel>` already exists, it is moved under
+`~/tokamak-private-channels/workspace-rebuild-backups/` before the current-format workspace is
+created. This backup step is workspace-only; files under `~/tokamak-private-channels/secrets/`,
+including account private keys and wallet viewing/spending key files, are not removed.
+During RPC recovery, the CLI writes a usable channel workspace checkpoint after each RPC log chunk. If an RPC recovery
+run is interrupted, the next non-`--from-genesis` RPC recovery resumes from the last completed chunk. Mirror recovery
+can also start from that local checkpoint: it uses a matching delta bundle when one is available, otherwise a newer
+verified full mirror checkpoint replaces the local checkpoint before RPC catch-up.
+
 `channel create` is the exception: after the channel is created on-chain, the CLI initializes that new local workspace
 by replaying from the channel's genesis block because no prior recovery index can exist for a new channel.
 
@@ -169,12 +178,18 @@ registration transaction. For a channel that was created elsewhere, run `channel
 once before joining, or recover from a registered workspace mirror; later joins and wallet commands resume from the
 saved index instead of silently replaying from genesis.
 
-Wallet getter commands that need channel state, including `wallet get-meta`, `wallet get-channel-fund`, and
-`wallet get-notes`, refresh stale local workspaces through saved recovery indexes before reading state. `wallet get-notes`
-also refreshes received-note logs through the saved wallet note recovery index. Automatic refresh never replays from
-channel genesis and only runs when the recovery delta fits within the 7,200-block pre-command budget. If a saved index
-is missing, unusable, or too far behind, the command stops and asks the user to run the appropriate recovery command
-with `--from-genesis` explicitly when needed.
+Wallet commands that need channel state, including `wallet recover-workspace`, `wallet get-meta`,
+`wallet get-channel-fund`, and `wallet get-notes`, refresh stale local channel workspaces through saved recovery
+indexes before reading state. `wallet get-notes` and `wallet recover-workspace` also refresh received-note logs
+through the saved wallet note recovery index. Automatic refresh never replays from channel genesis and only runs when
+the recovery delta fits within the 7,200-block pre-command budget. If a saved index is missing, unusable, or too far
+behind, the command stops and asks the user to run the appropriate recovery command first.
+
+Wallet note-delivery recovery checkpoints after each RPC log chunk by updating
+`noteReceiveLastScannedBlock`. If an ordinary `wallet recover-workspace` run is interrupted during note recovery, the
+next run resumes from the last completed chunk. This does not add a special resume path for
+`wallet recover-workspace --from-genesis`; that command intentionally starts received-note scanning from channel
+genesis after the channel workspace has passed the same freshness preflight used by other wallet commands.
 
 Local wallet workspaces are epoch-aware. Each successful channel registration creates a wallet epoch under the
 canonical wallet directory. `channel exit` does not delete the local wallet workspace; it marks the active epoch as
@@ -419,6 +434,12 @@ Operating rules:
   - A workspace recovery index is the saved block pointer and state-root hash that lets the CLI resume log scanning
     without replaying the channel from its creation block. If it is missing, explain `--from-genesis` before using it
     because genesis replay can take much longer.
+- Before guiding a user to run `channel recover-workspace --source rpc --from-genesis`, explain that RPC genesis
+  recovery can be very slow because it scans channel logs from the creation block. If a channel workspace mirror is
+  available, try mirror-based recovery first, and use RPC genesis replay only when mirror recovery is unavailable or
+  unsuitable.
+- When a CLI command fails, read the error message and any printed `Try:` hints first. Prefer the corrective action
+  suggested by the CLI before inventing a different recovery sequence.
 - When the user does not have a network RPC URL yet, explain that they need an Ethereum JSON-RPC endpoint for the
   selected network. They can obtain one from an infrastructure provider such as Alchemy, Infura, QuickNode, or from
   their own node. Ask the user to create or select the endpoint in that provider's UI, then paste only the endpoint URL
@@ -481,7 +502,7 @@ Suggested interaction flow:
    `wallet mint-notes`.
 7. For a confidential note transfer, select available note IDs from `wallet get-notes`, find the recipient L2 address from
    `wallet get-meta`, then build `wallet transfer-notes`.
-8. After transfer, guide the recipient to run `wallet get-notes`; it refreshes received notes from the saved recovery index when the delta fits the 7,200-block pre-command budget. If the index is missing or too far behind, explain `wallet recover-workspace --from-genesis`.
+8. After transfer, guide the recipient to run `wallet get-notes`; it refreshes received notes from the saved recovery index when the delta fits the 7,200-block pre-command budget. If the index is missing or too far behind, explain `wallet recover-workspace`.
 
 Example onboarding explanation for `channel join`:
 

package/lib/private-state-cli-command-registry.mjs

@@ -337,8 +337,11 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     help: [
       "By default, --source rpc resumes RPC log scanning from the workspace recovery index when available",
       "--source mirror validates the channel leader's registered checkpoint manifest, downloads only the needed checkpoint or delta bundle, and then replays RPC logs to latest",
+      "RPC recovery writes a usable channel workspace checkpoint after each RPC log chunk, so interrupted runs can resume from the last completed chunk",
+      "Mirror recovery uses a matching delta bundle when available; otherwise a newer verified full checkpoint replaces the local checkpoint before RPC catch-up",
       "Fails instead of falling back to genesis when no usable recovery index exists",
       "Use --source rpc --from-genesis to ignore the recovery index and replay logs from channel genesis",
+      "--from-genesis moves the existing local channel workspace to workspace-rebuild-backups before writing the current-format workspace; local secrets are preserved",
       "Prints RPC log scan progress while rebuilding the workspace",
     ],
   },
@@ -410,10 +413,11 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     help: [
       "Rebuilds backup metadata from channel state without recreating the spending key",
       "Derives and stores the viewing key when the local account signer can reproduce the registered viewing public key",
-      "By default, resumes RPC log scanning from the workspace recovery index when available",
-      "Fails instead of falling back to genesis when no usable recovery index exists",
-      "Use --from-genesis to ignore the recovery index and replay channel logs from channel genesis",
-      "Prints RPC log scan progress while rebuilding channel state and received-note state",
+      "Before wallet recovery, refreshes stale channel workspace state only when the saved recovery index delta fits the pre-command budget",
+      "Fails and asks for channel recover-workspace first when the channel workspace is missing, unusable, or too stale for automatic recovery",
+      "Use --from-genesis to restart received-note scanning from channel genesis; it does not rebuild the channel workspace from genesis",
+      "Received-note recovery checkpoints after each RPC log chunk during ordinary recovery; --from-genesis still starts received-note scanning from channel genesis",
+      "Prints RPC log scan progress while refreshing channel state and rebuilding received-note state",
     ],
   },
   {
@@ -619,7 +623,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     help: [
       "Refreshes the local channel workspace through the saved recovery index before reading notes when the scan fits the 10 second pre-command budget",
       "Refreshes received-note logs through the saved wallet note recovery index when the scan fits the 10 second pre-command budget",
-      "Fails instead of replaying from genesis; run wallet recover-workspace --from-genesis when a genesis rebuild is required",
+      "Fails instead of replaying from genesis; run wallet recover-workspace first when explicit wallet recovery is required",
       "Use --export-evidence <PATH> with --acknowledge-full-note-plaintext-export to write a local full-note evidence ZIP for private-state-cli investigator",
       "Evidence export includes all local epochs for the selected wallet, including exited epochs retained for dispute evidence",
     ],

package/lib/private-state-note-delivery.mjs

@@ -1,7 +1,12 @@
 import { randomBytes } from "node:crypto";
 import { AbiCoder, ethers } from "ethers";
-import { deriveL2KeysFromSignature, poseidon } from "tokamak-l2js";
+import { deriveL2KeysFromSignature } from "tokamak-l2js";
 import { jubjub } from "@noble/curves/jubjub";
+import {
+  normalizeBytesHex,
+  normalizeBytes32Hex,
+  poseidonHexFromBytes,
+} from "@tokamak-private-dapps/common-library/tokamak-l2-helpers";
 
 const abiCoder = AbiCoder.defaultAbiCoder();
 
@@ -42,18 +47,6 @@ function expect(condition, message) {
   }
 }
 
-function normalizeBytes32Hex(value) {
-  return ethers.hexlify(ethers.zeroPadValue(ethers.hexlify(value), 32)).toLowerCase();
-}
-
-function normalizeBytes16Hex(value) {
-  return ethers.hexlify(ethers.zeroPadValue(ethers.hexlify(value), 16)).toLowerCase();
-}
-
-function poseidonHexFromBytes(bytesLike) {
-  return ethers.hexlify(poseidon(ethers.getBytes(bytesLike))).toLowerCase();
-}
-
 function noteReceivePubKeyFromPoint(point) {
   const affine = point.toAffine();
   return {
@@ -371,7 +364,7 @@ function decryptFieldEncryptedNoteValue({
     encryptionInfo,
   });
   expect(
-    normalizeBytes16Hex(expectedTag) === normalizeBytes16Hex(normalized.tag),
+    normalizeBytesHex(expectedTag, 16) === normalizeBytesHex(normalized.tag, 16),
     "Encrypted note value integrity tag mismatch.",
   );
   const fieldMask = deriveFieldMask({

package/lib/private-state-runtime-management.mjs

@@ -9,7 +9,6 @@ import { fetchNpmPackageMetadata } from "@tokamak-private-dapps/common-library/n
 import {
   normalizePackageVersionToCompatibleBackendVersion,
   readTokamakZkEvmCompatibleBackendVersionFromPackageJson,
-  requireCanonicalCompatibleBackendVersion,
   requireExactSemverVersion,
 } from "@tokamak-private-dapps/common-library/proof-backend-versioning";
 import {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamak-private-dapps/private-state-cli",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "Command-line client for the Tokamak private-state DApp.",
   "license": "MIT OR Apache-2.0",
   "author": "Tokamak Network",
@@ -44,7 +44,7 @@
   "dependencies": {
     "@ethereumjs/util": "^10.1.1",
     "@noble/curves": "1.9.7",
-    "@tokamak-private-dapps/common-library": "^0.1.1",
+    "@tokamak-private-dapps/common-library": "^0.1.2",
     "@tokamak-private-dapps/groth16": "^0.2.0",
     "@tokamak-zk-evm/cli": "^2.1.0",
     "adm-zip": "^0.5.17",

package/private-state-bridge-cli.mjs

@@ -44,6 +44,18 @@ import {
   requireCanonicalCompatibleBackendVersion,
   requireExactSemverVersion,
 } from "@tokamak-private-dapps/common-library/proof-backend-versioning";
+import {
+  bigintToHex32,
+  buildStateManager,
+  buildTokamakTxSnapshot,
+  currentStorageBigInt,
+  deriveChannelTokenVaultLeafIndex,
+  deriveLiquidBalanceStorageKey,
+  fetchContractCodes,
+  normalizeBytesHex,
+  normalizeBytes32Hex,
+  serializeBigInts,
+} from "@tokamak-private-dapps/common-library/tokamak-l2-helpers";
 import {
   resolveTokamakBlockInputConfig,
 } from "@tokamak-private-dapps/common-library/tokamak-runtime-paths";
@@ -107,20 +119,6 @@ import {
   normalizeEncryptedNoteValueWords,
   unpackEncryptedNoteValue,
 } from "./lib/private-state-note-delivery.mjs";
-import {
-  bigintToHex32,
-  buildStateManager,
-  buildTokamakTxSnapshot,
-  bytes32FromHex,
-  currentStorageBigInt,
-  deriveChannelTokenVaultLeafIndex,
-  deriveLiquidBalanceStorageKey,
-  fetchContractCodes,
-  normalizeBytesHex,
-  normalizeBytes32Hex,
-  serializeBigInts,
-} from "./lib/private-state-tokamak-helpers.mjs";
-
 const require = createRequire(import.meta.url);
 const defaultCommandCwd = process.cwd();
 const privateStateCliPackageJson = require("./package.json");
@@ -920,7 +918,12 @@ async function handleWorkspaceInit({ args, network, provider }) {
   const bridgeResources = loadBridgeResources({ chainId: network.chainId });
   const recoverySource = resolveWorkspaceRecoverySource(args);
 
-  const { workspaceDir, workspace, currentSnapshot } = await syncChannelWorkspace({
+  const {
+    workspaceDir,
+    workspace,
+    currentSnapshot,
+    cleanRebuildBackup,
+  } = await syncChannelWorkspace({
     workspaceName,
     channelName,
     network,
@@ -939,6 +942,7 @@ async function handleWorkspaceInit({ args, network, provider }) {
     source: workspace.recoverySource ?? recoverySource,
     workspace: workspaceName,
     workspaceDir,
+    cleanRebuildBackup: cleanRebuildBackup ?? null,
     channelName,
     channelId: workspace.channelId,
     channelManager: workspace.channelManager,
@@ -1649,10 +1653,18 @@ async function fetchChannelWorkspaceMirror({
 
   const mirrorAheadOfLocal = localRecoveryIndex
     && Number(manifestPrecheck.recoveryLastScannedBlock) > Number(localRecoveryIndex.nextBlock);
-  const bundleResult = mirrorAheadOfLocal
+  const deltaBundleDescriptor = mirrorAheadOfLocal
+    ? selectWorkspaceMirrorDeltaBundle({
+      manifest,
+      fromBlock: Number(localRecoveryIndex.nextBlock),
+      toBlock: Number(manifest.checkpoint.recoveryLastScannedBlock) - 1,
+    })
+    : null;
+  const bundleResult = mirrorAheadOfLocal && deltaBundleDescriptor
     ? await fetchAndApplyWorkspaceMirrorDelta({
       manifest,
       manifestUrl,
+      bundleDescriptor: deltaBundleDescriptor,
       localRecoveryIndex,
       chainId,
       channelId,
@@ -2054,6 +2066,7 @@ function validateWorkspaceMirrorCheckpointArchive({
 async function fetchAndApplyWorkspaceMirrorDelta({
   manifest,
   manifestUrl,
+  bundleDescriptor,
   localRecoveryIndex,
   chainId,
   channelId,
@@ -2067,7 +2080,6 @@ async function fetchAndApplyWorkspaceMirrorDelta({
 }) {
   const fromBlock = Number(localRecoveryIndex.nextBlock);
   const toBlock = Number(manifest.checkpoint.recoveryLastScannedBlock) - 1;
-  const bundleDescriptor = selectWorkspaceMirrorDeltaBundle({ manifest, fromBlock, toBlock });
   expect(
     bundleDescriptor,
     `Workspace mirror does not provide a delta bundle for local recovery index ${fromBlock} to checkpoint block ${toBlock}.`,
@@ -2165,6 +2177,7 @@ async function syncChannelWorkspace({
 }) {
   const workspaceDir = channelWorkspacePath(networkNameFromChainId(network.chainId), workspaceName);
   const channelDir = channelDataPath(workspaceDir);
+  let cleanRebuildBackup = null;
   const hasPersistedChannelData = fs.existsSync(channelWorkspaceConfigPath(workspaceDir))
     || fs.existsSync(channelWorkspaceCurrentPath(workspaceDir))
     || fs.existsSync(channelWorkspaceOperationsPath(workspaceDir));
@@ -2176,6 +2189,13 @@ async function syncChannelWorkspace({
   const existingArtifacts = persist && hasPersistedChannelData
     ? loadExistingWorkspaceArtifacts(workspaceDir)
     : null;
+  if (persist && useWorkspaceRecoveryIndex && fromGenesis) {
+    cleanRebuildBackup = backupWorkspaceForCleanRebuild({
+      workspaceDir,
+      networkName: networkNameFromChainId(network.chainId),
+      channelName,
+    });
+  }
 
   const { bridgeDeployment, bridgeAbiManifest } = bridgeResources;
   const bridgeCore = new Contract(bridgeDeployment.bridgeCore, bridgeAbiManifest.contracts.bridgeCore.abi, provider);
@@ -2287,9 +2307,57 @@ async function syncChannelWorkspace({
     throw new Error([
       `Workspace recovery index is missing or unusable for channel ${channelName} on ${networkNameFromChainId(network.chainId)}.`,
       "The CLI will not fall back to replaying channel logs from genesis unless explicitly requested.",
-      "Run channel recover-workspace --source rpc --from-genesis or wallet recover-workspace --from-genesis to rebuild from channel genesis.",
+      "Run channel recover-workspace first to refresh the local channel workspace.",
     ].join(" "));
   }
+  const workspaceBase = {
+    name: workspaceName,
+    network: networkNameFromChainId(network.chainId),
+    chainId: network.chainId,
+    appDeploymentPath: deploymentManifestPath,
+    storageLayoutPath: storageLayoutManifestPath,
+    channelId: channelId.toString(),
+    channelName,
+    dappId: Number(channelInfo.dappId),
+    genesisBlockNumber,
+    bridgeCore: getAddress(bridgeDeployment.bridgeCore),
+    channelManager: getAddress(channelInfo.manager),
+    bridgeTokenVault: getAddress(channelInfo.bridgeTokenVault),
+    canonicalAsset,
+    canonicalAssetDecimals,
+    controller: controllerAddress,
+    l2AccountingVault: l2AccountingVaultAddress,
+    aPubBlockHash: normalizeBytes32Hex(channelInfo.aPubBlockHash),
+    dappMetadataDigestSchema: policySnapshot.dappMetadataDigestSchema,
+    dappMetadataDigest: policySnapshot.dappMetadataDigest,
+    functionRoot: policySnapshot.functionRoot,
+    policySnapshot,
+    managedStorageAddresses,
+    liquidBalancesSlot: liquidBalancesSlot.toString(),
+    recoverySource,
+    workspaceMirror: mirrorRecovery.workspaceMirror,
+  };
+  const buildWorkspaceForSnapshot = ({ currentSnapshot, scanRange }) => {
+    const recoveryRootVectorHash = normalizeBytes32Hex(hashRootVector(currentSnapshot.stateRoots));
+    return {
+      ...workspaceBase,
+      recoveryLastScannedBlock: Number(scanRange.toBlock) + 1,
+      recoveryRootVectorHash,
+      recoveryScanRange: scanRange,
+    };
+  };
+  const persistWorkspaceCheckpoint = persist
+    ? ({ currentSnapshot, scanRange }) => {
+      persistChannelWorkspaceFiles({
+        workspaceDir,
+        channelDir,
+        workspace: buildWorkspaceForSnapshot({ currentSnapshot, scanRange }),
+        currentSnapshot,
+        blockInfo,
+        contractCodes,
+      });
+    }
+    : null;
   const reconstruction = localSnapshotReusable
     ? {
       currentSnapshot: existingArtifacts.stateSnapshot,
@@ -2325,56 +2393,23 @@ async function syncChannelWorkspace({
       fromBlock: selectedRecoveryIndex?.nextBlock ?? genesisBlockNumber,
       toBlock: latestBlock,
       progressAction,
+      onCheckpoint: persistWorkspaceCheckpoint,
     });
   const currentSnapshot = reconstruction.currentSnapshot;
-  const recoveryRootVectorHash = normalizeBytes32Hex(hashRootVector(currentSnapshot.stateRoots));
-  const recoveryLastScannedBlock = Number(reconstruction.scanRange.toBlock) + 1;
-
-  const workspace = {
-    name: workspaceName,
-    network: networkNameFromChainId(network.chainId),
-    chainId: network.chainId,
-    appDeploymentPath: deploymentManifestPath,
-    storageLayoutPath: storageLayoutManifestPath,
-    channelId: channelId.toString(),
-    channelName,
-    dappId: Number(channelInfo.dappId),
-    genesisBlockNumber,
-    bridgeCore: getAddress(bridgeDeployment.bridgeCore),
-    channelManager: getAddress(channelInfo.manager),
-    bridgeTokenVault: getAddress(channelInfo.bridgeTokenVault),
-    canonicalAsset,
-    canonicalAssetDecimals,
-    controller: controllerAddress,
-    l2AccountingVault: l2AccountingVaultAddress,
-    aPubBlockHash: normalizeBytes32Hex(channelInfo.aPubBlockHash),
-    dappMetadataDigestSchema: policySnapshot.dappMetadataDigestSchema,
-    dappMetadataDigest: policySnapshot.dappMetadataDigest,
-    functionRoot: policySnapshot.functionRoot,
-    policySnapshot,
-    managedStorageAddresses,
-    liquidBalancesSlot: liquidBalancesSlot.toString(),
-    recoverySource,
-    workspaceMirror: mirrorRecovery.workspaceMirror,
-    recoveryLastScannedBlock,
-    recoveryRootVectorHash,
-    recoveryScanRange: reconstruction.scanRange,
-  };
+  const workspace = buildWorkspaceForSnapshot({
+    currentSnapshot,
+    scanRange: reconstruction.scanRange,
+  });
 
   if (persist) {
-    ensureDir(channelDir);
-    ensureDir(channelWorkspaceCurrentPath(workspaceDir));
-    ensureDir(channelWorkspaceOperationsPath(workspaceDir));
-    ensureDir(workspaceWalletsDir(workspaceDir));
-
-    writeJsonIfChanged(channelWorkspaceConfigPath(workspaceDir), workspace);
-    writeJsonIfChanged(path.join(channelWorkspaceCurrentPath(workspaceDir), "state_snapshot.json"), currentSnapshot);
-    writeJsonIfChanged(
-      path.join(channelWorkspaceCurrentPath(workspaceDir), "state_snapshot.normalized.json"),
+    persistChannelWorkspaceFiles({
+      workspaceDir,
+      channelDir,
+      workspace,
       currentSnapshot,
-    );
-    writeJsonIfChanged(path.join(channelWorkspaceCurrentPath(workspaceDir), "block_info.json"), blockInfo);
-    writeJsonIfChanged(path.join(channelWorkspaceCurrentPath(workspaceDir), "contract_codes.json"), contractCodes);
+      blockInfo,
+      contractCodes,
+    });
   }
 
   return {
@@ -2383,6 +2418,7 @@ async function syncChannelWorkspace({
     currentSnapshot,
     blockInfo,
     contractCodes,
+    cleanRebuildBackup,
   };
 }
 
@@ -2463,39 +2499,13 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
   const channelName = requireArg(args.channelName, "--channel-name");
   const signer = requireL1Signer(args, provider);
   const walletName = walletNameForChannelAndAddress(channelName, signer.address);
-  const bridgeResources = loadBridgeResources({ chainId: network.chainId });
-  const initialized = await syncChannelWorkspace({
-    workspaceName: channelName,
+  const channelContextResult = await loadFreshChannelWorkspaceContextResult({
     channelName,
-    network,
+    networkName: requireNetworkName(args),
     provider,
-    bridgeResources,
-    persist: true,
-    allowExistingWorkspaceSync: true,
-    useWorkspaceRecoveryIndex: true,
-    fromGenesis: args.fromGenesis === true,
     progressAction: "wallet recover-workspace",
   });
-  const context = {
-    workspaceName: channelName,
-    workspaceDir: initialized.workspaceDir,
-    persistChannelWorkspace: true,
-    workspace: initialized.workspace,
-    bridgeAbiManifest: bridgeResources.bridgeAbiManifest,
-    currentSnapshot: initialized.currentSnapshot,
-    blockInfo: initialized.blockInfo,
-    contractCodes: initialized.contractCodes,
-    channelManager: new Contract(
-      initialized.workspace.channelManager,
-      bridgeResources.bridgeAbiManifest.contracts.channelManager.abi,
-      provider,
-    ),
-    bridgeTokenVault: new Contract(
-      initialized.workspace.bridgeTokenVault,
-      bridgeResources.bridgeAbiManifest.contracts.bridgeTokenVault.abi,
-      provider,
-    ),
-  };
+  const context = channelContextResult.context;
   const noteReceiveKeyMaterial = await deriveNoteReceiveKeyMaterial({
     signer,
     chainId: network.chainId,
@@ -2563,6 +2573,8 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
       status: "already-recovered",
       wallet: walletName,
       walletDir: existingWallet.walletDir,
+      recoveredChannelWorkspace: channelContextResult.recoveredWorkspace,
+      channelAutoRecoveryBlockDelta: channelContextResult.autoRecoveryBlockDelta,
       workspace: context.workspaceName,
       channelName: context.workspace.channelName,
       channelId: context.workspace.channelId,
@@ -2612,6 +2624,8 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
     status: "recovered",
     wallet: walletName,
     walletDir: walletContext.walletDir,
+    recoveredChannelWorkspace: channelContextResult.recoveredWorkspace,
+    channelAutoRecoveryBlockDelta: channelContextResult.autoRecoveryBlockDelta,
     workspace: context.workspaceName,
     channelName: context.workspace.channelName,
     channelId: context.workspace.channelId,
@@ -2730,6 +2744,73 @@ function uniquePaths(paths) {
   return [...new Set(paths.map((entry) => path.resolve(entry)))];
 }
 
+function backupWorkspaceForCleanRebuild({ workspaceDir, networkName, channelName }) {
+  const resolvedWorkspaceDir = path.resolve(workspaceDir);
+  if (!fs.existsSync(resolvedWorkspaceDir)) {
+    return null;
+  }
+  expectPathWithinRoot(
+    resolvedWorkspaceDir,
+    workspaceRoot,
+    `Clean rebuild refuses to move a path outside the private-state workspace root: ${resolvedWorkspaceDir}.`,
+  );
+
+  const backupRoot = path.join(
+    privateStateCliDataRoot(),
+    "workspace-rebuild-backups",
+    slugifyPathComponent(networkName),
+  );
+  ensureDir(backupRoot);
+  const timestamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+  const backupBasePath = path.join(
+    backupRoot,
+    `${slugifyPathComponent(channelName)}-${timestamp}`,
+  );
+  const backupPath = nextAvailablePath(backupBasePath);
+  fs.renameSync(resolvedWorkspaceDir, backupPath);
+  return {
+    workspaceDir: resolvedWorkspaceDir,
+    backupPath,
+    secretsPreserved: true,
+  };
+}
+
+function persistChannelWorkspaceFiles({
+  workspaceDir,
+  channelDir,
+  workspace,
+  currentSnapshot,
+  blockInfo,
+  contractCodes,
+}) {
+  ensureDir(channelDir);
+  ensureDir(channelWorkspaceCurrentPath(workspaceDir));
+  ensureDir(channelWorkspaceOperationsPath(workspaceDir));
+  ensureDir(workspaceWalletsDir(workspaceDir));
+
+  writeJsonIfChanged(path.join(channelWorkspaceCurrentPath(workspaceDir), "state_snapshot.json"), currentSnapshot);
+  writeJsonIfChanged(
+    path.join(channelWorkspaceCurrentPath(workspaceDir), "state_snapshot.normalized.json"),
+    currentSnapshot,
+  );
+  writeJsonIfChanged(path.join(channelWorkspaceCurrentPath(workspaceDir), "block_info.json"), blockInfo);
+  writeJsonIfChanged(path.join(channelWorkspaceCurrentPath(workspaceDir), "contract_codes.json"), contractCodes);
+  writeJsonIfChanged(channelWorkspaceConfigPath(workspaceDir), workspace);
+}
+
+function nextAvailablePath(basePath) {
+  if (!fs.existsSync(basePath)) {
+    return basePath;
+  }
+  for (let index = 1; index <= 1000; index += 1) {
+    const candidate = `${basePath}-${index}`;
+    if (!fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  throw new Error(`Unable to allocate a clean rebuild backup path for ${basePath}.`);
+}
+
 function removeManagedRoot({ label, rootPath }) {
   const resolvedPath = path.resolve(rootPath);
   try {
@@ -2950,7 +3031,6 @@ function handleInvestigator() {
 function resolveInvestigatorIndexPath() {
   const candidates = [
     path.join(privateStateCliPackageRoot, "investigator", "index.html"),
-    path.resolve(privateStateCliPackageRoot, "..", "investigator", "index.html"),
   ];
   const htmlPath = candidates.find((candidate) => fs.existsSync(candidate));
   if (!htmlPath) {
@@ -6110,10 +6190,16 @@ async function recoverDeliveredNotesFromEventLogs({
   };
 
   if (scanStartBlock > latestBlock) {
+    const reconciledState = await reconcileWalletNotesWithBridgeState({
+      walletContext,
+      currentSnapshot: context.currentSnapshot,
+      controllerAddress: context.workspace.controller,
+    });
     walletContext.wallet.noteReceiveLastScannedBlock = latestBlock + 1;
     persistWallet(walletContext);
     return {
       importedNotes: [],
+      reconciledState,
       scannedLogs: 0,
       scanRange,
     };
@@ -6124,18 +6210,67 @@ async function recoverDeliveredNotesFromEventLogs({
   );
   const commitmentExistsSlot = ethers.toBigInt(findStorageSlot(storageLayoutManifest, "PrivateStateController", "commitmentExists"));
   const nullifierUsedSlot = ethers.toBigInt(findStorageSlot(storageLayoutManifest, "PrivateStateController", "nullifierUsed"));
-  const observedLogs = await fetchLogsChunked(provider, {
+  const importedNotes = [];
+  let reconciledState = null;
+  let scannedLogs = 0;
+
+  await fetchLogsChunked(provider, {
     address: context.workspace.channelManager,
     topics: [NOTE_VALUE_ENCRYPTED_TOPIC],
     fromBlock: scanStartBlock,
     toBlock: latestBlock,
+    collectLogs: false,
     onProgress: progressAction
       ? createRpcLogScanProgress({ action: progressAction, label: "note-delivery events" })
       : null,
+    onChunk: async ({ logs, chunkToBlock }) => {
+      scannedLogs += logs.length;
+      const importedCandidates = await recoverDeliveredNoteCandidatesFromLogs({
+        logs,
+        walletContext,
+        context,
+        noteReceivePrivateKey,
+        commitmentExistsSlot,
+        nullifierUsedSlot,
+      });
+      if (importedCandidates.length > 0) {
+        importedNotes.push(...mergeTrackedNotesIntoWallet(walletContext, importedCandidates));
+        reconciledState = await reconcileWalletNotesWithBridgeState({
+          walletContext,
+          currentSnapshot: context.currentSnapshot,
+          controllerAddress: context.workspace.controller,
+        });
+      }
+      walletContext.wallet.noteReceiveLastScannedBlock = Number(chunkToBlock) + 1;
+      persistWallet(walletContext);
+    },
   });
 
+  reconciledState = await reconcileWalletNotesWithBridgeState({
+    walletContext,
+    currentSnapshot: context.currentSnapshot,
+    controllerAddress: context.workspace.controller,
+  });
+  walletContext.wallet.noteReceiveLastScannedBlock = latestBlock + 1;
+  persistWallet(walletContext);
+  return {
+    importedNotes,
+    reconciledState,
+    scannedLogs,
+    scanRange,
+  };
+}
+
+async function recoverDeliveredNoteCandidatesFromLogs({
+  logs,
+  walletContext,
+  context,
+  noteReceivePrivateKey,
+  commitmentExistsSlot,
+  nullifierUsedSlot,
+}) {
   const importedCandidates = [];
-  for (const log of observedLogs) {
+  for (const log of logs) {
     const encryptedNoteValue = extractEncryptedNoteValueFromBridgeLog(log);
     if (!encryptedNoteValue) {
       continue;
@@ -6200,21 +6335,7 @@ async function recoverDeliveredNotesFromEventLogs({
     }
     importedCandidates.push(trackedNote);
   }
-
-  const importedNotes = mergeTrackedNotesIntoWallet(walletContext, importedCandidates);
-  const reconciledState = await reconcileWalletNotesWithBridgeState({
-    walletContext,
-    currentSnapshot: context.currentSnapshot,
-    controllerAddress: context.workspace.controller,
-  });
-  walletContext.wallet.noteReceiveLastScannedBlock = latestBlock + 1;
-  persistWallet(walletContext);
-  return {
-    importedNotes,
-    reconciledState,
-    scannedLogs: observedLogs.length,
-    scanRange,
-  };
+  return importedCandidates;
 }
 
 function requireUsableWalletNoteReceiveRecoveryIndex({ walletContext, context, latestBlock }) {
@@ -6228,7 +6349,7 @@ function requireUsableWalletNoteReceiveRecoveryIndex({ walletContext, context, l
     throw new Error([
       `Wallet note recovery index is missing or unusable for wallet ${walletContext.walletName}.`,
       `Expected noteReceiveLastScannedBlock to be an integer between ${genesisBlockNumber} and ${Number(latestBlock) + 1}.`,
-      "Run wallet recover-workspace --from-genesis to rebuild wallet note state from channel genesis.",
+      "Run wallet recover-workspace --from-genesis to restart received-note scanning from channel genesis.",
     ].join(" "));
   }
   return nextBlock;
@@ -6274,7 +6395,7 @@ async function ensureWalletNoteReceiveStateCurrent({
     throw new Error([
       `Wallet note recovery index is missing or unusable for wallet ${walletContext.walletName}.`,
       "Automatic wallet recovery uses only the saved note recovery index and will not replay from genesis.",
-      `Run wallet recover-workspace --channel-name ${context.workspace.channelName} --network ${context.workspace.network} --account <ACCOUNT> --from-genesis if a genesis rebuild is required.`,
+      `Run wallet recover-workspace --channel-name ${context.workspace.channelName} --network ${context.workspace.network} --account <ACCOUNT> --from-genesis if received-note scanning must restart from channel genesis.`,
       `Details: ${indexError.message}`,
     ].join(" "));
   }
@@ -6312,7 +6433,7 @@ async function ensureWalletNoteReceiveStateCurrent({
     throw new Error([
       `Wallet workspace is not current for wallet ${walletContext.walletName}.`,
       "Automatic wallet recovery uses only the saved note recovery index and will not replay from genesis.",
-      `Run wallet recover-workspace --channel-name ${context.workspace.channelName} --network ${context.workspace.network} --account <ACCOUNT> --from-genesis if a genesis rebuild is required.`,
+      `Run wallet recover-workspace --channel-name ${context.workspace.channelName} --network ${context.workspace.network} --account <ACCOUNT> --from-genesis if received-note scanning must restart from channel genesis.`,
       `Details: ${recoveryError.message}`,
     ].join(" "));
   }
@@ -6328,7 +6449,7 @@ async function ensureWalletNoteReceiveStateCurrent({
     throw new Error([
       `Wallet workspace is still stale after recovery-index sync for wallet ${walletContext.walletName}.`,
       "Automatic wallet recovery will not replay from genesis.",
-      `Run wallet recover-workspace --channel-name ${context.workspace.channelName} --network ${context.workspace.network} --account <ACCOUNT> --from-genesis if a genesis rebuild is required.`,
+      `Run wallet recover-workspace --channel-name ${context.workspace.channelName} --network ${context.workspace.network} --account <ACCOUNT> --from-genesis if received-note scanning must restart from channel genesis.`,
       `Details: ${postRecoveryError.message}`,
     ].join(" "));
   }
@@ -6948,7 +7069,7 @@ async function recoverChannelWorkspaceFromIndexOnly({
     throw new Error([
       `Channel workspace is not current for ${channelName} on ${networkName}.`,
       "Automatic channel workspace recovery uses only the saved recovery index and will not replay from genesis.",
-      `Run channel recover-workspace --channel-name ${channelName} --network ${networkName} --source rpc --from-genesis if a genesis rebuild is required.`,
+      `Run channel recover-workspace --channel-name ${channelName} --network ${networkName} first.`,
       `Details: ${recoveryError.message}`,
       cause ? `Initial freshness failure: ${cause.message}` : null,
     ].filter(Boolean).join(" "));
@@ -6961,7 +7082,7 @@ async function recoverChannelWorkspaceFromIndexOnly({
     throw new Error([
       `Channel workspace is still stale after recovery-index sync for ${channelName} on ${networkName}.`,
       "Automatic channel workspace recovery will not replay from genesis.",
-      `Run channel recover-workspace --channel-name ${channelName} --network ${networkName} --source rpc --from-genesis if a genesis rebuild is required.`,
+      `Run channel recover-workspace --channel-name ${channelName} --network ${networkName} first.`,
       `Details: ${postRecoveryError.message}`,
       cause ? `Initial freshness failure: ${cause.message}` : null,
     ].filter(Boolean).join(" "));
@@ -6985,7 +7106,7 @@ async function requireChannelWorkspaceRecoveryIndexForAutoRefresh({
     throw new Error([
       message,
       "Automatic channel workspace recovery uses only the saved recovery index and will not replay from genesis.",
-      `Run channel recover-workspace --channel-name ${channelName} --network ${networkName} --source rpc --from-genesis if a genesis rebuild is required.`,
+      `Run channel recover-workspace --channel-name ${channelName} --network ${networkName} first.`,
       cause ? `Initial freshness failure: ${cause.message}` : null,
     ].filter(Boolean).join(" "));
   };
@@ -7995,9 +8116,9 @@ async function buildGrothTransition({ operationDir, workspace, stateManager, vau
     update: {
       currentRootVector: normalizedRootVector(currentSnapshot.stateRoots),
       updatedRoot: bigintToHex32(updatedRoot),
-      currentUserKey: bytes32FromHex(keyHex),
+      currentUserKey: normalizeBytes32Hex(keyHex),
       currentUserValue: currentValue,
-      updatedUserKey: bytes32FromHex(keyHex),
+      updatedUserKey: normalizeBytes32Hex(keyHex),
       updatedUserValue: nextValue,
     },
     nextSnapshot,
@@ -8188,10 +8309,6 @@ function normalizeBytes12Hex(value) {
   return normalizeBytesHex(value, 12);
 }
 
-function normalizeBytes16Hex(value) {
-  return normalizeBytesHex(value, 16);
-}
-
 function hashTokamakPublicInputs(values) {
   return keccak256(abiCoder.encode(["uint256[]"], [values]));
 }
@@ -8319,6 +8436,67 @@ async function fetchChannelRecoveryLogs({
   };
 }
 
+async function fetchChannelRecoveryEventGroupsChunked({
+  provider,
+  bridgeAbiManifest,
+  channelInfo,
+  channelManager = null,
+  fromBlock,
+  toBlock,
+  progressAction = null,
+  onChunk,
+}) {
+  const resolvedChannelManager = channelManager ?? new Contract(
+    channelInfo.manager,
+    bridgeAbiManifest.contracts.channelManager.abi,
+    provider,
+  );
+  const currentRootVectorObservedTopic =
+    normalizeBytes32Hex(resolvedChannelManager.interface.getEvent("CurrentRootVectorObserved").topicHash);
+  const bridgeTokenVault = new Contract(
+    channelInfo.bridgeTokenVault,
+    bridgeAbiManifest.contracts.bridgeTokenVault.abi,
+    provider,
+  );
+  const bridgeVaultTopic = bridgeTokenVault.interface.getEvent("StorageWriteObserved").topicHash;
+
+  await fetchLogsChunked(provider, {
+    address: channelInfo.manager,
+    topics: [[
+      currentRootVectorObservedTopic,
+      CONTROLLER_STORAGE_KEY_OBSERVED_TOPIC,
+      VAULT_STORAGE_WRITE_OBSERVED_TOPIC,
+    ]],
+    fromBlock,
+    toBlock,
+    collectLogs: false,
+    onProgress: progressAction
+      ? createRpcLogScanProgress({ action: progressAction, label: "channel-recovery chunks" })
+      : null,
+    onChunk: async ({ logs: channelManagerLogs, chunkFromBlock, chunkToBlock }) => {
+      await throttleLogRequest();
+      const bridgeVaultLogs = await provider.getLogs({
+        address: channelInfo.bridgeTokenVault,
+        topics: [bridgeVaultTopic],
+        fromBlock: chunkFromBlock,
+        toBlock: chunkToBlock,
+      });
+      const groupedValues = normalizeWorkspaceMirrorDeltaEventGroups({
+        logs: [...channelManagerLogs, ...bridgeVaultLogs],
+        channelInfo,
+        bridgeAbiManifest,
+        fromBlock: chunkFromBlock,
+        toBlock: chunkToBlock,
+      });
+      await onChunk?.({
+        groupedValues,
+        chunkFromBlock,
+        chunkToBlock,
+      });
+    },
+  });
+}
+
 async function reconstructChannelSnapshot({
   provider,
   bridgeAbiManifest,
@@ -8336,6 +8514,7 @@ async function reconstructChannelSnapshot({
   fromBlock = genesisBlockNumber,
   toBlock = null,
   progressAction = null,
+  onCheckpoint = null,
 }) {
   let startingSnapshot = baseSnapshot;
   if (!startingSnapshot) {
@@ -8351,11 +8530,20 @@ async function reconstructChannelSnapshot({
 
   const latestBlock = toBlock === null ? await provider.getBlockNumber() : Number(toBlock);
   const scanFromBlock = Math.max(Number(genesisBlockNumber), Number(fromBlock));
-  const {
-    currentRootVectorObservedTopic,
-    channelManagerLogs,
-    bridgeVaultLogs,
-  } = await fetchChannelRecoveryLogs({
+  let currentSnapshot = startingSnapshot;
+  if (onCheckpoint && scanFromBlock <= latestBlock) {
+    await onCheckpoint({
+      currentSnapshot,
+      scanRange: {
+        fromBlock: scanFromBlock,
+        toBlock: scanFromBlock - 1,
+        mode: baseSnapshot ? "recovery-index-initial" : "genesis-initial",
+      },
+    });
+  }
+  const stateManager = await buildStateManager(currentSnapshot, contractCodes);
+
+  await fetchChannelRecoveryEventGroupsChunked({
     provider,
     bridgeAbiManifest,
     channelInfo,
@@ -8363,37 +8551,27 @@ async function reconstructChannelSnapshot({
     fromBlock: scanFromBlock,
     toBlock: latestBlock,
     progressAction,
-  });
-  const channelManagerEvents = channelManagerLogs.map((log) => {
-    const topic0 = log.topics[0] ? normalizeBytes32Hex(log.topics[0]) : null;
-    if (topic0 !== null && ethers.toBigInt(topic0) === ethers.toBigInt(currentRootVectorObservedTopic)) {
-      const parsed = channelManager.interface.parseLog(log);
-      return {
-        ...log,
-        args: parsed.args,
-        fragment: parsed.fragment,
-      };
-    }
-    return log;
-  });
-
-  const groupedEvents = new Map();
-  for (const event of [...channelManagerEvents, ...bridgeVaultLogs]) {
-    const key = event.transactionHash;
-    const group = groupedEvents.get(key) ?? [];
-    group.push(event);
-    groupedEvents.set(key, group);
-  }
-
-  const groupedValues = [...groupedEvents.values()].sort((left, right) => compareLogsByPosition(left[0], right[0]));
-  const currentSnapshot = await applyChannelRecoveryEventGroups({
-    startingSnapshot,
-    groupedValues,
-    contractCodes,
-    channelInfo,
-    controllerAddress,
-    l2AccountingVaultAddress,
-    liquidBalancesSlot,
+    onChunk: async ({ groupedValues, chunkFromBlock, chunkToBlock }) => {
+      currentSnapshot = await applyChannelRecoveryEventGroupsToStateManager({
+        stateManager,
+        fallbackSnapshot: currentSnapshot,
+        groupedValues,
+        channelInfo,
+        controllerAddress,
+        l2AccountingVaultAddress,
+        liquidBalancesSlot,
+      });
+      await onCheckpoint?.({
+        currentSnapshot,
+        scanRange: {
+          fromBlock: scanFromBlock,
+          toBlock: chunkToBlock,
+          chunkFromBlock,
+          chunkToBlock,
+          mode: baseSnapshot ? "recovery-index" : "genesis",
+        },
+      });
+    },
   });
 
   expect(
@@ -8421,9 +8599,28 @@ async function applyChannelRecoveryEventGroups({
   l2AccountingVaultAddress,
   liquidBalancesSlot,
 }) {
-  let currentSnapshot = startingSnapshot;
-  const stateManager = await buildStateManager(currentSnapshot, contractCodes);
+  const stateManager = await buildStateManager(startingSnapshot, contractCodes);
+  return applyChannelRecoveryEventGroupsToStateManager({
+    stateManager,
+    fallbackSnapshot: startingSnapshot,
+    groupedValues,
+    channelInfo,
+    controllerAddress,
+    l2AccountingVaultAddress,
+    liquidBalancesSlot,
+  });
+}
 
+async function applyChannelRecoveryEventGroupsToStateManager({
+  stateManager,
+  fallbackSnapshot,
+  groupedValues,
+  channelInfo,
+  controllerAddress,
+  l2AccountingVaultAddress,
+  liquidBalancesSlot,
+}) {
+  let currentSnapshot = fallbackSnapshot;
   for (const group of groupedValues) {
     const orderedGroup = [...group].sort(compareLogsByPosition);
     const rootEvent = orderedGroup.find(
@@ -8670,11 +8867,14 @@ async function fetchLogsChunked(provider, {
   fromBlock,
   toBlock,
   initialChunkSize = DEFAULT_LOG_CHUNK_SIZE,
+  collectLogs = true,
   onProgress = null,
+  onChunk = null,
 }) {
   const normalizedFromBlock = Number(fromBlock);
   const resolvedToBlock = toBlock === "latest" ? await provider.getBlockNumber() : Number(toBlock);
   const aggregatedLogs = [];
+  let logsFound = 0;
 
   if (normalizedFromBlock > resolvedToBlock) {
     onProgress?.({
@@ -8702,27 +8902,15 @@ async function fetchLogsChunked(provider, {
   let cursor = normalizedFromBlock;
   while (cursor <= resolvedToBlock) {
     const chunkToBlock = Math.min(resolvedToBlock, cursor + chunkSize - 1);
+    let logs;
     try {
       await throttleLogRequest();
-      const logs = await provider.getLogs({
+      logs = await provider.getLogs({
         address,
         topics,
         fromBlock: cursor,
         toBlock: chunkToBlock,
       });
-      aggregatedLogs.push(...logs);
-      onProgress?.({
-        status: "progress",
-        fromBlock: normalizedFromBlock,
-        toBlock: resolvedToBlock,
-        chunkFromBlock: cursor,
-        chunkToBlock,
-        scannedBlocks: chunkToBlock - normalizedFromBlock + 1,
-        totalBlocks,
-        logsFound: aggregatedLogs.length,
-        chunkLogs: logs.length,
-      });
-      cursor = chunkToBlock + 1;
     } catch (error) {
       if (isRateLimitError(error)) {
         throw new Error(
@@ -8735,7 +8923,36 @@ async function fetchLogsChunked(provider, {
         throw error;
       }
       chunkSize = suggestedChunkSize;
+      continue;
+    }
+    logsFound += logs.length;
+    if (collectLogs) {
+      aggregatedLogs.push(...logs);
     }
+    onProgress?.({
+      status: "progress",
+      fromBlock: normalizedFromBlock,
+      toBlock: resolvedToBlock,
+      chunkFromBlock: cursor,
+      chunkToBlock,
+      scannedBlocks: chunkToBlock - normalizedFromBlock + 1,
+      totalBlocks,
+      logsFound,
+      chunkLogs: logs.length,
+    });
+    await onChunk?.({
+      status: "progress",
+      fromBlock: normalizedFromBlock,
+      toBlock: resolvedToBlock,
+      chunkFromBlock: cursor,
+      chunkToBlock,
+      scannedBlocks: chunkToBlock - normalizedFromBlock + 1,
+      totalBlocks,
+      logsFound,
+      chunkLogs: logs.length,
+      logs,
+    });
+    cursor = chunkToBlock + 1;
   }
 
   onProgress?.({
@@ -8744,7 +8961,7 @@ async function fetchLogsChunked(provider, {
     toBlock: resolvedToBlock,
     scannedBlocks: totalBlocks,
     totalBlocks,
-    logsFound: aggregatedLogs.length,
+    logsFound,
   });
 
   return aggregatedLogs;
@@ -8780,7 +8997,7 @@ function assertAutoRecoveryBlockBudget({
     `Automatic recovery for ${label} would exceed the ${AUTO_RECOVERY_BLOCK_BUDGET}-block pre-command budget.`,
     `Recovery delta is ${blockDelta} blocks from ${normalizedFromBlock} to ${normalizedToBlock}.`,
     `Remaining automatic recovery budget is ${normalizedBudget} blocks.`,
-    `Run ${recoveryCommand} first; add --from-genesis only if the saved recovery index is unusable.`,
+    `Run ${recoveryCommand} first.`,
   ].join(" "));
 }
 
@@ -10512,9 +10729,9 @@ function writeEncryptedWalletFile(filePath, plaintextBytes, walletSecret) {
     version: WALLET_ENCRYPTION_VERSION,
     algorithm: WALLET_ENCRYPTION_ALGORITHM,
     kdf: "scrypt",
-    salt: normalizeBytes16Hex(salt),
+    salt: normalizeBytesHex(salt, 16),
     iv: normalizeBytes12Hex(iv),
-    tag: normalizeBytes16Hex(tag),
+    tag: normalizeBytesHex(tag, 16),
     ciphertext: ethers.hexlify(ciphertext),
   };
   fs.writeFileSync(filePath, `${JSON.stringify(envelope, null, 2)}\n`);
@@ -11012,8 +11229,7 @@ function buildRecoveryHints(error, args = {}) {
   }
 
   if (message.includes("Workspace recovery index is missing or unusable")) {
-    hints.push(`private-state-cli channel recover-workspace --channel-name ${channelName} --network ${networkName} --source rpc --from-genesis`);
-    hints.push(`private-state-cli wallet recover-workspace --channel-name ${channelName} --network ${networkName} --account ${accountName} --from-genesis`);
+    hints.push(`private-state-cli channel recover-workspace --channel-name ${channelName} --network ${networkName}`);
   }
 
   if (message.includes("Wallet note recovery index is missing or unusable")) {

package/lib/private-state-tokamak-helpers.mjs

@@ -1,184 +0,0 @@
-import { ethers, getAddress } from "ethers";
-import {
-  MAX_MT_LEAVES,
-  TokamakL2StateManager,
-  createTokamakL2Common,
-  createTokamakL2StateManagerFromStateSnapshot,
-  createTokamakL2Tx,
-  getUserStorageKey,
-  poseidon,
-} from "tokamak-l2js";
-import {
-  addHexPrefix,
-  bytesToBigInt,
-  bytesToHex,
-  createAddressFromString,
-  hexToBigInt,
-  hexToBytes,
-} from "@ethereumjs/util";
-import {
-  resolveTokamakBlockInputConfig,
-} from "@tokamak-private-dapps/common-library/tokamak-runtime-paths";
-
-const { previousBlockHashCount: tokamakPrevBlockHashCount } = resolveTokamakBlockInputConfig();
-
-export function normalizeBytesHex(value, byteLength) {
-  if (!Number.isInteger(byteLength) || byteLength <= 0) {
-    throw new Error("normalizeBytesHex requires a positive byte length.");
-  }
-  const targetHexLength = byteLength * 2;
-  let hex;
-  if (typeof value === "string") {
-    const trimmed = value.trim();
-    if (!/^0x[0-9a-fA-F]*$/.test(trimmed)) {
-      throw new Error(`Expected a hex string, received ${value}.`);
-    }
-    hex = trimmed.replace(/^0x/i, "");
-    if (hex.length % 2 !== 0) {
-      hex = `0${hex}`;
-    }
-  } else {
-    hex = ethers.hexlify(value).replace(/^0x/i, "");
-  }
-  if (hex.length > targetHexLength) {
-    throw new Error(`Expected at most ${byteLength} bytes, received ${Math.ceil(hex.length / 2)} bytes.`);
-  }
-  return `0x${hex.padStart(targetHexLength, "0").toLowerCase()}`;
-}
-
-export function normalizeBytes32Hex(hexValue) {
-  return normalizeBytesHex(hexValue, 32);
-}
-
-export function bytes32FromHex(hexValue) {
-  return normalizeBytes32Hex(hexValue);
-}
-
-export function bigintToHex32(value) {
-  return normalizeBytes32Hex(ethers.toBeHex(value));
-}
-
-export function poseidonHexFromBytes(bytesLike) {
-  return ethers.hexlify(poseidon(ethers.getBytes(bytesLike))).toLowerCase();
-}
-
-export function serializeBigInts(value) {
-  return JSON.parse(JSON.stringify(value, (_key, current) => (
-    typeof current === "bigint" ? current.toString() : current
-  )));
-}
-
-export function buildTokamakTxSnapshot({ signerPrivateKey, senderPubKey, to, data, nonce }) {
-  return serializeBigInts(
-    createTokamakL2Tx(
-      {
-        nonce: ethers.toBigInt(nonce),
-        to: createAddressFromString(to),
-        data: hexToBytes(addHexPrefix(String(data ?? "").replace(/^0x/i, ""))),
-        senderPubKey,
-      },
-      { common: createTokamakL2Common() },
-    )
-      .sign(signerPrivateKey)
-      .captureTxSnapshot(),
-  );
-}
-
-export async function fetchContractCodes(provider, addresses, { requireBytecode = false } = {}) {
-  const codes = [];
-  for (const address of addresses) {
-    const normalizedAddress = getAddress(address);
-    const code = await provider.getCode(normalizedAddress);
-    if (requireBytecode && code === "0x") {
-      throw new Error(`No deployed bytecode found at ${normalizedAddress}.`);
-    }
-    codes.push({ address: normalizedAddress, code });
-  }
-  return codes;
-}
-
-export async function buildStateManager(snapshot, contractCodes) {
-  return createTokamakL2StateManagerFromStateSnapshot(snapshot, {
-    contractCodes: contractCodes.map((entry) => ({
-      address: createAddressFromString(entry.address),
-      code: addHexPrefix(entry.code),
-    })),
-  });
-}
-
-export async function currentStorageBigInt(stateManager, address, keyHex) {
-  const valueBytes = await stateManager.getStorage(
-    createAddressFromString(address),
-    hexToBytes(addHexPrefix(String(keyHex ?? "").replace(/^0x/i, ""))),
-  );
-  if (valueBytes.length === 0) {
-    return 0n;
-  }
-  return bytesToBigInt(valueBytes);
-}
-
-export async function putStorageValue(stateManager, address, keyHex, nextValue) {
-  await stateManager.putStorage(
-    createAddressFromString(address),
-    hexToBytes(addHexPrefix(String(keyHex ?? "").replace(/^0x/i, ""))),
-    hexToBytes(addHexPrefix(String(bigintToHex32(nextValue) ?? "").replace(/^0x/i, ""))),
-  );
-}
-
-export async function putStorageAndCapture(stateManager, address, keyHex, nextValue) {
-  await currentStorageBigInt(stateManager, address, keyHex);
-  await putStorageValue(stateManager, address, keyHex, nextValue);
-  return stateManager.captureStateSnapshot();
-}
-
-export async function initializePrivateStateSnapshot({ controllerAddress, vaultAddress, channelId }) {
-  const stateManager = new TokamakL2StateManager({ common: createTokamakL2Common() });
-  const addresses = [controllerAddress, vaultAddress].map((address) => createAddressFromString(address));
-  await stateManager._initializeForAddresses(addresses);
-  stateManager._channelId = channelId;
-  for (const address of addresses) {
-    stateManager._commitResolvedStorageEntries(address, []);
-  }
-  return stateManager.captureStateSnapshot();
-}
-
-export async function getBlockInfoAt(provider, blockNumber, { send = (method, params) => provider.send(method, params) } = {}) {
-  const blockTag = ethers.toQuantity(blockNumber);
-  const block = await send("eth_getBlockByNumber", [blockTag, false]);
-  const prevBlockHashes = [];
-  for (let offset = 1; offset <= tokamakPrevBlockHashCount; offset += 1) {
-    if (blockNumber <= offset) {
-      prevBlockHashes.push("0x0");
-      continue;
-    }
-    const previousBlock = await send("eth_getBlockByNumber", [ethers.toQuantity(blockNumber - offset), false]);
-    prevBlockHashes.push(previousBlock.hash);
-  }
-  const chainId = await send("eth_chainId", []);
-  return {
-    coinBase: block.miner,
-    timeStamp: block.timestamp,
-    blockNumber: block.number,
-    prevRanDao: block.prevRandao ?? block.mixHash ?? block.difficulty ?? "0x0",
-    gasLimit: block.gasLimit,
-    chainId,
-    selfBalance: "0x0",
-    baseFee: block.baseFeePerGas ?? "0x0",
-    prevBlockHashes,
-  };
-}
-
-export async function getFixedBlockInfo(provider, options = {}) {
-  const send = options.send ?? ((method, params) => provider.send(method, params));
-  const latestNumberHex = await send("eth_blockNumber", []);
-  const latestNumber = Number(hexToBigInt(addHexPrefix(String(latestNumberHex ?? "").replace(/^0x/i, ""))));
-  return getBlockInfoAt(provider, latestNumber, { send });
-}
-
-export function deriveLiquidBalanceStorageKey(l2Address, slot) {
-  return normalizeBytes32Hex(bytesToHex(getUserStorageKey([l2Address, ethers.toBigInt(slot)], "TokamakL2")));
-}
-
-export function deriveChannelTokenVaultLeafIndex(storageKey) {
-  return hexToBigInt(addHexPrefix(String(storageKey ?? "").replace(/^0x/i, ""))) % ethers.toBigInt(MAX_MT_LEAVES);
-}