@tokamak-private-dapps/private-state-cli 2.4.2 → 2.4.3

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 2.4.3 - 2026-06-01
+
+- Added pre-submit transaction dry-runs for every transaction-sending CLI command.
+- Added post-proof local prechecks before dry-run for proof-backed commands.
+- Improved dry-run and submit failure messages with decoded revert details when available.
+- Standardized CLI `--json` output so final success and failure results are JSON objects on stdout.
+- Changed progress, warning, and informational events to emit JSON Lines on stderr in `--json` mode.
+- Added structured JSON command-reference output for `help commands --json` and `--help --json`.
+
 ## 2.4.2 - 2026-05-30
 
 - Changed channel workspace recovery guidance so CLI help, guide output, agent instructions, and documentation direct

package/README.md

@@ -170,7 +170,8 @@ A common note-use flow after channel policy review is:
 `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.
+continues to print the same command list for shell compatibility. Add `--json` to either form to print the command
+reference as structured JSON on stdout.
 
 ### Action-impact acknowledgement
 
@@ -524,6 +525,15 @@ LLM agents that guide users through this CLI should read [`agents.md`](agents.md
 commands. That file contains the agent-specific operating rules, including secret-handling boundaries, onboarding
 sequence, acknowledgement handling, recovery behavior, and error-response policy.
 
+When `--json` is used, the CLI follows one output contract for all commands:
+
+- the final success result is one JSON object on stdout
+- command failures are one JSON object on stdout with `ok: false`
+- progress, warning, and informational events are JSON Lines on stderr
+- human-readable mode remains the default when `--json` is omitted
+
+Agents should parse stdout for the final result and may stream stderr JSONL events to explain progress to the user.
+
 ## Artifacts
 
 Proof-backed and channel-mutating commands require full installed bridge, DApp, and Groth16 artifacts. Run

package/agents.md

@@ -48,6 +48,9 @@ activity or as a bridge-wide disclosure rule for every DApp.
   `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.
+- Prefer `--json` when running commands on behalf of a user. In JSON mode, parse stdout as the final success or failure
+  result. Failures use `ok: false` on stdout. Progress, warning, and informational events are emitted as JSON Lines on
+  stderr; stream or summarize those events for the human user instead of treating them as fatal by default.
 - 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

package/commands/index.mjs

@@ -1,8 +1,8 @@
 import {
   assertHelpCommandsArgs,
   assertVersionArgs,
+  cliOutput,
   configureOutput,
-  formatCliErrorForDisplay,
   parseArgs,
   printHelp,
   printVersion,
@@ -52,11 +52,7 @@ export async function runPrivateStateCli(argv) {
     }
     await command(args);
   } catch (error) {
-    console.error(formatCliErrorForDisplay(error, args));
+    cliOutput.error(error, args);
     process.exitCode = 1;
   }
 }
-
-export function privateStateCliDispatchTable() {
-  return COMMANDS;
-}

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

@@ -313,8 +313,11 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     id: "help-commands",
     display: "help commands",
     description: "Show the private-state CLI command reference.",
