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

package/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 ## Unreleased
 
+## 2.1.2 - 2026-05-15
+
+- Fixed wallet lifecycle recovery log lookups so account-specific registration and exit event scans
+  use the same chunked `eth_getLogs` path as the rest of RPC workspace recovery.
+- Removed synthetic wallet lifecycle epoch fallback creation; wallet recovery now requires
+  lifecycle registration events to be found in RPC log history instead of fabricating epochs from
+  current registration state.
+- Fixed RPC log request pacing so every `eth_getLogs` call passes through a shared async limiter
+  instead of relying on a race-prone timestamp throttle during concurrent scans.
+- Added progress output for the wallet lifecycle registered/exited event scans that run before
+  note-delivery recovery in `wallet recover-workspace`.
+- Added `set rpc` for per-network RPC configuration with built-in `eth_getLogs` scan-limit tables
+  for Ankr, Chainstack, Chainnodes, QuickNode, and Alchemy, using 90% of the provider reference
+  request-rate values.
+- Simplified note-mutating command post-processing so accepted note transactions wait for the
+  receipt block, then refresh channel and wallet workspaces from their recovery indexes instead of
+  manually applying note lifecycle metadata.
+- Extended wallet recovery to persist public creation/spend linkage from commitment and
+  nullifier storage observations so raw evidence export can package stored metadata without
+  running its own log scan.
+- Fixed raw evidence spend linkage so nullifier observation transactions are used as the spend
+  transition references and included with their transaction, receipt, and event evidence.
+- Redesigned the bundled investigator GUI around purpose-first disclosure requests, an interactive
+  SVG note-linkage graph, node detail overlays, and Markdown ASCII-art linkage report export.
+- Updated private-state documentation to reflect `set rpc` as the only CLI RPC configuration path
+  for ordinary bridge-facing and wallet commands.
+- Split the CLI entrypoint into command dispatch modules and moved the shared runtime implementation
+  under `lib/runtime.mjs`; the published package now includes the `commands/` modules.
+- Removed the `channel get-meta` workspace mirror lookup fallback so contract lookup errors surface
+  directly instead of being hidden behind `null` metadata.
+- Changed `channel join` to derive the wallet lifecycle epoch from the accepted join receipt instead
+  of rescanning full account registration and exit history.
+- Changed investigator numeric block filters to reject invalid values instead of silently treating
+  them as absent filters.
+
+## 2.1.1 - 2026-05-14
+
+- Changed `channel recover-workspace --from-genesis` to move any existing local channel workspace
+  to `workspace-rebuild-backups/` before writing the current-format workspace. The clean rebuild
+  path is limited to workspace files and preserves local account and wallet key secrets under
+  `secrets/`.
+- Added channel workspace recovery checkpointing at the existing RPC log chunk boundary so
+  interrupted RPC recovery can resume from the last completed chunk.
+- Changed mirror recovery to fall back to a newer verified full mirror checkpoint when no matching
+  delta bundle exists for the local recovery index.
+- Changed `wallet recover-workspace` to use the same bounded channel-workspace freshness preflight
+  as other wallet commands. `wallet recover-workspace --from-genesis` now restarts received-note
+  scanning from channel genesis but does not rebuild the channel workspace from genesis.
+- Added received-note recovery checkpointing at the existing RPC log chunk boundary so ordinary
+  `wallet recover-workspace` resumes from the last completed chunk after an interruption.
+
 ## 2.1.0 - 2026-05-14
 
 - Required current epoch-aware wallet workspaces for wallet commands and backup imports. Local

package/README.md

@@ -151,16 +151,25 @@ Static warning scope:
 centralized-exchange controlled address as a self-custody bridge source or as the direct bridge withdrawal target
 unless the user explicitly understands the compliance implications. Prefer a self-custody L1 wallet.
 
