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

package/CHANGELOG.md

@@ -2,6 +2,51 @@
 
 ## Unreleased
 
+## 2.2.0 - 2026-05-18
+
+- Added `install --read-only` for channel-state read commands and commands that do not depend on channel state. This
+  mode installs only the bridge deployment, bridge ABI manifest, DApp deployment, and storage layout artifacts.
+- Kept default `install` as full mode for proof-backed and channel-mutating commands, and made deployment artifact
+  validation mode-aware before command execution.
+- Extended `help doctor` with per-command availability so read-only installs clearly report which commands are usable
+  and which commands still require full install.
+- Added private-state CLI E2E coverage for the read-only install mode before the full install flow.
+
+## 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

package/README.md

@@ -4,16 +4,16 @@ Command-line client for the Tokamak private-state DApp.
 
 The full private-state DApp documentation is published with the repository:
 
-- https://github.com/tokamak-network/Tokamak-zk-EVM-contracts/tree/main/packages/apps/private-state/docs
+- https://github.com/tokamak-network/Tokamak-zk-EVM-contracts/tree/main/docs/dapps/private-state
 
-## Terminology And CEX Boundary
+## Terminology And Exchange Boundary
 
 This npm README uses the same terminology as the repository README:
 
 - `Tokamak Private App Channels`: Ethereum-settled, validity-proven execution domains for bridge-coupled DApps.
 - `private-state DApp`: the current reference DApp that programs confidential application state inside a channel.
 - `canonical Tokamak Network Token`: the L1 asset whose custody remains anchored on Ethereum.
-- `self-custody L1 wallet`: a user-controlled L1 account, not a centralized-exchange deposit address.
+- `self-custody L1 wallet`: a user-controlled L1 account, not an exchange deposit address.
 - `L1-transparent bridge edge`: public bridge deposit and withdrawal transactions involving the canonical token.
 - `channel-local accounting balance`: liquid application balance inside a channel before or after note use.
 - `private-state note`: a channel-local application note, not an exchange-supported token or deposit asset.
@@ -22,10 +22,20 @@ This npm README uses the same terminology as the repository README:
 - `viewing key`: the note-receive private key used to decrypt note-delivery events for the registered note-receive public key.
 - `spending key`: the channel-bound L2 private key used to authorize proof-backed note use.
 
-Tokamak Private App Channels are not a centralized-exchange deposit network. CEX-facing token transfers and bridge
+Tokamak Private App Channels are not an exchange deposit network. Exchange-facing token transfers and bridge
 entry or exit remain public L1 activity. Internal private-state note counterparty relationships and note provenance are
 not public by default and are not reconstructed by Tokamak on a user's behalf.
 
+## Address And Key-Safety Warnings
+
+Do not use an exchange deposit address as a private-state wallet address. Private-state notes are not
+supported exchange assets. Always withdraw TON to a self-custody L1 wallet before using a channel.
+
+Bridge deposits and withdrawals are public L1 events. Internal note transfers are private by design and are not
+automatically reconstructible by Tokamak, exchanges, or public observers.
+
+This CLI does not send your spending key, wallet secret, or private note plaintext to Tokamak.
+
 ## Tokamak-Operated Mainnet Channels
 
 The table below lists private-state mainnet channels directly opened by Tokamak Network. Dates are
@@ -41,8 +51,8 @@ UTC.
 npm install -g @tokamak-private-dapps/private-state-cli
 ```
 
-Install the local Tokamak zk-EVM runtime workspace, Groth16 runtime workspace, and public private-state deployment
-artifacts:
+Install the full local Tokamak zk-EVM runtime workspace, Groth16 runtime workspace, and public private-state deployment
+artifacts needed by transaction-sending channel commands:
 
 ```bash
 private-state-cli install
@@ -61,6 +71,18 @@ selected Groth16 CLI package version.
 The Tokamak zk-EVM installer requires the selected CLI package to declare
 `tokamakZkEvm.compatibleBackendVersion` as a canonical major.minor version matching the selected package version.
 
+For read-only channel recovery, channel metadata lookup, wallet recovery, wallet metadata lookup, bridge balance
+lookup, bridge deposit, bridge withdrawal, and local helper commands, install only the read-only artifact subset:
+
+```bash
+private-state-cli install --read-only
+```
+
+Read-only install materializes only `bridge.<chainId>.json`, `bridge-abi-manifest.<chainId>.json`,
+`deployment.<chainId>.latest.json`, and `storage-layout.<chainId>.latest.json`. It does not install the Tokamak
+zk-EVM runtime, Groth16 runtime, Groth16 zkey, callable DApp ABI, or DApp registration artifact, so commands that
+create or mutate channel state require a later full `private-state-cli install`.
+
 `install` downloads public deployment artifacts from the configured artifact index. It does not read repository-local
 `deployment/` outputs by default. Repository development workflows that need local anvil artifacts can opt in explicitly:
 