-    fields: [],
-    usage: "no options",
+    fields: ["json"],
+    usage: "optional --json",
+    help: [
+      "Use --json to emit the full command reference as structured JSON on stdout.",
+    ],
   },
   {
     id: "help-update",

package/lib/runtime.mjs

@@ -166,6 +166,8 @@ const CLI_ERROR_CODES = Object.freeze({
   MISSING_CHANNEL_REGISTRATION: "MISSING_CHANNEL_REGISTRATION",
   STALE_WORKSPACE: "STALE_WORKSPACE",
   STALE_CHANNEL_ROOT: "STALE_CHANNEL_ROOT",
+  TX_DRY_RUN_FAILED: "TX_DRY_RUN_FAILED",
+  TX_SUBMIT_FAILED: "TX_SUBMIT_FAILED",
 });
 
 class PrivateStateCliError extends Error {
@@ -288,7 +290,13 @@ function printImmutableChannelPolicyWarning({
       "Do not sign if any snapshot value is unexpected or has not been reviewed.",
     );
   }
-  console.error(details.join("\n"));
+  cliOutput.warning("channel-policy", details.join("\n"), {
+    action,
+    channelName,
+    channelId: channelId.toString(),
+    channelManager,
+    policySnapshot,
+  });
 }
 
 const ACTION_IMPACT_SUMMARIES = Object.freeze({
@@ -483,7 +491,16 @@ function printActionImpactSummary(summary, details) {
     lines.push(`- Exchange-controlled address warning: ${summary.exchangeControlledAddressWarning}`);
   }
   lines.push(`- Confirmation: pass --acknowledge-action-impact or type the exact confirmation phrase when prompted.`);
-  console.error(lines.join("\n"));
+  cliOutput.warning("action-impact", lines.join("\n"), {
+    command: summary.display,
+    l1PublicEvent: summary.l1PublicEvent,
+    privateNoteState: summary.privateNoteState,
+    publicFields: normalizeImpactLines(summary.publicFields, details),
+    notPublic: normalizeImpactLines(summary.notPublic, details),
+    noteProvenance: summary.noteProvenance,
+    policy: summary.policy,
+    exchangeControlledAddressWarning: summary.exchangeControlledAddressWarning ?? null,
+  });
 }
 
 function normalizeImpactLines(value, details) {
@@ -609,8 +626,15 @@ async function handleChannelCreate({ args, network, provider }) {
     channelId,
     policySnapshot,
   });
-  const receipt =
-    await waitForReceipt(await bridgeCore.createChannel(channelId, dappId, joinToll, dapp.metadataDigest));
+  const receipt = await dryRunThenSubmitTransaction({
+    operationName: "channel create",
+    call: contractTxCall(
+      bridgeCore.createChannel,
+      [channelId, dappId, joinToll, dapp.metadataDigest],
+      undefined,
+      bridgeCore.interface,
+    ),
+  });
   const channelInfo = await bridgeCore.getChannel(channelId);
 
   const workspaceResult = await syncChannelWorkspace({
@@ -625,7 +649,7 @@ async function handleChannelCreate({ args, network, provider }) {
     progressAction: "channel create",
   });
 
-  printJson({
+  cliOutput.result({
     action: "channel create",
     channelName,
     channelId: channelId.toString(),
@@ -767,7 +791,7 @@ async function handleWorkspaceInit({ args, network, provider }) {
     })
     : null;
 
-  printJson({
+  cliOutput.result({
     action: "channel recover-workspace",
     source: workspace.recoverySource ?? recoverySource,
     workspace: workspaceName,
@@ -804,7 +828,7 @@ async function handleGetChannel({ args, network, provider }) {
     channelInfo = await bridgeCore.getChannel(channelId);
   } catch (error) {
     if (isContractError(error, bridgeCore.interface, "UnknownChannel")) {
-      printJson({
+      cliOutput.result({
         action: "channel get-meta",
         channelName,
         channelId: channelId.toString(),
@@ -843,7 +867,7 @@ async function handleGetChannel({ args, network, provider }) {
     readChannelRefundSchedule(channelManager),
   ]);
 
-  printJson({
+  cliOutput.result({
     action: "channel get-meta",
     channelName,
     channelId: channelId.toString(),
@@ -880,10 +904,18 @@ async function handleSetChannelWorkspaceMirror({ args, network, provider }) {
   );
   const channelId = deriveChannelIdFromName(channelName);
   const previousUrl = await readChannelWorkspaceMirror({ bridgeCore, channelId });
-  const receipt = await waitForReceipt(await bridgeCore.setChannelWorkspaceMirror(channelId, url));
+  const receipt = await dryRunThenSubmitTransaction({
+    operationName: "channel set-workspace-mirror",
+    call: contractTxCall(
+      bridgeCore.setChannelWorkspaceMirror,
+      [channelId, url],
+      undefined,
+      bridgeCore.interface,
+    ),
+  });
   const currentUrl = await readChannelWorkspaceMirror({ bridgeCore, channelId });
 
-  printJson({
+  cliOutput.result({
     action: "channel set-workspace-mirror",
     channelName,
     channelId: channelId.toString(),
@@ -2210,12 +2242,28 @@ async function handleDepositBridge({ args, network, provider }) {
     signer,
   );
   let nextNonce = await provider.getTransactionCount(signer.address, "pending");
-  const approveReceipt =
-    await waitForReceipt(await asset.approve(bridgeVaultContext.bridgeTokenVaultAddress, amount, { nonce: nextNonce++ }));
-  const fundReceipt = await waitForReceipt(await bridgeTokenVault.fund(amount, { nonce: nextNonce++ }));
+  const approveReceipt = await dryRunThenSubmitTransaction({
+    operationName: "account deposit-bridge approve",
+    call: contractTxCall(
+      asset.approve,
+      [bridgeVaultContext.bridgeTokenVaultAddress, amount],
+      { nonce: nextNonce++ },
+      asset.interface,
+    ),
+  });
+  const fundReceipt = await dryRunThenSubmitTransaction({
+    operationName: "account deposit-bridge fund",
+    call: contractTxCall(
+      bridgeTokenVault.fund,
+      [amount],
+      { nonce: nextNonce++ },
+      bridgeTokenVault.interface,
+    ),
+    submittedBefore: [submittedReceiptSummary("account deposit-bridge approve", approveReceipt)],
+  });
   const availableBalance = await bridgeTokenVault.availableBalanceOf(signer.address);
 
-  printJson({
+  cliOutput.result({
     action: "account deposit-bridge",
     amountInput,
     amountBaseUnits: amount.toString(),
@@ -2243,7 +2291,7 @@ async function handleAccountGetBridgeFund({ args, provider }) {
   );
   const availableBalance = await bridgeTokenVault.availableBalanceOf(signer.address);
 
-  printJson({
+  cliOutput.result({
     action: "account get-bridge-fund",
     l1Address: signer.address,
     bridgeTokenVault: bridgeVaultContext.bridgeTokenVaultAddress,
@@ -2393,7 +2441,7 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
     latestBlock: recoveryEventScan.scanRange.toBlock,
   });
 
-  printJson({
+  cliOutput.result({
     action: "wallet recover-workspace",
     status,
     wallet: walletName,
@@ -2491,7 +2539,7 @@ async function handleInstallZkEvm({ args }) {
     tokamakCliRuntime,
     groth16Runtime,
   });
-  printJson({
+  cliOutput.result({
     action: "install",
     installMode,
     selectedVersions,
@@ -2532,7 +2580,7 @@ async function handleUninstall() {
   });
   const globalPackage = uninstallGlobalPrivateStateCliPackage();
 
-  printJson({
+  cliOutput.result({
     action: "uninstall",
     confirmationAccepted: true,
     removedPrivateStateRoots,
@@ -2559,7 +2607,7 @@ async function handleSetRpc({ args }) {
     LOG_CHUNK_SIZE: rpcScanLimits.blockRangeCap,
     RPC_BLOCK_RANGE_CAP: rpcScanLimits.blockRangeCap,
   });
-  printJson({
+  cliOutput.result({
     action: "set rpc",
     network: networkName,
     rpcConfigPath: rpcConfigEnvPath(networkName),
@@ -2964,12 +3012,12 @@ async function handleUpdate() {
   };
 
   if (!updateAvailable) {
-    printJson(result);
+    cliOutput.result(result);
     return;
   }
 
   if (runningFromRepositoryCheckout) {
-    printJson({
+    cliOutput.result({
       ...result,
       reason: "running from a repository checkout; update the checkout with git/npm instead of mutating source files",
     });
@@ -2977,7 +3025,7 @@ async function handleUpdate() {
   }
 
   if (!globalPackage.installed) {
-    printJson({
+    cliOutput.result({
       ...result,
       reason: "global npm package is not installed; install or update the CLI with the printed command",
     });
@@ -2991,7 +3039,7 @@ async function handleUpdate() {
       stripAnsi(install.stderr || install.stdout).trim(),
     ].filter(Boolean).join(" "));
   }
-  printJson({
+  cliOutput.result({
     ...result,
     attempted: true,
     updated: true,
@@ -3043,18 +3091,14 @@ function isRepositoryCliPackageRoot(packageRoot) {
 
 async function handleDoctor({ args }) {
   const report = buildDoctorReport({ probeGpu: args.gpu === true });
-  if (isJsonOutputRequested()) {
-    printJson(report);
-  } else {
-    printDoctorHumanReport(report);
-  }
+  cliOutput.result(report);
   if (!report.ok) {
     process.exitCode = 1;
   }
 }
 
 function handleObserver() {
-  printJson({
+  cliOutput.result({
     action: "observer",
     url: PRIVATE_STATE_OBSERVER_URL,
     scope: "Public monitoring observer for Tokamak Private App Channels and the private-state DApp.",
@@ -3069,7 +3113,7 @@ function handleInvestigator() {
   const htmlPath = resolveInvestigatorIndexPath();
   const fileUrl = pathToFileURL(htmlPath).href;
   const browser = openFileInDefaultBrowser(fileUrl);
-  printJson({
+  cliOutput.result({
     action: "investigator",
     htmlPath,
     fileUrl,
@@ -3138,7 +3182,7 @@ async function handleTransactionFees({ network, provider, rpcUrl }) {
     ethUsd,
   });
 
-  printJson({
+  cliOutput.result({
     action: "transaction-fees",
     generatedAt: new Date().toISOString(),
     network: network.name,
@@ -3266,7 +3310,7 @@ function trimFixedNumber(value, maxDecimals) {
 
 function handleAccountGetL1Address({ args }) {
   const signer = requireL1Signer(args);
-  printJson({
+  cliOutput.result({
     action: "account get-l1-address",
     l1Address: signer.address,
     account: args.account ?? null,
@@ -3293,7 +3337,7 @@ function handleAccountImport({ args }) {
     l1Address: getAddress(signer.address),
     privateKeyPath,
   }, 0o600);
-  printJson({
+  cliOutput.result({
     action: "account import",
     account,
     network: networkName,
@@ -3314,7 +3358,7 @@ function handleListLocalWallets({ args }) {
     channelFilter,
   });
 
-  printJson({
+  cliOutput.result({
     action: "wallet list",
     workspaceRoot,
     filters: {
@@ -3382,7 +3426,7 @@ function handleWalletExportBackup({ args }) {
   archive.writeZip(outputPath);
   protectSecretFile(outputPath, "wallet export ZIP");
 
-  printJson({
+  cliOutput.result({
     action: "wallet export backup",
     output: outputPath,
     exportMode: manifest.exportMode,
@@ -3407,7 +3451,7 @@ function handleWalletExportKey({ args, keyKind }) {
   validateWalletKeyPayload(payload, keyKind);
   fs.writeFileSync(outputPath, `${JSON.stringify(payload, null, 2)}\n`, { mode: 0o600 });
   protectSecretFile(outputPath, `${keyKind} key export`);
-  printJson({
+  cliOutput.result({
     action: `wallet export ${keyKind}-key`,
     wallet: wallet.walletName,
     network: networkName,
@@ -3452,7 +3496,7 @@ function handleWalletImportBackup({ args }) {
 
   commitWalletImportFiles({ targetRoot, plannedWrites });
 
-  printJson({
+  cliOutput.result({
     action: "wallet import backup",
     input: inputPath,
     exportMode: manifest.exportMode,
@@ -3495,7 +3539,7 @@ function handleWalletImportKey({ args, keyKind }) {
       writeJson(metadataPath, metadata);
     }
   }
-  printJson({
+  cliOutput.result({
     action: `wallet import ${keyKind}-key`,
     input: inputPath,
     network: networkName,
@@ -3637,7 +3681,7 @@ async function handleGuide({ args }) {
         "help guide --network anvil",
       ],
     });
-    printJson(guide);
+    cliOutput.result(guide);
     return;
   }
 
@@ -3650,7 +3694,7 @@ async function handleGuide({ args }) {
       command: "help guide --network <NAME>",
       why: `The requested network ${networkName} is not supported by the CLI network config.`,
     });
-    printJson(guide);
+    cliOutput.result(guide);
     return;
   }
 
@@ -3737,7 +3781,7 @@ async function handleGuide({ args }) {
 
   destroyGuideProvider(provider);
   applyGuideNextAction(guide);
-  printJson(guide);
+  cliOutput.result(guide);
 }
 
 function inspectGuideLocalState(args) {
@@ -4226,7 +4270,7 @@ async function handleWalletGetMeta({ args, provider }) {
     provider,
   });
 
-  printJson({
+  cliOutput.result({
     action: "wallet get-meta",
     wallet: wallet.walletName,
     ...walletLifecycleMetadata(wallet.wallet),
@@ -4560,7 +4604,7 @@ async function handleWalletGetChannelFund({ args, provider }) {
     provider,
   });
 
-  printJson({
+  cliOutput.result({
     action: "wallet get-channel-fund",
     wallet: wallet.walletName,
     network: walletMetadata.network,
@@ -4641,20 +4685,32 @@ async function handleJoinChannel({ args, network, provider, rpcUrl }) {
     channelId: context.workspace.channelId,
   });
   if (joinToll !== 0n) {
-    approveReceipt = await waitForReceipt(
-      await asset.approve(context.workspace.bridgeTokenVault, joinToll, { nonce: nextNonce++ }),
-    );
+    approveReceipt = await dryRunThenSubmitTransaction({
+      operationName: "channel join approve",
+      call: contractTxCall(
+        asset.approve,
+        [context.workspace.bridgeTokenVault, joinToll],
+        { nonce: nextNonce++ },
+        asset.interface,
+      ),
+    });
   }
-  receipt = await waitForReceipt(
-    await context.bridgeTokenVault.connect(signer).joinChannel(
-      ethers.toBigInt(context.workspace.channelId),
-      l2Identity.l2Address,
-      storageKey,
-      leafIndex,
-      noteReceiveKeyMaterial.noteReceivePubKey,
+  receipt = await dryRunThenSubmitTransaction({
+    operationName: "channel join",
+    call: contractTxCall(
+      context.bridgeTokenVault.connect(signer).joinChannel,
+      [
+        ethers.toBigInt(context.workspace.channelId),
+        l2Identity.l2Address,
+        storageKey,
+        leafIndex,
+        noteReceiveKeyMaterial.noteReceivePubKey,
+      ],
       { nonce: nextNonce++ },
+      context.bridgeTokenVault.interface,
     ),
-  );
+    submittedBefore: approveReceipt ? [submittedReceiptSummary("channel join approve", approveReceipt)] : [],
+  });
   const registered = await context.channelManager.getChannelTokenVaultRegistration(signer.address);
   const lifecycleEpoch = await walletEpochFromJoinReceipt({
     receipt,
@@ -4683,7 +4739,7 @@ async function handleJoinChannel({ args, network, provider, rpcUrl }) {
     rpcUrl,
   });
 
-  printJson({
+  cliOutput.result({
     action: "channel join",
     workspace: context.workspaceName,
     wallet: walletContext.walletName,
@@ -4733,16 +4789,22 @@ async function handleExitChannel({ args, provider }) {
     ].join(" "),
   );
   const [refundAmount, refundBps] = await context.channelManager.getExitTollRefundQuote(ownerSigner.address);
-  const receipt = await waitForReceipt(
-    await context.bridgeTokenVault.connect(ownerSigner).exitChannel(ethers.toBigInt(context.workspace.channelId)),
-  );
+  const receipt = await dryRunThenSubmitTransaction({
+    operationName: "channel exit",
+    call: contractTxCall(
+      context.bridgeTokenVault.connect(ownerSigner).exitChannel,
+      [ethers.toBigInt(context.workspace.channelId)],
+      undefined,
+      context.bridgeTokenVault.interface,
+    ),
+  });
   const lifecycleEpoch = await markWalletEpochExited({
     walletContext,
     receipt,
     provider,
   });
 
-  printJson({
+  cliOutput.result({
     action: "channel exit",
     wallet: walletContext.walletName,
     network: walletMetadata.network,
@@ -4867,16 +4929,22 @@ async function handleGrothVaultMove({ args, provider, direction }) {
   });
 
   const methodName = direction === "deposit" ? "depositToChannelVault" : "withdrawFromChannelVault";
-  await assertWorkspaceAlignedWithChain(context);
   emitProgress(operationName, "submitting");
-  const receipt = await submitProofBackedRootUpdate({
+  const receipt = await dryRunThenSubmitTransaction({
+    operationName,
     context,
     walletName: walletContext.walletName,
-    operationName,
-    submit: () => bridgeTokenVault[methodName](
-      ethers.toBigInt(context.workspace.channelId),
-      transition.proof,
-      transition.update,
+    operationDir,
+    precheck: () => precheckGrothRootUpdate({ context, transition, operationName }),
+    call: contractTxCall(
+      bridgeTokenVault[methodName],
+      [
+        ethers.toBigInt(context.workspace.channelId),
+        transition.proof,
+        transition.update,
+      ],
+      undefined,
+      bridgeTokenVault.interface,
     ),
   });
   const onchainRootVectorHash = normalizeBytes32Hex(await context.channelManager.currentRootVectorHash());
@@ -4900,7 +4968,7 @@ async function handleGrothVaultMove({ args, provider, direction }) {
   });
 
   emitProgress(operationName, "done");
-  printJson({
+  cliOutput.result({
     action: operationName,
     workspace: context.workspaceName,
     wallet: walletContext.walletName,
@@ -4934,9 +5002,17 @@ async function handleWithdrawBridge({ args, network, provider }) {
     bridgeVaultContext.bridgeAbiManifest.contracts.bridgeTokenVault.abi,
     signer,
   );
-  const receipt = await waitForReceipt(await bridgeTokenVault.claimToWallet(amount));
+  const receipt = await dryRunThenSubmitTransaction({
+    operationName: "account withdraw-bridge",
+    call: contractTxCall(
+      bridgeTokenVault.claimToWallet,
+      [amount],
+      undefined,
+      bridgeTokenVault.interface,
+    ),
+  });
 
-  printJson({
+  cliOutput.result({
     action: "account withdraw-bridge",
     l1Address: signer.address,
     amountInput,
@@ -5067,7 +5143,7 @@ async function handleMintNotes({ args, provider }) {
     preparedContextResult,
   });
 
-  printJson({
+  cliOutput.result({
     action: "wallet mint-notes",
     wallet: wallet.walletName,
     workspace: execution.context.workspaceName,
@@ -5142,7 +5218,7 @@ async function handleRedeemNotes({ args, provider }) {
     preparedContextResult,
   });
 
-  printJson({
+  cliOutput.result({
     action: "wallet redeem-notes",
     wallet: wallet.walletName,
     workspace: execution.context.workspaceName,
@@ -5234,7 +5310,7 @@ async function handleWalletGetNotes({ args, provider }) {
     })
     : null;
 
-  printJson({
+  cliOutput.result({
     action: "wallet get-notes",
     wallet: wallet.walletName,
     network: walletMetadata.network,
@@ -6002,7 +6078,7 @@ async function handleTransferNotes({ args, provider }) {
     counterpartyDirection: "sent",
   });
 
-  printJson({
+  cliOutput.result({
     action: "wallet transfer-notes",
     wallet: wallet.walletName,
     workspace: execution.context.workspaceName,
@@ -7656,7 +7732,7 @@ async function executeWalletTemplateSend({
   functionName,
   templatePayload,
 }) {
-  await assertWorkspaceAlignedWithChain(context, signer.provider);
+  await assertWorkspaceAlignedWithChain(context);
   assertWalletMatchesChannelContext(wallet, l2Identity, context);
   await assertChannelProofBackendVersionCompatibility({ context, operationName });
 
@@ -7712,19 +7788,26 @@ async function executeWalletTemplateSend({
     expectedFunctionRoot: context.workspace.functionRoot ?? context.workspace.policySnapshot?.functionRoot,
   });
   const aPubBlockHash = hashTokamakPublicInputs(payload.aPubBlock);
-  expect(
-    ethers.toBigInt(normalizeBytes32Hex(aPubBlockHash))
-      === ethers.toBigInt(normalizeBytes32Hex(context.workspace.aPubBlockHash)),
-    "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 submitProofBackedRootUpdate({
+  const receipt = await dryRunThenSubmitTransaction({
+    operationName,
     context,
     walletName: wallet.walletName,
-    operationName,
-    submit: () => context.channelManager.connect(txSubmitter).executeChannelTransaction(payload, functionProof),
+    operationDir,
+    precheck: () => precheckTokamakExecution({
+      context,
+      payload,
+      functionProof,
+      aPubBlockHash,
+      operationName,
+    }),
+    call: contractTxCall(
+      context.channelManager.connect(txSubmitter).executeChannelTransaction,
+      [payload, functionProof],
+      undefined,
+      context.channelManager.interface,
+    ),
   });
   await waitForProviderBlockAtLeast(provider, receipt.blockNumber, { action: operationName });
 
@@ -8399,25 +8482,219 @@ function isUnexpectedCurrentRootVectorError(error, context) {
   return String(error?.message ?? error).includes("UnexpectedCurrentRootVector");
 }
 
-async function submitProofBackedRootUpdate({
-  context,
-  walletName,
+function precheckGrothRootUpdate({ context, transition, operationName }) {
+  expect(transition && typeof transition === "object", `${operationName} proof precheck failed: missing transition.`);
+  expect(transition.proof && typeof transition.proof === "object", `${operationName} proof precheck failed: missing Groth16 proof.`);
+  expect(transition.update && typeof transition.update === "object", `${operationName} proof precheck failed: missing root update.`);
+  expect(
+    Array.isArray(transition.update.currentRootVector) && transition.update.currentRootVector.length > 0,
+    `${operationName} proof precheck failed: missing current root vector.`,
+  );
+  expect(
+    normalizeBytes32Hex(hashRootVector(transition.update.currentRootVector))
+      === normalizeBytes32Hex(hashRootVector(context.currentSnapshot.stateRoots)),
+    `${operationName} proof precheck failed: root update does not match the local workspace snapshot.`,
+  );
+  normalizeBytes32Hex(transition.update.updatedRoot);
+  normalizeBytes32Hex(transition.update.currentUserKey);
+  normalizeBytes32Hex(transition.update.updatedUserKey);
+  expect(transition.nextSnapshot?.stateRoots, `${operationName} proof precheck failed: missing next snapshot roots.`);
+}
+
+function precheckTokamakExecution({ context, payload, functionProof, aPubBlockHash, operationName }) {
+  expect(payload && typeof payload === "object", `${operationName} proof precheck failed: missing Tokamak payload.`);
+  for (const key of [
+    "proofPart1",
+    "proofPart2",
+    "functionPreprocessPart1",
+    "functionPreprocessPart2",
+    "aPubUser",
+    "aPubBlock",
+  ]) {
+    expect(Array.isArray(payload[key]) && payload[key].length > 0, `${operationName} proof precheck failed: payload.${key} is missing.`);
+  }
+  expect(functionProof?.metadata, `${operationName} proof precheck failed: missing function metadata proof.`);
+  expect(Array.isArray(functionProof?.siblings), `${operationName} proof precheck failed: missing function metadata proof siblings.`);
+  expect(
+    ethers.toBigInt(normalizeBytes32Hex(aPubBlockHash))
+      === ethers.toBigInt(normalizeBytes32Hex(context.workspace.aPubBlockHash)),
+    `${operationName} proof precheck failed: generated aPubBlockHash does not match the channel aPubBlockHash.`,
+  );
+}
+
+function contractTxCall(contractMethod, args = [], overrides = undefined, contractInterface = null) {
+  expect(typeof contractMethod === "function", "Internal error: contract transaction method must be callable.");
+  expect(
+    typeof contractMethod.staticCall === "function",
+    "Internal error: contract transaction method must support staticCall.",
+  );
+  const finalArgs = overrides === undefined ? [...args] : [...args, overrides];
+  return {
+    contractInterface,
+    dryRun: () => contractMethod.staticCall(...finalArgs),
+    submit: () => contractMethod(...finalArgs),
+  };
+}
+
+async function dryRunThenSubmitTransaction({
   operationName,
-  submit,
+  call,
+  precheck = null,
+  context = null,
+  walletName = null,
+  operationDir = null,
+  submittedBefore = [],
 }) {
+  expect(typeof call?.dryRun === "function", "Internal error: transaction dry-run callback is required.");
+  expect(typeof call?.submit === "function", "Internal error: transaction submit callback is required.");
+  if (precheck) {
+    await precheck();
+  }
   try {
-    return await waitForReceipt(await submit());
+    await call.dryRun();
   } catch (error) {
-    if (isUnexpectedCurrentRootVectorError(error, context)) {
-      throw staleChannelRootError({
-        cause: error,
-        context,
-        walletName,
-        operationName,
-      });
+    throw transactionPreflightOrSubmitError({
+      phase: "dry-run",
+      operationName,
+      cause: error,
+      context,
+      walletName,
+      operationDir,
+      submittedBefore,
+      contractInterface: call.contractInterface,
+    });
+  }
+  try {
+    return await waitForReceipt(await call.submit());
+  } catch (error) {
+    throw transactionPreflightOrSubmitError({
+      phase: "submit",
+      operationName,
+      cause: error,
+      context,
+      walletName,
+      operationDir,
+      submittedBefore,
+      contractInterface: call.contractInterface,
+    });
+  }
+}
+
+function transactionPreflightOrSubmitError({
+  phase,
+  operationName,
+  cause,
+  context = null,
+  walletName = null,
+  operationDir = null,
+  submittedBefore = [],
+  contractInterface = null,
+}) {
+  if (context && isUnexpectedCurrentRootVectorError(cause, context)) {
+    return staleChannelRootError({
+      cause,
+      context,
+      walletName,
+      operationName,
+      phase,
+    });
+  }
+  const decodedError = decodeTransactionContractError(cause, [
+    contractInterface,
+    context?.channelManager?.interface,
+    context?.bridgeTokenVault?.interface,
+  ]);
+  const details = [
+    phase === "dry-run"
+      ? `${operationName} pre-submit dry-run failed. No ${operationName} transaction was submitted.`
+      : `${operationName} transaction submission failed.`,
+  ];
+  const submitted = normalizeSubmittedBefore(submittedBefore);
+  if (submitted.length > 0) {
+    details.push(`Already submitted before this failure: ${submitted.join("; ")}.`);
+  }
+  if (walletName) {
+    details.push(`Wallet: ${walletName}.`);
+  }
+  if (operationDir) {
+    details.push(`Operation directory: ${operationDir}.`);
+  }
+  if (decodedError) {
+    details.push(`Decoded contract error: ${decodedError}.`);
+  }
+  details.push(`Provider error: ${extractProviderErrorMessage(cause)}.`);
+  const error = cliError(
+    phase === "dry-run" ? CLI_ERROR_CODES.TX_DRY_RUN_FAILED : CLI_ERROR_CODES.TX_SUBMIT_FAILED,
+    details.join(" "),
+    { cause },
+  );
+  error.phase = phase;
+  error.operationName = operationName;
+  error.transactionSubmitted = phase !== "dry-run";
+  error.submittedBefore = submitted;
+  error.walletName = walletName;
+  error.operationDir = operationDir;
+  error.decodedContractError = decodedError;
+  error.providerError = extractProviderErrorMessage(cause);
+  if (context) {
+    error.channelName = context.workspace?.channelName;
+    error.networkName = context.workspace?.network;
+  }
+  return error;
+}
+
+function submittedReceiptSummary(label, receipt) {
+  return `${label} tx ${receipt?.hash ?? "<unknown>"} in block ${receipt?.blockNumber ?? "<unknown>"}`;
+}
+
+function normalizeSubmittedBefore(entries) {
+  return entries
+    .filter(Boolean)
+    .map((entry) => {
+      if (typeof entry === "string") {
+        return entry;
+      }
+      if (entry?.hash) {
+        return submittedReceiptSummary(entry.label ?? "transaction", entry);
+      }
+      return String(entry);
+    });
+}
+
+function decodeTransactionContractError(error, contractInterfaces) {
+  if (error?.revert?.name) {
+    return formatDecodedContractError(error.revert.name, error.revert.args ?? []);
+  }
+  for (const contractInterface of contractInterfaces.filter(Boolean)) {
+    for (const errorData of extractContractErrorDataCandidates(error)) {
+      try {
+        const parsed = contractInterface.parseError(errorData);
+        if (parsed) {
+          return formatDecodedContractError(parsed.name, parsed.args ?? []);
+        }
+      } catch {
+        // Keep scanning provider error payloads and interfaces.
+      }
     }
-    throw error;
   }
+  return null;
+}
+
+function formatDecodedContractError(name, args) {
+  const renderedArgs = Array.from(args ?? [])
+    .map((value) => serializeBigInts(normalizeCliOutputValue(value, [])));
+  return `${name}(${renderedArgs.map((value) => JSON.stringify(value)).join(", ")})`;
+}
+
+function extractProviderErrorMessage(error) {
+  return String(
+    error?.shortMessage
+      ?? error?.reason
+      ?? error?.info?.error?.message
+      ?? error?.error?.message
+      ?? error?.message
+      ?? error,
+  );
 }
 
 function staleChannelRootError({
@@ -8425,17 +8702,24 @@ function staleChannelRootError({
   context,
   walletName,
   operationName,
+  phase = "submit",
 }) {
   const message = [
-    `${operationName} failed because the submitted proof was generated for an older channel root.`,
+    phase === "dry-run"
+      ? `${operationName} pre-submit dry-run failed because the generated proof targets an older channel root. No ${operationName} transaction was submitted.`
+      : `${operationName} failed because the submitted proof was generated for an older channel root.`,
     "The rejected proof cannot be reused.",
     "Do not change recipients, amounts, note counts, function arity, or split the command as recovery.",
     "Refresh the channel workspace, re-check affected wallet state when the command uses notes, then rerun the original intended command so the CLI regenerates a proof from a fresh snapshot.",
   ].join(" ");
   const error = cliError(CLI_ERROR_CODES.STALE_CHANNEL_ROOT, message, { cause });
+  error.phase = phase;
+  error.operationName = operationName;
+  error.transactionSubmitted = phase !== "dry-run";
   error.channelName = context.workspace.channelName;
   error.networkName = context.workspace.network;
   error.walletName = walletName;
+  error.providerError = extractProviderErrorMessage(cause);
   error.retryPolicy = "recover_workspace_then_regenerate_proof";
   error.semanticMutationAllowed = false;
   error.reuseProofAllowed = false;
@@ -9742,15 +10026,11 @@ function assertVersionArgs(args) {
 }
 
 function printVersion() {
-  if (isJsonOutputRequested()) {
-    printJson({
-      action: "version",
-      packageName: privateStateCliPackageJson.name,
-      version: privateStateCliPackageJson.version,
-    });
-    return;
-  }
-  console.log(privateStateCliPackageJson.version);
+  cliOutput.result({
+    action: "version",
+    packageName: privateStateCliPackageJson.name,
+    version: privateStateCliPackageJson.version,
+  });
 }
 
 function requireWorkspaceName(args) {
@@ -10795,38 +11075,53 @@ function buildWalletViewingKeyMetadata(wallet) {
 }
 
 function printHelp() {
-  const commandHelp = PRIVATE_STATE_CLI_COMMANDS.map((command) => [
-    `  ${privateStateCliCommandSynopsis(command)}`,
-    `      ${command.description}`,
-    ...(command.help ?? []).map((line) => `      ${line}`),
-  ].join("\n")).join("\n\n");
-  console.log(`
-Commands:
-${commandHelp}
-
-Secret source options:
-  Use account import --private-key-file once to create a protected local account secret.
-  L1 signing commands use --account only.
-  A wallet secret source file is arbitrary high-entropy secret text read once by channel join.
-  Create one before joining a channel, for example:
-      openssl rand -hex 32 > ./wallet-secret.txt
-      private-state-cli channel join --channel-name <NAME> --network <NAME> --account <NAME> --wallet-secret-path ./wallet-secret.txt --acknowledge-action-impact
-  Configure each network RPC endpoint once with set rpc. The CLI reads RPC_URL, LOG_CHUNK_SIZE,
-  and LOG_REQUESTS_PER_SECOND from ~/tokamak-private-channels/workspace/<network>/rpc-config.env.
-  Wallet commands use separate protected viewing-key and spending-key files when those capabilities are needed.
-  Source files passed to --private-key-file and --wallet-secret-path are not required to use 0600 permissions, but
-  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.
+  cliOutput.result(buildHelpCommandsResult());
+}
 
-  --json
-      Print the command result as JSON. Without --json, commands print human-readable output.
+function buildHelpCommandsResult() {
+  return {
+    action: "help commands",
+    commands: PRIVATE_STATE_CLI_COMMANDS.map(buildHelpCommandEntry),
+    secretSourceOptions: [
+      "Use account import --private-key-file once to create a protected local account secret.",
+      "L1 signing commands use --account only.",
+      "A wallet secret source file is arbitrary high-entropy secret text read once by channel join.",
+      "Configure each network RPC endpoint once with set rpc.",
+      "Wallet commands use separate protected viewing-key and spending-key files when those capabilities are needed.",
+      "Source files passed to --private-key-file and --wallet-secret-path are not required to use 0600 permissions, but canonical CLI secret files remain protected.",
+    ],
+    globalOptions: [
+      {
+        option: "--version",
+        description: "Print the private-state CLI package version and exit.",
+      },
+      {
+        option: "--json",
+        description: "Print the final success or failure result as JSON on stdout. Progress, warning, and info events are JSONL on stderr.",
+      },
+      {
+        option: "--help",
+        description: "Show this help. Equivalent to help commands.",
+      },
+    ],
+  };
+}
 
-  --help
-      Show this help. Equivalent to help commands.
-`);
+function buildHelpCommandEntry(command) {
+  const requiredFields = privateStateCliCommandRequiredOptionKeys(command);
+  const fields = command.fields ?? [];
+  return {
+    id: command.id,
+    display: privateStateCliCommandDisplay(command),
+    synopsis: privateStateCliCommandSynopsis(command),
+    description: command.description,
+    usage: command.usage,
+    fields,
+    requiredFields,
+    optionalFields: fields.filter((field) => !requiredFields.includes(field)),
+    installMode: privateStateCliCommandInstallMode(command),
+    help: command.help ?? [],
+  };
 }
 
 function readJson(filePath) {
@@ -11350,29 +11645,122 @@ function loadWalletCommandRuntime(args, { prepareArtifacts = false } = {}) {
 }
 
 const HUMAN_RESULT_RENDERERS = Object.freeze({
+  doctor: printDoctorHumanReport,
   guide: printGuideHumanResult,
+  "help commands": printHelpCommandsHumanResult,
   investigator: printInvestigatorHumanResult,
   observer: printObserverHumanResult,
   "transaction-fees": printTransactionFeesHumanResult,
   update: printUpdateHumanResult,
+  version: printVersionHumanResult,
 });
 
 function normalizePrivateKey(value) {
   return value.startsWith("0x") ? value : `0x${value}`;
 }
 
-function printJson(value) {
-  const normalized = normalizeCliOutput(value);
+const cliOutput = Object.freeze({
+  result(value) {
+    const normalized = normalizeCliOutput(value);
+    if (isJsonOutputRequested()) {
+      console.log(JSON.stringify(buildJsonSuccessPayload(normalized), null, 2));
+      return;
+    }
+    const renderer = HUMAN_RESULT_RENDERERS[normalized?.action];
+    if (renderer) {
+      renderer(normalized);
+      return;
+    }
+    printHumanResult(normalized);
+  },
+  error(error, args = {}) {
+    if (isJsonOutputRequested()) {
+      console.log(JSON.stringify(normalizeCliOutput(buildJsonErrorPayload(error, args)), null, 2));
+      return;
+    }
+    console.error(formatHumanError(error, args));
+  },
+  progress(action, phase, details = {}) {
+    emitOutputEvent({
+      event: "progress",
+      action,
+      phase,
+      message: details.message ?? `[${action}] ${phase}`,
+      details,
+    });
+  },
+  warning(kind, message, details = {}) {
+    emitOutputEvent({
+      event: "warning",
+      kind,
+      message,
+      details,
+    });
+  },
+});
+
+function buildJsonSuccessPayload(value) {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return Object.hasOwn(value, "ok") ? value : { ok: true, ...value };
+  }
+  return {
+    ok: true,
+    action: "result",
+    value,
+  };
+}
+
+function emitOutputEvent(event) {
+  const normalized = normalizeCliOutput({
+    timestamp: new Date().toISOString(),
+    ...event,
+  });
   if (isJsonOutputRequested()) {
-    console.log(JSON.stringify(normalized, null, 2));
+    console.error(JSON.stringify(normalized));
     return;
   }
-  const renderer = HUMAN_RESULT_RENDERERS[normalized?.action];
-  if (renderer) {
-    renderer(normalized);
+  const message = event.message ?? `[${event.action ?? event.kind ?? "cli"}] ${event.phase ?? event.event}`;
+  if (event.event === "warning") {
+    console.error(message);
     return;
   }
-  printHumanResult(normalized);
+  console.log(message);
+}
+
+function printVersionHumanResult(result) {
+  console.log(result.version);
+}
+
+function printHelpCommandsHumanResult(help) {
+  const commandHelp = (help.commands ?? []).map((command) => [
+    `  ${command.synopsis}`,
+    `      ${command.description}`,
+    ...(command.help ?? []).map((line) => `      ${line}`),
+  ].join("\n")).join("\n\n");
+  const globalOptions = (help.globalOptions ?? []).map((option) => [
+    `  ${option.option}`,
+    `      ${option.description}`,
+  ].join("\n")).join("\n\n");
+  console.log(`
+Commands:
+${commandHelp}
+
+Secret source options:
+  Use account import --private-key-file once to create a protected local account secret.
+  L1 signing commands use --account only.
+  A wallet secret source file is arbitrary high-entropy secret text read once by channel join.
+  Create one before joining a channel, for example:
+      openssl rand -hex 32 > ./wallet-secret.txt
+      private-state-cli channel join --channel-name <NAME> --network <NAME> --account <NAME> --wallet-secret-path ./wallet-secret.txt --acknowledge-action-impact
+  Configure each network RPC endpoint once with set rpc. The CLI reads RPC_URL, LOG_CHUNK_SIZE,
+  and LOG_REQUESTS_PER_SECOND from ~/tokamak-private-channels/workspace/<network>/rpc-config.env.
+  Wallet commands use separate protected viewing-key and spending-key files when those capabilities are needed.
+  Source files passed to --private-key-file and --wallet-secret-path are not required to use 0600 permissions, but
+  canonical CLI secret files remain protected. On macOS/Linux this means 0600; on Windows the CLI repairs ACLs when possible.
+
+Options:
+${globalOptions}
+`);
 }
 
 function printGuideHumanResult(guide) {
@@ -11604,12 +11992,7 @@ function humanizeLabel(value) {
 }
 
 function emitProgress(action, phase) {
-  const line = `[${action}] ${phase}`;
-  if (isJsonOutputRequested()) {
-    console.error(line);
-  } else {
-    console.log(line);
-  }
+  cliOutput.progress(action, phase);
 }
 
 function createByteDownloadProgress({ action, label, url }) {
@@ -11745,7 +12128,7 @@ function createRpcLogScanProgress({ action, label }) {
   };
 }
 
-function formatCliErrorForDisplay(error, args = {}) {
+function formatHumanError(error, args = {}) {
   const message = String(error?.message ?? error);
   const hints = buildRecoveryHints(error, args);
   if (hints.length === 0) {
@@ -11758,6 +12141,41 @@ function formatCliErrorForDisplay(error, args = {}) {
   ].join("\n");
 }
 
+function buildJsonErrorPayload(error, args = {}) {
+  const message = String(error?.message ?? error);
+  const hints = buildRecoveryHints(error, args);
+  return {
+    ok: false,
+    action: "error",
+    error: {
+      name: error?.name ?? "Error",
+      code: error?.code ?? "ERROR",
+      command: typeof args.command === "string" ? args.command : null,
+      message,
+      hints,
+      phase: error?.phase ?? null,
+      operationName: error?.operationName ?? null,
+      transactionSubmitted: typeof error?.transactionSubmitted === "boolean"
+        ? error.transactionSubmitted
+        : null,
+      submittedBefore: Array.isArray(error?.submittedBefore) ? error.submittedBefore : [],
+      decodedContractError: error?.decodedContractError ?? null,
+      providerError: error?.providerError ?? null,
+      channelName: error?.channelName ?? (typeof args.channelName === "string" ? args.channelName : null),
+      networkName: error?.networkName ?? (typeof args.network === "string" ? args.network : null),
+      walletName: error?.walletName ?? (typeof args.wallet === "string" ? args.wallet : null),
+      operationDir: error?.operationDir ?? null,
+      retryPolicy: error?.retryPolicy ?? null,
+      semanticMutationAllowed: typeof error?.semanticMutationAllowed === "boolean"
+        ? error.semanticMutationAllowed
+        : null,
+      reuseProofAllowed: typeof error?.reuseProofAllowed === "boolean"
+        ? error.reuseProofAllowed
+        : null,
+    },
+  };
+}
+
 function buildRecoveryHints(error, args = {}) {
   const message = String(error?.message ?? error);
   const hints = [];
@@ -11950,5 +12368,5 @@ export {
   loadExplicitCommandRuntime,
   loadWalletCommandRuntime,
   assertProviderChainIdMatchesNetwork,
-  formatCliErrorForDisplay,
+  cliOutput,
 };

package/package.json

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