-Workspace recovery commands use the saved recovery index by default. If the local workspace is missing, corrupted, or
-does not contain a usable index, `channel recover-workspace` and `wallet recover-workspace` stop with an explicit error instead of
-silently replaying logs from channel genesis. Use `--source rpc --from-genesis` only when you intentionally want to
-rebuild channel workspace state from the channel creation block:
+Workspace recovery commands use saved recovery indexes by default. If the local channel workspace is missing,
+corrupted, or does not contain a usable index, `channel recover-workspace` stops with an explicit error instead of
+silently replaying logs from channel genesis. Use `channel recover-workspace --source rpc --from-genesis` only when
+you intentionally want to rebuild channel workspace state from the channel creation block:
 
 ```bash
 private-state-cli channel recover-workspace --channel-name <CHANNEL> --network mainnet --source rpc --from-genesis
-private-state-cli wallet recover-workspace --channel-name <CHANNEL> --network mainnet --account <ACCOUNT> --from-genesis
 ```
 
+When `channel recover-workspace --from-genesis` is used, the CLI treats the local channel workspace as a clean rebuild target.
+If `~/tokamak-private-channels/workspace/<network>/<channel>` already exists, it is moved under
+`~/tokamak-private-channels/workspace-rebuild-backups/` before the current-format workspace is
+created. This backup step is workspace-only; files under `~/tokamak-private-channels/secrets/`,
+including account private keys and wallet viewing/spending key files, are not removed.
+During RPC recovery, the CLI writes a usable channel workspace checkpoint after each RPC log chunk. If an RPC recovery
+run is interrupted, the next non-`--from-genesis` RPC recovery resumes from the last completed chunk. Mirror recovery
+can also start from that local checkpoint: it uses a matching delta bundle when one is available, otherwise a newer
+verified full mirror checkpoint replaces the local checkpoint before RPC catch-up.
+
 `channel create` is the exception: after the channel is created on-chain, the CLI initializes that new local workspace
 by replaying from the channel's genesis block because no prior recovery index can exist for a new channel.
 
@@ -169,12 +178,18 @@ registration transaction. For a channel that was created elsewhere, run `channel
 once before joining, or recover from a registered workspace mirror; later joins and wallet commands resume from the
 saved index instead of silently replaying from genesis.
 
-Wallet getter commands that need channel state, including `wallet get-meta`, `wallet get-channel-fund`, and
-`wallet get-notes`, refresh stale local workspaces through saved recovery indexes before reading state. `wallet get-notes`
-also refreshes received-note logs through the saved wallet note recovery index. Automatic refresh never replays from
-channel genesis and only runs when the recovery delta fits within the 7,200-block pre-command budget. If a saved index
-is missing, unusable, or too far behind, the command stops and asks the user to run the appropriate recovery command
-with `--from-genesis` explicitly when needed.
+Wallet commands that need channel state, including `wallet recover-workspace`, `wallet get-meta`,
+`wallet get-channel-fund`, and `wallet get-notes`, refresh stale local channel workspaces through saved recovery
+indexes before reading state. `wallet get-notes` and `wallet recover-workspace` also refresh received-note logs
+through the saved wallet note recovery index. Automatic refresh never replays from channel genesis and only runs when
+the recovery delta fits within the 7,200-block pre-command budget. If a saved index is missing, unusable, or too far
+behind, the command stops and asks the user to run the appropriate recovery command first.
+
+Wallet note-delivery recovery checkpoints after each RPC log chunk by updating
+`noteReceiveLastScannedBlock`. If an ordinary `wallet recover-workspace` run is interrupted during note recovery, the
+next run resumes from the last completed chunk. This does not add a special resume path for
+`wallet recover-workspace --from-genesis`; that command intentionally starts received-note scanning from channel
+genesis after the channel workspace has passed the same freshness preflight used by other wallet commands.
 
 Local wallet workspaces are epoch-aware. Each successful channel registration creates a wallet epoch under the
 canonical wallet directory. `channel exit` does not delete the local wallet workspace; it marks the active epoch as
@@ -249,8 +264,11 @@ private-state-cli investigator
 ```
 
 The command prints the bundled investigator HTML path and file URL, then opens the static browser GUI. Load the raw
-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.
+evidence ZIP in that GUI, choose the disclosure request type, inspect the interactive note-linkage graph, and export a
+narrower user-consent disclosure ZIP. The graph view renders every matched note as a node and shows creation, spend,
+and local note-to-note linkage edges when the raw bundle contains enough local evidence. The GUI can also export a
+Markdown ASCII-art linkage report with a compact graph section and per-note detail sections. 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`.
@@ -258,7 +276,7 @@ the wallet workspace with `wallet recover-workspace` and export a new bundle wit
 Estimate live transaction costs before sending commands with:
 
 ```bash
