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

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(),
@@ -2061,7 +2093,8 @@ async function syncChannelWorkspace({
     throw new Error([
       `Workspace recovery index is missing or unusable for channel ${channelName} on ${networkNameFromChainId(network.chainId)}.`,
       "The CLI will not fall back to replaying channel logs from genesis unless explicitly requested.",
-      "Run channel recover-workspace first to refresh the local channel workspace.",
+      `If a workspace mirror is registered, run channel recover-workspace --channel-name ${channelName} --network ${networkNameFromChainId(network.chainId)} --source mirror first.`,
+      `Use channel recover-workspace --channel-name ${channelName} --network ${networkNameFromChainId(network.chainId)} --source rpc --from-genesis only when no compatible mirror is available.`,
     ].join(" "));
   }
   const workspaceBase = {
@@ -2209,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(),
@@ -2242,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,
@@ -2392,7 +2441,7 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
     latestBlock: recoveryEventScan.scanRange.toBlock,
   });
 
-  printJson({
+  cliOutput.result({
     action: "wallet recover-workspace",
     status,
     wallet: walletName,
@@ -2490,7 +2539,7 @@ async function handleInstallZkEvm({ args }) {
     tokamakCliRuntime,
     groth16Runtime,
   });
-  printJson({
+  cliOutput.result({
     action: "install",
     installMode,
     selectedVersions,
@@ -2531,7 +2580,7 @@ async function handleUninstall() {
   });
   const globalPackage = uninstallGlobalPrivateStateCliPackage();
 
-  printJson({
+  cliOutput.result({
     action: "uninstall",
     confirmationAccepted: true,
     removedPrivateStateRoots,
@@ -2558,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),
@@ -2963,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",
     });
@@ -2976,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",
     });
@@ -2990,7 +3039,7 @@ async function handleUpdate() {
       stripAnsi(install.stderr || install.stdout).trim(),
     ].filter(Boolean).join(" "));
   }
-  printJson({
+  cliOutput.result({
     ...result,
     attempted: true,
     updated: true,
@@ -3042,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.",
@@ -3068,7 +3113,7 @@ function handleInvestigator() {
   const htmlPath = resolveInvestigatorIndexPath();
   const fileUrl = pathToFileURL(htmlPath).href;
   const browser = openFileInDefaultBrowser(fileUrl);
-  printJson({
+  cliOutput.result({
     action: "investigator",
     htmlPath,
     fileUrl,
@@ -3137,7 +3182,7 @@ async function handleTransactionFees({ network, provider, rpcUrl }) {
     ethUsd,
   });
 
-  printJson({
+  cliOutput.result({
     action: "transaction-fees",
     generatedAt: new Date().toISOString(),
     network: network.name,
@@ -3265,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,
@@ -3292,7 +3337,7 @@ function handleAccountImport({ args }) {
     l1Address: getAddress(signer.address),
     privateKeyPath,
   }, 0o600);
-  printJson({
+  cliOutput.result({
     action: "account import",
     account,
     network: networkName,
@@ -3313,7 +3358,7 @@ function handleListLocalWallets({ args }) {
     channelFilter,
   });
 
-  printJson({
+  cliOutput.result({
     action: "wallet list",
     workspaceRoot,
     filters: {
@@ -3381,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,
@@ -3406,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,
@@ -3451,7 +3496,7 @@ function handleWalletImportBackup({ args }) {
 
   commitWalletImportFiles({ targetRoot, plannedWrites });
 
-  printJson({
+  cliOutput.result({
     action: "wallet import backup",
     input: inputPath,
     exportMode: manifest.exportMode,
@@ -3494,7 +3539,7 @@ function handleWalletImportKey({ args, keyKind }) {
       writeJson(metadataPath, metadata);
     }
   }
-  printJson({
+  cliOutput.result({
     action: `wallet import ${keyKind}-key`,
     input: inputPath,
     network: networkName,
@@ -3636,7 +3681,7 @@ async function handleGuide({ args }) {
         "help guide --network anvil",
       ],
     });
-    printJson(guide);
+    cliOutput.result(guide);
     return;
   }
 
@@ -3649,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;
   }
 
@@ -3736,7 +3781,7 @@ async function handleGuide({ args }) {
 
   destroyGuideProvider(provider);
   applyGuideNextAction(guide);
-  printJson(guide);
+  cliOutput.result(guide);
 }
 
 function inspectGuideLocalState(args) {
@@ -3873,12 +3918,14 @@ async function inspectGuideChannel({ channelName, network, provider, artifactsIn
         bridgeResources.bridgeAbiManifest.contracts.channelManager.abi,
         provider,
       );
-      const [joinToll, refundSchedule] = await Promise.all([
+      const [joinToll, refundSchedule, workspaceMirror] = await Promise.all([
         channelManager.joinToll(),
         readChannelRefundSchedule(channelManager),
+        readChannelWorkspaceMirror({ bridgeCore, channelId }),
       ]);
       result.onchain.joinTollBaseUnits = joinToll.toString();
       result.onchain.refundSchedule = refundSchedule;
+      result.onchain.workspaceMirror = workspaceMirror;
     }
   } catch (error) {
     result.error = error.message;
@@ -4054,9 +4101,19 @@ function applyGuideNextAction(guide) {
     return;
   }
   if (guide.selectors.channelName && guide.state.channel?.onchain?.exists && !guide.state.channel?.local?.workspaceExists) {
+    const workspaceMirror = typeof guide.state.channel.onchain.workspaceMirror === "string"
+      ? guide.state.channel.onchain.workspaceMirror.trim()
+      : "";
+    if (workspaceMirror) {
+      setGuideNextAction(guide, {
+        command: `channel recover-workspace --channel-name ${guide.selectors.channelName} --network ${guide.selectors.network} --source mirror`,
+        why: "The channel has a registered workspace mirror. Use mirror recovery before considering an explicit RPC genesis rebuild.",
+      });
+      return;
+    }
     setGuideNextAction(guide, {
       command: `channel recover-workspace --channel-name ${guide.selectors.channelName} --network ${guide.selectors.network} --source rpc --from-genesis`,
-      why: "The channel exists on-chain, but the local channel workspace has not been recovered yet, so there is no local recovery index to resume from.",
+      why: "The channel exists on-chain, but the local channel workspace has not been recovered yet and no workspace mirror is registered. RPC genesis rebuild is the remaining explicit bootstrap path.",
     });
     return;
   }
@@ -4213,7 +4270,7 @@ async function handleWalletGetMeta({ args, provider }) {
     provider,
   });
 
-  printJson({
+  cliOutput.result({
     action: "wallet get-meta",
     wallet: wallet.walletName,
     ...walletLifecycleMetadata(wallet.wallet),
@@ -4547,7 +4604,7 @@ async function handleWalletGetChannelFund({ args, provider }) {
     provider,
   });
 
-  printJson({
+  cliOutput.result({
     action: "wallet get-channel-fund",
     wallet: wallet.walletName,
     network: walletMetadata.network,
@@ -4628,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,
@@ -4670,7 +4739,7 @@ async function handleJoinChannel({ args, network, provider, rpcUrl }) {
     rpcUrl,
   });
 
-  printJson({
+  cliOutput.result({
     action: "channel join",
     workspace: context.workspaceName,
     wallet: walletContext.walletName,
@@ -4720,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,
@@ -4854,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());
@@ -4887,7 +4968,7 @@ async function handleGrothVaultMove({ args, provider, direction }) {
   });
 
   emitProgress(operationName, "done");
-  printJson({
+  cliOutput.result({
     action: operationName,
     workspace: context.workspaceName,
     wallet: walletContext.walletName,
@@ -4921,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,
@@ -5054,7 +5143,7 @@ async function handleMintNotes({ args, provider }) {
     preparedContextResult,
   });
 
-  printJson({
+  cliOutput.result({
     action: "wallet mint-notes",
     wallet: wallet.walletName,
     workspace: execution.context.workspaceName,
@@ -5129,7 +5218,7 @@ async function handleRedeemNotes({ args, provider }) {
     preparedContextResult,
   });
 
-  printJson({
+  cliOutput.result({
     action: "wallet redeem-notes",
     wallet: wallet.walletName,
     workspace: execution.context.workspaceName,
@@ -5221,7 +5310,7 @@ async function handleWalletGetNotes({ args, provider }) {
     })
     : null;
 
-  printJson({
+  cliOutput.result({
     action: "wallet get-notes",
     wallet: wallet.walletName,
     network: walletMetadata.network,
@@ -5989,7 +6078,7 @@ async function handleTransferNotes({ args, provider }) {
     counterpartyDirection: "sent",
   });
 
-  printJson({
+  cliOutput.result({
     action: "wallet transfer-notes",
     wallet: wallet.walletName,
     workspace: execution.context.workspaceName,
@@ -7643,7 +7732,7 @@ async function executeWalletTemplateSend({
   functionName,
   templatePayload,
 }) {
-  await assertWorkspaceAlignedWithChain(context, signer.provider);
+  await assertWorkspaceAlignedWithChain(context);
   assertWalletMatchesChannelContext(wallet, l2Identity, context);
   await assertChannelProofBackendVersionCompatibility({ context, operationName });
 
@@ -7699,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 });
 
@@ -8386,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({
@@ -8412,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;
@@ -9729,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) {
@@ -10782,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) {
@@ -11337,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) {
@@ -11591,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 }) {
@@ -11732,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) {
@@ -11745,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 = [];
@@ -11802,7 +12233,9 @@ function buildRecoveryHints(error, args = {}) {
   }
 
   if (error?.code === CLI_ERROR_CODES.STALE_WORKSPACE) {
-    hints.push(`private-state-cli channel recover-workspace --channel-name ${channelName} --network ${networkName}`);
+    hints.push(`private-state-cli channel get-meta --channel-name ${channelName} --network ${networkName}`);
+    hints.push(`if workspaceMirror is set: private-state-cli channel recover-workspace --channel-name ${channelName} --network ${networkName} --source mirror`);
+    hints.push(`otherwise use indexed RPC recovery: private-state-cli channel recover-workspace --channel-name ${channelName} --network ${networkName}`);
     hints.push(`private-state-cli help guide --network ${networkName} --channel-name ${channelName}`);
   }
 
@@ -11810,7 +12243,9 @@ function buildRecoveryHints(error, args = {}) {
     error?.code === CLI_ERROR_CODES.STALE_CHANNEL_ROOT
     || message.includes("UnexpectedCurrentRootVector")
   ) {
-    hints.push(`private-state-cli channel recover-workspace --channel-name ${channelName} --network ${networkName}`);
+    hints.push(`private-state-cli channel get-meta --channel-name ${channelName} --network ${networkName}`);
+    hints.push(`if workspaceMirror is set: private-state-cli channel recover-workspace --channel-name ${channelName} --network ${networkName} --source mirror`);
+    hints.push(`otherwise use indexed RPC recovery: private-state-cli channel recover-workspace --channel-name ${channelName} --network ${networkName}`);
     if (walletName !== "<WALLET>") {
       hints.push(`private-state-cli wallet get-notes --wallet ${walletName} --network ${networkName}`);
     }
@@ -11818,7 +12253,9 @@ function buildRecoveryHints(error, args = {}) {
   }
 
   if (message.includes("Workspace recovery index is missing or unusable")) {
-    hints.push(`private-state-cli channel recover-workspace --channel-name ${channelName} --network ${networkName}`);
+    hints.push(`private-state-cli channel get-meta --channel-name ${channelName} --network ${networkName}`);
+    hints.push(`if workspaceMirror is set: private-state-cli channel recover-workspace --channel-name ${channelName} --network ${networkName} --source mirror`);
+    hints.push(`only if no compatible workspace mirror is available: private-state-cli channel recover-workspace --channel-name ${channelName} --network ${networkName} --source rpc --from-genesis`);
   }
 
   if (message.includes("Wallet note recovery index is missing or unusable")) {
@@ -11931,5 +12368,5 @@ export {
   loadExplicitCommandRuntime,
   loadWalletCommandRuntime,
   assertProviderChainIdMatchesNetwork,
-  formatCliErrorForDisplay,
+  cliOutput,
 };