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

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 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 +33,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

@@ -176,6 +176,16 @@ channel genesis and only runs when the recovery delta fits within the 7,200-bloc
 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.
 
+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
 already exists. The channel leader can build the static mirror files with
@@ -228,8 +238,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 +252,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 +312,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

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

@@ -441,7 +441,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 +551,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",
@@ -615,6 +621,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
       "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",
       "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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamak-private-dapps/private-state-cli",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Command-line client for the Tokamak private-state DApp.",
   "license": "MIT OR Apache-2.0",
   "author": "Tokamak Network",