-private-state-cli help transaction-fees --network mainnet --rpc-url <RPC_URL>
+private-state-cli help transaction-fees --network mainnet
 ```
 
 `help transaction-fees` uses the measured gas data packaged in `assets/tx-fees.json`, the selected network's live fee data,
@@ -351,8 +369,9 @@ note-delivery events and rebuild the user's readable note view. Sharing it gives
 registered note-receive public key, but not spending authority.
 
 The spending key is the channel-bound L2 private key. It authorizes proof-backed use of the wallet identity. Commands
-that consume existing notes, such as `wallet transfer-notes` and `wallet redeem-notes`, need both the viewing key and
-the spending key because the CLI must first reconstruct the plaintext notes and then prove authorized use of them.
+that create or consume notes, such as `wallet mint-notes`, `wallet transfer-notes`, and `wallet redeem-notes`, need both
+the viewing key and the spending key because the CLI refreshes the readable note workspace after accepted note
+transactions and then proves authorized note use when inputs are consumed.
 
 Key recovery is intentionally split. Recreating the viewing key requires the original L1 private key and the same channel
 context. Recreating the spending key requires the original L1 private key, the same channel context, and the same wallet
@@ -375,11 +394,40 @@ The CLI stores user workspaces under:
 Wallet backup metadata lives under the channel workspace. Viewing and spending private keys live as separate protected
 key files under `~/tokamak-private-channels/secrets/<network>/wallets/<wallet>/`.
 
-Bridge-facing commands accept optional `--rpc-url <URL>`. When `--rpc-url` is provided, the CLI stores it in
-`~/tokamak-private-channels/secrets/<network>/.env` as `RPC_URL=<URL>` with protected canonical secret permissions.
-When `--rpc-url` is omitted, the CLI reads `RPC_URL` from that file. The `anvil` network falls back to
-`http://127.0.0.1:8545` when no saved RPC URL exists. Canonical CLI secrets are checked on read: macOS/Linux uses
-`0600`, while Windows uses ACL repair and inspection when possible.
+Configure the network RPC endpoint before bridge-facing or wallet recovery commands:
+
+```bash
+private-state-cli set rpc --network mainnet --rpc-url <RPC_URL> --provider alchemy
+```
+
+The CLI writes `~/tokamak-private-channels/workspace/<network>/rpc-config.env` and later commands read `RPC_URL`,
+`LOG_CHUNK_SIZE`, `LOG_REQUESTS_PER_SECOND`, and `RPC_BLOCK_RANGE_CAP` from that file. Built-in provider limits are
+set to 90% of the provider reference values: Ankr `27 calls/s, 3000 blocks`; Chainstack `22.5 calls/s, 100 blocks`;
+Chainnodes `22.5 calls/s, 20000 blocks`; QuickNode `13.5 calls/s, 5 blocks`; Alchemy `7.497 calls/s, 10 blocks`.
+If the provider is not listed, use
+`--log-requests-per-second <N>` and `--block-range-cap <N>` instead of `--provider`.
+
+### Slow Workspace Recovery
+
+`channel recover-workspace` and `wallet recover-workspace` scan on-chain logs with `eth_getLogs`. If recovery is
+unexpectedly slow, first check the RPC scan limits saved by `set rpc`. The main speed factors are the provider's
+`eth_getLogs` block range cap and the allowed log request rate. A small block range cap can turn the same channel scan
+into thousands of RPC calls.
+
+For example, an Alchemy free-tier-style cap of `10` blocks is much slower for long recovery scans than Ankr's built-in
+`3000` block setting or Chainnodes' built-in `20000` block setting. When recovery is too slow, re-run `set rpc` with a
+provider that supports a larger `eth_getLogs` block range cap, or provide explicit values:
+
+```bash
+private-state-cli set rpc --network mainnet --rpc-url <RPC_URL> --provider ankr
+private-state-cli set rpc --network mainnet --rpc-url <RPC_URL> --log-requests-per-second <N> --block-range-cap <N>
+```
+
+If an RPC provider rejects the configured range or rate during recovery, run `set rpc` again with limits that match the
+provider's documented `eth_getLogs` policy, then retry the recovery command.
+
+Canonical CLI secrets are checked on read: macOS/Linux uses `0600`, while Windows uses ACL repair and inspection when
+possible.
 
 ## LLM Agent Guidance
 
