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

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

@@ -18,8 +18,34 @@ export const PRIVATE_STATE_CLI_FIELD_CATALOG = Object.freeze({
     type: "password",
     placeholder: "https://example-rpc",
     valueLabel: "<URL>",
-    hint: "Optional. When omitted, the CLI reads RPC_URL from ~/tokamak-private-channels/secrets/<network>/.env.",
+    hint: "Required by set rpc. Saved to ~/tokamak-private-channels/workspace/<network>/rpc-config.env.",
     option: "--rpc-url",
+  },
+  provider: {
+    label: "RPC Provider",
+    type: "select",
+    options: ["alchemy", "ankr", "chainstack", "chainnodes", "quicknode"],
+    valueLabel: "<PROVIDER>",
+    hint: "Optional for set rpc. Uses the built-in provider table for eth_getLogs request rate and block range cap.",
+    option: "--provider",
+    optional: true,
+  },
+  logRequestsPerSecond: {
+    label: "Log Requests Per Second",
+    type: "text",
+    placeholder: "7.497",
+    valueLabel: "<N>",
+    hint: "Optional for set rpc. Required with --block-range-cap when --provider is not used.",
+    option: "--log-requests-per-second",
+    optional: true,
+  },
+  blockRangeCap: {
+    label: "Block Range Cap",
+    type: "text",
+    placeholder: "10",
+    valueLabel: "<N>",
+    hint: "Optional for set rpc. Required with --log-requests-per-second when --provider is not used.",
+    option: "--block-range-cap",
     optional: true,
   },
   account: {
@@ -162,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",
@@ -213,7 +246,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.",
 });
@@ -221,10 +254,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",
@@ -236,6 +271,18 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     fields: [],
     usage: "no options",
   },
+  {
+    id: "set-rpc",
+    display: "set rpc",
+    description: "Configure the network RPC URL and fixed eth_getLogs scan limits.",
+    fields: ["network", "rpcUrl", "provider", "logRequestsPerSecond", "blockRangeCap"],
+    usage: "--network, --rpc-url, and either --provider or both --log-requests-per-second and --block-range-cap",
+    help: [
+      "Writes ~/tokamak-private-channels/workspace/<network>/rpc-config.env",
+      "Built-in provider limits: ankr=27 calls/s and 3000 blocks, chainstack=22.5 calls/s and 100 blocks, chainnodes=22.5 calls/s and 20000 blocks, quicknode=13.5 calls/s and 5 blocks, alchemy=7.497 calls/s and 10 blocks",
+      "All bridge-facing and wallet commands read RPC settings from this file and do not accept --rpc-url",
+    ],
+  },
   {
     id: "help-commands",
     display: "help commands",
@@ -257,11 +304,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",
     ],
   },
@@ -278,8 +326,8 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     id: "help-transaction-fees",
     display: "help transaction-fees",
     description: "Estimate ETH and USD fees for transaction-sending commands from packaged measured gas data and live network fee data.",