@@ -147,8 +169,8 @@ Static warning scope:
 | `wallet redeem-notes` | L1 submitter, input nullifier, accounting update, root update | Consumes notes | Prior path by which the note was received |
 | `wallet withdraw-channel` | L1 submitter, registered L2 address, amount, channel id, accounting update | No direct note spend | Prior private-state note path behind the liquid balance |
 
-`account deposit-bridge` and `account withdraw-bridge` also print a centralized-exchange address warning. Do not use a
-centralized-exchange controlled address as a self-custody bridge source or as the direct bridge withdrawal target
+`account deposit-bridge` and `account withdraw-bridge` also print an exchange-controlled address warning. Do not use an
+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 saved recovery indexes by default. If the local channel workspace is missing,
@@ -208,7 +230,7 @@ already exists. The channel leader can build the static mirror files with
 host. If the existing mirror manifest is unreadable or invalid, the leader can use
 `channel publish-workspace-mirror --force` to write a full checkpoint without trusting that remote
 manifest as a delta base. The CLI protocol is documented at
-https://github.com/tokamak-network/Tokamak-zk-EVM-contracts/blob/main/packages/apps/private-state/docs/channel-workspace-mirror-protocol.md.
+https://github.com/tokamak-network/Tokamak-zk-EVM-contracts/blob/main/docs/dapps/private-state/channel-workspace-mirror-protocol.md.
 
 Back up a local wallet with:
 
@@ -264,8 +286,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`.
@@ -273,7 +298,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,
@@ -306,9 +331,11 @@ Channel policy warning:
   a new channel; it does not rewrite the policy of an already-created channel.
 
 `private-state-cli help doctor` reports the CLI package version, dependency versions recorded by the last
-`private-state-cli install`, selected proof backend runtime versions, current dependency versions through `tokamak-l2js`, and Tokamak zk-EVM runtime
-install mode, Docker mode, CUDA runtime metadata, live `nvidia-smi` and Docker GPU probe results, and Groth16
-runtime health. The doctor check fails when the Tokamak Docker `useGpus` metadata does not match the live GPU probes.
+`private-state-cli install`, selected proof backend runtime versions when full mode was installed, current dependency
+versions through `tokamak-l2js`, Tokamak zk-EVM runtime install mode, Docker mode, CUDA runtime metadata, live
+`nvidia-smi` and Docker GPU probe results, Groth16 runtime health, deployment artifact readiness, and per-command
+availability. In read-only install mode, proof runtime checks are skipped and proof-backed or channel-mutating
+commands are reported unavailable until full install is completed.
 
 Local helper commands:
 
@@ -366,8 +393,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
@@ -390,11 +418,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
 
@@ -429,8 +486,9 @@ 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.
@@ -438,25 +496,32 @@ Operating rules:
   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.
@@ -520,8 +585,9 @@ command.
 
 ## Artifacts
 
-Proof-backed commands require installed bridge, DApp, and Groth16 artifacts. Run `private-state-cli install` before
-using bridge-facing commands on a new machine.
+Proof-backed and channel-mutating commands require full installed bridge, DApp, and Groth16 artifacts. Run
+`private-state-cli install` before creating, joining, exiting, or mutating channels on a new machine. Channel-state read
+commands and commands unrelated to channel state can run after `private-state-cli install --read-only`.
 
 Channel balance commands such as `wallet deposit-channel` and `wallet withdraw-channel` use the installed Groth16 runtime workspace
 directly. Proof generation writes to the fixed workspace paths under `~/tokamak-private-channels/groth16/proof`; the CLI
@@ -538,11 +604,16 @@ Release order matters for npm publication. `@tokamak-private-dapps/common-librar
 
 It installs the `private-state-cli` terminal command and the local files needed by that command.
 It does not install bridge contracts, app contracts, or local deployment outputs. The `private-state-cli install`
-command provisions the local Tokamak zk-EVM and Groth16 runtime workspaces used by proof-backed commands.
+command defaults to full mode, which provisions local Tokamak zk-EVM and Groth16 runtime workspaces used by
+proof-backed commands. `private-state-cli install --read-only` installs only the public bridge and private-state DApp
+artifacts needed by channel-state read commands and commands that do not depend on channel state.
 
 ### When should I run `private-state-cli install`?
 
-Run it once on a new machine, or after public bridge, DApp, Groth16, or Tokamak zk-EVM runtime artifacts are updated.
+Run full install once on a machine that will create, join, exit, or mutate channels. Run read-only install on a machine
+that only needs channel recovery, wallet recovery, metadata lookup, bridge balance lookup, bridge deposit or withdrawal,
+and local import/export/helper commands. Re-run the relevant mode after public bridge, DApp, Groth16, or Tokamak zk-EVM
+runtime artifacts are updated.
 
 ### Does this package publish private user data?
 

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,39 @@
+import {
+  assertAccountGetBridgeFundArgs,
+  assertAccountGetL1AddressArgs,
+  assertAccountImportArgs,
+  assertDepositBridgeArgs,
+  assertWithdrawBridgeArgs,
+  handleAccountGetBridgeFund,
+  handleAccountGetL1Address,
+  handleAccountImport,
+  handleDepositBridge,
+  handleWithdrawBridge,
+  loadExplicitCommandRuntime,
+} 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 { provider } = loadExplicitCommandRuntime(args, { prepareArtifacts: true });
+    await handleAccountGetBridgeFund({ args, provider });
+  },
+  "account-deposit-bridge": async (args) => {
+    assertDepositBridgeArgs(args);
+    const { network, provider } = loadExplicitCommandRuntime(args, { prepareArtifacts: true });
+    await handleDepositBridge({ args, network, provider });
+  },
+  "account-withdraw-bridge": async (args) => {
+    assertWithdrawBridgeArgs(args);
+    const { network, provider } = loadExplicitCommandRuntime(args, { prepareArtifacts: true });
+    await handleWithdrawBridge({ args, network, provider });
+  },
+});