@@ -414,28 +462,42 @@ Operating rules:
   - A viewing key decrypts encrypted note-delivery events for the registered note-receive public key. A spending key is
     the channel-bound L2 private key used to authorize note use. Do not describe either key as interchangeable with the
     other.
-  - The network RPC URL is the endpoint used to read and write chain state. It can be supplied once with `--rpc-url`
-    on a bridge-facing command, after which the CLI saves it under the selected network.
+  - The network RPC URL is the endpoint used to read and write chain state. It must be configured once with
+    `private-state-cli set rpc --network <NETWORK> --rpc-url <URL> --provider <PROVIDER>`, or with explicit
+    `--log-requests-per-second` and `--block-range-cap` values when the provider is not built in.
   - 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 `channel recover-workspace` or `wallet recover-workspace` is unexpectedly slow, first inspect the RPC provider
+  configured by `set rpc`. Explain that recovery speed is dominated by `eth_getLogs` block range cap and log request
+  rate. Suggest re-running `set rpc` with a provider that supports a larger block range cap, such as Ankr or Chainnodes
+  when appropriate, or with explicit `--log-requests-per-second` and `--block-range-cap` values from the provider's
+  documentation.
+- 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
-  into the CLI command that accepts `--rpc-url`; do not ask for provider account passwords, API dashboards, seed phrases,
-  private keys, or wallet secrets.
+  selected network. They can obtain one from an infrastructure provider such as Alchemy, Ankr, Chainstack, Chainnodes,
+  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 into `private-state-cli set rpc`; do not ask for provider account passwords, API dashboards, seed
+  phrases, private keys, or wallet secrets.
 - When a user wants to join a channel, do not jump straight to `channel join`. Walk them through:
   1. choose the network and channel name
   2. run `private-state-cli install`
   3. run `private-state-cli help doctor`
   4. obtain or confirm a network RPC URL for the selected network
-  5. prepare a private key source file locally, without pasting the key into chat
-  6. run `account import --account <NAME> --network <NETWORK> --private-key-file <PATH>`
-  7. prepare a wallet secret source file locally, for example with `openssl rand -hex 32 > ./wallet-secret.txt`
-  8. inspect the channel with `channel get-meta` if it already exists, or create it with `channel create` if the user is
+  5. run `set rpc --network <NETWORK> --rpc-url <URL> --provider <PROVIDER>`, or use explicit scan limits for an
+     unlisted provider
+  6. prepare a private key source file locally, without pasting the key into chat
+  7. run `account import --account <NAME> --network <NETWORK> --private-key-file <PATH>`
+  8. prepare a wallet secret source file locally, for example with `openssl rand -hex 32 > ./wallet-secret.txt`
+  9. inspect the channel with `channel get-meta` if it already exists, or create it with `channel create` if the user is
      the channel creator
-  9. explain the immutable policy warning printed by the CLI
-  10. run `channel join --channel-name <CHANNEL> --network <NETWORK> --account <ACCOUNT> --wallet-secret-path <PATH> --acknowledge-action-impact`
+  10. explain the immutable policy warning printed by the CLI
+  11. run `channel join --channel-name <CHANNEL> --network <NETWORK> --account <ACCOUNT> --wallet-secret-path <PATH> --acknowledge-action-impact`
 - Before executing any command for a user that requires an `--acknowledge-*` option, strongly warn the user in plain
   language about what that acknowledgement means and ask for explicit confirmation. Do not add
   `--acknowledge-action-impact` or `--acknowledge-full-note-plaintext-export` on the user's behalf until they confirm.
@@ -481,7 +543,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/cli-assistant.html

@@ -413,16 +413,22 @@
           <h2>Command Guide</h2>
           <div class="box">
             <ol class="guide-list">