-    fields: ["network", "rpcUrl", "json"],
-    usage: "--network, optional --rpc-url, and optional --json",
+    fields: ["network", "json"],
+    usage: "--network and optional --json",
     help: [
       "Uses packages/apps/private-state/cli/assets/tx-fees.json as the measured gas source packaged with the CLI",
       "Reads live fee data from the selected network RPC and live ETH/USD from CoinGecko",
@@ -314,15 +362,17 @@ 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.",
-    fields: ["network", "account", "rpcUrl"],
-    usage: "--network, --account, and optional --rpc-url",
+    installMode: "read-only",
+    fields: ["network", "account"],
+    usage: "--network, --account",
   },
   {
     id: "channel-create",
     display: "channel create",
     description: "Create a bridge channel and initialize its workspace.",
-    fields: ["channelName", "joinToll", "network", "account", "rpcUrl"],
-    usage: "--channel-name, --join-toll, --network, --account, and optional --rpc-url",
+    installMode: "full",
+    fields: ["channelName", "joinToll", "network", "account"],
+    usage: "--channel-name, --join-toll, --network, --account",
     help: [
       "Prints the immutable policy snapshot before sending the transaction",
       "Initializes the local channel workspace by replaying channel logs from channel genesis",
@@ -332,8 +382,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", "rpcUrl"],
-    usage: "--channel-name, --network, optional --source, optional --from-genesis, and optional --rpc-url",
+    installMode: "read-only",
+    fields: ["channelName", "network", "source", "fromGenesis"],
+    usage: "--channel-name, --network, optional --source, optional --from-genesis",
     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",
@@ -349,8 +400,9 @@ 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.",
-    fields: ["channelName", "network", "account", "url", "rpcUrl"],
-    usage: "--channel-name, --network, --account, --url, and optional --rpc-url",
+    installMode: "full",
+    fields: ["channelName", "network", "account", "url"],
+    usage: "--channel-name, --network, --account, --url",
     help: [
       "Only the on-chain channel leader can update the registered mirror URL",
       "The URL points to a server implementing the private-state channel workspace mirror protocol",
@@ -360,8 +412,9 @@ 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.",
-    fields: ["channelName", "network", "account", "output", "force", "rpcUrl"],
-    usage: "--channel-name, --network, --account, --output, optional --force, and optional --rpc-url",
+    installMode: "read-only",
+    fields: ["channelName", "network", "account", "output", "force"],
+    usage: "--channel-name, --network, --account, --output, optional --force",
     help: [
       "Requires the local channel workspace to be current and ahead of the registered mirror checkpoint",
       "--force ignores an unreadable or invalid existing mirror manifest and publishes a full checkpoint without a delta",
@@ -373,19 +426,21 @@ 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.",
-    fields: ["channelName", "network", "rpcUrl"],
-    usage: "--channel-name, --network, and optional --rpc-url",
+    installMode: "read-only",
+    fields: ["channelName", "network"],
+    usage: "--channel-name, --network",
   },
   {
     id: "account-deposit-bridge",
     display: "account deposit-bridge",
     description: "Deposit canonical tokens into the shared bridge vault.",
-    fields: ["amount", "network", "account", "acknowledgeActionImpact", "rpcUrl"],
-    usage: "--amount, --network, --account, --acknowledge-action-impact, and optional --rpc-url",
+    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,
     ],
@@ -394,12 +449,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.",
-    fields: ["amount", "network", "account", "acknowledgeActionImpact", "rpcUrl"],
-    usage: "--amount, --network, --account, --acknowledge-action-impact, and optional --rpc-url",
+    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,
     ],
@@ -408,8 +464,9 @@ 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.",
-    fields: ["channelName", "network", "account", "fromGenesis", "rpcUrl"],
-    usage: "--channel-name, --network, --account, optional --from-genesis, and optional --rpc-url",
+    installMode: "read-only",
+    fields: ["channelName", "network", "account", "fromGenesis"],
+    usage: "--channel-name, --network, --account, optional --from-genesis",
     help: [
       "Rebuilds backup metadata from channel state without recreating the spending key",
       "Derives and stores the viewing key when the local account signer can reproduce the registered viewing public key",
@@ -424,8 +481,9 @@ 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.",
-    fields: ["channelName", "network", "account", "walletSecretPath", "acknowledgeActionImpact", "rpcUrl"],
-    usage: "--channel-name, --network, --account, --wallet-secret-path, --acknowledge-action-impact, and optional --rpc-url",
+    installMode: "full",
+    fields: ["channelName", "network", "account", "walletSecretPath", "acknowledgeActionImpact"],
+    usage: "--channel-name, --network, --account, --wallet-secret-path, --acknowledge-action-impact",
     help: [
       "Refreshes the local channel workspace through the saved recovery index before joining when the scan fits the 10 second pre-command budget",
       "Fails instead of replaying from genesis; run channel recover-workspace --source rpc --from-genesis when a genesis rebuild is required",
@@ -443,6 +501,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: [
@@ -512,6 +571,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: [
@@ -528,6 +588,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: [
@@ -545,6 +606,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"],
@@ -553,6 +615,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: [
@@ -564,10 +627,12 @@ 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: [
       "Refreshes the local channel workspace through the saved recovery index before proving the mint when the scan fits the 10 second pre-command budget",
+      "Requires both viewing and spending key capability so the accepted mint can be recovered through the normal note event path",
       "Use --tx-submitter <ACCOUNT> to let a separate local L1 account pay gas for stronger transaction privacy",
       "Action impact: emits public accepted-transition, commitment, encrypted note-delivery, root update, and transaction events.",
       "Private note state changes by creating local note plaintext and public commitments; note owner/value/salt are not public by default.",
@@ -582,6 +647,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: [
@@ -600,6 +666,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: [
@@ -618,6 +685,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: [
@@ -630,6 +698,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;
 }