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

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+## 2.2.1 - 2026-05-18
+
+- Added `channel recover-workspace --source rpc --output-raw` to append raw JSON-RPC request and response history
+  to method-specific JSON files under the channel workspace `rpcCallHistory/` directory, with `eth_getLogs` split by event.
+  Indexed recovery appends to existing history; `--from-genesis` overwrites it with one full genesis-to-latest scan.
+
+## 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

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,
@@ -170,6 +192,12 @@ run is interrupted, the next non-`--from-genesis` RPC recovery resumes from the
 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.
 
+Use `channel recover-workspace --source rpc --output-raw` when you need to preserve the raw JSON-RPC request and
+response history for inspection. The CLI appends calls to method-specific JSON files, and splits `eth_getLogs` into
+event-specific files such as `eth_getLogs.CurrentRootVectorObserved.json`, under
+`~/tokamak-private-channels/workspace/<network>/<channel>/channel/rpcCallHistory/`. Indexed recovery appends to the
+existing history, while `--from-genesis` overwrites it with one full genesis-to-latest scan.
+
 `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.
 
@@ -208,7 +236,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:
 
@@ -309,9 +337,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:
 
@@ -561,8 +591,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
@@ -579,11 +610,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/commands/account.mjs

@@ -10,7 +10,6 @@ import {
   handleDepositBridge,
   handleWithdrawBridge,
   loadExplicitCommandRuntime,
-  prepareDeploymentArtifacts,
 } from "../lib/runtime.mjs";
 
 export const accountCommands = Object.freeze({
@@ -24,20 +23,17 @@ export const accountCommands = Object.freeze({
   },
   "account-get-bridge-fund": async (args) => {
     assertAccountGetBridgeFundArgs(args);
-    const { network, provider } = loadExplicitCommandRuntime(args);
-    await prepareDeploymentArtifacts(network.chainId);
+    const { provider } = loadExplicitCommandRuntime(args, { prepareArtifacts: true });
     await handleAccountGetBridgeFund({ args, provider });
   },
   "account-deposit-bridge": async (args) => {
     assertDepositBridgeArgs(args);
-    const { network, provider } = loadExplicitCommandRuntime(args);
-    await prepareDeploymentArtifacts(network.chainId);
+    const { network, provider } = loadExplicitCommandRuntime(args, { prepareArtifacts: true });
     await handleDepositBridge({ args, network, provider });
   },
   "account-withdraw-bridge": async (args) => {
     assertWithdrawBridgeArgs(args);
-    const { network, provider } = loadExplicitCommandRuntime(args);
-    await prepareDeploymentArtifacts(network.chainId);
+    const { network, provider } = loadExplicitCommandRuntime(args, { prepareArtifacts: true });
     await handleWithdrawBridge({ args, network, provider });
   },
 });

package/commands/channel.mjs

@@ -16,51 +16,43 @@ import {
   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);
+    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 });
+    const { network, provider, rpcUrl } = loadExplicitCommandRuntime(args, { staticNetwork: true, prepareArtifacts: 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);
+    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);
-    await prepareDeploymentArtifacts(network.chainId);
+    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);
-    await prepareDeploymentArtifacts(network.chainId);
+    const { network, provider } = loadExplicitCommandRuntime(args, { prepareArtifacts: true });
     await handlePublishChannelWorkspaceMirror({ args, network, provider });
   },
   "channel-join": async (args) => {
     assertJoinChannelArgs(args);
-    const { network, provider, rpcUrl } = loadExplicitCommandRuntime(args);
-    await prepareDeploymentArtifacts(network.chainId);
+    const { network, provider, rpcUrl } = loadExplicitCommandRuntime(args, { prepareArtifacts: true });
     await handleJoinChannel({ args, network, provider, rpcUrl });
   },
   "channel-exit": async (args) => {
     assertExitChannelArgs(args);
-    const { network, provider } = loadWalletCommandRuntime(args);
-    await prepareDeploymentArtifacts(network.chainId);
+    const { provider } = loadWalletCommandRuntime(args, { prepareArtifacts: true });
     await handleExitChannel({ args, provider });
   },
 });

package/commands/notes.mjs

@@ -8,32 +8,27 @@ import {
   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);
+    const { provider } = loadWalletCommandRuntime(args, { prepareArtifacts: true });
     await handleMintNotes({ args, provider });
   },
   "wallet-redeem-notes": async (args) => {
     assertRedeemNotesArgs(args);
-    const { network, provider } = loadWalletCommandRuntime(args);
-    await prepareDeploymentArtifacts(network.chainId);
+    const { provider } = loadWalletCommandRuntime(args, { prepareArtifacts: true });
     await handleRedeemNotes({ args, provider });
   },
   "wallet-get-notes": async (args) => {
     assertWalletGetNotesArgs(args);
-    const { network, provider } = loadWalletCommandRuntime(args);
-    await prepareDeploymentArtifacts(network.chainId);
+    const { provider } = loadWalletCommandRuntime(args, { prepareArtifacts: true });
     await handleWalletGetNotes({ args, provider });
   },
   "wallet-transfer-notes": async (args) => {
     assertTransferNotesArgs(args);
-    const { network, provider } = loadWalletCommandRuntime(args);
-    await prepareDeploymentArtifacts(network.chainId);
+    const { provider } = loadWalletCommandRuntime(args, { prepareArtifacts: true });
     await handleTransferNotes({ args, provider });
   },
 });

package/commands/wallet.mjs

@@ -20,7 +20,6 @@ import {
   handleWalletImportKey,
   loadExplicitCommandRuntime,
   loadWalletCommandRuntime,
-  prepareDeploymentArtifacts,
 } from "../lib/runtime.mjs";
 
 export const walletCommands = Object.freeze({
@@ -54,33 +53,28 @@ export const walletCommands = Object.freeze({
   },
   "wallet-recover-workspace": async (args) => {
     assertRecoverWalletArgs(args);
-    const { network, provider, rpcUrl } = loadExplicitCommandRuntime(args, { staticNetwork: true });
+    const { network, provider, rpcUrl } = loadExplicitCommandRuntime(args, { staticNetwork: true, prepareArtifacts: true });
     await assertProviderChainIdMatchesNetwork({ provider, network, rpcUrl });
-    await prepareDeploymentArtifacts(network.chainId);
     await handleRecoverWallet({ args, network, provider, rpcUrl });
   },
   "wallet-get-meta": async (args) => {
     assertWalletGetMetaArgs(args);
-    const { network, provider } = loadWalletCommandRuntime(args);
-    await prepareDeploymentArtifacts(network.chainId);
+    const { provider } = loadWalletCommandRuntime(args, { prepareArtifacts: true });
     await handleWalletGetMeta({ args, provider });
   },
   "wallet-get-channel-fund": async (args) => {
     assertWalletGetChannelFundArgs(args);
-    const { network, provider } = loadWalletCommandRuntime(args);
-    await prepareDeploymentArtifacts(network.chainId);
+    const { provider } = loadWalletCommandRuntime(args, { prepareArtifacts: true });
     await handleWalletGetChannelFund({ args, provider });
   },
   "wallet-deposit-channel": async (args) => {
     assertWalletChannelMoveArgs(args, "wallet-deposit-channel");
-    const { network, provider } = loadWalletCommandRuntime(args);
-    await prepareDeploymentArtifacts(network.chainId);
+    const { provider } = loadWalletCommandRuntime(args, { prepareArtifacts: true });
     await handleGrothVaultMove({ args, provider, direction: "deposit" });
   },
   "wallet-withdraw-channel": async (args) => {
     assertWalletChannelMoveArgs(args, "wallet-withdraw-channel");
-    const { network, provider } = loadWalletCommandRuntime(args);
-    await prepareDeploymentArtifacts(network.chainId);
+    const { provider } = loadWalletCommandRuntime(args, { prepareArtifacts: true });
     await handleGrothVaultMove({ args, provider, direction: "withdraw" });
   },
 });

package/lib/private-state-cli-command-registry.mjs

@@ -188,6 +188,13 @@ export const PRIVATE_STATE_CLI_FIELD_CATALOG = Object.freeze({
     valueLabel: "<VERSION>",
     optional: true,
   },
+  readOnly: {
+    label: "Read-Only Install",
+    type: "checkbox",
+    hint: "Install only artifacts needed by channel-state read commands and commands that do not depend on channel state.",
+    option: "--read-only",
+    optional: true,
+  },
   fromGenesis: {
     label: "Scan From Genesis",
     type: "checkbox",
@@ -195,6 +202,13 @@ export const PRIVATE_STATE_CLI_FIELD_CATALOG = Object.freeze({
     option: "--from-genesis",
     optional: true,
   },
+  outputRaw: {
+    label: "Output Raw RPC History",
+    type: "checkbox",
+    hint: "With channel recover-workspace --source rpc, preserve raw JSON-RPC request and response history under the channel workspace.",
+    option: "--output-raw",
+    optional: true,
+  },
   source: {
     label: "Recovery Source",
     type: "select",
@@ -239,7 +253,7 @@ const ACTION_IMPACT_HELP = Object.freeze({
   acknowledgement: "Requires --acknowledge-action-impact after the user reviews the action-impact warning.",
   illegalUse: "The command must not be used for money laundering, sanctions evasion, terrorist financing, illegal gambling, criminal-proceeds concealment, or regulatory evasion.",
   secretRecovery: "Losing wallet secrets, viewing keys, or spending keys can prevent note discovery or note use; the CLI cannot recover lost secrets.",
-  cexAddress: "Do not use a centralized-exchange controlled address as a self-custody bridge source or direct bridge withdrawal target.",
+  exchangeControlledAddress: "Do not use an exchange-controlled address as a self-custody bridge source or direct bridge withdrawal target.",
   policy: "The user must review the channel policy snapshot before accepting channel-bound actions.",
   provenance: "Public observers cannot reconstruct private note counterparty relationships or note provenance from public contract state alone.",
 });
@@ -247,10 +261,12 @@ const ACTION_IMPACT_HELP = Object.freeze({
 export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
   {
     id: "install",
-    description: "Install the Tokamak zk-EVM CLI runtime, Groth16 runtime, and private-state deployment artifacts.",
-    fields: ["docker", "includeLocalArtifacts", "groth16CliVersion", "tokamakZkEvmCliVersion"],
-    usage: "optional --docker, --include-local-artifacts, --groth16-cli-version, and --tokamak-zk-evm-cli-version",
+    description: "Install private-state CLI runtime artifacts in full or read-only mode.",
+    fields: ["readOnly", "docker", "includeLocalArtifacts", "groth16CliVersion", "tokamakZkEvmCliVersion"],
+    usage: "optional --read-only, --docker, --include-local-artifacts, --groth16-cli-version, and --tokamak-zk-evm-cli-version",
     help: [
+      "Default full mode installs proof runtimes and all deployment artifacts needed by transaction-sending commands",
+      "--read-only installs only artifacts needed by channel-state read commands and commands unrelated to channel state",
       "Version options install exact CLI package versions; omitted versions resolve to npm registry latest",
       "Use --docker on Linux to forward Docker mode to the Tokamak zk-EVM and Groth16 runtimes",
       "Use --include-local-artifacts to also install local deployment/ artifacts from the current working directory",
@@ -295,11 +311,12 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
   {
     id: "help-doctor",
     display: "help doctor",
-    description: "Check private-state CLI package versions, runtime install state, Docker mode, CUDA mode, and deployment artifacts.",
+    description: "Check private-state CLI package versions, install state, deployment artifacts, and command availability.",
     fields: ["gpu", "json"],
     usage: "optional --gpu and optional --json",
     help: [
       "Prints a concise human-readable table by default; use --json for the full machine-readable report",
+      "Reports whether each command is usable with the current read-only or full install state",
       "Use --gpu to run live NVIDIA/Docker GPU probes",
     ],
   },
@@ -352,6 +369,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     id: "account-get-bridge-fund",
     display: "account get-bridge-fund",
     description: "Read the local account's current shared bridge vault balance.",
+    installMode: "read-only",
     fields: ["network", "account"],
     usage: "--network, --account",
   },
@@ -359,6 +377,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     id: "channel-create",
     display: "channel create",
     description: "Create a bridge channel and initialize its workspace.",
+    installMode: "full",
     fields: ["channelName", "joinToll", "network", "account"],
     usage: "--channel-name, --join-toll, --network, --account",
     help: [
@@ -370,8 +389,9 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     id: "channel-recover-workspace",
     display: "channel recover-workspace",
     description: "Rebuild the local channel workspace from bridge state.",
-    fields: ["channelName", "network", "source", "fromGenesis"],
-    usage: "--channel-name, --network, optional --source, optional --from-genesis",
+    installMode: "read-only",
+    fields: ["channelName", "network", "source", "fromGenesis", "outputRaw"],
+    usage: "--channel-name, --network, optional --source, optional --from-genesis, optional --output-raw",
     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",
@@ -379,6 +399,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
       "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",
+      "--output-raw with --source rpc appends raw JSON-RPC request and response history to method-specific JSON files under the channel workspace rpcCallHistory directory; eth_getLogs is split by event",
       "--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",
     ],
@@ -387,6 +408,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     id: "channel-set-workspace-mirror",
     display: "channel set-workspace-mirror",
     description: "Register or update the channel leader's workspace mirror base URL.",
+    installMode: "full",
     fields: ["channelName", "network", "account", "url"],
     usage: "--channel-name, --network, --account, --url",
     help: [
@@ -398,6 +420,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     id: "channel-publish-workspace-mirror",
     display: "channel publish-workspace-mirror",
     description: "Build static workspace mirror files for the registered mirror URL.",
+    installMode: "read-only",
     fields: ["channelName", "network", "account", "output", "force"],
     usage: "--channel-name, --network, --account, --output, optional --force",
     help: [
@@ -411,6 +434,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     id: "channel-get-meta",
     display: "channel get-meta",
     description: "Read channel existence, manager, vault, toll, refund schedule, and immutable policy snapshot.",
+    installMode: "read-only",
     fields: ["channelName", "network"],
     usage: "--channel-name, --network",
   },
@@ -418,12 +442,13 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     id: "account-deposit-bridge",
     display: "account deposit-bridge",
     description: "Deposit canonical tokens into the shared bridge vault.",
+    installMode: "read-only",
     fields: ["amount", "network", "account", "acknowledgeActionImpact"],
     usage: "--amount, --network, --account, --acknowledge-action-impact",
     help: [
       "Action impact: emits public L1 approval and bridge funding events that expose the local L1 account, bridge vault, amount, and transaction hashes.",
       "Private note state is not changed by this command.",
-      ACTION_IMPACT_HELP.cexAddress,
+      ACTION_IMPACT_HELP.exchangeControlledAddress,
       ACTION_IMPACT_HELP.illegalUse,
       ACTION_IMPACT_HELP.acknowledgement,
     ],
@@ -432,12 +457,13 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     id: "account-withdraw-bridge",
     display: "account withdraw-bridge",
     description: "Withdraw tokens from the shared bridge vault back to the wallet.",
+    installMode: "read-only",
     fields: ["amount", "network", "account", "acknowledgeActionImpact"],
     usage: "--amount, --network, --account, --acknowledge-action-impact",
     help: [
       "Action impact: emits a public L1 bridge withdrawal event that exposes the local L1 recipient, bridge vault, amount, and transaction hash.",
       "Private note state is not changed by this command; prior note provenance is not public by default.",
-      ACTION_IMPACT_HELP.cexAddress,
+      ACTION_IMPACT_HELP.exchangeControlledAddress,
       ACTION_IMPACT_HELP.illegalUse,
       ACTION_IMPACT_HELP.acknowledgement,
     ],
@@ -446,6 +472,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     id: "wallet-recover-workspace",
     display: "wallet recover-workspace",
     description: "Rebuild a recoverable local wallet from on-chain channel state.",
+    installMode: "read-only",
     fields: ["channelName", "network", "account", "fromGenesis"],
     usage: "--channel-name, --network, --account, optional --from-genesis",
     help: [
@@ -462,6 +489,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     id: "channel-join",
     display: "channel join",
     description: "Pay the channel join toll and bind a wallet to a channel-specific L2 identity.",
+    installMode: "full",
     fields: ["channelName", "network", "account", "walletSecretPath", "acknowledgeActionImpact"],
     usage: "--channel-name, --network, --account, --wallet-secret-path, --acknowledge-action-impact",
     help: [
@@ -481,6 +509,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     id: "wallet-get-meta",
     display: "wallet get-meta",
     description: "Check whether a wallet matches the on-chain channel registration.",
+    installMode: "read-only",
     fields: ["wallet", "network"],
     usage: "--wallet and --network",
     help: [
@@ -550,6 +579,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     id: "wallet-deposit-channel",
     display: "wallet deposit-channel",
     description: "Move bridged funds into the channel L2 accounting balance.",
+    installMode: "full",
     fields: ["wallet", "network", "amount", "acknowledgeActionImpact"],
     usage: "--wallet, --network, --amount, and --acknowledge-action-impact",
     help: [
@@ -566,6 +596,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     id: "wallet-withdraw-channel",
     display: "wallet withdraw-channel",
     description: "Move channel L2 balance back into the shared bridge vault.",
+    installMode: "full",
     fields: ["wallet", "network", "amount", "acknowledgeActionImpact"],
     usage: "--wallet, --network, --amount, and --acknowledge-action-impact",
     help: [
@@ -583,6 +614,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     id: "wallet-get-channel-fund",
     display: "wallet get-channel-fund",
     description: "Read the current channel L2 accounting balance.",
+    installMode: "read-only",
     fields: ["wallet", "network"],
     usage: "--wallet and --network",
     help: ["Refreshes the local channel workspace through the saved recovery index before reading the L2 accounting balance when the scan fits the 10 second pre-command budget"],
@@ -591,6 +623,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     id: "channel-exit",
     display: "channel exit",
     description: "Exit a channel. Both the CLI and bridge contract require a zero channel balance.",
+    installMode: "full",
     fields: ["wallet", "network"],
     usage: "--wallet and --network",
     help: [
@@ -602,6 +635,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     id: "wallet-mint-notes",
     display: "wallet mint-notes",
     description: "Mint one or two private-state notes from the wallet's channel balance.",
+    installMode: "full",
     fields: ["wallet", "network", "amounts", "acknowledgeActionImpact", "txSubmitter"],
     usage: "--wallet, --network, --amounts, --acknowledge-action-impact, and optional --tx-submitter",
     help: [
@@ -621,6 +655,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     id: "wallet-transfer-notes",
     display: "wallet transfer-notes",
     description: "Spend input notes into the registered 1->1, 1->2, or 2->1 private transfer shapes.",
+    installMode: "full",
     fields: ["wallet", "network", "noteIds", "recipients", "amounts", "acknowledgeActionImpact", "txSubmitter"],
     usage: "--wallet, --network, --note-ids, --recipients, --amounts, --acknowledge-action-impact, and optional --tx-submitter",
     help: [
@@ -639,6 +674,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     id: "wallet-redeem-notes",
     display: "wallet redeem-notes",
     description: "Redeem one tracked note back into the wallet's channel balance.",
+    installMode: "full",
     fields: ["wallet", "network", "noteIds", "acknowledgeActionImpact", "txSubmitter"],
     usage: "--wallet, --network, --note-ids, --acknowledge-action-impact, and optional --tx-submitter",
     help: [
@@ -657,6 +693,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     id: "wallet-get-notes",
     display: "wallet get-notes",
     description: "Refresh received notes when the saved recovery index is recent, then show tracked note state.",
+    installMode: "read-only",
     fields: ["wallet", "network", "exportEvidence", "acknowledgeFullNotePlaintextExport"],
     usage: "--wallet, --network, optional --export-evidence, and optional --acknowledge-full-note-plaintext-export",
     help: [
@@ -669,6 +706,10 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
   },
 ]);
 
+export function privateStateCliCommandInstallMode(command) {
+  return command.installMode ?? "none";
+}
+
 export function privateStateCliCommandDisplay(command) {
   return command.display ?? command.id;
 }
@@ -698,7 +739,7 @@ export function privateStateCliCommandSynopsis(command) {
         return null;
       }
       const valueLabel = field.valueLabel ?? field.placeholderLabel ?? `<${field.label?.toUpperCase().replace(/\s+/g, "_") ?? "VALUE"}>`;
-      const option = field.type === "checkbox" || fieldKey === "fromGenesis"
+      const option = field.type === "checkbox"
         ? field.option
         : `${field.option} ${valueLabel}`;
       return field.optional || optionalFields.has(fieldKey) ? `[${option}]` : option;