+              <li>
+                <span class="guide-label">Configure RPC:</span> <code>set rpc</code>
+                <div class="guide-example">
+                  <code>set rpc --network 'sepolia' --rpc-url '__RPC_URL__' --provider 'alchemy'</code>
+                </div>
+              </li>
               <li>
                 <span class="guide-label">Join a channel:</span> <code>channel join</code>
                 <div class="guide-example">
-                  <code>channel join --channel-name 'my-private-channel' --network 'sepolia' --account 'my-account' --wallet-secret-path '/path/to/wallet-secret' --rpc-url '__RPC_URL__'</code>
+                  <code>channel join --channel-name 'my-private-channel' --network 'sepolia' --account 'my-account' --wallet-secret-path '/path/to/wallet-secret'</code>
                 </div>
               </li>
               <li>
                 <span class="guide-label">Create notes:</span> <code>account deposit-bridge</code> -&gt; <code>wallet deposit-channel</code> -&gt; <code>wallet mint-notes</code>
                 <div class="guide-example">
-                  <code>account deposit-bridge --amount '100' --network 'sepolia' --account 'my-account' --rpc-url '__RPC_URL__'</code><br />
+                  <code>account deposit-bridge --amount '100' --network 'sepolia' --account 'my-account'</code><br />
                   <code>wallet deposit-channel --wallet 'my-private-channel-0xYourL1Address' --network 'sepolia' --amount '100'</code><br />
                   <code>wallet mint-notes --wallet 'my-private-channel-0xYourL1Address' --network 'sepolia' --amounts '[&quot;50&quot;,&quot;50&quot;,&quot;0&quot;]'</code>
                 </div>
@@ -438,7 +444,7 @@
                 <div class="guide-example">
                   <code>wallet redeem-notes --wallet 'my-private-channel-0xYourL1Address' --network 'sepolia' --note-ids '[&quot;0xNoteIdA&quot;]'</code><br />
                   <code>wallet withdraw-channel --wallet 'my-private-channel-0xYourL1Address' --network 'sepolia' --amount '25'</code><br />
-                  <code>account withdraw-bridge --amount '25' --network 'sepolia' --account 'my-account' --rpc-url '__RPC_URL__'</code>
+                  <code>account withdraw-bridge --amount '25' --network 'sepolia' --account 'my-account'</code>
                 </div>
               </li>
             </ol>
@@ -1420,7 +1426,7 @@
         ].forEach((fieldKey) => {
           memoryFieldsEl.appendChild(createField(fieldKey));
         });
-        memoryStatusEl.textContent = "Use account import --private-key-file before signing commands. Optional --rpc-url is saved as the network RPC_URL for later commands.";
+        memoryStatusEl.textContent = "Use set rpc once before bridge-facing commands, then use account import --private-key-file before signing commands.";
       }
 
       function renderCommandSelect() {
@@ -1480,7 +1486,7 @@
             : "",
         ].join("");
         warningEl.textContent = missing.length === 0
-          ? `Ready. If --rpc-url is omitted, the CLI uses the saved network RPC_URL.${workspaceWarnings}`
+          ? `Ready. Bridge-facing commands use the saved network RPC configuration.${workspaceWarnings}`
           : `Missing inputs: ${missing.map((fieldKey) => fieldCatalog[fieldKey].label).join(", ")}.${workspaceWarnings}`;
       }
 

package/commands/account.mjs

@@ -0,0 +1,43 @@
+import {
+  assertAccountGetBridgeFundArgs,
+  assertAccountGetL1AddressArgs,
+  assertAccountImportArgs,
+  assertDepositBridgeArgs,
+  assertWithdrawBridgeArgs,
+  handleAccountGetBridgeFund,
+  handleAccountGetL1Address,
+  handleAccountImport,
+  handleDepositBridge,
+  handleWithdrawBridge,
+  loadExplicitCommandRuntime,
+  prepareDeploymentArtifacts,
+} from "../lib/runtime.mjs";
+
+export const accountCommands = Object.freeze({
+  "account-get-l1-address": async (args) => {
+    assertAccountGetL1AddressArgs(args);
+    handleAccountGetL1Address({ args });
+  },
+  "account-import": async (args) => {
+    assertAccountImportArgs(args);
+    handleAccountImport({ args });
+  },
+  "account-get-bridge-fund": async (args) => {
+    assertAccountGetBridgeFundArgs(args);
+    const { network, provider } = loadExplicitCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleAccountGetBridgeFund({ args, provider });
+  },
+  "account-deposit-bridge": async (args) => {
+    assertDepositBridgeArgs(args);
+    const { network, provider } = loadExplicitCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleDepositBridge({ args, network, provider });
+  },
+  "account-withdraw-bridge": async (args) => {
+    assertWithdrawBridgeArgs(args);
+    const { network, provider } = loadExplicitCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleWithdrawBridge({ args, network, provider });
+  },
+});

