@tokamak-private-dapps/private-state-cli 0.1.9 → 1.0.1

package/CHANGELOG.md

@@ -1,5 +1,106 @@
 # Changelog
 
+## Unreleased
+
+- 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.
+- 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.
+- Centralized CLI command option schemas used by validation, while keeping the existing command
+  implementations in the single CLI entrypoint.
+- Moved private-state Tokamak L2 snapshot, storage, and leaf-index helpers into a shared CLI library
+  reused by the CLI and registration materialization scripts.
+- Moved runtime install, artifact install, and doctor report helpers out of the CLI entrypoint.
+- Reused the same command registry for CLI help text and the browser command assistant so command
+  additions no longer require three separate hardcoded updates.
+- Made live Docker/NVIDIA GPU probing in `doctor` opt-in through `doctor --gpu`; the default doctor
+  run now reports runtime metadata without launching GPU containers.
+- Shared private-state registration fixture builders between DApp registration materialization and
+  the CLI end-to-end scenario.
+- Moved note receive key derivation and note value encryption/decryption into a CLI library helper
+  reused by the CLI, DApp registration materializer, and CLI end-to-end scenario.
+- Removed the CLI end-to-end runner's trailing-JSON fallback now that CLI progress logs are kept off
+  stdout in `--json` mode.
+- Required public-network private-state DApp deployment scripts to receive an explicit `--rpc-url`
+  instead of deriving deployment RPC endpoints from environment-only Alchemy settings.
+- Replaced local wallet recovery hint string matching with typed CLI error codes for local RPC,
+  wallet, artifact, registration, and stale-workspace failures.
+- Removed unused replay/synthetic snapshot helpers from the CLI end-to-end script.
+- Added deterministic anvil account and wallet secret cleanup to the CLI end-to-end runner so
+  repeated local runs do not fail on stale canonical secret files.
+- Stopped parsing the `install --include-local-artifacts` end-to-end step as JSON because runtime
+  package installation legitimately writes installer logs to stdout.
+- Reused a shared artifact selection helper for Drive and local private-state artifact installs.
+- Removed stale `--install` and `--doctor` compatibility aliases after the command syntax was
+  standardized around positional command names.
+- Tightened local wallet loading to require the current wallet format instead of silently filling
+  legacy defaults.
+- Renamed stale internal wallet-secret terminology consistently around wallet secrets and moved the
+  canonical wallet secret path from `password` to `secret`.
+- Reused private-state CLI shared helpers in the CLI end-to-end test instead of duplicating channel
+  ID, wallet path, and L2 identity derivation logic.
+- Fixed the browser CLI assistant's `create-channel` builder to include required `--join-toll`.
+- Preserved the resolved network name in CLI runtime contexts so account-backed commands and
+  wallet-backed commands can pass the correct network selector into downstream recovery helpers.
+- Routed Groth16 prover package root, entrypoint, and proof-manifest path resolution through
+  runtime management instead of leaving the CLI entrypoint to call internal runtime helper names.
+- Routed Tokamak CLI invocation resolution through runtime management instead of calling internal
+  runtime helper names from the CLI entrypoint.
+- Kept Groth16 prover stdout quiet during `--json` proof-backed commands so machine-readable output
+  remains valid JSON.
+- Verified the full private-state CLI end-to-end flow through channel exit and bridge withdrawal
+  after the runtime-management refactor.
+
+## 1.0.0 - 2026-05-04
+
+- Stabilized the private-state CLI command contract for the first mainnet-ready release.
+- Removed routine raw `--private-key` and `--password` command arguments.
+- Added named local L1 account management through `account import --private-key-file`, with later
+  signing commands using `--account`.
+- Moved wallet commands to wallet-local canonical secret files instead of explicit password input.
+- Added the wallet secret source-file flow for `join-channel --wallet-secret-path <PATH>`.
+- Removed `join-channel --random-wallet-secret`; channel joins now always require
+  `--wallet-secret-path <PATH>`.
+- Relaxed imported source secret file permission checks while keeping canonical CLI secrets
+  protected with POSIX `0600` or Windows ACL repair and inspection.
+- Added per-network RPC URL persistence under the private-state workspace, with `--rpc-url` as
+  the optional bridge-facing override.
+- Renamed private-state CLI commands `--install` and `--doctor` to `install` and `doctor` so
+  commands consistently omit a leading `--`.
+- Replaced the old zk-EVM-only uninstall command with interactive `uninstall`, which removes local
+  private-state data, Tokamak zk-EVM runtime data, and the global CLI package when installed.
+- Added `guide` as the state-aware workflow assistant command.
+- Added `get-channel` for channel policy, toll, refund schedule, and immutable policy snapshot
+  inspection.
+- Added CLI-wide `--json`; commands print human-readable output by default and structured output
+  when requested.
+- Made `doctor` human-readable by default while preserving full machine-readable diagnostics through
+  `doctor --json`.
+- Added durable progress phases for proof-backed commands: `loading`, `proving`, `submitting`,
+  `persisting`, and `done`.
+- Added centralized recovery hints for common RPC, artifact, account, wallet, channel selector,
+  registration, and local-state errors.
+
 ## 0.1.9 - 2026-05-03
 
 - Used the bundled Groth16 package version as the default `private-state-cli --install` Groth16 runtime version.

