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

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");
@@ -137,9 +135,11 @@ const GROTH16_PACKAGE_NAME = "@tokamak-private-dapps/groth16";
 const TOKAMAK_ZKEVM_CLI_PACKAGE_NAME = "@tokamak-zk-evm/cli";
 const WALLET_BACKUP_EXPORT_FORMAT = "tokamak-private-state-wallet-backup-export";
 const WALLET_KEY_EXPORT_FORMAT = "tokamak-private-state-wallet-key-export";
+const WALLET_INDEX_FORMAT = "tokamak-private-state-wallet-index";
 const WALLET_EVIDENCE_BUNDLE_FORMAT = "tokamak-private-state-raw-evidence-bundle";
 const WALLET_EXPORT_FORMAT_VERSION = 2;
-const WALLET_EVIDENCE_BUNDLE_FORMAT_VERSION = 1;
+const WALLET_INDEX_FORMAT_VERSION = 1;
+const WALLET_EVIDENCE_BUNDLE_FORMAT_VERSION = 2;
 const WALLET_WORKSPACE_FORMAT_VERSION = 2;
 const CHANNEL_WORKSPACE_MIRROR_PROTOCOL_VERSION = 2;
 const CHANNEL_WORKSPACE_MIRROR_MANIFEST_PATH_PREFIX =