package/commands/channel.mjs

@@ -0,0 +1,66 @@
+import {
+  assertCreateChannelArgs,
+  assertExitChannelArgs,
+  assertGetChannelArgs,
+  assertJoinChannelArgs,
+  assertProviderChainIdMatchesNetwork,
+  assertPublishWorkspaceMirrorArgs,
+  assertRecoverWorkspaceArgs,
+  assertSetWorkspaceMirrorArgs,
+  handleChannelCreate,
+  handleExitChannel,
+  handleGetChannel,
+  handleJoinChannel,
+  handlePublishChannelWorkspaceMirror,
+  handleSetChannelWorkspaceMirror,
+  handleWorkspaceInit,
+  loadExplicitCommandRuntime,
+  loadWalletCommandRuntime,
+  prepareDeploymentArtifacts,
+} from "../lib/runtime.mjs";
+
+export const channelCommands = Object.freeze({
+  "channel-create": async (args) => {
+    assertCreateChannelArgs(args);
+    const { network, provider } = loadExplicitCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleChannelCreate({ args, network, provider });
+  },
+  "channel-recover-workspace": async (args) => {
+    assertRecoverWorkspaceArgs(args);
+    const { network, provider, rpcUrl } = loadExplicitCommandRuntime(args, { staticNetwork: true });
+    await assertProviderChainIdMatchesNetwork({ provider, network, rpcUrl });
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleWorkspaceInit({ args, network, provider });
+  },
+  "channel-get-meta": async (args) => {
+    assertGetChannelArgs(args);
+    const { network, provider } = loadExplicitCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleGetChannel({ args, network, provider });
+  },
+  "channel-set-workspace-mirror": async (args) => {
+    assertSetWorkspaceMirrorArgs(args);
+    const { network, provider } = loadExplicitCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleSetChannelWorkspaceMirror({ args, network, provider });
+  },
+  "channel-publish-workspace-mirror": async (args) => {
+    assertPublishWorkspaceMirrorArgs(args);
+    const { network, provider } = loadExplicitCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handlePublishChannelWorkspaceMirror({ args, network, provider });
+  },
+  "channel-join": async (args) => {
+    assertJoinChannelArgs(args);
+    const { network, provider, rpcUrl } = loadExplicitCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleJoinChannel({ args, network, provider, rpcUrl });
+  },
+  "channel-exit": async (args) => {
+    assertExitChannelArgs(args);
+    const { network, provider } = loadWalletCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleExitChannel({ args, provider });
+  },
+});

package/commands/index.mjs

@@ -0,0 +1,62 @@
+import {
+  assertHelpCommandsArgs,
+  assertVersionArgs,
+  configureOutput,
+  formatCliErrorForDisplay,
+  parseArgs,
+  printHelp,
+  printVersion,
+} from "../lib/runtime.mjs";
+import { accountCommands } from "./account.mjs";
+import { channelCommands } from "./channel.mjs";
+import { investigatorCommands } from "./investigator.mjs";
+import { notesCommands } from "./notes.mjs";
+import { systemCommands } from "./system.mjs";
+import { walletCommands } from "./wallet.mjs";
+
+const COMMANDS = Object.freeze({
+  ...systemCommands,
+  ...investigatorCommands,
+  ...accountCommands,
+  ...channelCommands,
+  ...walletCommands,
+  ...notesCommands,
+});
+
+export async function runPrivateStateCli(argv) {
+  let args = {};
+  try {
+    args = parseArgs(argv);
+    configureOutput(args);
+
+    if (args.version !== undefined) {
+      assertVersionArgs(args);
+      printVersion();
+      return;
+    }
+
+    if (args.help || !args.command) {
+      printHelp();
+      return;
+    }
+
+    if (args.command === "help-commands") {
+      assertHelpCommandsArgs(args);
+      printHelp();
+      return;
+    }
+
+    const command = COMMANDS[args.command];
+    if (!command) {
+      throw new Error(`Unsupported command: ${args.command}`);
+    }
+    await command(args);
+  } catch (error) {
+    console.error(formatCliErrorForDisplay(error, args));
+    process.exitCode = 1;
+  }
+}
+
+export function privateStateCliDispatchTable() {
+  return COMMANDS;
+}

