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

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 ## 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
+  wallet metadata must include the wallet index and epoch metadata; users with older local
+  workspaces should rebuild them with `wallet recover-workspace`.
+- Required current epoch-aware evidence bundle note paths in the investigator and removed the
+  special-case legacy evidence layout branch.
+- Consolidated the static evidence investigator into the CLI package under `cli/investigator/`
+  and removed the duplicate top-level investigator copy.
+- Simplified wallet command argument validation by removing unused schema fallback wrappers.
+
 ## 2.0.0 - 2026-05-13
 
 - Split wallet export/import into `wallet export backup`, `wallet export viewing-key`,
@@ -22,6 +49,10 @@
   commitments and nullifiers, creation/spend transaction references, receipts, events, calldata, and
   filtering indexes, while excluding viewing keys, spending keys, wallet secrets, account private
   keys, and `.key` files.
+- Made local wallet workspaces epoch-aware. `channel exit` now marks the active wallet epoch as
+  exited and retains its local note metadata instead of deleting the wallet workspace, while
+  `wallet recover-workspace` and `wallet get-notes --export-evidence` can still use retained exited
+  epochs for historical disclosure.
 - Added a local static evidence investigator GUI and bundled it with the NPM package. The new
   top-level `private-state-cli investigator` command prints the bundled HTML path, prints the file
   URL, and opens the GUI in the default browser.

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,28 @@ 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
+exited with the exit transaction, block, and timestamp, then keeps that epoch read-only for historical note inspection
+and evidence export. If the same account later joins the same channel again, the new registration is a separate active
+epoch under the same canonical wallet name.
+
+The current CLI only supports this epoch-aware wallet workspace layout. If a local wallet directory was created by an
+older CLI and does not contain `wallet-index.metadata.json` plus `epochs/<epoch-id>/` metadata files, rebuild it with
+`wallet recover-workspace` before using wallet commands.
 
 Channel leaders can optionally register a workspace mirror server so users can bootstrap recovery
 from a signed checkpoint and download only the local-to-checkpoint delta when a local recovery index
@@ -228,8 +253,9 @@ private-state-cli wallet get-notes --network mainnet --wallet <WALLET> --export-
 This ZIP is an input for `private-state-cli investigator`. It contains plaintext for all locally known
 notes, derived commitments and nullifiers, creation and spend transaction references, transaction calldata, receipts,
 events, and indexes for filtering by note, nullifier, transaction, block range, or available counterparty metadata. It
-does not include viewing keys, spending keys, wallet secret material, account private keys, or `.key` files. Do not
-submit the raw ZIP as an exchange or auditor package unless full wallet-history disclosure is intended.
+includes all local epochs for the selected wallet, including exited epochs retained after `channel exit`. It does not
+include viewing keys, spending keys, wallet secret material, account private keys, or `.key` files. Do not submit the
+raw ZIP as an exchange or auditor package unless full wallet-history disclosure is intended.
 
 Open the local evidence investigator with:
 
@@ -241,6 +267,9 @@ The command prints the bundled investigator HTML path and file URL, then opens t
 evidence ZIP in that GUI, apply the requested filters, and export a narrower user-consent disclosure ZIP. The GUI runs
 locally in the browser and does not send files over the network.
 