package/README.md

@@ -16,15 +16,15 @@ Install the local Tokamak zk-EVM runtime workspace, Groth16 runtime workspace, a
 artifacts:
 
 ```bash
-private-state-cli --install
+private-state-cli install
 ```
 
-By default, `--install` resolves the latest `@tokamak-zk-evm/cli` from the npm registry and uses the bundled
+By default, `install` resolves the latest `@tokamak-zk-evm/cli` from the npm registry and uses the bundled
 `@tokamak-private-dapps/groth16` dependency version selected by the installed private-state CLI package. To pin exact
 proof backend versions for a channel, pass explicit versions:
 
 ```bash
-private-state-cli --install --tokamak-zk-evm-cli-version 2.1.0 --groth16-cli-version 0.2.0
+private-state-cli install --tokamak-zk-evm-cli-version 2.1.0 --groth16-cli-version 0.2.0
 ```
 
 The Groth16 installer downloads the public Google Drive CRS archive whose major.minor compatibility version matches the
@@ -32,11 +32,11 @@ 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.
 
-`--install` downloads public deployment artifacts from the configured artifact index. It does not read repository-local
+`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:
 
 ```bash
-private-state-cli --install --include-local-artifacts
+private-state-cli install --include-local-artifacts
 ```
 
 Run the CLI with:
@@ -48,9 +48,26 @@ private-state-cli <command> ...
 Check the installed package and runtime state with:
 
 ```bash
-private-state-cli --doctor
+private-state-cli doctor
 ```
 
+Print only the installed CLI package version with:
+
+```bash
+private-state-cli --version
+```
+
+Remove all local private-state CLI data with:
+
+```bash
+private-state-cli uninstall
+```
+
+`uninstall` is intentionally interactive. It requires typing
+`I understand that the wallet secrets deleted due to this decision cannot be recovered` before deleting
+`~/tokamak-private-channels/`, the Tokamak zk-EVM runtime cache, and the global CLI npm package when npm reports that it
+is globally installed.
+
 ## Commands
 
 A common private-state flow is:
@@ -64,10 +81,33 @@ A common private-state flow is:
 7. `get-my-notes`
 8. `redeem-notes`
 9. `withdraw-channel`
-10. `withdraw-bridge`
+10. `exit-channel`
+11. `withdraw-bridge`
 
 Use `private-state-cli --help` for the full command list and required options.
 
+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,
@@ -81,23 +121,44 @@ Channel policy warning:
   backend version is unexpected or has not been reviewed, do not create or join the channel. A later correction creates
   a new channel; it does not rewrite the policy of an already-created channel.
 
-`private-state-cli --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
+`private-state-cli 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.
 
 Local helper commands:
 
 ```bash
+private-state-cli account import --account <ACCOUNT_NAME> --network sepolia --private-key-file <PATH>
 private-state-cli list-local-wallets --network sepolia --channel-name cuda