package/commands/investigator.mjs

@@ -0,0 +1,11 @@
+import {
+  assertInvestigatorArgs,
+  handleInvestigator,
+} from "../lib/runtime.mjs";
+
+export const investigatorCommands = Object.freeze({
+  investigator: async (args) => {
+    assertInvestigatorArgs(args);
+    handleInvestigator();
+  },
+});

package/commands/notes.mjs

@@ -0,0 +1,39 @@
+import {
+  assertMintNotesArgs,
+  assertRedeemNotesArgs,
+  assertTransferNotesArgs,
+  assertWalletGetNotesArgs,
+  handleMintNotes,
+  handleRedeemNotes,
+  handleTransferNotes,
+  handleWalletGetNotes,
+  loadWalletCommandRuntime,
+  prepareDeploymentArtifacts,
+} from "../lib/runtime.mjs";
+
+export const notesCommands = Object.freeze({
+  "wallet-mint-notes": async (args) => {
+    assertMintNotesArgs(args);
+    const { network, provider } = loadWalletCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleMintNotes({ args, provider });
+  },
+  "wallet-redeem-notes": async (args) => {
+    assertRedeemNotesArgs(args);
+    const { network, provider } = loadWalletCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleRedeemNotes({ args, provider });
+  },
+  "wallet-get-notes": async (args) => {
+    assertWalletGetNotesArgs(args);
+    const { network, provider } = loadWalletCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleWalletGetNotes({ args, provider });
+  },
+  "wallet-transfer-notes": async (args) => {
+    assertTransferNotesArgs(args);
+    const { network, provider } = loadWalletCommandRuntime(args);
+    await prepareDeploymentArtifacts(network.chainId);
+    await handleTransferNotes({ args, provider });
+  },
+});

package/commands/system.mjs

@@ -0,0 +1,49 @@
+import {
+  assertDoctorArgs,
+  assertGuideArgs,
+  assertInstallZkEvmArgs,
+  assertSetRpcArgs,
+  assertTransactionFeesArgs,
+  assertUninstallArgs,
+  assertUpdateArgs,
+  handleDoctor,
+  handleGuide,
+  handleInstallZkEvm,
+  handleSetRpc,
+  handleTransactionFees,
+  handleUninstall,
+  handleUpdate,
+  loadExplicitCommandRuntime,
+} from "../lib/runtime.mjs";
+
+export const systemCommands = Object.freeze({
+  install: async (args) => {
+    assertInstallZkEvmArgs(args);
+    await handleInstallZkEvm({ args });
+  },
+  uninstall: async (args) => {
+    assertUninstallArgs(args);
+    await handleUninstall();
+  },
+  "set-rpc": async (args) => {
+    assertSetRpcArgs(args);
+    await handleSetRpc({ args });
+  },
+  "help-update": async (args) => {
+    assertUpdateArgs(args);
+    await handleUpdate();
+  },
+  "help-doctor": async (args) => {
+    assertDoctorArgs(args);
+    await handleDoctor({ args });
+  },
+  "help-guide": async (args) => {
+    assertGuideArgs(args);
+    await handleGuide({ args });
+  },
+  "help-transaction-fees": async (args) => {
+    assertTransactionFeesArgs(args);
+    const { network, provider, rpcUrl } = loadExplicitCommandRuntime(args);
+    await handleTransactionFees({ network, provider, rpcUrl });
+  },
+});