@@ -918,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,
@@ -937,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,
@@ -1647,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,
@@ -2052,6 +2066,7 @@ function validateWorkspaceMirrorCheckpointArchive({
 async function fetchAndApplyWorkspaceMirrorDelta({
   manifest,
   manifestUrl,
+  bundleDescriptor,
   localRecoveryIndex,
   chainId,
   channelId,
@@ -2065,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}.`,
@@ -2163,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));
@@ -2174,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);
@@ -2285,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,
@@ -2323,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 {
@@ -2381,6 +2418,7 @@ async function syncChannelWorkspace({
     currentSnapshot,
     blockInfo,
     contractCodes,
+    cleanRebuildBackup,
   };
 }
 
@@ -2461,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,
@@ -2502,64 +2514,51 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
     account: signer.address,
   });
   const registration = await context.channelManager.getChannelTokenVaultRegistration(signer.address);
-
-  if (!registration.exists) {
-    const cleanup = removeLocalWalletArtifacts(walletName, context.workspace.network);
-    if (cleanup.removed) {
-      printJson({
-        action: "wallet recover-workspace",
-        status: "stale-wallet-removed",
-        wallet: walletName,
-        removedWalletDir: cleanup.removedWalletDir ? cleanup.walletDir : null,
-        removedWalletSecretFile: cleanup.removedWalletSecret ? cleanup.walletSecretFile : null,
-        workspace: context.workspaceName,
-        channelName: context.workspace.channelName,
-        channelId: context.workspace.channelId,
-        l1Address: signer.address,
-        l2Address: null,
-        l2StorageKey: null,
-        leafIndex: null,
-        reason: "The local wallet existed, but the L1 address is no longer registered in the channel.",
-        nextAction: buildRecoverWalletRemovedNextAction({
-          channelName,
-          networkName: network.name,
-          accountName: args.account,
-        }),
-      });
-      return;
-    }
-    expect(
-      false,
-      cliError(
-        CLI_ERROR_CODES.MISSING_CHANNEL_REGISTRATION,
-        `No channelTokenVault registration exists for ${signer.address}. Run channel join first.`,
-      ),
-    );
-  }
+  const lifecycleEpoch = await resolveWalletLifecycleEpoch({
+    context,
+    provider,
+    l1Address: signer.address,
+    registration,
+  });
+  expect(
+    lifecycleEpoch,
+    cliError(
+      CLI_ERROR_CODES.MISSING_CHANNEL_REGISTRATION,
+      `No channelTokenVault registration history exists for ${signer.address}. Run channel join first.`,
+    ),
+  );
+  const registeredNoteReceivePubKey = lifecycleEpoch.noteReceivePubKey;
   expect(
-    ethers.toBigInt(normalizeBytes32Hex(registration.noteReceivePubKey.x))
+    ethers.toBigInt(normalizeBytes32Hex(registeredNoteReceivePubKey.x))
       === ethers.toBigInt(normalizeBytes32Hex(noteReceiveKeyMaterial.noteReceivePubKey.x)),
     "The existing note-receive public key X does not match the derived note-receive public key.",
   );
   expect(
-    Number(registration.noteReceivePubKey.yParity) === Number(noteReceiveKeyMaterial.noteReceivePubKey.yParity),
+    Number(registeredNoteReceivePubKey.yParity) === Number(noteReceiveKeyMaterial.noteReceivePubKey.yParity),
     "The existing note-receive public key parity does not match the derived note-receive public key.",
   );
   const l2Identity = {
     l2PrivateKey: null,
     l2PublicKey: null,
-    l2Address: getAddress(registration.l2Address),
+    l2Address: getAddress(lifecycleEpoch.l2Address),
   };
-  const storageKey = normalizeBytes32Hex(registration.channelTokenVaultKey);
+  const storageKey = normalizeBytes32Hex(lifecycleEpoch.channelTokenVaultKey);
 
-  const walletDir = walletPath(walletName, context.workspace.network);
+  const walletDir = walletEpochPath(walletName, context.workspace.network, lifecycleEpoch.epochId);
   const existingWallet = walletConfigExists(walletDir)
-    ? loadWallet(walletName, context.workspace.network)
+    ? loadWalletFromDir({
+      walletName,
+      networkName: context.workspace.network,
+      walletDir,
+    })
     : null;
 
   if (existingWallet) {
     existingWallet.wallet.noteReceivePrivateKey = noteReceiveKeyMaterial.privateKey;
+    applyWalletLifecycleEpoch(existingWallet.wallet, lifecycleEpoch);
     persistWalletKeys(existingWallet);
+    persistWallet(existingWallet);
+    persistWalletIndexForContext(existingWallet);
     const { recoveredDeliveryState } = await recoverWalletReceivedNotes({
       walletContext: existingWallet,
       context,
@@ -2574,13 +2573,18 @@ 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,
       l1Address: signer.address,
       l2Address: l2Identity.l2Address,
       l2StorageKey: storageKey,
-      leafIndex: registration.leafIndex.toString(),
+      leafIndex: lifecycleEpoch.leafIndex.toString(),
+      epochId: lifecycleEpoch.epochId,
+      lifecycleStatus: lifecycleEpoch.lifecycleStatus,
+      exitedAtTxHash: lifecycleEpoch.exitedAtTxHash,
       noteReceivePubKey: noteReceiveKeyMaterial.noteReceivePubKey,
       l2Nonce: existingWallet.wallet.l2Nonce,
       recoveredFromLogs: recoveredDeliveryState.importedNotes,
@@ -2590,8 +2594,6 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
     return;
   }
 
-  fs.rmSync(walletPath(walletName, context.workspace.network), { recursive: true, force: true });
-
   const walletContext = ensureWallet({
     channelContext: context,
     signerAddress: signer.address,
@@ -2599,8 +2601,9 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
     l2Identity,
     walletSecret: noteReceiveKeyMaterial.privateKey,
     storageKey,
-    leafIndex: registration.leafIndex,
+    leafIndex: lifecycleEpoch.leafIndex,
     noteReceiveKeyMaterial,
+    lifecycleEpoch,
     rpcUrl,
   });
   walletContext.wallet.l2Nonce = 0;
@@ -2621,13 +2624,18 @@ 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,
     l1Address: signer.address,
     l2Address: l2Identity.l2Address,
     l2StorageKey: storageKey,
-    leafIndex: registration.leafIndex.toString(),
+    leafIndex: lifecycleEpoch.leafIndex.toString(),
+    epochId: lifecycleEpoch.epochId,
+    lifecycleStatus: lifecycleEpoch.lifecycleStatus,
+    exitedAtTxHash: lifecycleEpoch.exitedAtTxHash,
     noteReceivePubKey: noteReceiveKeyMaterial.noteReceivePubKey,
     l2Nonce: walletContext.wallet.l2Nonce,
     recoveredFromLogs: recoveredDeliveryState.importedNotes,
@@ -2636,32 +2644,6 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
   });
 }
 
-function removeLocalWalletArtifacts(walletName, networkName) {
-  const walletDir = walletPath(walletName, networkName);
-  const walletSecretFile = walletSecretPath(networkName, walletName);
-  const walletSecretDir = path.dirname(walletSecretFile);
-  const removedWalletDir = fs.existsSync(walletDir);
-  const removedWalletSecret = fs.existsSync(walletSecretFile) || fs.existsSync(walletSecretDir);
-  if (removedWalletDir) {
-    fs.rmSync(walletDir, { recursive: true, force: true });
-  }
-  if (removedWalletSecret) {
-    fs.rmSync(walletSecretDir, { recursive: true, force: true });
-  }
-  return {
-    walletDir,
-    walletSecretFile,
-    removed: removedWalletDir || removedWalletSecret,
-    removedWalletDir,
-    removedWalletSecret,
-  };
-}
-
-function buildRecoverWalletRemovedNextAction({ channelName, networkName, accountName }) {
-  const account = accountName ? String(accountName) : "<ACCOUNT>";
-  return `channel join --channel-name ${channelName} --network ${networkName} --account ${account} --wallet-secret-path <PATH> --acknowledge-action-impact`;
-}
-
 async function handleInstallZkEvm({ args }) {
   const selectedVersions = await resolvePrivateStateInstallRuntimeVersions(args);
   const tokamakCliRuntime = await installTokamakCliRuntimeForPrivateState({
@@ -2762,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 {
@@ -2982,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) {
@@ -3371,9 +3419,13 @@ function handleWalletImportKey({ args, keyKind }) {
     : walletViewingKeySecretPath(networkName, walletName);
   expect(!fs.existsSync(targetPath), `Refusing to overwrite existing ${keyKind} key: ${targetPath}.`);
   writeSecretFile(targetPath, JSON.stringify(payload, null, 2));
-  const walletDir = walletPath(walletName, networkName);
-  ensureDir(walletDir);
-  if (walletConfigExists(walletDir)) {
+  const walletRoot = walletRootPath(walletName, networkName);
+  const walletIndex = fs.existsSync(walletRoot)
+    ? requireWalletIndex({ walletRoot, walletName, networkName })
+    : null;
+  const selectedEpoch = walletIndex ? selectedWalletEpoch(walletIndex, walletName, networkName) : null;
+  if (selectedEpoch) {
+    const walletDir = walletEpochPathFromRoot(walletRoot, selectedEpoch.epochId);
     const metadataPath = keyKind === "spending"
       ? walletSpendingKeyMetadataPath(walletDir)
       : walletViewingKeyMetadataPath(walletDir);
@@ -3842,7 +3894,13 @@ async function inspectGuideAccount({ account, networkName, network, provider, ar
 }
 
 async function inspectGuideWallet({ walletName, networkName, provider, artifactsInstalled }) {
-  const walletDir = walletPath(walletName, networkName);
+  let walletDir = walletRootPath(walletName, networkName);
+  let workspaceError = null;
+  try {
+    walletDir = selectedWalletEpochDir(walletName, networkName);
+  } catch (error) {
+    workspaceError = error.message;
+  }
   const viewingKeyFile = walletViewingKeySecretPath(networkName, walletName);
   const spendingKeyFile = walletSpendingKeySecretPath(networkName, walletName);
   const result = {
@@ -3865,9 +3923,9 @@ async function inspectGuideWallet({ walletName, networkName, provider, artifacts
     unusedNoteBalanceBaseUnits: null,
     unusedNoteBalanceTokens: null,
     spentNoteCount: null,
-    error: null,
+    error: workspaceError,
   };
-  if (!result.exists) {
+  if (workspaceError || !result.exists) {
     return result;
   }
 
@@ -4109,6 +4167,7 @@ async function handleWalletGetMeta({ args, provider }) {
   printJson({
     action: "wallet get-meta",
     wallet: wallet.walletName,
+    ...walletLifecycleMetadata(wallet.wallet),
     network: walletMetadata.network,
     channelName: walletMetadata.channelName,
     l1Address: signer.address,
@@ -4202,6 +4261,156 @@ async function loadWalletChannelRegistrationState({
   };
 }
 
+async function resolveWalletLifecycleEpoch({
+  context,
+  provider,
+  l1Address,
+  registration = null,
+}) {
+  const epochs = await readWalletLifecycleEpochs({
+    context,
+    provider,
+    l1Address,
+  });
+  if (epochs.length === 0 && registration?.exists) {
+    const block = await provider.getBlock("latest").catch(() => null);
+    return {
+      epochId: `join-registered-${String(registration.joinedAt)}-${String(registration.leafIndex)}`,
+      lifecycleStatus: "active",
+      joinedAtTxHash: null,
+      joinedAtBlockNumber: null,
+      joinedAtLogIndex: null,
+      joinedAtBlockTimestamp: Number(registration.joinedAt),
+      joinedAtBlockTimestampIso: Number(registration.joinedAt) > 0
+        ? new Date(Number(registration.joinedAt) * 1000).toISOString()
+        : null,
+      exitedAtTxHash: null,
+      exitedAtBlockNumber: null,
+      exitedAtLogIndex: null,
+      exitedAtBlockTimestamp: null,
+      exitedAtBlockTimestampIso: null,
+      l2Address: getAddress(registration.l2Address),
+      channelTokenVaultKey: normalizeBytes32Hex(registration.channelTokenVaultKey),
+      leafIndex: registration.leafIndex,
+      noteReceivePubKey: {
+        x: normalizeBytes32Hex(registration.noteReceivePubKey.x),
+        yParity: Number(registration.noteReceivePubKey.yParity),
+      },
+      observedAtBlockNumber: block?.number ?? null,
+    };
+  }
+  if (registration?.exists) {
+    const active = [...epochs].reverse().find((epoch) => (
+      epoch.lifecycleStatus === "active"
+      && ethers.toBigInt(getAddress(epoch.l2Address)) === ethers.toBigInt(getAddress(registration.l2Address))
+      && ethers.toBigInt(normalizeBytes32Hex(epoch.channelTokenVaultKey))
+        === ethers.toBigInt(normalizeBytes32Hex(registration.channelTokenVaultKey))
+    ));
+    if (active) {
+      return active;
+    }
+  }
+  return epochs[epochs.length - 1] ?? null;
+}
+
+async function readWalletLifecycleEpochs({ context, provider, l1Address }) {
+  const fromBlock = Number(context.workspace.genesisBlockNumber ?? 0);
+  const [registeredLogs, exitedLogs] = await Promise.all([
+    context.channelManager.queryFilter(
+      context.channelManager.filters.ChannelTokenVaultIdentityRegistered(l1Address),
+      fromBlock,
+      "latest",
+    ),
+    context.channelManager.queryFilter(
+      context.channelManager.filters.ChannelTokenVaultIdentityExited(l1Address),
+      fromBlock,
+      "latest",
+    ),
+  ]);
+  const exits = await Promise.all(exitedLogs.map((log) => walletExitFromLog({ log, provider })));
+  const epochs = [];
+  for (const log of registeredLogs.sort(compareLogsByPosition)) {
+    const registered = await walletEpochFromRegisteredLog({ log, provider });
+    const exit = exits.find((entry) => (
+      compareLogPosition(entry, registered) > 0
+      && ethers.toBigInt(entry.leafIndex) === ethers.toBigInt(registered.leafIndex)
+      && !epochs.some((epoch) => epoch.exitedAtTxHash === entry.exitedAtTxHash)
+    ));
+    if (exit) {
+      epochs.push({
+        ...registered,
+        lifecycleStatus: "exited",
+        exitedAtTxHash: exit.exitedAtTxHash,
+        exitedAtBlockNumber: exit.exitedAtBlockNumber,
+        exitedAtLogIndex: exit.exitedAtLogIndex,
+        exitedAtBlockTimestamp: exit.exitedAtBlockTimestamp,
+        exitedAtBlockTimestampIso: exit.exitedAtBlockTimestampIso,
+      });
+    } else {
+      epochs.push(registered);
+    }
+  }
+  return epochs.sort(compareWalletEpochs);
+}
+
+async function walletEpochFromRegisteredLog({ log, provider }) {
+  const block = await provider.getBlock(log.blockNumber).catch(() => null);
+  const args = log.args;
+  return {
+    epochId: walletEpochIdFromLog(log),
+    lifecycleStatus: "active",
+    joinedAtTxHash: log.transactionHash,
+    joinedAtBlockNumber: log.blockNumber,
+    joinedAtLogIndex: log.index ?? log.logIndex ?? null,
+    joinedAtBlockTimestamp: block?.timestamp ?? Number(args.joinedAt ?? 0) ?? null,
+    joinedAtBlockTimestampIso: block?.timestamp
+      ? new Date(Number(block.timestamp) * 1000).toISOString()
+      : Number(args.joinedAt ?? 0) > 0
+        ? new Date(Number(args.joinedAt) * 1000).toISOString()
+        : null,
+    exitedAtTxHash: null,
+    exitedAtBlockNumber: null,
+    exitedAtLogIndex: null,
+    exitedAtBlockTimestamp: null,
+    exitedAtBlockTimestampIso: null,
+    l2Address: getAddress(args.l2Address),
+    channelTokenVaultKey: normalizeBytes32Hex(args.channelTokenVaultKey),
+    leafIndex: args.leafIndex,
+    noteReceivePubKey: {
+      x: normalizeBytes32Hex(args.noteReceivePubKeyX),
+      yParity: Number(args.noteReceivePubKeyYParity),
+    },
+  };
+}
+
+async function walletExitFromLog({ log, provider }) {
+  const block = await provider.getBlock(log.blockNumber).catch(() => null);
+  return {
+    exitedAtTxHash: log.transactionHash,
+    exitedAtBlockNumber: log.blockNumber,
+    exitedAtLogIndex: log.index ?? log.logIndex ?? null,
+    exitedAtBlockTimestamp: block?.timestamp ?? null,
+    exitedAtBlockTimestampIso: block?.timestamp ? new Date(Number(block.timestamp) * 1000).toISOString() : null,
+    leafIndex: log.args.leafIndex,
+  };
+}
+
+function walletEpochIdFromLog(log) {
+  return `join-${String(log.transactionHash).toLowerCase()}-${Number(log.index ?? log.logIndex ?? 0)}`;
+}
+
+function compareLogPosition(left, right) {
+  return Number(left.exitedAtBlockNumber ?? left.blockNumber ?? 0) - Number(right.joinedAtBlockNumber ?? right.blockNumber ?? 0)
+    || Number((left.exitedAtLogIndex ?? left.index ?? left.logIndex) ?? 0)
+      - Number((right.joinedAtLogIndex ?? right.index ?? right.logIndex) ?? 0);
+}
+
+function compareWalletEpochs(left, right) {
+  return Number(left.joinedAtBlockNumber ?? 0) - Number(right.joinedAtBlockNumber ?? 0)
+    || Number(left.joinedAtLogIndex ?? 0) - Number(right.joinedAtLogIndex ?? 0)
+    || String(left.epochId).localeCompare(String(right.epochId));
+}
+
 async function handleWalletGetChannelFund({ args, provider }) {
   const { wallet, walletMetadata } = loadUnlockedWalletWithMetadata(args);
   const {
@@ -4311,6 +4520,14 @@ async function handleJoinChannel({ args, network, provider, rpcUrl }) {
       { nonce: nextNonce++ },
     ),
   );
+  const registered = await context.channelManager.getChannelTokenVaultRegistration(signer.address);
+  const lifecycleEpoch = await resolveWalletLifecycleEpoch({
+    context,
+    provider,
+    l1Address: signer.address,
+    registration: registered,
+  });
+  expect(lifecycleEpoch, "Unable to resolve the channel join epoch from emitted registration logs.");
   await refreshPersistedWorkspaceAfterLocalTransaction({
     context,
     provider,
@@ -4327,6 +4544,7 @@ async function handleJoinChannel({ args, network, provider, rpcUrl }) {
     storageKey,
     leafIndex,
     noteReceiveKeyMaterial,
+    lifecycleEpoch,
     rpcUrl,
   });
 
@@ -4343,6 +4561,10 @@ async function handleJoinChannel({ args, network, provider, rpcUrl }) {
     l2Address: l2Identity.l2Address,
     l2StorageKey: storageKey,
     leafIndex: leafIndex.toString(),
+    epochId: lifecycleEpoch.epochId,
+    lifecycleStatus: lifecycleEpoch.lifecycleStatus,
+    joinedAtTxHash: lifecycleEpoch.joinedAtTxHash,
+    joinedAtBlockNumber: lifecycleEpoch.joinedAtBlockNumber,
     joinTollBaseUnits: joinToll.toString(),
     joinTollTokens: ethers.formatUnits(joinToll, Number(context.workspace.canonicalAssetDecimals)),
     noteReceivePubKey: noteReceiveKeyMaterial.noteReceivePubKey,
@@ -4359,6 +4581,7 @@ async function handleJoinChannel({ args, network, provider, rpcUrl }) {
 
 async function handleExitChannel({ args, provider }) {
   const { wallet: walletContext, walletMetadata } = loadUnlockedWalletWithMetadata(args);
+  requireActiveWalletLifecycle(walletContext, "channel exit");
   const { signer, context, channelFund, contextResult } = await loadWalletChannelFundState({
     walletContext,
     provider,
@@ -4378,7 +4601,11 @@ async function handleExitChannel({ args, provider }) {
   const receipt = await waitForReceipt(
     await context.bridgeTokenVault.connect(ownerSigner).exitChannel(ethers.toBigInt(context.workspace.channelId)),
   );
-  const cleanup = removeLocalWalletArtifacts(walletContext.walletName, walletMetadata.network);
+  const lifecycleEpoch = await markWalletEpochExited({
+    walletContext,
+    receipt,
+    provider,
+  });
 
   printJson({
     action: "channel exit",
@@ -4396,8 +4623,12 @@ async function handleExitChannel({ args, provider }) {
     gasUsed: receiptGasUsed(receipt),
     txUrl: explorerTxUrl(network, receipt.hash),
     receipt: sanitizeReceipt(receipt),
-    removedWalletDir: cleanup.removedWalletDir ? cleanup.walletDir : null,
-    removedWalletSecretFile: cleanup.removedWalletSecret ? cleanup.walletSecretFile : null,
+    epochId: lifecycleEpoch.epochId,
+    lifecycleStatus: lifecycleEpoch.lifecycleStatus,
+    exitedAtTxHash: lifecycleEpoch.exitedAtTxHash,
+    exitedAtBlockNumber: lifecycleEpoch.exitedAtBlockNumber,
+    exitedAtBlockTimestampIso: lifecycleEpoch.exitedAtBlockTimestampIso,
+    archivedWalletDir: walletContext.walletDir,
   });
 }
 
@@ -4409,6 +4640,7 @@ async function handleGrothVaultMove({ args, provider, direction }) {
       : "wallet withdraw-channel";
   emitProgress(operationName, "loading");
   const { wallet: walletContext } = loadUnlockedWalletWithMetadata(args);
+  requireActiveWalletLifecycle(walletContext, operationName);
   const contextResult = await loadFreshWalletChannelContext({
     walletContext,
     provider,
@@ -4634,6 +4866,7 @@ function resolveFunctionMetadataProofForExecution({
 
 async function handleMintNotes({ args, provider }) {
   const { wallet } = loadUnlockedWalletWithMetadata(args);
+  requireActiveWalletLifecycle(wallet, "wallet mint-notes");
   requireWalletSpendingCapability(wallet);
   const canonicalAssetDecimals = Number(wallet.wallet.canonicalAssetDecimals);
   const amountInputs = parseAmountVector(requireArg(args.amounts, "--amounts"), {
@@ -4722,6 +4955,7 @@ async function handleMintNotes({ args, provider }) {
 
 async function handleRedeemNotes({ args, provider }) {
   const { wallet } = loadUnlockedWalletWithMetadata(args);
+  requireActiveWalletLifecycle(wallet, "wallet redeem-notes");
   requireWalletViewingCapability(wallet);
   requireWalletSpendingCapability(wallet);
   const noteIds = parseNoteIdVector(requireArg(args.noteIds, "--note-ids"));
@@ -4890,24 +5124,39 @@ async function exportWalletGetNotesEvidenceBundle({
   const outputPath = path.resolve(String(requireArg(args.exportEvidence, "--export-evidence")));
   ensureDir(path.dirname(outputPath));
 
-  const notes = [
-    ...unusedTrackedNotes.map(normalizeTrackedNote),
-    ...spentTrackedNotes.map(normalizeTrackedNote),
-  ].sort((left, right) => left.commitment.localeCompare(right.commitment));
-
-  for (const note of notes) {
-    validateEvidenceNotePlaintext(note, walletContext.wallet);
+  const evidenceWalletContexts = loadWalletEpochContextsForEvidence({
+    baseWalletContext: walletContext,
+    networkName: walletMetadata.network,
+  });
+  const noteInputs = [];
+  for (const candidateWalletContext of evidenceWalletContexts) {
+    const notes = candidateWalletContext === walletContext
+      ? [
+        ...unusedTrackedNotes.map(normalizeTrackedNote),
+        ...spentTrackedNotes.map(normalizeTrackedNote),
+      ]
+      : [
+        ...Object.values(candidateWalletContext.wallet.notes.unused).map(normalizeTrackedNote),
+        ...Object.values(candidateWalletContext.wallet.notes.spent).map(normalizeTrackedNote),
+      ];
+    for (const note of notes) {
+      validateEvidenceNotePlaintext(note, candidateWalletContext.wallet);
+      noteInputs.push({ note, walletContext: candidateWalletContext });
+    }
   }
+  noteInputs.sort((left, right) =>
+    String(left.walletContext.wallet.walletEpochId ?? "").localeCompare(String(right.walletContext.wallet.walletEpochId ?? ""))
+    || left.note.commitment.localeCompare(right.note.commitment));
 
   const txHashes = uniqueNonNull([
-    ...notes.map((note) => note.createdAtTxHash),
-    ...notes.map((note) => note.spentAtTxHash),
+    ...noteInputs.map(({ note }) => note.createdAtTxHash),
+    ...noteInputs.map(({ note }) => note.spentAtTxHash),
   ]);
   const transactionEvidence = await buildTransactionEvidenceMap({ provider, txHashes });
   const blockTimestampCache = buildBlockTimestampCache(transactionEvidence);
-  const noteRecords = notes.map((note) => buildEvidenceNoteRecord({
+  const noteRecords = noteInputs.map(({ note, walletContext: noteWalletContext }) => buildEvidenceNoteRecord({
     note,
-    walletContext,
+    walletContext: noteWalletContext,
     walletMetadata,
     context,
     transactionEvidence,
@@ -4917,6 +5166,7 @@ async function exportWalletGetNotesEvidenceBundle({
   const manifest = buildEvidenceManifest({
     outputPath,
     walletContext,
+    walletContexts: evidenceWalletContexts,
     walletMetadata,
     context,
     noteRecords,
@@ -4932,7 +5182,7 @@ async function exportWalletGetNotesEvidenceBundle({
   addEvidenceJson(archive, "indexes/by-block-range.json", indexes.byBlockRange);
   addEvidenceJson(archive, "indexes/by-counterparty.json", indexes.byCounterparty);
   for (const record of noteRecords) {
-    addEvidenceJson(archive, `notes/${record.derived.commitment}.json`, record);
+    addEvidenceJson(archive, evidenceNotePath(record), record);
   }
   for (const [txHash, txRecord] of Object.entries(transactionEvidence)) {
     addEvidenceJson(archive, `transactions/${txHash}.json`, txRecord.transaction);
@@ -4941,7 +5191,7 @@ async function exportWalletGetNotesEvidenceBundle({
   }
 
   assertEvidenceBundleDoesNotContainSecrets({
-    wallet: walletContext.wallet,
+    wallets: evidenceWalletContexts.map((entry) => entry.wallet),
     payload: {
       manifest,
       indexes,
@@ -4958,6 +5208,7 @@ async function exportWalletGetNotesEvidenceBundle({
     format: WALLET_EVIDENCE_BUNDLE_FORMAT,
     formatVersion: WALLET_EVIDENCE_BUNDLE_FORMAT_VERSION,
     noteCount: noteRecords.length,
+    walletEpochCount: evidenceWalletContexts.length,
     transactionCount: txHashes.length,
     containsNotePlaintext: true,
     containsSpendingKey: false,
@@ -4967,6 +5218,33 @@ async function exportWalletGetNotesEvidenceBundle({
   };
 }
 
+function loadWalletEpochContextsForEvidence({ baseWalletContext, networkName }) {
+  const walletRoot = walletRootPath(baseWalletContext.walletName, networkName);
+  const index = requireWalletIndex({
+    walletRoot,
+    walletName: baseWalletContext.walletName,
+    networkName,
+  });
+  const contexts = [];
+  for (const epoch of index.epochs) {
+    const walletDir = walletEpochPathFromRoot(walletRoot, epoch.epochId);
+    if (!walletConfigExists(walletDir)) {
+      continue;
+    }
+    const context = loadWalletFromDir({
+      walletName: baseWalletContext.walletName,
+      networkName,
+      walletDir,
+    });
+    contexts.push(context);
+  }
+  expect(
+    contexts.length > 0,
+    `Wallet ${baseWalletContext.walletName} on ${networkName} has no readable wallet epochs. Run wallet recover-workspace and then wallet get-notes --export-evidence again.`,
+  );
+  return contexts;
+}
+
 function validateEvidenceNotePlaintext(note, wallet) {
   expect(
     note.owner && note.value !== null && note.salt && note.encryptedNoteValue,
@@ -5084,6 +5362,7 @@ function buildEvidenceNoteRecord({
       channelName: walletMetadata.channelName,
       channelId: walletContext.wallet.channelId,
       wallet: walletContext.walletName,
+      ...walletLifecycleMetadata(walletContext.wallet),
       walletL1Address: walletContext.wallet.l1Address,
       walletL2Address: walletContext.wallet.l2Address,
       controller: context.workspace.controller,
@@ -5198,7 +5477,7 @@ function buildEvidenceIndexes(noteRecords) {
     },
   };
   for (const record of noteRecords) {
-    const pathName = `notes/${record.derived.commitment}.json`;
+    const pathName = evidenceNotePath(record);
     indexes.byCommitment[record.derived.commitment] = pathName;
     indexes.byNullifier[record.derived.nullifier] = pathName;
     pushIndexEntry(indexes.byCreationTx, record.creation.txHash, pathName);
@@ -5227,6 +5506,21 @@ function buildEvidenceIndexes(noteRecords) {
   return indexes;
 }
 
+function evidenceNotePath(record) {
+  expect(
+    record.walletScope?.canonicalWalletName && record.walletScope?.epochId,
+    "Evidence note path requires the current epoch-aware wallet scope.",
+  );
+  return [
+    "wallets",
+    slugifyPathComponent(record.walletScope.canonicalWalletName),
+    "epochs",
+    slugifyPathComponent(record.walletScope.epochId),
+    "notes",
+    `${record.derived.commitment}.json`,
+  ].join("/");
+}
+
 function pushIndexEntry(index, key, value) {
   if (!key) {
     return;
@@ -5240,6 +5534,7 @@ function pushIndexEntry(index, key, value) {
 function buildEvidenceManifest({
   outputPath,
   walletContext,
+  walletContexts = [walletContext],
   walletMetadata,
   context,
   noteRecords,
@@ -5258,10 +5553,17 @@ function buildEvidenceManifest({
     wallet: walletContext.walletName,
     walletL1Address: walletContext.wallet.l1Address,
     walletL2Address: walletContext.wallet.l2Address,
+    wallets: walletContexts.map((entry) => ({
+      wallet: entry.walletName,
+      ...walletLifecycleMetadata(entry.wallet),
+      walletL1Address: entry.wallet.l1Address,
+      walletL2Address: entry.wallet.l2Address,
+    })),
     controller: context.workspace.controller,
     channelManager: context.workspace.channelManager,
     bridgeTokenVault: context.workspace.bridgeTokenVault,
     containsAllLocallyKnownNotes: true,
+    containsAllLocalWalletEpochs: true,
     containsNotePlaintext: true,
     noteCount: noteRecords.length,
     transactionCount: txHashes.length,
@@ -5281,12 +5583,13 @@ function addEvidenceJson(archive, archivePath, value) {
   archive.addFile(archivePath, Buffer.from(`${JSON.stringify(normalizeCliOutput(value), null, 2)}\n`, "utf8"));
 }
 
-function assertEvidenceBundleDoesNotContainSecrets({ wallet, payload }) {
+function assertEvidenceBundleDoesNotContainSecrets({ wallet = null, wallets = null, payload }) {
   const serialized = JSON.stringify(payload);
-  const forbiddenValues = [
-    wallet.l2PrivateKey,
-    wallet.noteReceivePrivateKey,
-  ].filter((value) => typeof value === "string" && value.length > 0);
+  const walletList = wallets ?? (wallet ? [wallet] : []);
+  const forbiddenValues = walletList.flatMap((entry) => [
+    entry.l2PrivateKey,
+    entry.noteReceivePrivateKey,
+  ]).filter((value) => typeof value === "string" && value.length > 0);
   for (const value of forbiddenValues) {
     expect(
       !serialized.includes(value),
@@ -5301,6 +5604,7 @@ function uniqueNonNull(values) {
 
 async function handleTransferNotes({ args, provider }) {
   const { wallet } = loadUnlockedWalletWithMetadata(args);
+  requireActiveWalletLifecycle(wallet, "wallet transfer-notes");
   requireWalletViewingCapability(wallet);
   requireWalletSpendingCapability(wallet);
   const { signer } = restoreWalletParticipant(wallet, provider);
@@ -5497,10 +5801,20 @@ function ensureWallet({
   storageKey,
   leafIndex,
   noteReceiveKeyMaterial,
+  lifecycleEpoch,
   rpcUrl,
 }) {
   const walletName = walletNameForChannelAndAddress(channelContext.workspace.channelName, signerAddress);
-  const walletDir = walletPath(walletName, channelContext.workspace.network);
+  const walletRoot = walletRootPath(walletName, channelContext.workspace.network);
+  if (fs.existsSync(walletRoot)) {
+    requireWalletIndex({
+      walletRoot,
+      walletName,
+      networkName: channelContext.workspace.network,
+    });
+  }
+  expect(lifecycleEpoch, "Current wallet workspace creation requires an on-chain wallet lifecycle epoch.");
+  const walletDir = walletEpochPath(walletName, channelContext.workspace.network, lifecycleEpoch.epochId);
   expect(!walletConfigExists(walletDir), `Wallet ${walletName} already exists on ${channelContext.workspace.network}.`);
   ensureDir(walletDir);
   ensureDir(path.join(walletDir, "operations"));
@@ -5508,6 +5822,19 @@ function ensureWallet({
   const wallet = normalizeWallet({
     walletFormatVersion: WALLET_WORKSPACE_FORMAT_VERSION,
     name: walletName,
+    canonicalWalletName: walletName,
+    walletEpochId: lifecycleEpoch.epochId,
+    lifecycleStatus: lifecycleEpoch.lifecycleStatus,
+    joinedAtTxHash: lifecycleEpoch.joinedAtTxHash,
+    joinedAtBlockNumber: lifecycleEpoch.joinedAtBlockNumber,
+    joinedAtLogIndex: lifecycleEpoch.joinedAtLogIndex,
+    joinedAtBlockTimestamp: lifecycleEpoch.joinedAtBlockTimestamp,
+    joinedAtBlockTimestampIso: lifecycleEpoch.joinedAtBlockTimestampIso,
+    exitedAtTxHash: lifecycleEpoch.exitedAtTxHash,
+    exitedAtBlockNumber: lifecycleEpoch.exitedAtBlockNumber,
+    exitedAtLogIndex: lifecycleEpoch.exitedAtLogIndex,
+    exitedAtBlockTimestamp: lifecycleEpoch.exitedAtBlockTimestamp,
+    exitedAtBlockTimestampIso: lifecycleEpoch.exitedAtBlockTimestampIso,
     network: channelContext.workspace.network,
     rpcUrl,
     chainId: channelContext.workspace.chainId,
@@ -5553,18 +5880,57 @@ function ensureWallet({
   };
   persistWalletKeys(context);
   persistWallet(context);
-  persistWalletMetadata(context);
+  persistWalletIndexForContext(context);
   return context;
 }
 
+function applyWalletLifecycleEpoch(wallet, epoch) {
+  wallet.canonicalWalletName = wallet.name;
+  wallet.walletEpochId = epoch.epochId;
+  wallet.lifecycleStatus = epoch.lifecycleStatus;
+  wallet.joinedAtTxHash = epoch.joinedAtTxHash;
+  wallet.joinedAtBlockNumber = epoch.joinedAtBlockNumber;
+  wallet.joinedAtLogIndex = epoch.joinedAtLogIndex;
+  wallet.joinedAtBlockTimestamp = epoch.joinedAtBlockTimestamp;
+  wallet.joinedAtBlockTimestampIso = epoch.joinedAtBlockTimestampIso;
+  wallet.exitedAtTxHash = epoch.exitedAtTxHash;
+  wallet.exitedAtBlockNumber = epoch.exitedAtBlockNumber;
+  wallet.exitedAtLogIndex = epoch.exitedAtLogIndex;
+  wallet.exitedAtBlockTimestamp = epoch.exitedAtBlockTimestamp;
+  wallet.exitedAtBlockTimestampIso = epoch.exitedAtBlockTimestampIso;
+}
+
+function walletLifecycleMetadata(wallet) {
+  expect(wallet.walletEpochId, "Current wallet workspace metadata is missing walletEpochId.");
+  return {
+    canonicalWalletName: wallet.canonicalWalletName ?? wallet.name,
+    epochId: wallet.walletEpochId,
+    lifecycleStatus: wallet.lifecycleStatus ?? "active",
+    joinedAtTxHash: wallet.joinedAtTxHash ?? null,
+    joinedAtBlockNumber: wallet.joinedAtBlockNumber ?? null,
+    joinedAtLogIndex: wallet.joinedAtLogIndex ?? null,
+    joinedAtBlockTimestamp: wallet.joinedAtBlockTimestamp ?? null,
+    joinedAtBlockTimestampIso: wallet.joinedAtBlockTimestampIso ?? null,
+    exitedAtTxHash: wallet.exitedAtTxHash ?? null,
+    exitedAtBlockNumber: wallet.exitedAtBlockNumber ?? null,
+    exitedAtLogIndex: wallet.exitedAtLogIndex ?? null,
+    exitedAtBlockTimestamp: wallet.exitedAtBlockTimestamp ?? null,
+    exitedAtBlockTimestampIso: wallet.exitedAtBlockTimestampIso ?? null,
+  };
+}
+
 function normalizeWallet(wallet) {
   assertWalletHasCurrentFormat(wallet, wallet.name ?? "unknown");
+  expect(wallet.walletEpochId, "Current wallet metadata requires walletEpochId. Run wallet recover-workspace to rebuild this wallet.");
   const unusedNotes = Object.values(wallet.notes.unused).map(normalizeTrackedNote);
   unusedNotes.sort(compareNotesByValueDesc);
   const spentNotes = Object.values(wallet.notes.spent).map(normalizeTrackedNote);
 
   return {
     ...wallet,
+    canonicalWalletName: wallet.canonicalWalletName ?? wallet.name,
+    walletEpochId: wallet.walletEpochId,
+    lifecycleStatus: wallet.lifecycleStatus ?? "active",
     canonicalAssetDecimals: Number(wallet.canonicalAssetDecimals),
     l2Nonce: Number(wallet.l2Nonce),
     l2PrivateKey: wallet.l2PrivateKey ? ethers.hexlify(wallet.l2PrivateKey) : null,
@@ -5824,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,
     };
@@ -5838,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;
@@ -5914,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 }) {
@@ -5942,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;
@@ -5988,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(" "));
   }
@@ -6026,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(" "));
   }
@@ -6042,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(" "));
   }
@@ -6662,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(" "));
@@ -6675,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(" "));
@@ -6699,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(" "));
   };
@@ -7062,7 +7469,17 @@ async function loadJoinChannelContext({ args, network, provider }) {
 function loadWallet(walletName, networkName) {
   const normalizedWalletName = requireWalletName({ wallet: walletName });
   const normalizedNetworkName = requireNetworkName({ network: networkName });
-  const walletDir = walletPath(normalizedWalletName, normalizedNetworkName);
+  const walletDir = selectedWalletEpochDir(normalizedWalletName, normalizedNetworkName);
+  return loadWalletFromDir({
+    walletName: normalizedWalletName,
+    networkName: normalizedNetworkName,
+    walletDir,
+  });
+}
+
+function loadWalletFromDir({ walletName, networkName, walletDir }) {
+  const normalizedWalletName = requireWalletName({ wallet: walletName });
+  const normalizedNetworkName = requireNetworkName({ network: networkName });
   if (!walletConfigExists(walletDir)) {
     throw cliError(CLI_ERROR_CODES.UNKNOWN_WALLET, `Unknown wallet: ${normalizedWalletName} on ${normalizedNetworkName}.`);
   }
@@ -7077,11 +7494,11 @@ function loadWallet(walletName, networkName) {
     walletName: normalizedWalletName,
     keyKind: "viewing",
   });
-  if (spendingKey) {
+  if (spendingKey && walletSpendingKeyMatchesWallet(spendingKey.metadata, rawWallet)) {
     rawWallet.l2PrivateKey = spendingKey.privateKey;
     rawWallet.l2PublicKey = spendingKey.metadata?.l2PublicKey ?? rawWallet.l2PublicKey;
   }
-  if (viewingKey) {
+  if (viewingKey && walletViewingKeyMatchesWallet(viewingKey.metadata, rawWallet)) {
     rawWallet.noteReceivePrivateKey = viewingKey.privateKey;
   }
   assertWalletHasRequiredKeys(rawWallet, normalizedWalletName);
@@ -7104,6 +7521,18 @@ function loadWallet(walletName, networkName) {
   return context;
 }
 
+function walletSpendingKeyMatchesWallet(metadata, wallet) {
+  return metadata?.l2Address
+    && ethers.toBigInt(getAddress(metadata.l2Address)) === ethers.toBigInt(getAddress(wallet.l2Address));
+}
+
+function walletViewingKeyMatchesWallet(metadata, wallet) {
+  return metadata?.noteReceivePubKey?.x
+    && ethers.toBigInt(normalizeBytes32Hex(metadata.noteReceivePubKey.x))
+      === ethers.toBigInt(normalizeBytes32Hex(wallet.noteReceivePubKeyX))
+    && Number(metadata.noteReceivePubKey.yParity) === Number(wallet.noteReceivePubKeyYParity);
+}
+
 function loadUnlockedWalletWithMetadata(args) {
   const networkName = requireNetworkName(args);
   const wallet = loadWallet(requireWalletName(args), networkName);
@@ -7274,6 +7703,16 @@ function requireWalletViewingCapability(walletContext) {
   );
 }
 
+function requireActiveWalletLifecycle(walletContext, commandName) {
+  expect(
+    walletContext.wallet.lifecycleStatus !== "exited",
+    [
+      `${commandName} cannot operate on exited wallet epoch ${walletContext.wallet.walletEpochId ?? "unknown"}.`,
+      "Exited wallet epochs are read-only. Use wallet get-notes or wallet get-notes --export-evidence for historical disclosure.",
+    ].join(" "),
+  );
+}
+
 function walletOperationSealSecret(walletContext) {
   const secret = walletContext.wallet.l2PrivateKey
     ?? walletContext.wallet.noteReceivePrivateKey
@@ -7328,7 +7767,7 @@ function loadBridgeResources({ chainId }) {
 function loadWalletMetadata(walletName, networkName) {
   const normalizedWalletName = requireWalletName({ wallet: walletName });
   const normalizedNetworkName = requireNetworkName({ network: networkName });
-  const walletDir = walletPath(normalizedWalletName, normalizedNetworkName);
+  const walletDir = selectedWalletEpochDir(normalizedWalletName, normalizedNetworkName);
   if (!walletConfigExists(walletDir)) {
     throw cliError(CLI_ERROR_CODES.UNKNOWN_WALLET, `Unknown wallet: ${normalizedWalletName} on ${normalizedNetworkName}.`);
   }
@@ -7677,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,
@@ -7870,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]));
 }
@@ -8001,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,
@@ -8018,6 +8514,7 @@ async function reconstructChannelSnapshot({
   fromBlock = genesisBlockNumber,
   toBlock = null,
   progressAction = null,
+  onCheckpoint = null,
 }) {
   let startingSnapshot = baseSnapshot;
   if (!startingSnapshot) {
@@ -8033,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,
@@ -8045,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(
@@ -8103,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(
@@ -8352,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?.({
@@ -8384,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(
@@ -8417,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?.({
@@ -8426,7 +8961,7 @@ async function fetchLogsChunked(provider, {
     toBlock: resolvedToBlock,
     scannedBlocks: totalBlocks,
     totalBlocks,
-    logsFound: aggregatedLogs.length,
+    logsFound,
   });
 
   return aggregatedLogs;
@@ -8462,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(" "));
 }
 
@@ -8912,16 +9447,18 @@ function prepareJoinWalletSecretForName({
   walletName,
 }) {
   const { channelName } = parseWalletName(walletName);
-  const walletDir = walletPath(walletName, networkName);
+  const walletRoot = walletRootPath(walletName, networkName);
+  const walletIndex = fs.existsSync(walletRoot)
+    ? requireWalletIndex({ walletRoot, walletName, networkName })
+    : null;
+  const activeEpoch = walletIndex ? activeWalletEpoch(walletIndex) : null;
   expect(
-    !walletConfigExists(walletDir),
+    !activeEpoch,
     [
       `Wallet ${walletName} already exists on ${networkName}.`,
-      "channel join always creates a new local wallet.",
-      "If this wallet was previously exited on-chain, run",
-      `wallet recover-workspace --channel-name ${channelName} --network ${networkName} --account ${args.account ?? "<ACCOUNT>"}`,
-      "once to remove the stale local wallet, then retry channel join.",
+      "channel join creates a new active wallet epoch.",
       "Use normal wallet commands for an existing active local wallet.",
+      `For exited history, keep using wallet recover-workspace --channel-name ${channelName} --network ${networkName} --account ${args.account ?? "<ACCOUNT>"}.`,
     ].join(" "),
   );
   const sourcePath = path.resolve(String(requireArg(args.walletSecretPath, "--wallet-secret-path")));
@@ -8932,7 +9469,7 @@ function channelWorkspacePath(networkName, name) {
   return workspaceDirForName(workspaceRoot, networkName, name);
 }
 
-function walletPath(name, networkName) {
+function walletRootPath(name, networkName) {
   const walletName = String(name);
   const { channelName } = parseWalletName(walletName);
   const normalizedNetworkName = requireNetworkName({ network: networkName });
@@ -8940,6 +9477,91 @@ function walletPath(name, networkName) {
   return walletDirForName(workspaceWalletsDir(workspaceDir), walletName);
 }
 
+function selectedWalletEpochDir(name, networkName) {
+  const root = walletRootPath(name, networkName);
+  const walletName = requireWalletName({ wallet: name });
+  const normalizedNetworkName = requireNetworkName({ network: networkName });
+  expect(
+    fs.existsSync(root),
+    cliError(CLI_ERROR_CODES.UNKNOWN_WALLET, `Unknown wallet: ${walletName} on ${normalizedNetworkName}.`),
+  );
+  const index = requireWalletIndex({ walletRoot: root, walletName, networkName: normalizedNetworkName });
+  const selected = selectedWalletEpoch(index, walletName, normalizedNetworkName);
+  return walletEpochPathFromRoot(root, selected.epochId);
+}
+
+function walletEpochPath(walletName, networkName, epochId) {
+  return walletEpochPathFromRoot(walletRootPath(walletName, networkName), epochId);
+}
+
+function walletEpochPathFromRoot(walletRoot, epochId) {
+  return path.join(walletRoot, "epochs", slugifyPathComponent(epochId));
+}
+
+function walletIndexMetadataPath(walletRoot) {
+  return path.join(walletRoot, "wallet-index.metadata.json");
+}
+
+function readWalletIndexIfExists(walletRoot) {
+  const indexPath = walletIndexMetadataPath(walletRoot);
+  if (!fs.existsSync(indexPath)) {
+    return null;
+  }
+  return normalizeWalletIndex(readJson(indexPath));
+}
+
+function requireWalletIndex({ walletRoot, walletName, networkName }) {
+  const index = readWalletIndexIfExists(walletRoot);
+  expect(index, currentWalletIndexRequiredMessage({ walletName, networkName, walletRoot }));
+  return index;
+}
+
+function selectedWalletEpoch(index, walletName, networkName) {
+  const selected = activeWalletEpoch(index) ?? latestWalletEpoch(index);
+  expect(
+    selected,
+    `Wallet ${walletName} on ${networkName} has no epoch entries. Run wallet recover-workspace to rebuild the workspace in the current format.`,
+  );
+  return selected;
+}
+
+function currentWalletIndexRequiredMessage({ walletName, networkName, walletRoot }) {
+  const channelName = parseWalletName(walletName).channelName;
+  return [
+    `Current wallet index is required for ${walletName} on ${networkName}: ${walletRoot}.`,
+    `Run wallet recover-workspace --channel-name ${channelName} --network ${networkName} --account <ACCOUNT> to rebuild the workspace.`,
+  ].join(" ");
+}
+
+function activeWalletEpoch(index) {
+  const activeEpochId = index?.activeEpochId ?? null;
+  return activeEpochId
+    ? (index.epochs ?? []).find((epoch) => epoch.epochId === activeEpochId && epoch.lifecycleStatus === "active") ?? null
+    : null;
+}
+
+function latestWalletEpoch(index) {
+  const epochs = [...(index?.epochs ?? [])];
+  epochs.sort((left, right) =>
+    Number(right.joinedAtBlockNumber ?? 0) - Number(left.joinedAtBlockNumber ?? 0)
+    || String(right.epochId).localeCompare(String(left.epochId)));
+  return epochs[0] ?? null;
+}
+
+function normalizeWalletIndex(index) {
+  expect(index?.format === WALLET_INDEX_FORMAT, "Invalid wallet index format.");
+  expect(Number(index.formatVersion) === WALLET_INDEX_FORMAT_VERSION, "Unsupported wallet index format version.");
+  expect(Array.isArray(index.epochs), "Wallet index is missing epochs[].");
+  return {
+    ...index,
+    epochs: index.epochs.map((epoch) => ({
+      ...epoch,
+      epochId: String(epoch.epochId),
+      lifecycleStatus: epoch.lifecycleStatus === "active" ? "active" : "exited",
+    })),
+  };
+}
+
 function accountPrivateKeyPath(networkName, accountName) {
   return path.join(
     secretRoot,
@@ -9013,7 +9635,8 @@ function resolveWalletPathCandidates(walletName) {
       "wallets",
       walletSlug,
     );
-    if (walletConfigExists(candidate)) {
+    if (fs.existsSync(candidate)) {
+      requireWalletIndex({ walletRoot: candidate, walletName, networkName: entry.name });
       candidates.push(candidate);
     }
   }
@@ -9044,12 +9667,24 @@ function listLocalWallets({ networkFilter = null, channelFilter = null } = {}) {
         if (!walletEntry.isDirectory()) {
           continue;
         }
-        const walletDir = path.join(walletsDir, walletEntry.name);
+        const walletRoot = path.join(walletsDir, walletEntry.name);
+        const walletIndex = requireWalletIndex({
+          walletRoot,
+          walletName: walletEntry.name,
+          networkName: networkEntry.name,
+        });
+        const selectedEpoch = selectedWalletEpoch(walletIndex, walletEntry.name, networkEntry.name);
+        const walletDir = walletEpochPathFromRoot(walletRoot, selectedEpoch.epochId);
         wallets.push({
           wallet: walletEntry.name,
           network: networkEntry.name,
           channelName: channelEntry.name,
           walletDir,
+          walletRoot,
+          activeEpochId: walletIndex?.activeEpochId ?? null,
+          selectedEpochId: selectedEpoch?.epochId ?? null,
+          lifecycleStatus: selectedEpoch.lifecycleStatus,
+          epochs: walletIndex.epochs,
           metadataPath: walletNotesMetadataPath(walletDir),
           hasMetadata: fs.existsSync(walletNotesMetadataPath(walletDir)),
           hasEncryptedWallet: false,
@@ -9077,7 +9712,7 @@ function privateStateCliDataRoot() {
 
 function resolveExportWalletInfo({ networkName, walletName }) {
   resolveCliNetwork(networkName);
-  const walletDir = walletPath(walletName, networkName);
+  const walletDir = selectedWalletEpochDir(walletName, networkName);
   return {
     wallet: walletName,
     network: networkName,
@@ -9092,7 +9727,7 @@ function resolveExportWalletInfo({ networkName, walletName }) {
 function normalizeExportWalletInfo(walletInfo) {
   const wallet = requireWalletName({ wallet: walletInfo.wallet });
   const network = requireNetworkName({ network: walletInfo.network });
-  const walletDir = walletInfo.walletDir ?? walletPath(wallet, network);
+  const walletDir = walletInfo.walletDir ?? selectedWalletEpochDir(wallet, network);
   const metadataPath = walletNotesMetadataPath(walletDir);
   const metadata = readJsonIfExists(metadataPath);
   const channelName = metadata?.channelName ?? walletInfo.channelName ?? parseWalletName(wallet).channelName;
@@ -9119,6 +9754,13 @@ function walletBackupExportFilePaths(walletInfo) {
   const walletFiles = [
     walletNotesMetadataPath(walletInfo.walletDir),
   ];
+  const walletRoot = walletRootPath(walletInfo.wallet, walletInfo.network);
+  requireWalletIndex({
+    walletRoot,
+    walletName: walletInfo.wallet,
+    networkName: walletInfo.network,
+  });
+  walletFiles.push(walletIndexMetadataPath(walletRoot));
   for (const metadataPath of [
     walletViewingKeyMetadataPath(walletInfo.walletDir),
     walletSpendingKeyMetadataPath(walletInfo.walletDir),
@@ -9172,9 +9814,18 @@ function validateWalletExportManifest(manifest) {
     validateWalletArchivePath(filePath);
   }
   for (const wallet of manifest.wallets) {
-    requireNetworkName({ network: wallet.network });
-    requireWalletName({ wallet: wallet.wallet });
+    const networkName = requireNetworkName({ network: wallet.network });
+    const walletName = requireWalletName({ wallet: wallet.wallet });
     requireArg(wallet.channelName, "wallets[].channelName");
+    const walletRoot = walletRootPath(walletName, networkName);
+    const expectedIndexPath = archivePathForLocalCliFile(walletIndexMetadataPath(walletRoot));
+    expect(
+      uniqueFiles.has(expectedIndexPath),
+      [
+        "Wallet import ZIP must include the current wallet index metadata.",
+        "Run wallet recover-workspace with the current CLI, then export a new backup.",
+      ].join(" "),
+    );
   }
 }
 
@@ -9276,21 +9927,8 @@ function assertAllowedCommandKeys(args, commandName, allowedKeys, acceptedUsage)
   );
 }
 
-function assertWalletSecretArgs(args, commandName, extraOptionKeys = [], acceptedUsage = "--wallet and --network") {
-  if (COMMAND_ARG_SCHEMAS[commandName]) {
-    assertAllowedCommandSchema(args, commandName);
-    return;
-  }
-  assertAllowedCommandKeys(
-    args,
-    commandName,
-    new Set(["command", "positional", "wallet", "network", ...extraOptionKeys]),
-    acceptedUsage,
-  );
-}
-
 function assertWalletChannelMoveArgs(args, commandName) {
-  assertWalletSecretArgs(args, commandName, ["amount"], "--wallet, --network, and --amount");
+  assertAllowedCommandSchema(args, commandName);
   assertActionImpactArg(args, COMMAND_ARG_SCHEMAS[commandName]?.label ?? commandName);
 }
 
@@ -9404,7 +10042,7 @@ function assertActionImpactArg(args, commandName) {
 }
 
 function assertWalletGetNotesArgs(args) {
-  assertWalletSecretArgs(args, "wallet-get-notes");
+  assertAllowedCommandSchema(args, "wallet-get-notes");
   if (args.exportEvidence !== undefined) {
     requireArg(args.exportEvidence, "--export-evidence");
     if (args.acknowledgeFullNotePlaintextExport !== true) {
@@ -9459,12 +10097,8 @@ function assertAccountGetBridgeFundArgs(args) {
   assertAllowedCommandSchema(args, "account-get-bridge-fund");
 }
 
-function assertExplicitSignerCommandArgs(args, commandName) {
-  assertAllowedCommandSchema(args, commandName);
-}
-
 function assertRecoverWalletArgs(args) {
-  assertExplicitSignerCommandArgs(args, "wallet-recover-workspace");
+  assertAllowedCommandSchema(args, "wallet-recover-workspace");
   if (args.fromGenesis !== undefined && args.fromGenesis !== true) {
     throw new Error("wallet recover-workspace option --from-genesis does not accept a value.");
   }
@@ -9476,7 +10110,7 @@ function assertJoinChannelArgs(args) {
 }
 
 function assertWalletGetMetaArgs(args) {
-  assertWalletSecretArgs(args, "wallet-get-meta");
+  assertAllowedCommandSchema(args, "wallet-get-meta");
 }
 
 function assertAccountGetL1AddressArgs(args) {
@@ -9521,17 +10155,17 @@ function assertWithdrawBridgeArgs(args) {
 }
 
 function assertWalletGetChannelFundArgs(args) {
-  assertWalletSecretArgs(args, "wallet-get-channel-fund");
+  assertAllowedCommandSchema(args, "wallet-get-channel-fund");
 }
 
 function assertExitChannelArgs(args) {
-  assertWalletSecretArgs(args, "channel-exit");
+  assertAllowedCommandSchema(args, "channel-exit");
 }
 
 function createWalletOperationDir(walletName, networkName, suffix) {
   const timestamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
   const operationDir = path.join(
-    walletPath(walletName, networkName),
+    selectedWalletEpochDir(walletName, networkName),
     "operations",
     `${timestamp}-${slugifyPathComponent(suffix)}`,
   );
@@ -9576,8 +10210,73 @@ function persistWalletKeys(context) {
   }
 }
 
-function persistWalletMetadata(context) {
-  persistWallet(context);
+function persistWalletIndexForContext(context) {
+  const walletRoot = walletRootPath(context.walletName, context.wallet.network);
+  ensureDir(walletRoot);
+  const currentIndex = readWalletIndexIfExists(walletRoot) ?? {
+    format: WALLET_INDEX_FORMAT,
+    formatVersion: WALLET_INDEX_FORMAT_VERSION,
+    canonicalWalletName: context.walletName,
+    network: context.wallet.network,
+    channelName: context.wallet.channelName,
+    channelId: context.wallet.channelId,
+    l1Address: context.wallet.l1Address,
+    activeEpochId: null,
+    epochs: [],
+  };
+  const epoch = walletEpochSummaryFromWallet(context.wallet);
+  const epochs = [
+    ...currentIndex.epochs.filter((entry) => entry.epochId !== epoch.epochId),
+    epoch,
+  ].sort((left, right) =>
+    Number(left.joinedAtBlockNumber ?? 0) - Number(right.joinedAtBlockNumber ?? 0)
+    || String(left.epochId).localeCompare(String(right.epochId)));
+  const activeEpoch = epochs.find((entry) => entry.lifecycleStatus === "active") ?? null;
+  const nextIndex = {
+    ...currentIndex,
+    canonicalWalletName: context.walletName,
+    network: context.wallet.network,
+    channelName: context.wallet.channelName,
+    channelId: context.wallet.channelId,
+    l1Address: context.wallet.l1Address,
+    activeEpochId: activeEpoch?.epochId ?? null,
+    epochs,
+  };
+  writeJson(walletIndexMetadataPath(walletRoot), nextIndex);
+}
+
+async function markWalletEpochExited({ walletContext, receipt, provider }) {
+  const block = receipt?.blockNumber === null || receipt?.blockNumber === undefined
+    ? null
+    : await provider.getBlock(receipt.blockNumber).catch(() => null);
+  const exitedAtBlockTimestamp = block?.timestamp ?? null;
+  walletContext.wallet.lifecycleStatus = "exited";
+  walletContext.wallet.exitedAtTxHash = receipt?.hash ?? null;
+  walletContext.wallet.exitedAtBlockNumber = receipt?.blockNumber ?? null;
+  walletContext.wallet.exitedAtLogIndex = firstReceiptLogIndex(receipt);
+  walletContext.wallet.exitedAtBlockTimestamp = exitedAtBlockTimestamp;
+  walletContext.wallet.exitedAtBlockTimestampIso = exitedAtBlockTimestamp === null
+    ? null
+    : new Date(Number(exitedAtBlockTimestamp) * 1000).toISOString();
+  persistWallet(walletContext);
+  persistWalletIndexForContext(walletContext);
+  return walletEpochSummaryFromWallet(walletContext.wallet);
+}
+
+function firstReceiptLogIndex(receipt) {
+  const first = receipt?.logs?.[0] ?? null;
+  return first?.index ?? first?.logIndex ?? null;
+}
+
+function walletEpochSummaryFromWallet(wallet) {
+  const lifecycle = walletLifecycleMetadata(wallet);
+  return {
+    ...lifecycle,
+    walletDirName: slugifyPathComponent(lifecycle.epochId),
+    l2Address: wallet.l2Address,
+    l2StorageKey: wallet.l2StorageKey,
+    leafIndex: wallet.leafIndex,
+  };
 }
 
 function sanitizeWalletForNotesMetadata(wallet) {
@@ -9633,6 +10332,7 @@ function buildWalletSpendingKeyMetadata(wallet) {
     walletFormatVersion: WALLET_WORKSPACE_FORMAT_VERSION,
     network: wallet.network,
     wallet: wallet.name,
+    ...walletLifecycleMetadata(wallet),
     channelName: wallet.channelName,
     channelId: wallet.channelId,
     l1Address: wallet.l1Address,
@@ -9650,6 +10350,7 @@ function buildWalletViewingKeyMetadata(wallet) {
     walletFormatVersion: WALLET_WORKSPACE_FORMAT_VERSION,
     network: wallet.network,
     wallet: wallet.name,
+    ...walletLifecycleMetadata(wallet),
     channelName: wallet.channelName,
     channelId: wallet.channelId,
     l1Address: wallet.l1Address,
@@ -10028,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`);
@@ -10528,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")) {