@tokamak-private-dapps/private-state-cli 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 ## Unreleased
 
+## 1.0.2 - 2026-05-06
+
+- Added `update`, which checks npm registry for the latest private-state CLI package and updates
+  global npm installs when a newer version exists.
+- Kept repository checkouts and non-global installs read-only during `update`; those modes print
+  the exact `npm install -g @tokamak-private-dapps/private-state-cli@latest` command instead.
+- Reused runtime-management output parsing helpers for `update` and `uninstall` instead of
+  duplicating npm JSON and ANSI-output handling in the CLI entrypoint.
+- Added `transaction-fees`, which reads packaged measured gas data from `assets/tx-fees.json`,
+  combines it with live RPC fee data and live ETH/USD pricing, and prints a per-command ETH/USD
+  fee table.
+- Split `transaction-fees` estimates into typical cost from RPC `gasPrice` and worst-case cost
+  from EIP-1559 `maxFeePerGas`.
+- Added optional `--tx-submitter <ACCOUNT>` support to `mint-notes`, `transfer-notes`, and
+  `redeem-notes` so proof-backed note owners can separate note ownership from the L1 account
+  that submits `executeChannelTransaction` and pays gas.
+- Expanded LLM-agent README guidance so agents explain private key files, local account aliases,
+  wallet secret source files, network RPC URLs, and immutable channel policy step by step before
+  guiding new users through `join-channel`.
+- Added RPC log scan progress output to `recover-workspace` and `recover-wallet`, with progress
+  routed to stderr in `--json` mode so machine-readable command results stay valid.
+- Added `recover-wallet --from-genesis` and removed implicit genesis replay fallback from
+  `recover-workspace` and `recover-wallet`; both commands now require a usable recovery index
+  unless the user explicitly requests `--from-genesis`.
+- Changed `get-my-wallet-meta`, `get-my-channel-fund`, and `get-my-notes` to use indexed
+  recovery only before reading channel state, with `get-my-notes` also validating the wallet
+  note-receive recovery index before scanning delivery logs.
+- Unified wallet command workspace refresh through the same recovery-indexed path used by
+  `recover-workspace`, and shared received-note recovery through the wallet's
+  `noteReceiveLastScannedBlock` index.
+
+## 1.0.1 - 2026-05-05
+
+- Added global `--version` output for scripts that need the installed private-state CLI package
+  version without running `doctor`.
 - Changed the channel-bound L2 identity derivation signing domain and mode from password wording
   to wallet-secret wording. Existing local wallets from the pre-1.0.0 cleanup path are not
   compatibility targets.

package/README.md

@@ -51,6 +51,22 @@ Check the installed package and runtime state with:
 private-state-cli doctor
 ```
 
+Print only the installed CLI package version with:
+
+```bash
+private-state-cli --version
+```
+
+Check npm registry for a newer CLI package and update a global npm install when possible:
+
+```bash
+private-state-cli update
+```
+
+`update` keeps `--version` suitable for scripts by using a separate command for registry checks. If the CLI is running
+from a repository checkout or npm does not report a global install, it does not edit local source files; it prints the
+recommended `npm install -g @tokamak-private-dapps/private-state-cli@latest` command instead.
+
 Remove all local private-state CLI data with:
 
 ```bash
@@ -80,6 +96,46 @@ A common private-state flow is:
 
 Use `private-state-cli --help` for the full command list and required options.
 
+Workspace recovery commands use the saved recovery index by default. If the local workspace is missing, corrupted, or
+does not contain a usable index, `recover-workspace` and `recover-wallet` stop with an explicit error instead of
+silently replaying logs from channel genesis. Use `--from-genesis` only when you intentionally want to rebuild from the
+channel creation block:
+
+```bash
+private-state-cli recover-workspace --channel-name <CHANNEL> --network mainnet --from-genesis
+private-state-cli recover-wallet --channel-name <CHANNEL> --network mainnet --account <ACCOUNT> --from-genesis
+```
+
+`create-channel` 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.
+
+Wallet getter commands that need channel state, including `get-my-wallet-meta`, `get-my-channel-fund`, and
+`get-my-notes`, follow the same indexed recovery rule before reading local or on-chain state. `get-my-notes` also uses
+the wallet's saved note-receive scan index for encrypted note delivery logs. If either index is unusable, the command
+stops and asks the user to run the appropriate recovery command with `--from-genesis`.
+
+Estimate live transaction costs before sending commands with:
+
+```bash
+private-state-cli transaction-fees --network mainnet --rpc-url <RPC_URL>
+```
+
+`transaction-fees` uses the measured gas data packaged in `assets/tx-fees.json`, the selected network's live fee data,
+and live ETH/USD pricing to print an ETH/USD fee table for transaction-sending commands. The table separates typical
+cost, based on the RPC `gasPrice`, from worst-case cost, based on `maxFeePerGas` when the network reports EIP-1559 fee
+data.
+
+Proof-backed note commands can use a separate L1 transaction submitter:
+
+```bash
+private-state-cli mint-notes --wallet <WALLET> --network mainnet --amounts '[1]' --tx-submitter <ACCOUNT>
+```
+
+`--tx-submitter <ACCOUNT>` is available on `mint-notes`, `transfer-notes`, and `redeem-notes`. The wallet still proves
+note ownership and builds the ZK proof, but the selected local account submits `executeChannelTransaction` and pays gas.
+Use this option when you want stronger privacy by avoiding a direct on-chain link between the note owner's wallet L1
+account and the proof-submission transaction.
+
 Channel policy warning:
 
 - `create-channel` commits to an immutable channel policy: verifier bindings, DApp execution metadata, function layout,
