@tokamak-private-dapps/private-state-cli 2.3.2 → 2.3.4

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+## 2.3.4 - 2026-05-29
+
+- Removed the implicit wallet proof context recovery path so proof-backed wallet commands require
+  their channel context to be prepared before proof generation.
+- Added a post-proof, pre-submit channel root check for proof-backed channel state updates so stale
+  proofs are rejected before submitting transactions whenever the root changed during proof generation.
+
+## 2.3.3 - 2026-05-27
+
+- Changed `help observer` and monitoring references to use the public observer URL
+  `https://observer.tonnel.io`.
+- Clarified CLI help, guide output, and README guidance so channel join tolls are paid directly
+  from the L1 wallet, while `account deposit-bridge` is only for channel liquidity.
+- Clarified README and `help commands` guidance so AI agents answer user gas, fee, and USD cost
+  questions by running `help transaction-fees --json` instead of escalating to developers.
+
 ## 2.3.2 - 2026-05-21
 
 - Clarified `wallet transfer-notes` JSON-array argument formats in CLI help and README guidance.

package/README.md

@@ -131,11 +131,11 @@ and the global CLI npm package when npm reports that it is globally installed.
 
 ## Commands
 
-A common private-state flow is:
+A common note-use flow after channel policy review is:
 
 1. `channel create`
-2. `account deposit-bridge`
-3. `channel join`
+2. `channel join`
+3. `account deposit-bridge`
 4. `wallet deposit-channel`
 5. `wallet mint-notes`
 6. `wallet transfer-notes`
@@ -145,6 +145,8 @@ A common private-state flow is:
 10. `channel exit`
 11. `account withdraw-bridge`
 
+`channel join` pays any join toll directly from the L1 wallet; `account deposit-bridge` funds later channel liquidity and does not pay the join toll.
+
 Use `private-state-cli help commands` for the full command list and required options. `private-state-cli --help`
 continues to print the same command list for shell compatibility.
 