+The investigator accepts current epoch-aware evidence bundles only. If a bundle was generated by an older CLI, rebuild
+the wallet workspace with `wallet recover-workspace` and export a new bundle with `wallet get-notes --export-evidence`.
+
 Estimate live transaction costs before sending commands with:
 
 ```bash
@@ -298,7 +327,8 @@ and stores a protected local account secret for later `--account` use. The sourc
 wallet backup metadata, viewing-key metadata, and spending-key metadata as separate files. `wallet list` reads only the local workspace and prints saved wallet names that can be reused with
 `--wallet`.
 `wallet get-meta` opens the wallet metadata and reports the stored L1/L2 identity metadata plus the current
-on-chain channel registration match state, including the registered note-receive public key when present.
+on-chain channel registration match state, including the registered note-receive public key when present. On
+epoch-aware wallet workspaces it also reports the selected wallet epoch and whether that epoch is active or exited.
 `account get-l1-address` is a simple offline helper that derives the L1 address for a local account.
 
 ### Wallet Secret Source File
@@ -404,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
@@ -466,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/investigator/README.md

@@ -22,6 +22,10 @@ The raw evidence bundle contains plaintext for all locally known notes. Do not s
 as an exchange or auditor package unless full wallet-history disclosure is intended. Use the
 investigator output package for scoped disclosure.
 
+The investigator accepts current epoch-aware evidence bundles only. Supported note records live under
+`wallets/<wallet>/epochs/<epoch-id>/notes/` inside the ZIP. If a bundle uses an older layout, rebuild the local wallet
+workspace with `wallet recover-workspace` and export a new evidence ZIP with `wallet get-notes --export-evidence`.
+
 ## Supported Filtering
 
 - note commitment or nullifier

package/investigator/app.js

@@ -60,8 +60,11 @@ async function loadEvidenceBundle(bytes) {
   if (manifest.format !== "tokamak-private-state-raw-evidence-bundle") {
     throw new Error(`Unsupported evidence format: ${manifest.format ?? "missing"}.`);
   }
+  if (Number(manifest.formatVersion) !== 2) {
+    throw new Error("Current evidence bundle formatVersion 2 is required. Run wallet recover-workspace, then run wallet get-notes --export-evidence again.");
+  }
   const notes = [...files.entries()]
-    .filter(([path]) => path.startsWith("notes/") && path.endsWith(".json"))
+    .filter(([path]) => isEvidenceNotePath(path))
     .map(([path, content]) => ({
       path,
       record: JSON.parse(content),
@@ -69,7 +72,7 @@ async function loadEvidenceBundle(bytes) {
     .sort((left, right) =>
       String(left.record?.derived?.commitment ?? "").localeCompare(String(right.record?.derived?.commitment ?? "")));
   if (notes.length === 0) {
-    throw new Error("The evidence bundle does not contain note records.");
+    throw new Error("The evidence bundle does not contain current epoch-aware note records.");
   }
   state.files = files;
   state.manifest = manifest;
@@ -79,7 +82,20 @@ async function loadEvidenceBundle(bytes) {
   els.buildPackage.disabled = false;
   els.selectAll.disabled = false;
   els.selectNone.disabled = false;
-  setStatus(`Loaded ${notes.length} note records from ${manifest.wallet ?? "wallet"} on ${manifest.network ?? "network"}.`);
+  setStatus(
+    `Loaded ${notes.length} note records from ${evidenceWalletLabel(manifest)} on ${manifest.network ?? "network"}.`,
+  );
+}
+
+function isEvidenceNotePath(entryPath) {
+  return /^wallets\/[^/]+\/epochs\/[^/]+\/notes\/[^/]+\.json$/u.test(entryPath);
+}
+
+function evidenceWalletLabel(manifest) {
+  if (manifest.wallets?.length) {
+    return `${manifest.wallets[0].wallet ?? manifest.wallet ?? "wallet"} (${manifest.wallets.length} epochs)`;
+  }
+  return manifest.wallet ?? "wallet";
 }
 
 function resetBundle() {
@@ -324,6 +340,7 @@ function buildDisclosureManifest({ selectedNotes, selectedPaths, packageMetadata
       channelName: state.manifest.channelName,
       channelId: state.manifest.channelId,
       wallet: state.manifest.wallet,
+      wallets: state.manifest.wallets ?? null,
       walletL1Address: state.manifest.walletL1Address,
       walletL2Address: state.manifest.walletL2Address,
     },

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",
     ],
   },
   {
@@ -441,7 +445,10 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     description: "Check whether a wallet matches the on-chain channel registration.",
     fields: ["wallet", "network"],
     usage: "--wallet and --network",
-    help: ["Refreshes the local channel workspace through the saved recovery index before reading registration metadata when the scan fits the 10 second pre-command budget"],
+    help: [
+      "Refreshes the local channel workspace through the saved recovery index before reading registration metadata when the scan fits the 10 second pre-command budget",
+      "Reports the selected local wallet epoch and lifecycle status when the workspace uses the epoch-aware wallet format",
+    ],
   },
   {
     id: "wallet-list",
@@ -548,7 +555,10 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     description: "Exit a channel. Both the CLI and bridge contract require a zero channel balance.",
     fields: ["wallet", "network"],
     usage: "--wallet and --network",
-    help: ["Refreshes the local channel workspace through the saved recovery index before checking the channel balance when the scan fits the 10 second pre-command budget"],
+    help: [
+      "Refreshes the local channel workspace through the saved recovery index before checking the channel balance when the scan fits the 10 second pre-command budget",
+      "Marks the current local wallet epoch as exited and keeps its note metadata available for historical evidence export",
+    ],
   },
   {
     id: "wallet-mint-notes",
@@ -613,8 +623,9 @@ 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.0.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",