@@ -162,6 +218,43 @@ Operating rules:
 
 - Do not ask the user to reveal raw private keys or wallet secrets in chat. Use `account import --private-key-file`
   once, then use `--account` for L1 signing commands. Wallet commands use wallet-local default secret files.
+- Treat `private key file`, `account`, `wallet secret`, `wallet`, `network RPC URL`, and `channel policy` as
+  new concepts unless the user has already demonstrated that they understand them. Define each term before using it
+  in an instruction.
+- Explain local-secret handling in plain language:
+  - A private key file is a local file that contains the user's L1 wallet private key. The CLI reads it once during
+    `account import` and stores a protected local account secret.
+  - An account is the local nickname created by `account import`. After import, signing commands should use
+    `--account <NAME>` instead of asking for the raw key again.
+  - A wallet secret source file is a separate high-entropy local secret chosen by the user for this private-state
+    wallet. It is not the L1 private key. `join-channel` imports it once and uses it to protect and recover the
+    channel-local wallet.
+  - A wallet is the encrypted local private-state wallet created during `join-channel`. Its deterministic name is
+    `<channelName>-<l1Address>`.
+  - 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.
+  - 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.
+- 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.
+- When a user wants to join a channel, do not jump straight to `join-channel`. Walk them through:
+  1. choose the network and channel name
+  2. run `private-state-cli install`
+  3. run `private-state-cli 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 `get-channel` if it already exists, or create it with `create-channel` if the user is
+     the channel creator
+  9. explain the immutable policy warning printed by the CLI
+  10. run `join-channel --channel-name <CHANNEL> --network <NETWORK> --account <ACCOUNT> --wallet-secret-path <PATH>`
+- Before asking the user to create a file, explain what will be inside that file, who should be able to read it, and
+  whether losing it prevents wallet recovery.
 - Prefer testnet examples unless the user explicitly asks for mainnet.
 - Before any proof-backed or bridge-facing workflow, ask the user to run `private-state-cli doctor` and inspect
   whether the runtime, Docker mode, CUDA/GPU probes, Groth16 runtime, and deployment artifacts are healthy.
@@ -175,6 +268,9 @@ Operating rules:
   telling the user to move funds.
 - Explain that wallet names are local CLI identifiers, while private transfers use notes owned by L2 addresses
   registered in the channel.
+- Explain `--tx-submitter <ACCOUNT>` when the user wants stronger privacy for `mint-notes`, `transfer-notes`, or
+  `redeem-notes`: the wallet owner still proves note ownership, but another imported local L1 account can submit the
+  on-chain `executeChannelTransaction` and pay gas.
 - Before guiding a user through `create-channel` or `join-channel`, explain that channel policy is immutable after
   creation and that joining a channel means accepting its current verifier, DApp metadata, function layout, managed
   storage vector, and refund policy.
@@ -198,6 +294,14 @@ Suggested interaction flow:
    `get-my-wallet-meta`, then build `transfer-notes`.
 8. After transfer, guide the recipient to run `get-my-notes` to recover received notes from event logs.
 
+Example onboarding explanation for `join-channel`:
+
+> First we need two different local secrets. Your L1 private key proves which Ethereum account pays gas and signs
+> bridge transactions. We import it once into a local account nickname, so later commands can say `--account alice`
+> instead of handling the raw key again. Separately, the wallet secret protects the encrypted private-state wallet for
+> this channel. It is not sent on-chain and it is not the same as your L1 private key. If you lose the wallet secret,
+> recovering this channel wallet can become impossible.
+
 Example style: if the user says, "ADDR6 sends 10 tokens privately to ADDR8", do not assume the required note exists.
 First ask or check which channel and network to use, whether ADDR6 and ADDR8 are already joined, what the local wallet
 names are, and whether ADDR6 has an unused note worth exactly 10 or notes that sum to 10. Then provide the next concrete

package/assets/tx-fees.json

@@ -0,0 +1,170 @@
+{
+  "schema": "tokamak-private-state-cli-tx-fees.v1",
+  "measuredAt": "2026-05-05",
+  "measurementBasis": "Measured directly from the current repository worktree with forge test --root bridge --gas-report and completed local CLI e2e transaction receipts.",
+  "notes": [
+    "Gas values are protocol transaction gasUsed values, not a guarantee for every future calldata shape or verifier implementation.",
+    "ERC-20 approval transactions are listed as separate approve components when the CLI command sends an approval transaction.",
+    "transfer-notes and redeem-notes use the same proof-backed executeChannelTransaction baseline measured from the successful mint-notes CLI e2e receipt because the current e2e run stopped before producing fresh transfer/redeem receipts."
+  ],
+  "commands": [
+    {
+      "command": "create-channel",
+      "description": "Create a bridge channel and initialize its policy snapshot.",
+      "transactions": [
+        {
+          "label": "createChannel",
+          "contract": "BridgeCore",
+          "function": "createChannel",
+          "gasUsed": 2736229,
+          "source": "forge-gas-report",
+          "sourceDetail": "BridgeCore.createChannel max successful path from forge test --root bridge --gas-report."
+        }
+      ]
+    },
+    {
+      "command": "deposit-bridge",
+      "description": "Deposit canonical tokens into the shared bridge vault.",
+      "transactions": [
+        {
+          "label": "approve",
+          "contract": "MockERC20",
+          "function": "approve",
+          "gasUsed": 45729,
+          "source": "cast-local-measurement",
+          "sourceDetail": "Measured on local anvil by deploying bridge/src/mocks/MockERC20.sol and sending approve(address,uint256)."
+        },
+        {
+          "label": "fund",
+          "contract": "L1TokenVault",
+          "function": "fund",
+          "gasUsed": 68343,
+          "source": "forge-gas-report",
+          "sourceDetail": "L1TokenVault.fund from forge test --root bridge --gas-report."
+        }
+      ]
+    },
+    {
+      "command": "withdraw-bridge",
+      "description": "Withdraw canonical tokens from the shared bridge vault.",
+      "transactions": [
+        {
+          "label": "claimToWallet",
+          "contract": "L1TokenVault",
+          "function": "claimToWallet",
+          "gasUsed": 33824,
+          "source": "forge-gas-report",
+          "sourceDetail": "L1TokenVault.claimToWallet from forge test --root bridge --gas-report."
+        }
+      ]
+    },
+    {
+      "command": "join-channel",
+      "description": "Pay the channel join toll and register a wallet identity.",
+      "transactions": [
+        {
+          "label": "approve",
+          "contract": "MockERC20",
+          "function": "approve",
+          "gasUsed": 45729,
+          "source": "cast-local-measurement",
+          "sourceDetail": "Measured on local anvil by deploying bridge/src/mocks/MockERC20.sol and sending approve(address,uint256). join-channel sends this approval only when the channel join toll is nonzero."
+        },
+        {
+          "label": "joinChannel",
+          "contract": "L1TokenVault",
+          "function": "joinChannel",
+          "gasUsed": 341775,
+          "source": "forge-gas-report",
+          "sourceDetail": "L1TokenVault.joinChannel max successful path from forge test --root bridge --gas-report."
+        }
+      ]
+    },
+    {
+      "command": "deposit-channel",
+      "description": "Move bridged funds into the channel L2 accounting vault.",
+      "transactions": [
+        {
+          "label": "depositToChannelVault",
+          "contract": "L1TokenVault",
+          "function": "depositToChannelVault",
+          "gasUsed": 336496,
+          "gasUsedMin": 336464,
+          "gasUsedMax": 336496,
+          "source": "cli-e2e-receipts",
+          "sourceDetail": "Three completed local CLI e2e deposit-channel receipts from the current worktree."
+        }
+      ]
+    },
+    {
+      "command": "withdraw-channel",
+      "description": "Move channel L2 accounting vault funds back into the shared bridge vault.",
+      "transactions": [
+        {
+          "label": "withdrawFromChannelVault",
+          "contract": "L1TokenVault",
+          "function": "withdrawFromChannelVault",
+          "gasUsed": 95861,
+          "source": "forge-gas-report",
+          "sourceDetail": "L1TokenVault.withdrawFromChannelVault max successful path from forge test --root bridge --gas-report."
+        }
+      ]
+    },
+    {
+      "command": "exit-channel",
+      "description": "Exit a channel after the channel balance is zero.",
+      "transactions": [
+        {
+          "label": "exitChannel",
+          "contract": "L1TokenVault",
+          "function": "exitChannel",
+          "gasUsed": 119031,
+          "source": "forge-gas-report",
+          "sourceDetail": "L1TokenVault.exitChannel max successful path from forge test --root bridge --gas-report."
+        }
+      ]
+    },
+    {
+      "command": "mint-notes",
+      "description": "Submit a proof-backed private-state mint transaction.",
+      "transactions": [
+        {
+          "label": "executeChannelTransaction",
+          "contract": "ChannelManager",
+          "function": "executeChannelTransaction",
+          "gasUsed": 861627,
+          "source": "cli-e2e-receipt",
+          "sourceDetail": "Completed local CLI e2e mint-notes bridge-submit-receipt.json from the current worktree."
+        }
+      ]
+    },
+    {
+      "command": "transfer-notes",
+      "description": "Submit a proof-backed private-state transfer transaction.",
+      "transactions": [
+        {
+          "label": "executeChannelTransaction",
+          "contract": "ChannelManager",
+          "function": "executeChannelTransaction",
+          "gasUsed": 861627,
+          "source": "cli-e2e-baseline",
+          "sourceDetail": "Uses the current successful mint-notes executeChannelTransaction receipt as the shared proof-backed DApp command baseline."
+        }
+      ]
+    },
+    {
+      "command": "redeem-notes",
+      "description": "Submit a proof-backed private-state redeem transaction.",
+      "transactions": [
+        {
+          "label": "executeChannelTransaction",
+          "contract": "ChannelManager",
+          "function": "executeChannelTransaction",
+          "gasUsed": 861627,
+          "source": "cli-e2e-baseline",
+          "sourceDetail": "Uses the current successful mint-notes executeChannelTransaction receipt as the shared proof-backed DApp command baseline."
+        }
+      ]
+    }
+  ]
+}

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

@@ -29,6 +29,15 @@ export const PRIVATE_STATE_CLI_FIELD_CATALOG = Object.freeze({
     valueLabel: "<NAME>",
     option: "--account",
   },
+  txSubmitter: {
+    label: "Transaction Submitter",
+    type: "text",
+    placeholder: "relayer-account",
+    valueLabel: "<ACCOUNT>",
+    hint: "Optional for proof-backed note commands. Uses a separate local L1 account to submit executeChannelTransaction.",
+    option: "--tx-submitter",
+    optional: true,
+  },
   privateKeyFile: {
     label: "Private Key File",
     type: "text",
@@ -158,6 +167,16 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     fields: [],
     usage: "no options",
   },
+  {
+    id: "update",
+    description: "Check npm registry for the latest private-state CLI package and update global installs when possible.",
+    fields: ["json"],
+    usage: "optional --json",
+    help: [
+      "Global npm installs are updated with npm install -g when a newer registry version exists",
+      "Repository checkouts and non-global installs print the required update command instead of modifying source files",
+    ],
+  },
   {
     id: "doctor",
     description: "Check private-state CLI package versions, runtime install state, Docker mode, CUDA mode, and deployment artifacts.",
@@ -176,6 +195,16 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     usage: "optional --network, --channel-name, --account, and --wallet",
     help: ["Does not accept --rpc-url and never writes RPC configuration"],
   },
+  {
+    id: "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",
+    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",
+    ],
+  },
   {
     id: "account-import",
     display: "account import",
@@ -188,7 +217,10 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     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",
-    help: ["Prints the immutable policy snapshot before sending the transaction"],
+    help: [
+      "Prints the immutable policy snapshot before sending the transaction",
+      "Initializes the local channel workspace by replaying channel logs from channel genesis",
+    ],
   },
   {
     id: "recover-workspace",
@@ -197,7 +229,9 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     usage: "--channel-name, --network, optional --from-genesis, and optional --rpc-url",
     help: [
       "By default, resumes RPC log scanning from the workspace recovery index when available",
+      "Fails instead of falling back to genesis when no usable recovery index exists",
       "Use --from-genesis to ignore the recovery index and replay logs from channel genesis",
+      "Prints RPC log scan progress while rebuilding the workspace",
     ],
   },
   {
@@ -227,11 +261,15 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
   {
     id: "recover-wallet",
     description: "Rebuild a recoverable local wallet from on-chain channel state.",
-    fields: ["channelName", "network", "account", "rpcUrl"],
-    usage: "--channel-name, --network, --account, and optional --rpc-url",
+    fields: ["channelName", "network", "account", "fromGenesis", "rpcUrl"],
+    usage: "--channel-name, --network, --account, optional --from-genesis, and optional --rpc-url",
     help: [
       "Requires the protected wallet-local secret imported during join-channel to exist at the canonical secret path",
       "Does not create or recover the wallet secret itself",
+      "By default, resumes RPC log scanning from the workspace recovery index when available",
+      "Fails instead of falling back to genesis when no usable recovery index exists",
+      "Use --from-genesis to ignore the recovery index and replay channel logs from channel genesis",
+      "Prints RPC log scan progress while rebuilding channel state and received-note state",
     ],
   },
   {
@@ -249,6 +287,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     description: "Check whether a wallet matches the on-chain channel registration.",
     fields: ["wallet", "network"],
     usage: "--wallet and --network",
+    help: ["Refreshes channel state through the workspace recovery index before reading registration metadata"],
   },
   {
     id: "get-my-l1-address",
@@ -280,6 +319,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     description: "Read the current channel L2 accounting balance.",
     fields: ["wallet", "network"],
     usage: "--wallet and --network",
+    help: ["Refreshes channel state through the workspace recovery index before reading the L2 accounting balance"],
   },
   {
     id: "exit-channel",
@@ -290,26 +330,33 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
   {
     id: "mint-notes",
     description: "Mint one or two private-state notes from the wallet's channel balance.",
-    fields: ["wallet", "network", "amounts"],
-    usage: "--wallet, --network, and --amounts",
+    fields: ["wallet", "network", "amounts", "txSubmitter"],
+    usage: "--wallet, --network, --amounts, and optional --tx-submitter",
+    help: ["Use --tx-submitter <ACCOUNT> to let a separate local L1 account pay gas for stronger transaction privacy"],
   },
   {
     id: "transfer-notes",
     description: "Spend input notes into the registered 1->1, 1->2, or 2->1 private transfer shapes.",
-    fields: ["wallet", "network", "noteIds", "recipients", "amounts"],
-    usage: "--wallet, --network, --note-ids, --recipients, and --amounts",
+    fields: ["wallet", "network", "noteIds", "recipients", "amounts", "txSubmitter"],
+    usage: "--wallet, --network, --note-ids, --recipients, --amounts, and optional --tx-submitter",
+    help: ["Use --tx-submitter <ACCOUNT> to let a separate local L1 account pay gas for stronger transaction privacy"],
   },
   {
     id: "redeem-notes",
     description: "Redeem one tracked note back into the wallet's channel balance.",
-    fields: ["wallet", "network", "noteIds"],
-    usage: "--wallet, --network, and --note-ids",
+    fields: ["wallet", "network", "noteIds", "txSubmitter"],
+    usage: "--wallet, --network, --note-ids, and optional --tx-submitter",
+    help: ["Use --tx-submitter <ACCOUNT> to let a separate local L1 account pay gas for stronger transaction privacy"],
   },
   {
     id: "get-my-notes",
     description: "Show the wallet's tracked note state and refresh received notes.",
     fields: ["wallet", "network"],
     usage: "--wallet and --network",
+    help: [
+      "Refreshes channel state through the workspace recovery index before reading notes",
+      "Refreshes received-note logs through the wallet note recovery index",
+    ],
   },
 ]);
 

package/lib/private-state-runtime-management.mjs

@@ -1300,9 +1300,11 @@ export {
   installGroth16RuntimeForPrivateState,
   installPrivateStateCliArtifacts,
   writePrivateStateCliInstallManifest,
+  parseJsonReport,
   resolveArtifactCacheBaseRoot,
   privateStateCliArtifactPaths,
   inspectGroth16Runtime,
+  stripAnsi,
   resolveActiveGroth16ProverRuntime,
   resolveActiveTokamakCliInvocation,
   readTokamakCliPackageReport,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamak-private-dapps/private-state-cli",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Command-line client for the Tokamak private-state DApp.",
   "license": "MIT OR Apache-2.0",
   "author": "Tokamak Network",
@@ -30,6 +30,7 @@
     "LICENSE",
     "private-state-bridge-cli.mjs",
     "cli-assistant.html",
+    "assets",
     "lib"
   ],
   "scripts": {