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

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## 2.4.0 - 2026-05-29
+
+- Removed the standalone `channel publish-workspace-mirror` command. Channel leaders now publish
+  mirror files through `channel recover-workspace --publish-workspace-mirror --leader-account <ACCOUNT> --output <PATH>`.
+
 ## 2.3.4 - 2026-05-29
 
 - Removed the implicit wallet proof context recovery path so proof-backed wallet commands require

package/README.md

@@ -236,10 +236,10 @@ older CLI and does not contain `wallet-index.metadata.json` plus `epochs/<epoch-
 Channel leaders can optionally register a workspace mirror server so users can bootstrap recovery
 from a signed checkpoint and download only the local-to-checkpoint delta when a local recovery index
 already exists. The channel leader can build the static mirror files with
-`channel publish-workspace-mirror` and then deploy the output directory to the registered mirror
-host. If the existing mirror manifest is unreadable or invalid, the leader can use
-`channel publish-workspace-mirror --force` to write a full checkpoint without trusting that remote
-manifest as a delta base. The CLI protocol is documented at
+`channel recover-workspace --publish-workspace-mirror --leader-account <ACCOUNT> --output <PATH>` after
+recovering the channel workspace, and then deploy the output directory to the registered mirror host.
+If the existing mirror manifest is unreadable or invalid, add `--force` to write a full checkpoint
+without trusting that remote manifest as a delta base. The CLI protocol is documented at
 https://github.com/tokamak-network/Tokamak-zk-EVM-contracts/blob/main/docs/dapps/private-state/channel-workspace-mirror-protocol.md.
 
 Back up a local wallet with:
@@ -541,6 +541,9 @@ Operating rules:
   rate. Suggest re-running `set rpc` with a provider that supports a larger block range cap, such as Ankr or Chainnodes
   when appropriate, or with explicit `--log-requests-per-second` and `--block-range-cap` values from the provider's
   documentation.
+- When a channel leader needs to refresh workspace mirror files, guide them to run
+  `channel recover-workspace --publish-workspace-mirror --leader-account <ACCOUNT> --output <PATH>`. The standalone
+  `channel publish-workspace-mirror` command is no longer available.
 - When a CLI command fails, read the error message and any printed `Try:` hints first. Prefer the corrective action
   suggested by the CLI before inventing a different recovery sequence.
 - When the user does not have a network RPC URL yet, explain that they need an Ethereum JSON-RPC endpoint for the

package/commands/channel.mjs

@@ -4,14 +4,12 @@ import {
   assertGetChannelArgs,
   assertJoinChannelArgs,
   assertProviderChainIdMatchesNetwork,
-  assertPublishWorkspaceMirrorArgs,
   assertRecoverWorkspaceArgs,
   assertSetWorkspaceMirrorArgs,
   handleChannelCreate,
   handleExitChannel,
   handleGetChannel,
   handleJoinChannel,
-  handlePublishChannelWorkspaceMirror,
   handleSetChannelWorkspaceMirror,
   handleWorkspaceInit,
   loadExplicitCommandRuntime,
@@ -40,11 +38,6 @@ export const channelCommands = Object.freeze({
     const { network, provider } = loadExplicitCommandRuntime(args, { prepareArtifacts: true });
     await handleSetChannelWorkspaceMirror({ args, network, provider });
   },
-  "channel-publish-workspace-mirror": async (args) => {
-    assertPublishWorkspaceMirrorArgs(args);
-    const { network, provider } = loadExplicitCommandRuntime(args, { prepareArtifacts: true });
-    await handlePublishChannelWorkspaceMirror({ args, network, provider });
-  },
   "channel-join": async (args) => {
     assertJoinChannelArgs(args);
     const { network, provider, rpcUrl } = loadExplicitCommandRuntime(args, { prepareArtifacts: true });

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

@@ -55,6 +55,15 @@ export const PRIVATE_STATE_CLI_FIELD_CATALOG = Object.freeze({
     valueLabel: "<NAME>",
     option: "--account",
   },
+  leaderAccount: {
+    label: "Channel Leader Account",
+    type: "text",
+    placeholder: "leader-account",
+    valueLabel: "<ACCOUNT>",
+    hint: "Required with --publish-workspace-mirror. Signs the workspace mirror manifest and must match the on-chain channel leader.",
+    option: "--leader-account",
+    optional: true,
+  },
   txSubmitter: {
     label: "Transaction Submitter",
     type: "text",
@@ -212,6 +221,13 @@ export const PRIVATE_STATE_CLI_FIELD_CATALOG = Object.freeze({
     option: "--output-raw",
     optional: true,
   },
+  publishWorkspaceMirror: {
+    label: "Publish Workspace Mirror",
+    type: "checkbox",
+    hint: "After channel recovery, write the registered workspace mirror manifest, checkpoint, and any delta bundle.",
+    option: "--publish-workspace-mirror",
+    optional: true,
+  },
   source: {
     label: "Recovery Source",
     type: "select",
@@ -330,7 +346,11 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     fields: ["network", "channelName", "account", "wallet"],
     optionalFields: ["network", "channelName", "account", "wallet"],
     usage: "optional --network, --channel-name, --account, and --wallet",
-    help: ["Does not accept --rpc-url and never writes RPC configuration", "Recommends bridge deposits only after a wallet is joined and needs channel liquidity"],
+    help: [
+      "Does not accept --rpc-url and never writes RPC configuration",
+      "Recommends bridge deposits only after a wallet is joined and needs channel liquidity",
+      "Channel leaders publish workspace mirror files through channel recover-workspace --publish-workspace-mirror, not a standalone publish command",
+    ],
   },
   {
     id: "help-observer",
@@ -405,8 +425,9 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     display: "channel recover-workspace",
     description: "Rebuild the local channel workspace from bridge state.",
     installMode: "read-only",
-    fields: ["channelName", "network", "source", "fromGenesis", "outputRaw"],
-    usage: "--channel-name, --network, optional --source, optional --from-genesis, optional --output-raw",
+    fields: ["channelName", "network", "source", "fromGenesis", "outputRaw", "publishWorkspaceMirror", "leaderAccount", "output", "force"],
+    optionalFields: ["source", "fromGenesis", "outputRaw", "publishWorkspaceMirror", "leaderAccount", "output", "force"],
+    usage: "--channel-name, --network, optional --source, optional --from-genesis, optional --output-raw, optional --publish-workspace-mirror with --leader-account and --output, optional --force",
     help: [
       "By default, --source rpc resumes RPC log scanning from the workspace recovery index when available",
       "--source mirror validates the channel leader's registered checkpoint manifest, downloads only the needed checkpoint or delta bundle, and then replays RPC logs to latest",
@@ -416,6 +437,10 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
       "Use --source rpc --from-genesis to ignore the recovery index and replay logs from channel genesis",
       "--output-raw with --source rpc appends raw JSON-RPC request and response history to method-specific JSON files under the channel workspace rpcCallHistory directory; eth_getLogs is split by event",
       "--from-genesis moves the existing local channel workspace to workspace-rebuild-backups before writing the current-format workspace; local secrets are preserved",
+      "--publish-workspace-mirror writes manifest.json, checkpoint.zip, and any needed delta bundle after recovery",
+      "--publish-workspace-mirror requires --leader-account <ACCOUNT> and --output <PATH>; the leader account signs the mirror manifest and must match the on-chain channel leader",
+      "--force with --publish-workspace-mirror ignores an unreadable or invalid existing mirror manifest and publishes a full checkpoint without a delta",
+      "Workspace mirror publishing does not upload files to a remote server; deploy the output directory to the registered mirror host",
       "Prints RPC log scan progress while rebuilding the workspace",
     ],
   },
@@ -431,20 +456,6 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
       "The URL points to a server implementing the private-state channel workspace mirror protocol",
     ],
   },
-  {
-    id: "channel-publish-workspace-mirror",
-    display: "channel publish-workspace-mirror",
-    description: "Build static workspace mirror files for the registered mirror URL.",
-    installMode: "read-only",
-    fields: ["channelName", "network", "account", "output", "force"],
-    usage: "--channel-name, --network, --account, --output, optional --force",
-    help: [
-      "Requires the local channel workspace to be current and ahead of the registered mirror checkpoint",
-      "--force ignores an unreadable or invalid existing mirror manifest and publishes a full checkpoint without a delta",
-      "Writes manifest.json, checkpoint.zip, and any needed delta bundle under the workspace mirror static path",
-      "Does not upload files to a remote server; deploy the output directory to the registered HTTPS mirror host",
-    ],
-  },
   {
     id: "channel-get-meta",
     display: "channel get-meta",

package/lib/runtime.mjs

@@ -729,6 +729,8 @@ async function handleWorkspaceInit({ args, network, provider }) {
     workspaceDir,
     workspace,
     currentSnapshot,
+    blockInfo,
+    contractCodes,
     cleanRebuildBackup,
     rpcCallHistory,
   } = await syncChannelWorkspace({
@@ -746,6 +748,24 @@ async function handleWorkspaceInit({ args, network, provider }) {
     progressAction: "channel recover-workspace",
   });
 
+  const publishedWorkspaceMirror = args.publishWorkspaceMirror === true
+    ? await publishChannelWorkspaceMirrorFromRecoveredWorkspace({
+      args,
+      network,
+      provider,
+      bridgeResources,
+      channelName,
+      local: {
+        workspace,
+        stateSnapshot: currentSnapshot,
+        blockInfo,
+        contractCodes,
+        recoveryLastScannedBlock: workspace.recoveryLastScannedBlock,
+        recoveryRootVectorHash: workspace.recoveryRootVectorHash,
+      },
+    })
+    : null;
+
   printJson({
     action: "channel recover-workspace",
     source: workspace.recoverySource ?? recoverySource,
@@ -764,6 +784,7 @@ async function handleWorkspaceInit({ args, network, provider }) {
     recoveryScanRange: workspace.recoveryScanRange,
     rpcCallHistory,
     workspaceMirror: workspace.workspaceMirror ?? null,
+    publishedWorkspaceMirror,
   });
 }
 
@@ -875,12 +896,17 @@ async function handleSetChannelWorkspaceMirror({ args, network, provider }) {
   });
 }
 
-async function handlePublishChannelWorkspaceMirror({ args, network, provider }) {
-  const channelName = requireArg(args.channelName, "--channel-name");
+async function publishChannelWorkspaceMirrorFromRecoveredWorkspace({
+  args,
+  network,
+  provider,
+  bridgeResources,
+  channelName,
+  local,
+}) {
   const outputRoot = path.resolve(String(requireArg(args.output, "--output")));
   const force = args.force === true;
-  const signer = requireL1Signer(args, provider);
-  const bridgeResources = loadBridgeResources({ chainId: network.chainId });
+  const { signer, account: leaderAccount } = requireLeaderSigner(args, provider);
   const { bridgeDeployment, bridgeAbiManifest } = bridgeResources;
   const bridgeCore = new Contract(
     bridgeDeployment.bridgeCore,
@@ -906,13 +932,6 @@ async function handlePublishChannelWorkspaceMirror({ args, network, provider })
     channelId,
   });
 
-  const local = await loadPublishableLocalWorkspaceMirrorCheckpoint({
-    channelName,
-    network,
-    provider,
-    bridgeResources,
-    channelInfo,
-  });
   const remote = await readRemoteWorkspaceMirrorCheckpoint({
     manifestUrl,
     chainId: network.chainId,
@@ -927,9 +946,9 @@ async function handlePublishChannelWorkspaceMirror({ args, network, provider })
   expect(
     !remote.exists || Number(local.recoveryLastScannedBlock) > Number(remote.recoveryLastScannedBlock),
     [
-      `Local workspace recovery index ${local.recoveryLastScannedBlock} is not ahead of the registered mirror`,
+      `Recovered workspace index ${local.recoveryLastScannedBlock} is not ahead of the registered mirror`,
       `checkpoint ${remote.exists ? remote.recoveryLastScannedBlock : "<missing>"}.`,
-      "Run channel recover-workspace first if the local workspace is stale.",
+      "No newer workspace mirror checkpoint can be published.",
     ].join(" "),
   );
 
@@ -1023,11 +1042,13 @@ async function handlePublishChannelWorkspaceMirror({ args, network, provider })
   };
   writeJson(publishTarget.manifestPath, manifest);
 
-  printJson({
-    action: "channel publish-workspace-mirror",
+  return {
+    action: "channel recover-workspace publish-workspace-mirror",
     channelName,
     channelId: channelId.toString(),
     force,
+    leaderAccount,
+    leader: getAddress(signer.address),
     outputRoot,
     mirrorDir,
     manifestPath: publishTarget.manifestPath,
@@ -1053,7 +1074,7 @@ async function handlePublishChannelWorkspaceMirror({ args, network, provider })
       sizeBytes: checkpointBundle.bytes.length,
     },
     deltaBundles,
-  });
+  };
 }
 
 function resolveWorkspaceRecoverySource(args) {
@@ -1084,84 +1105,6 @@ async function readChannelWorkspaceMirror({ bridgeCore, channelId }) {
   return String(await bridgeCore.getChannelWorkspaceMirror(channelId));
 }
 
-async function loadPublishableLocalWorkspaceMirrorCheckpoint({
-  channelName,
-  network,
-  provider,
-  bridgeResources,
-  channelInfo,
-}) {
-  const workspaceDir = channelWorkspacePath(networkNameFromChainId(network.chainId), channelName);
-  const existingArtifacts = loadExistingWorkspaceArtifacts(workspaceDir);
-  const workspace = existingArtifacts.workspace;
-  expect(workspace, `Local channel workspace is missing at ${channelWorkspaceConfigPath(workspaceDir)}.`);
-  const stateSnapshot = existingArtifacts.stateSnapshot;
-  expect(stateSnapshot, `Local channel state snapshot is missing under ${channelWorkspaceCurrentPath(workspaceDir)}.`);
-  expect(existingArtifacts.blockInfo, `Local channel block_info.json is missing under ${channelWorkspaceCurrentPath(workspaceDir)}.`);
-  expect(existingArtifacts.contractCodes, `Local channel contract_codes.json is missing under ${channelWorkspaceCurrentPath(workspaceDir)}.`);
-  const channelManager = new Contract(
-    channelInfo.manager,
-    bridgeResources.bridgeAbiManifest.contracts.channelManager.abi,
-    provider,
-  );
-  const [
-    currentRootVectorHash,
-    genesisBlockNumber,
-    latestBlock,
-    managedStorageAddresses,
-  ] = await Promise.all([
-    channelManager.currentRootVectorHash(),
-    channelManager.genesisBlockNumber(),
-    provider.getBlockNumber(),
-    channelManager.getManagedStorageAddresses(),
-  ]);
-  const normalizedManagedStorageAddresses = normalizedAddressVector(managedStorageAddresses);
-  const recoveryIndex = getUsableWorkspaceRecoveryIndex({
-    existingArtifacts,
-    genesisBlockNumber: Number(genesisBlockNumber),
-    latestBlock,
-    managedStorageAddresses: normalizedManagedStorageAddresses,
-  });
-  expect(
-    recoveryIndex,
-    [
-      "Local channel workspace does not contain a usable recovery index.",
-      `Run channel recover-workspace --channel-name ${channelName} --network ${networkNameFromChainId(network.chainId)} first.`,
-    ].join(" "),
-  );
-  expect(
-    canReuseLocalWorkspaceSnapshot({
-      existingArtifacts,
-      currentRootVectorHash,
-      managedStorageAddresses: normalizedManagedStorageAddresses,
-    }),
-    [
-      "Local channel workspace is stale relative to the on-chain channel state.",
-      `Run channel recover-workspace --channel-name ${channelName} --network ${networkNameFromChainId(network.chainId)} first.`,
-    ].join(" "),
-  );
-  expect(Number(workspace.chainId) === Number(network.chainId), "Local workspace chainId does not match --network.");
-  expect(ethers.toBigInt(workspace.channelId) === ethers.toBigInt(deriveChannelIdFromName(channelName)), "Local workspace channelId mismatch.");
-  expect(String(workspace.channelName) === channelName, "Local workspace channelName mismatch.");
-  expect(
-    ethers.toBigInt(getAddress(workspace.channelManager)) === ethers.toBigInt(getAddress(channelInfo.manager)),
-    "Local workspace channelManager mismatch.",
-  );
-  expect(
-    ethers.toBigInt(getAddress(workspace.bridgeTokenVault)) === ethers.toBigInt(getAddress(channelInfo.bridgeTokenVault)),
-    "Local workspace bridgeTokenVault mismatch.",
-  );
-
-  return {
-    workspace,
-    stateSnapshot,
-    blockInfo: existingArtifacts.blockInfo,
-    contractCodes: existingArtifacts.contractCodes,
-    recoveryLastScannedBlock: recoveryIndex.nextBlock,
-    recoveryRootVectorHash: recoveryIndex.recoveryRootVectorHash,
-  };
-}
-
 async function readRemoteWorkspaceMirrorCheckpoint({
   manifestUrl,
   chainId,
@@ -3661,6 +3604,7 @@ async function handleGuide({ args }) {
     why: null,
     candidateCommands: [],
     privacyTip: "For wallet mint-notes, wallet transfer-notes, and wallet redeem-notes, add --tx-submitter <ACCOUNT> to let a separate local L1 account submit executeChannelTransaction and pay gas.",
+    mirrorTip: "Channel leaders refresh mirror files with channel recover-workspace --publish-workspace-mirror --leader-account <ACCOUNT> --output <PATH>; the standalone channel publish-workspace-mirror command is no longer available.",
   };
 
   guide.state.local = inspectGuideLocalState(args);
@@ -9764,6 +9708,19 @@ function requireL1Signer(args, provider) {
   return new Wallet(resolvePrivateKeySource(args), provider);
 }
 
+function requireLeaderSigner(args, provider) {
+  const networkName = requireNetworkName(args);
+  const account = String(requireArg(args.leaderAccount, "--leader-account")).trim();
+  expect(account.length > 0, "--leader-account requires a local account name.");
+  return {
+    signer: new Wallet(
+      normalizePrivateKey(readSecretFile(accountPrivateKeyPath(networkName, account), "--leader-account")),
+      provider,
+    ),
+    account,
+  };
+}
+
 function resolveTxSubmitterSigner({ args, ownerSigner, provider }) {
   if (args.txSubmitter === undefined) {
     expect(
@@ -10453,9 +10410,25 @@ function assertRecoverWorkspaceArgs(args) {
   const source = resolveWorkspaceRecoverySource(args);
   assertBooleanFlag(args, "fromGenesis", "channel recover-workspace option --from-genesis");
   assertBooleanFlag(args, "outputRaw", "channel recover-workspace option --output-raw");
+  assertBooleanFlag(args, "publishWorkspaceMirror", "channel recover-workspace option --publish-workspace-mirror");
+  assertBooleanFlag(args, "force", "channel recover-workspace option --force");
   if (args.outputRaw === true && source !== "rpc") {
     throw new Error("channel recover-workspace option --output-raw requires --source rpc.");
   }
+  if (args.publishWorkspaceMirror === true) {
+    requireArg(args.leaderAccount, "--leader-account");
+    requireArg(args.output, "--output");
+  } else {
+    if (args.leaderAccount !== undefined) {
+      throw new Error("channel recover-workspace option --leader-account requires --publish-workspace-mirror.");
+    }
+    if (args.output !== undefined) {
+      throw new Error("channel recover-workspace option --output requires --publish-workspace-mirror.");
+    }
+    if (args.force !== undefined) {
+      throw new Error("channel recover-workspace option --force requires --publish-workspace-mirror.");
+    }
+  }
 }
 
 function assertGetChannelArgs(args) {
@@ -10467,12 +10440,6 @@ function assertSetWorkspaceMirrorArgs(args) {
   requireWorkspaceMirrorUrl(args.url);
 }
 
-function assertPublishWorkspaceMirrorArgs(args) {
-  assertAllowedCommandSchema(args, "channel-publish-workspace-mirror");
-  requireArg(args.output, "--output");
-  assertBooleanFlag(args, "force", "channel publish-workspace-mirror option --force");
-}
-
 function assertDepositBridgeArgs(args) {
   assertAllowedCommandSchema(args, "account-deposit-bridge");
   assertActionImpactArg(args, "account deposit-bridge");
@@ -11369,6 +11336,11 @@ function printGuideHumanResult(guide) {
     "Privacy Tip",
     formatHumanValue(guide.privacyTip),
   );
+  lines.push(
+    "",
+    "Mirror Tip",
+    formatHumanValue(guide.mirrorTip),
+  );
   console.log(lines.join("\n"));
 }
 
@@ -11847,7 +11819,6 @@ export {
   assertRecoverWorkspaceArgs,
   assertGetChannelArgs,
   assertSetWorkspaceMirrorArgs,
-  assertPublishWorkspaceMirrorArgs,
   assertDepositBridgeArgs,
   assertWithdrawBridgeArgs,
   assertAccountGetBridgeFundArgs,
@@ -11881,7 +11852,6 @@ export {
   handleWorkspaceInit,
   handleGetChannel,
   handleSetChannelWorkspaceMirror,
-  handlePublishChannelWorkspaceMirror,
   handleDepositBridge,
   handleWithdrawBridge,
   handleAccountGetBridgeFund,

package/package.json

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