@@ -312,7 +314,8 @@ private-state-cli help transaction-fees --network mainnet
 `help 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.
+data. AI agents answering user questions about gas, transaction fees, transaction cost, or USD cost should run
+`private-state-cli help transaction-fees --network <NETWORK> --json` and answer from the returned table.
 
 Proof-backed note commands can use a separate L1 transaction submitter:
 
@@ -529,6 +532,10 @@ Operating rules:
   recovery can be very slow because it scans channel logs from the creation block. If a channel workspace mirror is
   available, try mirror-based recovery first, and use RPC genesis replay only when mirror recovery is unavailable or
   unsuitable.
+- When the user asks about gas use, transaction fees, transaction cost, or USD cost for private-state CLI commands, run
+  `private-state-cli help transaction-fees --network <NETWORK> --json` and answer from the returned `rows`. If the
+  network is unclear, ask which network to use. Do not tell the user to ask the developer unless the command fails after
+  following the CLI's printed corrective guidance.
 - When `channel recover-workspace` or `wallet recover-workspace` is unexpectedly slow, first inspect the RPC provider
   configured by `set rpc`. Explain that recovery speed is dominated by `eth_getLogs` block range cap and log request
   rate. Suggest re-running `set rpc` with a provider that supports a larger block range cap, such as Ankr or Chainnodes
@@ -553,7 +560,7 @@ Operating rules:
   8. prepare a wallet secret source file locally, for example with `openssl rand -hex 32 > ./wallet-secret.txt`
   9. inspect the channel with `channel get-meta` if it already exists, or create it with `channel create` if the user is
      the channel creator
-  10. explain the immutable policy warning printed by the CLI
+  10. explain the immutable policy warning and that the join toll is paid directly from the L1 wallet, not bridge-deposited balance
   11. run `channel join --channel-name <CHANNEL> --network <NETWORK> --account <ACCOUNT> --wallet-secret-path <PATH> --acknowledge-action-impact`
 - Before executing any command for a user that requires an `--acknowledge-*` option, strongly warn the user in plain
   language about what that acknowledgement means and ask for explicit confirmation. Do not add
@@ -585,7 +592,7 @@ Operating rules:
 - Do not present one fixed command sequence as universally correct. Some flows start from an existing channel or wallet,
   while others require creating or joining a channel first.
 - When the user asks for a transfer, first determine whether the sender has minted notes available. If not, guide them
-  through funding the bridge, joining or recovering the channel wallet, depositing into the channel, and minting notes.
+  through joining or recovering the channel wallet, funding the bridge for channel liquidity, depositing into the channel, and minting notes.
 - When generating commands, use placeholders for secrets and explicit values for public fields. Show one command at a
   time unless the user asks for a batch.
 
@@ -596,7 +603,7 @@ Suggested interaction flow:
 3. Identify the sender and recipient wallets or local account names.
 4. Run `help doctor`.
 5. Run `wallet list` and relevant metadata or balance checks.
-6. If needed, guide the user through `channel create`, `account deposit-bridge`, `channel join`, `wallet deposit-channel`, and
+6. If needed, guide the user through `channel create`, `channel join`, `account deposit-bridge`, `wallet deposit-channel`, and
    `wallet mint-notes`.
 7. For a confidential note transfer, select available note IDs from `wallet get-notes`, find the recipient L2 address from
    `wallet get-meta`, then build `wallet transfer-notes` with JSON arrays for `--note-ids`, `--recipients`, and `--amounts`.

package/cli-assistant.html

@@ -422,11 +422,12 @@
               <li>
                 <span class="guide-label">Join a channel:</span> <code>channel join</code>
                 <div class="guide-example">
-                  <code>channel join --channel-name 'my-private-channel' --network 'sepolia' --account 'my-account' --wallet-secret-path '/path/to/wallet-secret'</code>
+                  <code>channel join --channel-name 'my-private-channel' --network 'sepolia' --account 'my-account' --wallet-secret-path '/path/to/wallet-secret'</code><br />
+                  Pays the join toll directly from the L1 wallet, not from bridge-deposited balance.
                 </div>
               </li>
               <li>
-                <span class="guide-label">Create notes:</span> <code>account deposit-bridge</code> -&gt; <code>wallet deposit-channel</code> -&gt; <code>wallet mint-notes</code>
+                <span class="guide-label">Fund note balance:</span> <code>account deposit-bridge</code> -&gt; <code>wallet deposit-channel</code> -&gt; <code>wallet mint-notes</code>
                 <div class="guide-example">
                   <code>account deposit-bridge --amount '100' --network 'sepolia' --account 'my-account'</code><br />
                   <code>wallet deposit-channel --wallet 'my-private-channel-0xYourL1Address' --network 'sepolia' --amount '100'</code><br />

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

@@ -330,7 +330,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     fields: ["network", "channelName", "account", "wallet"],
     optionalFields: ["network", "channelName", "account", "wallet"],
     usage: "optional --network, --channel-name, --account, and --wallet",
-    help: ["Does not accept --rpc-url and never writes RPC configuration"],
+    help: ["Does not accept --rpc-url and never writes RPC configuration", "Recommends bridge deposits only after a wallet is joined and needs channel liquidity"],
   },
   {
     id: "help-observer",
@@ -352,6 +352,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     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",
+      "AI agents should run this command with --json when users ask about gas, transaction fees, transaction cost, or USD cost",
     ],
   },
   {
@@ -461,7 +462,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     usage: "--amount, --network, --account, --acknowledge-action-impact",
     help: [
       "Action impact: emits public L1 approval and bridge funding events that expose the local L1 account, bridge vault, amount, and transaction hashes.",
-      "Private note state is not changed by this command.",
+      "Private note state is not changed by this command; it does not pay a channel join toll.",
       ACTION_IMPACT_HELP.exchangeControlledAddress,
       ACTION_IMPACT_HELP.illegalUse,
       ACTION_IMPACT_HELP.acknowledgement,
@@ -514,6 +515,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
       "Refreshes the local channel workspace through the saved recovery index before joining when the scan fits the 7,200-block pre-command budget",
       "Fails instead of replaying from genesis; run channel recover-workspace --source rpc --from-genesis when a genesis rebuild is required",
       "--wallet-secret-path is read once for channel-bound L2 spending-key derivation and is not stored in the wallet workspace",
+      "Pays any join toll directly from the L1 wallet, not from bridge-deposited balance",
       "Prints the immutable policy snapshot before first registration",
       "Action impact: emits public channel join and token-vault registration events exposing the L1 account, L2 address pair, note-receive public key, join toll, and channel id.",
       "Private note state is not changed by this command.",

package/lib/runtime.mjs

@@ -137,7 +137,7 @@ const PRIVATE_STATE_UNINSTALL_CONFIRMATION =
 const ACTION_IMPACT_CONFIRMATION =
   "I understand the public and private impact of this action";
 const PRIVATE_STATE_CLI_PACKAGE_NAME = privateStateCliPackageJson.name;
-const PRIVATE_STATE_OBSERVER_URL = "https://project-scw1r.vercel.app";
+const PRIVATE_STATE_OBSERVER_URL = "https://observer.tonnel.io";
 const GROTH16_PACKAGE_NAME = "@tokamak-private-dapps/groth16";
 const TOKAMAK_ZKEVM_CLI_PACKAGE_NAME = "@tokamak-zk-evm/cli";
 const WALLET_BACKUP_EXPORT_FORMAT = "tokamak-private-state-wallet-backup-export";
@@ -327,7 +327,7 @@ const ACTION_IMPACT_SUMMARIES = Object.freeze({
   },
   "channel-join": {
     display: "channel join",
-    l1PublicEvent: "Yes. Channel join and token-vault registration transactions are public L1 data.",
+    l1PublicEvent: "Yes. Channel join and token-vault registration transactions are public L1 data; any join toll is paid directly from the L1 wallet.",
     privateNoteState: "No. This action registers identity and note-receive metadata; it does not create or spend notes.",
     publicFields: ({ l1Address, l2Address, noteReceivePubKey, joinToll, channelName, channelId }) => [
       `Channel: ${channelName} (${channelId})`,
@@ -4120,7 +4120,7 @@ function applyGuideNextAction(guide) {
     const account = guide.selectors.account ?? "<ACCOUNT>";
     setGuideNextAction(guide, {
       command: `channel join --channel-name ${channelName} --network ${guide.selectors.network} --account ${account} --wallet-secret-path <PATH> --acknowledge-action-impact`,
-      why: "The selected local wallet does not exist. Join the channel to create the wallet and register the channel L2 identity.",
+      why: "The selected local wallet does not exist. Join the channel to create the wallet, register the channel L2 identity, and pay any join toll directly from the L1 wallet.",
     });
     return;
   }
@@ -4129,7 +4129,7 @@ function applyGuideNextAction(guide) {
     const account = guide.selectors.account ?? "<ACCOUNT>";
     setGuideNextAction(guide, {
       command: `channel join --channel-name ${channelName} --network ${guide.selectors.network} --account ${account} --wallet-secret-path <PATH> --acknowledge-action-impact`,
-      why: "The local wallet exists, but the corresponding L1 address is not registered in the channel.",
+      why: "The local wallet exists, but the corresponding L1 address is not registered in the channel; joining pays any join toll directly from the L1 wallet.",
     });
     return;
   }
@@ -4146,7 +4146,7 @@ function applyGuideNextAction(guide) {
     const account = guide.selectors.account ?? "<ACCOUNT>";
     setGuideNextAction(guide, {
       command: `account deposit-bridge --amount <TOKENS> --network ${guide.selectors.network} --account ${account} --acknowledge-action-impact`,
-      why: "The wallet is joined, but there is no bridge balance, channel balance, or local unused note to spend.",
+      why: "The wallet is joined, but there is no bridge balance, channel balance, or local unused note to spend; bridge deposits fund channel liquidity and do not pay join tolls.",
     });
     return;
   }
@@ -4909,6 +4909,7 @@ async function handleGrothVaultMove({ args, provider, direction }) {
   });
 
   const methodName = direction === "deposit" ? "depositToChannelVault" : "withdrawFromChannelVault";
+  await assertWorkspaceAlignedWithChain(context);
   emitProgress(operationName, "submitting");
   const receipt = await waitForReceipt(
     await bridgeTokenVault[methodName](ethers.toBigInt(context.workspace.channelId), transition.proof, transition.update),
@@ -7639,7 +7640,7 @@ async function executeWalletDirectTemplateCommand({
   provider,
   operationName,
   templatePayload,
-  preparedContextResult = null,
+  preparedContextResult,
 }) {
   emitProgress(operationName, "loading");
   const { signer, l2Identity } = restoreWalletParticipant(wallet, provider);
@@ -7653,11 +7654,8 @@ async function executeWalletDirectTemplateCommand({
     ownerSigner: signer,
     provider,
   });
-  const contextResult = preparedContextResult ?? await loadFreshWalletChannelContext({
-    walletContext: wallet,
-    provider,
-    progressAction: operationName,
-  });
+  expect(preparedContextResult?.context, "Internal error: prepared channel context is required before proof generation.");
+  const contextResult = preparedContextResult;
   const execution = await executeWalletTemplateSend({
     wallet,
     signer,
@@ -7755,6 +7753,7 @@ async function executeWalletTemplateSend({
     "Generated Tokamak proof does not match the channel aPubBlockHash. Check the workspace block_info.json context.",
   );
 
+  await assertWorkspaceAlignedWithChain(context);
   emitProgress(operationName, "submitting");
   const receipt =
     await waitForReceipt(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamak-private-dapps/private-state-cli",
-  "version": "2.3.2",
+  "version": "2.3.4",
   "description": "Command-line client for the Tokamak private-state DApp.",
   "license": "MIT OR Apache-2.0",
   "author": "Tokamak Network",