package/commands/channel.mjs

@@ -0,0 +1,58 @@
+import {
+  assertCreateChannelArgs,
+  assertExitChannelArgs,
+  assertGetChannelArgs,
+  assertJoinChannelArgs,
+  assertProviderChainIdMatchesNetwork,
+  assertPublishWorkspaceMirrorArgs,
+  assertRecoverWorkspaceArgs,
+  assertSetWorkspaceMirrorArgs,
+  handleChannelCreate,
+  handleExitChannel,
+  handleGetChannel,
+  handleJoinChannel,
+  handlePublishChannelWorkspaceMirror,
+  handleSetChannelWorkspaceMirror,
+  handleWorkspaceInit,
+  loadExplicitCommandRuntime,
+  loadWalletCommandRuntime,
+} from "../lib/runtime.mjs";
+
+export const channelCommands = Object.freeze({
+  "channel-create": async (args) => {
+    assertCreateChannelArgs(args);
+    const { network, provider } = loadExplicitCommandRuntime(args, { prepareArtifacts: true });
+    await handleChannelCreate({ args, network, provider });
+  },
+  "channel-recover-workspace": async (args) => {
+    assertRecoverWorkspaceArgs(args);
+    const { network, provider, rpcUrl } = loadExplicitCommandRuntime(args, { staticNetwork: true, prepareArtifacts: true });
+    await assertProviderChainIdMatchesNetwork({ provider, network, rpcUrl });
+    await handleWorkspaceInit({ args, network, provider });
+  },
+  "channel-get-meta": async (args) => {
+    assertGetChannelArgs(args);
+    const { network, provider } = loadExplicitCommandRuntime(args, { prepareArtifacts: true });
+    await handleGetChannel({ args, network, provider });
+  },
+  "channel-set-workspace-mirror": async (args) => {
+    assertSetWorkspaceMirrorArgs(args);
+    const { network, provider } = loadExplicitCommandRuntime(args, { prepareArtifacts: true });
+    await handleSetChannelWorkspaceMirror({ args, network, provider });
+  },
+  "channel-publish-workspace-mirror": async (args) => {
+    assertPublishWorkspaceMirrorArgs(args);
+    const { network, provider } = loadExplicitCommandRuntime(args, { prepareArtifacts: true });
+    await handlePublishChannelWorkspaceMirror({ args, network, provider });
+  },
+  "channel-join": async (args) => {
+    assertJoinChannelArgs(args);
+    const { network, provider, rpcUrl } = loadExplicitCommandRuntime(args, { prepareArtifacts: true });
+    await handleJoinChannel({ args, network, provider, rpcUrl });
+  },
+  "channel-exit": async (args) => {
+    assertExitChannelArgs(args);
+    const { provider } = loadWalletCommandRuntime(args, { prepareArtifacts: true });
+    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,34 @@
+import {
+  assertMintNotesArgs,
+  assertRedeemNotesArgs,
+  assertTransferNotesArgs,
+  assertWalletGetNotesArgs,
+  handleMintNotes,
+  handleRedeemNotes,
+  handleTransferNotes,
+  handleWalletGetNotes,
+  loadWalletCommandRuntime,
+} from "../lib/runtime.mjs";
+
+export const notesCommands = Object.freeze({
+  "wallet-mint-notes": async (args) => {
+    assertMintNotesArgs(args);
+    const { provider } = loadWalletCommandRuntime(args, { prepareArtifacts: true });
+    await handleMintNotes({ args, provider });
+  },
+  "wallet-redeem-notes": async (args) => {
+    assertRedeemNotesArgs(args);
+    const { provider } = loadWalletCommandRuntime(args, { prepareArtifacts: true });
+    await handleRedeemNotes({ args, provider });
+  },
+  "wallet-get-notes": async (args) => {
+    assertWalletGetNotesArgs(args);
+    const { provider } = loadWalletCommandRuntime(args, { prepareArtifacts: true });
+    await handleWalletGetNotes({ args, provider });
+  },
+  "wallet-transfer-notes": async (args) => {
+    assertTransferNotesArgs(args);
+    const { provider } = loadWalletCommandRuntime(args, { prepareArtifacts: true });
+    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 });
+  },
+});