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

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## 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.

package/README.md

@@ -51,6 +51,12 @@ 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
+```
+
 Remove all local private-state CLI data with:
 
 ```bash
@@ -80,6 +86,28 @@ A common private-state flow is:
 
 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,
@@ -162,6 +190,40 @@ 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.
+- 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 +237,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 +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

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",
@@ -176,6 +185,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",
@@ -198,6 +217,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     help: [
       "By default, resumes RPC log scanning from the workspace recovery index when available",
       "Use --from-genesis to ignore the recovery index and replay logs from channel genesis",
+      "Prints RPC log scan progress while rebuilding the workspace",
     ],
   },
   {
@@ -232,6 +252,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     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",
+      "Prints RPC log scan progress while rebuilding channel state and received-note state",
     ],
   },
   {
@@ -290,20 +311,23 @@ 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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamak-private-dapps/private-state-cli",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "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": {

package/private-state-bridge-cli.mjs

@@ -120,6 +120,7 @@ import {
 
 const require = createRequire(import.meta.url);
 const defaultCommandCwd = process.cwd();
+const privateStateCliPackageJson = require("./package.json");
 const privateStateCliPackageRoot = path.dirname(require.resolve("./package.json"));
 const workspaceRoot = path.resolve(os.homedir(), "tokamak-private-channels", "workspace");
 const secretRoot = path.resolve(os.homedir(), "tokamak-private-channels", "secrets");
@@ -314,6 +315,12 @@ async function main() {
   activeCliArgs = args;
   configureOutput(args);
 
+  if (args.version !== undefined) {
+    assertVersionArgs(args);
+    printVersion();
+    return;
+  }
+
   if (args.help || !args.command) {
     printHelp();
     return;
@@ -343,6 +350,13 @@ async function main() {
     return;
   }
 
+  if (args.command === "transaction-fees") {
+    assertTransactionFeesArgs(args);
+    const { network, provider, rpcUrl } = loadExplicitCommandRuntime(args);
+    await handleTransactionFees({ network, provider, rpcUrl });
+    return;
+  }
+
   if (args.command === "get-my-l1-address") {
     assertGetMyL1AddressArgs(args);
     handleGetMyL1Address({ args });
@@ -622,6 +636,7 @@ async function handleWorkspaceInit({ args, network, provider }) {
     allowExistingWorkspaceSync: true,
     useWorkspaceRecoveryIndex: true,
     fromGenesis: args.fromGenesis === true,
+    progressAction: "recover-workspace",
   });
 
   printJson({
@@ -729,6 +744,7 @@ async function initializeChannelWorkspace({
   allowExistingWorkspaceSync = false,
   useWorkspaceRecoveryIndex = false,
   fromGenesis = false,
+  progressAction = null,
 }) {
   const workspaceDir = channelWorkspacePath(networkNameFromChainId(network.chainId), workspaceName);
   const channelDir = channelDataPath(workspaceDir);
@@ -831,6 +847,7 @@ async function initializeChannelWorkspace({
       baseSnapshot: recoveryIndex?.stateSnapshot ?? null,
       fromBlock: recoveryIndex?.nextBlock ?? genesisBlockNumber,
       toBlock: latestBlock,
+      progressAction,
     });
   const currentSnapshot = reconstruction.currentSnapshot;
   const recoveryRootVectorHash = normalizeBytes32Hex(hashRootVector(currentSnapshot.stateRoots));
@@ -975,6 +992,8 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
     bridgeResources,
     persist: true,
     allowExistingWorkspaceSync: true,
+    useWorkspaceRecoveryIndex: true,
+    progressAction: "recover-wallet",
   });
   const context = {
     workspaceName: channelName,
@@ -1056,6 +1075,14 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
   });
 
   if (existingWallet) {
+    const { recoveredDeliveryState } = await recoverWalletReceivedNotes({
+      walletContext: existingWallet,
+      context,
+      provider,
+      signer,
+      noteReceiveKeyMaterial,
+      progressAction: "recover-wallet",
+    });
     printJson({
       action: "recover-wallet",
       status: "already-recovered",
@@ -1071,6 +1098,10 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
       l2StorageKey: storageKey,
       leafIndex: registration.leafIndex.toString(),
       noteReceivePubKey: noteReceiveKeyMaterial.noteReceivePubKey,
+      l2Nonce: existingWallet.wallet.l2Nonce,
+      recoveredFromLogs: recoveredDeliveryState.importedNotes,
+      scannedDeliveryLogs: recoveredDeliveryState.scannedLogs,
+      noteReceiveScanRange: recoveredDeliveryState.scanRange,
     });
     return;
   }
@@ -1091,11 +1122,13 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
   walletContext.wallet.l2Nonce = 0;
   persistWallet(walletContext);
 
-  const recoveredDeliveryState = await recoverDeliveredNotesFromEventLogs({
+  const { recoveredDeliveryState } = await recoverWalletReceivedNotes({
     walletContext,
     context,
     provider,
-    noteReceivePrivateKey: noteReceiveKeyMaterial.privateKey,
+    signer,
+    noteReceiveKeyMaterial,
+    progressAction: "recover-wallet",
   });
 
   printJson({
@@ -1437,6 +1470,144 @@ async function handleDoctor({ args }) {
   }
 }
 
+async function handleTransactionFees({ network, provider, rpcUrl }) {
+  const feeAsset = loadTransactionFeeAsset();
+  const feeData = await provider.getFeeData();
+  const gasPrices = requireTransactionFeeGasPrices(feeData);
+  const ethUsd = await fetchEthUsdPrice();
+  const rows = buildTransactionFeeRows({
+    commands: feeAsset.commands,
+    typicalGasPriceWei: gasPrices.typical,
+    worstCaseGasPriceWei: gasPrices.worstCase,
+    ethUsd,
+  });
+
+  printJson({
+    action: "transaction-fees",
+    generatedAt: new Date().toISOString(),
+    network: network.name,
+    chainId: Number(network.chainId),
+    rpcUrl,
+    asset: {
+      schema: feeAsset.schema,
+      measuredAt: feeAsset.measuredAt,
+      measurementBasis: feeAsset.measurementBasis,
+      notes: feeAsset.notes,
+    },
+    livePricing: {
+      typicalGasPriceWei: gasPrices.typical.toString(),
+      typicalGasPriceGwei: formatGwei(gasPrices.typical),
+      typicalGasPriceSource: gasPrices.typicalSource,
+      worstCaseGasPriceWei: gasPrices.worstCase.toString(),
+      worstCaseGasPriceGwei: formatGwei(gasPrices.worstCase),
+      worstCaseGasPriceSource: gasPrices.worstCaseSource,
+      maxFeePerGasWei: feeData.maxFeePerGas?.toString() ?? null,
+      maxPriorityFeePerGasWei: feeData.maxPriorityFeePerGas?.toString() ?? null,
+      gasPriceWei: feeData.gasPrice?.toString() ?? null,
+      ethUsd,
+      ethUsdSource: "CoinGecko simple price API",
+    },
+    rows,
+  });
+}
+
+function loadTransactionFeeAsset() {
+  const assetPath = path.join(privateStateCliPackageRoot, "assets", "tx-fees.json");
+  const asset = readJson(assetPath);
+  expect(asset.schema === "tokamak-private-state-cli-tx-fees.v1", `Unsupported transaction fee asset schema: ${assetPath}`);
+  expect(Array.isArray(asset.commands), `Transaction fee asset is missing commands: ${assetPath}`);
+  return asset;
+}
+
+function requireTransactionFeeGasPrices(feeData) {
+  const typical = feeData.gasPrice ?? feeData.maxFeePerGas;
+  const worstCase = feeData.maxFeePerGas ?? feeData.gasPrice;
+  if (typical === null || typical === undefined || worstCase === null || worstCase === undefined) {
+    throw new Error("RPC provider did not return gasPrice or maxFeePerGas.");
+  }
+  return {
+    typical: ethers.toBigInt(typical),
+    typicalSource: feeData.gasPrice ? "gasPrice" : "maxFeePerGas",
+    worstCase: ethers.toBigInt(worstCase),
+    worstCaseSource: feeData.maxFeePerGas ? "maxFeePerGas" : "gasPrice",
+  };
+}
+
+async function fetchEthUsdPrice() {
+  const url = "https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd";
+  const response = await fetch(url, {
+    headers: {
+      accept: "application/json",
+      "user-agent": `${privateStateCliPackageJson.name}/${privateStateCliPackageJson.version}`,
+    },
+  });
+  if (!response.ok) {
+    throw new Error(`Unable to fetch live ETH/USD price from CoinGecko: HTTP ${response.status}.`);
+  }
+  const payload = await response.json();
+  const value = Number(payload?.ethereum?.usd);
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error("CoinGecko response did not include a valid ethereum.usd price.");
+  }
+  return value;
+}
+
+function buildTransactionFeeRows({ commands, typicalGasPriceWei, worstCaseGasPriceWei, ethUsd }) {
+  return commands.map((entry) => {
+    const transactions = expectTransactionFeeTransactions(entry);
+    const gasUsed = transactions.reduce((sum, transaction) => sum + Number(transaction.gasUsed), 0);
+    const typicalEth = ethers.formatEther(BigInt(gasUsed) * typicalGasPriceWei);
+    const worstCaseEth = ethers.formatEther(BigInt(gasUsed) * worstCaseGasPriceWei);
+    return {
+      command: entry.command,
+      description: entry.description,
+      transactions: transactions.map((transaction) => transaction.label).join(" + "),
+      gasUsed,
+      typicalGasPriceGwei: formatGwei(typicalGasPriceWei),
+      typicalEth: formatEthForDisplay(typicalEth),
+      typicalUsd: formatUsdForDisplay(Number(typicalEth) * ethUsd),
+      worstCaseGasPriceGwei: formatGwei(worstCaseGasPriceWei),
+      worstCaseEth: formatEthForDisplay(worstCaseEth),
+      worstCaseUsd: formatUsdForDisplay(Number(worstCaseEth) * ethUsd),
+      sources: [...new Set(transactions.map((transaction) => transaction.source))].join(", "),
+      sourceDetails: transactions.map((transaction) => transaction.sourceDetail),
+    };
+  });
+}
+
+function expectTransactionFeeTransactions(entry) {
+  expect(typeof entry?.command === "string" && entry.command.length > 0, "Transaction fee asset contains a command without command name.");
+  expect(Array.isArray(entry.transactions) && entry.transactions.length > 0, `Transaction fee asset command ${entry.command} has no transactions.`);
+  for (const transaction of entry.transactions) {
+    expect(Number.isInteger(transaction.gasUsed) && transaction.gasUsed > 0, `Transaction fee asset command ${entry.command} has invalid gasUsed.`);
+  }
+  return entry.transactions;
+}
+
+function formatGwei(wei) {
+  return trimFixedNumber(ethers.formatUnits(wei, "gwei"), 6);
+}
+
+function formatEthForDisplay(value) {
+  return trimFixedNumber(value, 8);
+}
+
+function formatUsdForDisplay(value) {
+  if (value > 0 && value < 0.01) {
+    return "<0.01";
+  }
+  return value.toFixed(2);
+}
+
+function trimFixedNumber(value, maxDecimals) {
+  const [integer, decimals = ""] = String(value).split(".");
+  if (!decimals || maxDecimals <= 0) {
+    return integer;
+  }
+  const trimmed = decimals.slice(0, maxDecimals).replace(/0+$/u, "");
+  return trimmed ? `${integer}.${trimmed}` : integer;
+}
+
 function handleGetMyL1Address({ args }) {
   const signer = requireL1Signer(args);
   printJson({
@@ -1513,6 +1684,7 @@ async function handleGuide({ args }) {
     nextSafeAction: null,
     why: null,
     candidateCommands: [],
+    privacyTip: "For mint-notes, transfer-notes, and redeem-notes, add --tx-submitter <ACCOUNT> to let a separate local L1 account submit executeChannelTransaction and pay gas.",
   };
 
   guide.state.local = inspectGuideLocalState(args);
@@ -2006,18 +2178,18 @@ function applyGuideNextAction(guide) {
   }
   if (guide.state.wallet?.exists && channelBalance !== null && channelBalance > 0n && unusedNotes === 0) {
     setGuideNextAction(guide, {
-      command: `mint-notes --wallet ${guide.selectors.wallet} --network ${guide.selectors.network} --amounts <A,B>`,
-      why: "The wallet has channel L2 balance and no unused private notes yet.",
+      command: `mint-notes --wallet ${guide.selectors.wallet} --network ${guide.selectors.network} --amounts <A,B> [--tx-submitter <ACCOUNT>]`,
+      why: "The wallet has channel L2 balance and no unused private notes yet. Use --tx-submitter for stronger transaction-submission privacy.",
     });
     return;
   }
   if (guide.state.wallet?.exists && unusedNotes !== null && unusedNotes > 0) {
     setGuideNextAction(guide, {
-      command: `transfer-notes --wallet ${guide.selectors.wallet} --network ${guide.selectors.network} --note-ids <ID,ID> --recipients <ADDR,ADDR> --amounts <A,B>`,
-      why: "The wallet has unused private notes. It can transfer or redeem those notes.",
+      command: `transfer-notes --wallet ${guide.selectors.wallet} --network ${guide.selectors.network} --note-ids <ID,ID> --recipients <ADDR,ADDR> --amounts <A,B> [--tx-submitter <ACCOUNT>]`,
+      why: "The wallet has unused private notes. It can transfer or redeem those notes. Use --tx-submitter for stronger transaction-submission privacy.",
       candidates: [
         `get-my-notes --wallet ${guide.selectors.wallet} --network ${guide.selectors.network}`,
-        `redeem-notes --wallet ${guide.selectors.wallet} --network ${guide.selectors.network} --note-ids <ID>`,
+        `redeem-notes --wallet ${guide.selectors.wallet} --network ${guide.selectors.network} --note-ids <ID> [--tx-submitter <ACCOUNT>]`,
       ],
     });
     return;
@@ -2128,9 +2300,13 @@ async function handleGetMyWalletMeta({ args, provider }) {
   });
 }
 
-async function loadWalletChannelFundState({ walletContext, provider }) {
+async function loadWalletChannelFundState({ walletContext, provider, progressAction = null }) {
   const { signer, l2Identity } = restoreWalletParticipant(walletContext, provider);
-  const contextResult = await loadPreferredWalletChannelContext({ walletContext, provider });
+  const contextResult = await loadPreferredWalletChannelContext({
+    walletContext,
+    provider,
+    progressAction,
+  });
   const context = contextResult.context;
   const registration = await context.channelManager.getChannelTokenVaultRegistration(signer.address);
   expect(
@@ -2357,7 +2533,11 @@ async function handleGrothVaultMove({ args, provider, direction }) {
       : "withdraw";
   emitProgress(operationName, "loading");
   const { wallet: walletContext } = loadUnlockedWalletWithMetadata(args);
-  const contextResult = await loadPreferredWalletChannelContext({ walletContext, provider });
+  const contextResult = await loadPreferredWalletChannelContext({
+    walletContext,
+    provider,
+    progressAction: operationName,
+  });
   const context = contextResult.context;
   const network = contextResult.network;
   expect(
@@ -2403,6 +2583,7 @@ async function handleGrothVaultMove({ args, provider, direction }) {
     "The derived L2 address does not match the registered channel L2 address.",
   );
 
+  await assertWorkspaceAlignedWithChain(context);
   const stateManager = await buildStateManager(context.currentSnapshot, context.contractCodes);
   const keyHex = storageKey;
   const currentValue = await currentStorageBigInt(stateManager, context.workspace.l2AccountingVault, keyHex);
@@ -2578,6 +2759,7 @@ async function handleMintNotes({ args, provider }) {
   const { channelFund } = await loadWalletChannelFundState({
     walletContext: wallet,
     provider,
+    progressAction: "mint-notes",
   });
   expect(
     totalMintAmount <= channelFund,
@@ -2591,6 +2773,7 @@ async function handleMintNotes({ args, provider }) {
     baseUnitAmounts: baseUnitAmounts.map(({ amountBaseUnits }) => amountBaseUnits),
   });
   const { execution, contextResult, recoveredWorkspace } = await executeWalletDirectTemplateCommand({
+    args,
     wallet,
     provider,
     operationName: "mint-notes",
@@ -2602,7 +2785,10 @@ async function handleMintNotes({ args, provider }) {
     wallet: wallet.walletName,
     workspace: execution.context.workspaceName,
     operationDir: execution.operationDir,
-    l1Submitter: execution.signer.address,
+    l1Submitter: execution.txSubmitter.address,
+    l1WalletOwner: execution.signer.address,
+    txSubmitterSource: execution.txSubmitterSource,
+    txSubmitterAccount: execution.txSubmitterAccount,
     l2Address: execution.l2Identity.l2Address,
     underlyingMethod: templatePayload.method,
     nonce: execution.nonce,
@@ -2631,6 +2817,7 @@ async function handleRedeemNotes({ args, provider }) {
     inputNotes,
   });
   const { execution, contextResult, recoveredWorkspace } = await executeWalletDirectTemplateCommand({
+    args,
     wallet,
     provider,
     operationName: "redeem-notes",
@@ -2642,7 +2829,10 @@ async function handleRedeemNotes({ args, provider }) {
     wallet: wallet.walletName,
     workspace: execution.context.workspaceName,
     operationDir: execution.operationDir,
-    l1Submitter: execution.signer.address,
+    l1Submitter: execution.txSubmitter.address,
+    l1WalletOwner: execution.signer.address,
+    txSubmitterSource: execution.txSubmitterSource,
+    txSubmitterAccount: execution.txSubmitterAccount,
     l2Address: execution.l2Identity.l2Address,
     receiver: wallet.wallet.l2Address,
     underlyingMethod: templatePayload.method,
@@ -2669,20 +2859,18 @@ async function handleGetMyNotes({ args, provider }) {
     `Wallet ${wallet.walletName} is missing the stored controller address.`,
   );
   const canonicalAssetDecimals = Number(wallet.wallet.canonicalAssetDecimals);
-  const { context } = await loadPreferredWalletChannelContext({ walletContext: wallet, provider });
-  const signer = restoreWalletSigner(wallet, provider);
-  const noteReceiveKeyMaterial = await deriveNoteReceiveKeyMaterial({
-    signer,
-    chainId: context.workspace.chainId,
-    channelId: context.workspace.channelId,
-    channelName: context.workspace.channelName,
-    account: signer.address,
+  const { context } = await loadPreferredWalletChannelContext({
+    walletContext: wallet,
+    provider,
+    progressAction: "get-my-notes",
   });
-  const recoveredDeliveryState = await recoverDeliveredNotesFromEventLogs({
+  const signer = restoreWalletSigner(wallet, provider);
+  const { recoveredDeliveryState } = await recoverWalletReceivedNotes({
     walletContext: wallet,
     context,
     provider,
-    noteReceivePrivateKey: noteReceiveKeyMaterial.privateKey,
+    signer,
+    progressAction: "get-my-notes",
   });
 
   const unusedTrackedNotes = wallet.wallet.notes.unusedOrder
@@ -2728,7 +2916,11 @@ async function handleGetMyNotes({ args, provider }) {
 async function handleTransferNotes({ args, provider }) {
   const { wallet } = loadUnlockedWalletWithMetadata(args);
   const { signer } = restoreWalletParticipant(wallet, provider);
-  const preparedContextResult = await loadPreferredWalletChannelContext({ walletContext: wallet, provider });
+  const preparedContextResult = await loadPreferredWalletChannelContext({
+    walletContext: wallet,
+    provider,
+    progressAction: "transfer-notes",
+  });
   const context = preparedContextResult.context;
   const canonicalAssetDecimals = Number(wallet.wallet.canonicalAssetDecimals);
   const noteIds = parseNoteIdVector(requireArg(args.noteIds, "--note-ids"));
@@ -2760,6 +2952,7 @@ async function handleTransferNotes({ args, provider }) {
     outputAmounts,
   });
   const { execution, contextResult, recoveredWorkspace } = await executeWalletDirectTemplateCommand({
+    args,
     wallet,
     provider,
     operationName: "transfer-notes",
@@ -2777,7 +2970,10 @@ async function handleTransferNotes({ args, provider }) {
     wallet: wallet.walletName,
     workspace: execution.context.workspaceName,
     operationDir: execution.operationDir,
-    l1Submitter: execution.signer.address,
+    l1Submitter: execution.txSubmitter.address,
+    l1WalletOwner: execution.signer.address,
+    txSubmitterSource: execution.txSubmitterSource,
+    txSubmitterAccount: execution.txSubmitterAccount,
     l2Address: execution.l2Identity.l2Address,
     underlyingMethod: templatePayload.method,
     nonce: execution.nonce,
@@ -3092,11 +3288,40 @@ function buildLifecycleTrackedOutputs({
   }));
 }
 
+async function recoverWalletReceivedNotes({
+  walletContext,
+  context,
+  provider,
+  signer,
+  noteReceiveKeyMaterial = null,
+  progressAction = null,
+}) {
+  const resolvedNoteReceiveKeyMaterial = noteReceiveKeyMaterial ?? await deriveNoteReceiveKeyMaterial({
+    signer,
+    chainId: context.workspace.chainId,
+    channelId: context.workspace.channelId,
+    channelName: context.workspace.channelName,
+    account: signer.address,
+  });
+  const recoveredDeliveryState = await recoverDeliveredNotesFromEventLogs({
+    walletContext,
+    context,
+    provider,
+    noteReceivePrivateKey: resolvedNoteReceiveKeyMaterial.privateKey,
+    progressAction,
+  });
+  return {
+    noteReceiveKeyMaterial: resolvedNoteReceiveKeyMaterial,
+    recoveredDeliveryState,
+  };
+}
+
 async function recoverDeliveredNotesFromEventLogs({
   walletContext,
   context,
   provider,
   noteReceivePrivateKey,
+  progressAction = null,
 }) {
   const scanStartBlock = Math.max(
     Number(walletContext.wallet.noteReceiveLastScannedBlock),
@@ -3128,6 +3353,9 @@ async function recoverDeliveredNotesFromEventLogs({
     topics: [NOTE_VALUE_ENCRYPTED_TOPIC],
     fromBlock: scanStartBlock,
     toBlock: latestBlock,
+    onProgress: progressAction
+      ? createRpcLogScanProgress({ action: progressAction, label: "note-delivery events" })
+      : null,
   });
 
   const importedCandidates = [];
@@ -3666,10 +3894,15 @@ function walletChannelWorkspaceIsReady(walletContext) {
     && fs.existsSync(path.join(channelWorkspaceCurrentPath(workspaceDir), "contract_codes.json"));
 }
 
-async function loadPreferredWalletChannelContext({ walletContext, provider, forceRecover = false }) {
+async function loadPreferredWalletChannelContext({
+  walletContext,
+  provider,
+  forceRecover = false,
+  progressAction = null,
+}) {
   let recoveredWorkspace = false;
   if (forceRecover || !walletChannelWorkspaceIsReady(walletContext)) {
-    await recoverWalletChannelWorkspace({ walletContext, provider });
+    await recoverWalletChannelWorkspace({ walletContext, provider, progressAction });
     recoveredWorkspace = true;
   }
   let context = await loadWorkspaceContext(walletContext.wallet.channelName, walletContext.wallet.network, provider);
@@ -3679,7 +3912,7 @@ async function loadPreferredWalletChannelContext({ walletContext, provider, forc
     if (!isRecoverableWalletWorkspaceFailure(error)) {
       throw error;
     }
-    await recoverWalletChannelWorkspace({ walletContext, provider });
+    await recoverWalletChannelWorkspace({ walletContext, provider, progressAction });
     recoveredWorkspace = true;
     context = await loadWorkspaceContext(walletContext.wallet.channelName, walletContext.wallet.network, provider);
     await assertWorkspaceAlignedWithChain(context);
@@ -3692,7 +3925,7 @@ async function loadPreferredWalletChannelContext({ walletContext, provider, forc
   };
 }
 
-async function recoverWalletChannelWorkspace({ walletContext, provider }) {
+async function recoverWalletChannelWorkspace({ walletContext, provider, progressAction = null }) {
   const networkName = walletContext.wallet.network ?? networkNameFromChainId(Number(walletContext.wallet.chainId));
   const network = resolveCliNetwork(networkName);
   const bridgeResources = loadBridgeResources({ chainId: network.chainId });
@@ -3704,6 +3937,8 @@ async function recoverWalletChannelWorkspace({ walletContext, provider }) {
     bridgeResources,
     persist: true,
     allowExistingWorkspaceSync: true,
+    useWorkspaceRecoveryIndex: true,
+    progressAction,
   });
 }
 
@@ -3725,6 +3960,7 @@ function assertWalletMatchesChannelContext(walletContext, l2Identity, context) {
 }
 
 async function executeWalletDirectTemplateCommand({
+  args,
   wallet,
   provider,
   operationName,
@@ -3732,13 +3968,29 @@ async function executeWalletDirectTemplateCommand({
 }) {
   emitProgress(operationName, "loading");
   const { signer, l2Identity } = restoreWalletParticipant(wallet, provider);
-  let contextResult = await loadPreferredWalletChannelContext({ walletContext: wallet, provider });
+  const {
+    txSubmitter,
+    source: txSubmitterSource,
+    account: txSubmitterAccount,
+  } = resolveTxSubmitterSigner({
+    args,
+    ownerSigner: signer,
+    provider,
+  });
+  let contextResult = await loadPreferredWalletChannelContext({
+    walletContext: wallet,
+    provider,
+    progressAction: operationName,
+  });
   let recoveredWorkspace = contextResult.recoveredWorkspace;
 
   try {
     const execution = await executeWalletTemplateSend({
       wallet,
       signer,
+      txSubmitter,
+      txSubmitterSource,
+      txSubmitterAccount,
       l2Identity,
       context: contextResult.context,
       operationName,
@@ -3761,11 +4013,15 @@ async function executeWalletDirectTemplateCommand({
     walletContext: wallet,
     provider,
     forceRecover: true,
+    progressAction: operationName,
   });
   recoveredWorkspace = contextResult.recoveredWorkspace;
   const execution = await executeWalletTemplateSend({
     wallet,
     signer,
+    txSubmitter,
+    txSubmitterSource,
+    txSubmitterAccount,
     l2Identity,
     context: contextResult.context,
     operationName,
@@ -3783,6 +4039,9 @@ async function executeWalletDirectTemplateCommand({
 async function executeWalletTemplateSend({
   wallet,
   signer,
+  txSubmitter,
+  txSubmitterSource,
+  txSubmitterAccount,
   l2Identity,
   context,
   operationName,
@@ -3860,7 +4119,7 @@ async function executeWalletTemplateSend({
   emitProgress(operationName, "submitting");
   const receipt =
     await waitForReceipt(
-      await context.channelManager.connect(signer).executeChannelTransaction(payload, functionProof),
+      await context.channelManager.connect(txSubmitter).executeChannelTransaction(payload, functionProof),
     );
 
   const onchainRootVectorHash = normalizeBytes32Hex(await context.channelManager.currentRootVectorHash());
@@ -3884,6 +4143,9 @@ async function executeWalletTemplateSend({
   return {
     wallet,
     signer,
+    txSubmitter,
+    txSubmitterSource,
+    txSubmitterAccount,
     l2Identity,
     context,
     noteLifecycle,
@@ -4732,6 +4994,7 @@ async function reconstructChannelSnapshot({
   baseSnapshot = null,
   fromBlock = genesisBlockNumber,
   toBlock = null,
+  progressAction = null,
 }) {
   let startingSnapshot = baseSnapshot;
   if (!startingSnapshot) {
@@ -4763,6 +5026,9 @@ async function reconstructChannelSnapshot({
     ]],
     fromBlock: scanFromBlock,
     toBlock: latestBlock,
+    onProgress: progressAction
+      ? createRpcLogScanProgress({ action: progressAction, label: "channel-manager events" })
+      : null,
   });
   const channelManagerEvents = channelManagerLogs.map((log) => {
     const topic0 = log.topics[0] ? normalizeBytes32Hex(log.topics[0]) : null;
@@ -4781,6 +5047,9 @@ async function reconstructChannelSnapshot({
     eventName: "StorageWriteObserved",
     fromBlock: scanFromBlock,
     toBlock: latestBlock,
+    onProgress: progressAction
+      ? createRpcLogScanProgress({ action: progressAction, label: "bridge-vault events" })
+      : null,
   });
 
   const groupedEvents = new Map();
@@ -4900,15 +5169,34 @@ async function fetchLogsChunked(provider, {
   fromBlock,
   toBlock,
   initialChunkSize = DEFAULT_LOG_CHUNK_SIZE,
+  onProgress = null,
 }) {
   const normalizedFromBlock = Number(fromBlock);
   const resolvedToBlock = toBlock === "latest" ? await provider.getBlockNumber() : Number(toBlock);
   const aggregatedLogs = [];
 
   if (normalizedFromBlock > resolvedToBlock) {
+    onProgress?.({
+      status: "skipped",
+      fromBlock: normalizedFromBlock,
+      toBlock: resolvedToBlock,
+      scannedBlocks: 0,
+      totalBlocks: 0,
+      logsFound: 0,
+    });
     return aggregatedLogs;
   }
 
+  const totalBlocks = resolvedToBlock - normalizedFromBlock + 1;
+  onProgress?.({
+    status: "start",
+    fromBlock: normalizedFromBlock,
+    toBlock: resolvedToBlock,
+    scannedBlocks: 0,
+    totalBlocks,
+    logsFound: 0,
+  });
+
   let chunkSize = Math.max(1, Number(initialChunkSize));
   let cursor = normalizedFromBlock;
   while (cursor <= resolvedToBlock) {
@@ -4922,6 +5210,17 @@ async function fetchLogsChunked(provider, {
         toBlock: chunkToBlock,
       });
       aggregatedLogs.push(...logs);
+      onProgress?.({
+        status: "progress",
+        fromBlock: normalizedFromBlock,
+        toBlock: resolvedToBlock,
+        chunkFromBlock: cursor,
+        chunkToBlock,
+        scannedBlocks: chunkToBlock - normalizedFromBlock + 1,
+        totalBlocks,
+        logsFound: aggregatedLogs.length,
+        chunkLogs: logs.length,
+      });
       cursor = chunkToBlock + 1;
     } catch (error) {
       if (isRateLimitError(error)) {
@@ -4938,6 +5237,15 @@ async function fetchLogsChunked(provider, {
     }
   }
 
+  onProgress?.({
+    status: "done",
+    fromBlock: normalizedFromBlock,
+    toBlock: resolvedToBlock,
+    scannedBlocks: totalBlocks,
+    totalBlocks,
+    logsFound: aggregatedLogs.length,
+  });
+
   return aggregatedLogs;
 }
 
@@ -4995,6 +5303,7 @@ async function queryContractEventsChunked({
   eventName,
   fromBlock,
   toBlock,
+  onProgress = null,
 }) {
   const eventFragment = contract.interface.getEvent(eventName);
   const eventTopic = contract.interface.getEvent(eventName).topicHash;
@@ -5006,6 +5315,7 @@ async function queryContractEventsChunked({
     topics: [eventTopic],
     fromBlock,
     toBlock,
+    onProgress,
   });
 
   return logs.map((log) => {
@@ -5278,6 +5588,33 @@ function requireArg(value, label) {
   return value;
 }
 
+function assertVersionArgs(args) {
+  if (args.version !== true) {
+    throw new Error("--version does not accept a value.");
+  }
+  if (args.command) {
+    throw new Error("--version must be used without a command.");
+  }
+  const allowedKeys = new Set(["version", "json"]);
+  const unknownKeys = Object.keys(args)
+    .filter((key) => key !== "positional" && key !== "command" && !allowedKeys.has(key));
+  if (unknownKeys.length > 0) {
+    throw new Error(`Unsupported --version option(s): ${unknownKeys.map(toKebabCase).join(", ")}.`);
+  }
+}
+
+function printVersion() {
+  if (isJsonOutputRequested()) {
+    printJson({
+      action: "version",
+      packageName: privateStateCliPackageJson.name,
+      version: privateStateCliPackageJson.version,
+    });
+    return;
+  }
+  console.log(privateStateCliPackageJson.version);
+}
+
 function requireWorkspaceName(args) {
   const value = typeof args === "string" ? args : args.workspace;
   if (!value) {
@@ -5306,6 +5643,29 @@ function requireL1Signer(args, provider) {
   return new Wallet(resolvePrivateKeySource(args), provider);
 }
 
+function resolveTxSubmitterSigner({ args, ownerSigner, provider }) {
+  if (args.txSubmitter === undefined) {
+    return {
+      txSubmitter: ownerSigner,
+      source: "wallet-owner",
+      account: null,
+    };
+  }
+  if (args.txSubmitter === true || String(args.txSubmitter).trim() === "") {
+    throw new Error("--tx-submitter requires a local account name.");
+  }
+  const networkName = requireNetworkName(args);
+  const account = String(args.txSubmitter).trim();
+  return {
+    txSubmitter: new Wallet(
+      normalizePrivateKey(readSecretFile(accountPrivateKeyPath(networkName, account), "--tx-submitter")),
+      provider,
+    ),
+    source: "tx-submitter-account",
+    account,
+  };
+}
+
 function resolvePrivateKeySource(args) {
   const networkName = requireNetworkName(args);
   const account = requireAccountName(args);
@@ -5616,12 +5976,17 @@ function assertGuideArgs(args) {
   assertAllowedCommandSchema(args, "guide");
 }
 
+function assertTransactionFeesArgs(args) {
+  assertAllowedCommandSchema(args, "transaction-fees");
+}
+
 function assertAccountImportArgs(args) {
   assertAllowedCommandSchema(args, "account-import");
 }
 
 function assertMintNotesArgs(args) {
   assertAllowedCommandSchema(args, "mint-notes");
+  assertTxSubmitterArg(args);
   parseAmountVector(args.amounts, {
     allowZeroEntries: true,
     requireAnyPositive: true,
@@ -5630,11 +5995,13 @@ function assertMintNotesArgs(args) {
 
 function assertRedeemNotesArgs(args) {
   assertAllowedCommandSchema(args, "redeem-notes");
+  assertTxSubmitterArg(args);
   selectRedeemNotesMethod(parseNoteIdVector(args.noteIds).length);
 }
 
 function assertTransferNotesArgs(args) {
   assertAllowedCommandSchema(args, "transfer-notes");
+  assertTxSubmitterArg(args);
   const noteIds = parseNoteIdVector(args.noteIds);
   const recipients = parseRecipientVector(args.recipients);
   const amounts = parseAmountVector(args.amounts);
@@ -5645,6 +6012,15 @@ function assertTransferNotesArgs(args) {
   selectTransferNotesMethod(noteIds.length, recipients.length);
 }
 
+function assertTxSubmitterArg(args) {
+  if (args.txSubmitter === undefined) {
+    return;
+  }
+  if (args.txSubmitter === true || String(args.txSubmitter).trim() === "") {
+    throw new Error("--tx-submitter requires a local account name.");
+  }
+}
+
 function assertGetMyNotesArgs(args) {
   assertWalletSecretArgs(args, "get-my-notes");
 }
@@ -5769,6 +6145,9 @@ Secret source options:
   canonical CLI secret files remain protected. On macOS/Linux this means 0600; on Windows the CLI repairs ACLs when possible.
 
 Options:
+  --version
+      Print the private-state CLI package version and exit.
+
   --json
       Print the command result as JSON. Without --json, commands print human-readable output.
 
@@ -6197,6 +6576,7 @@ function loadWalletCommandRuntime(args) {
 
 const HUMAN_RESULT_RENDERERS = Object.freeze({
   guide: printGuideHumanResult,
+  "transaction-fees": printTransactionFeesHumanResult,
 });
 
 function normalizePrivateKey(value) {
@@ -6246,9 +6626,61 @@ function printGuideHumanResult(guide) {
   }
 
   lines.push("", "Run with --json to inspect the full guide state.");
+  lines.push(
+    "",
+    "Privacy Tip",
+    formatHumanValue(guide.privacyTip),
+  );
   console.log(lines.join("\n"));
 }
 
+function printTransactionFeesHumanResult(report) {
+  const lines = [
+    "Transaction Fees",
+    `Generated: ${formatHumanValue(report.generatedAt)}`,
+    `Network: ${formatHumanValue(report.network)} (${formatHumanValue(report.chainId)})`,
+    `Typical gas price: ${formatHumanValue(report.livePricing?.typicalGasPriceGwei)} gwei (${formatHumanValue(report.livePricing?.typicalGasPriceSource)})`,
+    `Worst-case gas price: ${formatHumanValue(report.livePricing?.worstCaseGasPriceGwei)} gwei (${formatHumanValue(report.livePricing?.worstCaseGasPriceSource)})`,
+    `ETH/USD: $${formatHumanValue(report.livePricing?.ethUsd)} (${formatHumanValue(report.livePricing?.ethUsdSource)})`,
+    `Measured gas asset: ${formatHumanValue(report.asset?.schema)}, measured ${formatHumanValue(report.asset?.measuredAt)}`,
+    "",
+    formatHumanTable(
+      ["Command", "Transactions", "Gas", "Typical ETH", "Typical USD", "Worst ETH", "Worst USD", "Source"],
+      (report.rows ?? []).map((row) => [
+        row.command,
+        row.transactions,
+        String(row.gasUsed),
+        row.typicalEth,
+        `$${row.typicalUsd}`,
+        row.worstCaseEth,
+        `$${row.worstCaseUsd}`,
+        row.sources,
+      ]),
+    ),
+  ];
+  if (Array.isArray(report.asset?.notes) && report.asset.notes.length > 0) {
+    lines.push(
+      "",
+      "Notes",
+      ...report.asset.notes.map((note) => `- ${note}`),
+    );
+  }
+  console.log(lines.join("\n"));
+}
+
+function formatHumanTable(headers, rows) {
+  const values = [headers, ...rows].map((row) => row.map((value) => String(value ?? "")));
+  const widths = headers.map((_header, columnIndex) =>
+    Math.max(...values.map((row) => row[columnIndex].length)),
+  );
+  const formatRow = (row) => `| ${row.map((value, index) => value.padEnd(widths[index])).join(" | ")} |`;
+  return [
+    formatRow(values[0]),
+    formatRow(widths.map((width) => "-".repeat(width))),
+    ...values.slice(1).map(formatRow),
+  ].join("\n");
+}
+
 function formatGuideSelector(value) {
   return value === null || value === undefined || value === "" ? "not selected" : String(value);
 }
@@ -6327,6 +6759,51 @@ function emitProgress(action, phase) {
   }
 }
 
+function createRpcLogScanProgress({ action, label }) {
+  let lastBucket = -1;
+  return (event) => {
+    const totalBlocks = Number(event.totalBlocks ?? 0);
+    const scannedBlocks = Number(event.scannedBlocks ?? 0);
+    const logsFound = Number(event.logsFound ?? 0);
+    if (event.status === "skipped") {
+      emitProgress(action, `rpc-log-scan ${label}: skipped (no blocks to scan, ${logsFound} logs)`);
+      return;
+    }
+    if (event.status === "start") {
+      lastBucket = 0;
+      emitProgress(
+        action,
+        `rpc-log-scan ${label}: 0% (0/${totalBlocks} blocks, ${logsFound} logs, blocks ${event.fromBlock}-${event.toBlock})`,
+      );
+      return;
+    }
+    if (event.status === "done") {
+      emitProgress(
+        action,
+        `rpc-log-scan ${label}: 100% (${totalBlocks}/${totalBlocks} blocks, ${logsFound} logs, done)`,
+      );
+      return;
+    }
+    if (event.status !== "progress" || totalBlocks <= 0) {
+      return;
+    }
+
+    const percent = Math.min(100, Math.floor((scannedBlocks * 100) / totalBlocks));
+    if (percent >= 100) {
+      return;
+    }
+    const bucket = Math.floor(percent / 10) * 10;
+    if (bucket <= lastBucket) {
+      return;
+    }
+    lastBucket = bucket;
+    emitProgress(
+      action,
+      `rpc-log-scan ${label}: ${percent}% (${scannedBlocks}/${totalBlocks} blocks, ${logsFound} logs)`,
+    );
+  };
+}
+
 function formatCliErrorForDisplay(error, args = {}) {
   const message = String(error?.message ?? error);
   const hints = buildRecoveryHints(error, args);