-private-state-cli get-my-wallet-meta --wallet <WALLET_NAME> --password <PASSWORD> --network sepolia
-private-state-cli get-my-l1-address --private-key <HEX>
+private-state-cli get-my-wallet-meta --wallet <WALLET_NAME> --network sepolia
+private-state-cli get-my-l1-address --account <ACCOUNT_NAME> --network sepolia
 ```
 
-`list-local-wallets` reads only the local workspace and prints saved wallet names that can be reused with `--wallet`.
+`account import` is the only supported way to bring an L1 signing key into the CLI: it reads `--private-key-file` once
+and stores a protected local account secret for later `--account` use. The source file does not need `0600` permissions.
+`join-channel` imports `--wallet-secret-path <PATH>` into the protected wallet-local default secret while creating the
+encrypted local wallet. `list-local-wallets` reads only the local workspace and prints saved wallet names that can be reused with
+`--wallet`.
 `get-my-wallet-meta` opens an encrypted local wallet and reports the stored L1/L2 identity metadata plus the current
 on-chain channel registration match state. `get-my-l1-address` is a simple offline helper that derives the L1 address
-for a private key.
+for a local account.
+
+### Wallet Secret Source File
+
+`join-channel` needs a wallet secret source file because the CLI no longer accepts raw wallet secrets on the command
+line. The source file is arbitrary high-entropy secret text that the CLI reads once and imports into the protected
+wallet-local canonical secret.
+
+Create one before joining a channel:
+
+```bash
+openssl rand -hex 32 > ./wallet-secret.txt
+private-state-cli join-channel --channel-name <CHANNEL> --network sepolia --account <ACCOUNT> --wallet-secret-path ./wallet-secret.txt
+```
+
+The import source file does not need `0600` permissions. The canonical wallet-local secret written by the CLI remains
+protected: macOS/Linux uses `0600`, while Windows uses ACL repair and inspection when possible.
 
 ## Workspace
 
@@ -107,7 +168,14 @@ The CLI stores user workspaces under:
 ~/tokamak-private-channels/workspace/<network>/<channel>/
 ```
 
-Wallet data is encrypted with the password supplied to `join-channel` or `recover-wallet`.
+Wallet data is encrypted with the wallet-local default secret file under
+`~/tokamak-private-channels/secrets/<network>/wallets/<wallet>/secret`.
+
+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.
 
 ## LLM Agent Guidance
 
@@ -120,21 +188,58 @@ explaining each step only as much as needed to proceed safely.
 
 Operating rules:
 
-- Do not ask the user to reveal raw private keys in chat. Use environment variable placeholders such as `$ADDR6`,
-  `$CREATOR`, or `$PRIVATE_STATE_TEST_PK`.
+- 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.
+- 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
+- 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.
 - Use `private-state-cli list-local-wallets` to discover local wallet names instead of asking the user to inspect
   filesystem paths manually.
-- Use `private-state-cli get-my-l1-address --private-key "$KEY_ENV"` to derive the L1 address for a private-key
-  environment variable when wallet ownership needs to be identified.
-- Use `private-state-cli get-my-wallet-meta --wallet <WALLET> --password <PASSWORD> --network <NETWORK>` to inspect
+- Use `private-state-cli get-my-l1-address --account <ACCOUNT> --network <NETWORK>` to derive the L1 address for a
+  local account when wallet ownership needs to be identified.
+- Use `private-state-cli get-my-wallet-meta --wallet <WALLET> --network <NETWORK>` to inspect
   local wallet metadata and on-chain channel registration state.
 - Use `private-state-cli get-my-bridge-fund` and `private-state-cli get-my-channel-fund` to check balances before
   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.
@@ -149,8 +254,8 @@ Suggested interaction flow:
 
 1. Identify the target network, usually `sepolia` for testing.
 2. Identify whether a channel already exists.
-3. Identify the sender and recipient wallets or private-key environment variables.
-4. Run `--doctor`.
+3. Identify the sender and recipient wallets or local account names.
+4. Run `doctor`.
 5. Run `list-local-wallets` and relevant metadata or balance checks.
 6. If needed, guide the user through `create-channel`, `deposit-bridge`, `join-channel`, `deposit-channel`, and
    `mint-notes`.
@@ -158,6 +263,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
@@ -165,7 +278,7 @@ command.
 
 ## Artifacts
 
-Proof-backed commands require installed bridge, DApp, and Groth16 artifacts. Run `private-state-cli --install` before
+Proof-backed commands require installed bridge, DApp, and Groth16 artifacts. Run `private-state-cli install` before
 using bridge-facing commands on a new machine.
 
 Channel balance commands such as `deposit-channel` and `withdraw-channel` use the installed Groth16 runtime workspace
@@ -182,10 +295,10 @@ Release order matters for npm publication. `@tokamak-private-dapps/common-librar
 ### What does this package install?
 
 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`
+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.
 
-### When should I run `private-state-cli --install`?
+### 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.
 

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."
+        }
+      ]
+    }
+  ]
+}