@tokamak-private-dapps/private-state-cli 1.1.1 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 1.2.0 - 2026-05-08
+
+- Added optional channel workspace mirror recovery. `channel recover-workspace` now accepts
+  `--source rpc|mirror`, with `rpc` remaining the default when `--source` is omitted.
+- Added `channel set-workspace-mirror` so a channel leader can register the official workspace
+  mirror base URL stored in `BridgeCore`.
+- Added mirror checkpoint validation that checks signed checkpoint metadata before downloading
+  bundles, then validates downloaded checkpoint or delta bundle contents against on-chain channel
+  metadata before replaying the remaining RPC log delta to the latest block.
+- Documented the static server protocol for channel workspace mirrors.
+- Removed `--source auto` from `channel recover-workspace`; recovery source is now either
+  `rpc` or `mirror`.
+- Required `channel recover-workspace --from-genesis` to be paired with explicit `--source rpc`
+  so genesis replay cannot be requested accidentally through an omitted source.
+- Restored pre-command workspace refresh for commands that require current local state, but limited
+  automatic refresh to saved recovery indexes. Automatic command preflight never replays from
+  genesis and points users to explicit `channel recover-workspace` or `wallet recover-workspace`
+  when a genesis rebuild is required.
+- Restored received-note event-log refresh for `wallet get-notes`, `wallet transfer-notes`, and
+  `wallet redeem-notes`, limited to the saved wallet note recovery index.
+- Limited pre-command automatic recovery to a 10 second RPC log scan budget based on the CLI's
+  paced log query rate.
+- Reworked workspace mirror recovery around leader-signed checkpoint manifests and
+  delta bundles. When a local recovery index exists, the CLI prechecks the mirror checkpoint and
+  downloads only the matching delta bundle instead of a full workspace bundle.
+- Removed the version segment from workspace mirror URLs and kept the protocol version only in
+  manifest and bundle metadata.
+- Added `channel publish-workspace-mirror` to build static mirror files when the local workspace is
+  current and ahead of the registered mirror checkpoint.
+- Added `channel publish-workspace-mirror --force` so a channel leader can repair an unreadable or
+  invalid remote mirror manifest by publishing a full checkpoint without using that manifest as a
+  delta base.
+- Required mirror bundle `sizeBytes` and enforce it as the download limit before verifying bundle
+  contents.
+- Kept streaming checkpoint or delta bundle download progress with an estimated remaining time.
+
 ## 1.1.1 - 2026-05-08
 
 - Added bridge deployment verification support for Etherscan-compatible explorers, including

package/README.md

@@ -99,26 +99,37 @@ continues to print the same command list for shell compatibility.
 
 Workspace recovery commands use the saved recovery index by default. If the local workspace is missing, corrupted, or
 does not contain a usable index, `channel recover-workspace` and `wallet recover-workspace` stop with an explicit error instead of
-silently replaying logs from channel genesis. Use `--from-genesis` only when you intentionally want to rebuild from the
-channel creation block:
+silently replaying logs from channel genesis. Use `--source rpc --from-genesis` only when you intentionally want to
+rebuild channel workspace state from the channel creation block:
 
 ```bash
-private-state-cli channel recover-workspace --channel-name <CHANNEL> --network mainnet --from-genesis
+private-state-cli channel recover-workspace --channel-name <CHANNEL> --network mainnet --source rpc --from-genesis
 private-state-cli wallet recover-workspace --channel-name <CHANNEL> --network mainnet --account <ACCOUNT> --from-genesis
 ```
 
 `channel create` is the exception: after the channel is created on-chain, the CLI initializes that new local workspace
 by replaying from the channel's genesis block because no prior recovery index can exist for a new channel.
 
-`channel join` requires the channel workspace to have a usable recovery index and refreshes that workspace through the
-indexed path before submitting the registration transaction. For a channel that was created elsewhere, run
-`channel recover-workspace --from-genesis` once before joining; later joins and wallet commands resume from the saved
-index instead of silently replaying from genesis.
+`channel join` refreshes stale channel workspace state through the saved recovery index before submitting the
+registration transaction. For a channel that was created elsewhere, run `channel recover-workspace --source rpc --from-genesis`
+once before joining, or recover from a registered workspace mirror; later joins and wallet commands resume from the
+saved index instead of silently replaying from genesis.
 
 Wallet getter commands that need channel state, including `wallet get-meta`, `wallet get-channel-fund`, and
-`wallet get-notes`, follow the same indexed recovery rule before reading local or on-chain state. `wallet get-notes` also uses
-the wallet's saved note-receive scan index for encrypted note delivery logs. If either index is unusable, the command
-stops and asks the user to run the appropriate recovery command with `--from-genesis`.
+`wallet get-notes`, refresh stale local workspaces through saved recovery indexes before reading state. `wallet get-notes`
+also refreshes received-note logs through the saved wallet note recovery index. Automatic refresh never replays from
+channel genesis and only runs when the estimated RPC log scan fits within the 10 second pre-command budget. If a saved
+index is missing, unusable, or too far behind, the command stops and asks the user to run the appropriate recovery
+command with `--from-genesis` explicitly when needed.
+
+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
+https://github.com/tokamak-network/Tokamak-zk-EVM-contracts/blob/main/packages/apps/private-state/docs/channel-workspace-mirror-protocol.md.
 
 Back up a local wallet with:
 
@@ -134,7 +145,7 @@ run `channel recover-workspace` before using wallet commands that need channel s
 
 ```bash
 private-state-cli wallet import --input ./wallet-backup.zip
-private-state-cli channel recover-workspace --channel-name <CHANNEL> --network mainnet --from-genesis
+private-state-cli channel recover-workspace --channel-name <CHANNEL> --network mainnet --source rpc --from-genesis
 ```
 
 For a wider backup that can run wallet commands immediately when the imported channel workspace cache is still
@@ -330,7 +341,7 @@ Suggested interaction flow:
    `wallet mint-notes`.
 7. For a private transfer, select available note IDs from `wallet get-notes`, find the recipient L2 address from
    `wallet get-meta`, then build `wallet transfer-notes`.
-8. After transfer, guide the recipient to run `wallet get-notes` to recover received notes from event logs.
+8. After transfer, guide the recipient to run `wallet get-notes`; it refreshes received notes from the saved recovery index when the delta fits the 10 second pre-command budget. If the index is missing or too far behind, explain `wallet recover-workspace --from-genesis`.
 
 Example onboarding explanation for `channel join`:
 

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

@@ -69,10 +69,10 @@ export const PRIVATE_STATE_CLI_FIELD_CATALOG = Object.freeze({
     option: "--wallet",
   },
   output: {
-    label: "Output ZIP",
+    label: "Output Path",
     type: "text",
-    placeholder: "/path/to/wallet-export.zip",
-    valueLabel: "<ZIP>",
+    placeholder: "/path/to/output",
+    valueLabel: "<PATH>",
     option: "--output",
   },
   input: {
@@ -157,10 +157,34 @@ export const PRIVATE_STATE_CLI_FIELD_CATALOG = Object.freeze({
   fromGenesis: {
     label: "Scan From Genesis",
     type: "checkbox",
-    hint: "Ignore the local recovery index and replay channel logs from genesis.",
+    hint: "Requires --source rpc. Ignore the local recovery index and replay channel logs from genesis.",
     option: "--from-genesis",
     optional: true,
   },
+  source: {
+    label: "Recovery Source",
+    type: "select",
+    options: ["rpc", "mirror"],
+    valueLabel: "<rpc|mirror>",
+    hint: "Optional. Defaults to rpc. mirror validates the channel leader's checkpoint manifest and downloads only the needed checkpoint or delta bundle before RPC delta replay.",
+    option: "--source",
+    optional: true,
+  },
+  url: {
+    label: "Workspace Mirror URL",
+    type: "text",
+    placeholder: "https://mirror.example",
+    valueLabel: "<URL>",
+    hint: "Base URL for the channel workspace mirror protocol.",
+    option: "--url",
+  },
+  force: {
+    label: "Force",
+    type: "checkbox",
+    hint: "Ignore an unreadable or invalid existing mirror manifest and publish a full checkpoint instead of a delta.",
+    option: "--force",
+    optional: true,
+  },
   json: {
     label: "JSON Output",
     type: "checkbox",
@@ -280,15 +304,40 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     id: "channel-recover-workspace",
     display: "channel recover-workspace",
     description: "Rebuild the local channel workspace from bridge state.",
-    fields: ["channelName", "network", "fromGenesis", "rpcUrl"],
-    usage: "--channel-name, --network, optional --from-genesis, and optional --rpc-url",
+    fields: ["channelName", "network", "source", "fromGenesis", "rpcUrl"],
+    usage: "--channel-name, --network, optional --source, optional --from-genesis, and optional --rpc-url",
     help: [
-      "By default, resumes RPC log scanning from the workspace recovery index when available",
+      "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",
       "Fails instead of falling back to genesis when no usable recovery index exists",
-      "Use --from-genesis to ignore the recovery index and replay logs from channel genesis",
+      "Use --source rpc --from-genesis to ignore the recovery index and replay logs from channel genesis",
       "Prints RPC log scan progress while rebuilding the workspace",
     ],
   },
+  {
+    id: "channel-set-workspace-mirror",
+    display: "channel set-workspace-mirror",
+    description: "Register or update the channel leader's workspace mirror base URL.",
+    fields: ["channelName", "network", "account", "url", "rpcUrl"],
+    usage: "--channel-name, --network, --account, --url, and optional --rpc-url",
+    help: [
+      "Only the on-chain channel leader can update the registered mirror URL",
+      "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.",
+    fields: ["channelName", "network", "account", "output", "force", "rpcUrl"],
+    usage: "--channel-name, --network, --account, --output, optional --force, and optional --rpc-url",
+    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",
@@ -332,8 +381,8 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     fields: ["channelName", "network", "account", "walletSecretPath", "rpcUrl"],
     usage: "--channel-name, --network, --account, --wallet-secret-path, and optional --rpc-url",
     help: [
-      "Requires a recovered channel workspace and refreshes it through the workspace recovery index before joining",
-      "Run channel recover-workspace --from-genesis once if no usable local recovery index exists",
+      "Refreshes the local channel workspace through the saved recovery index before joining when the scan fits the 10 second pre-command budget",
+      "Fails instead of replaying from genesis; run channel recover-workspace --source rpc --from-genesis when a genesis rebuild is required",
       "--wallet-secret-path imports an existing source secret file into the protected wallet-local secret file",
       "Prints the immutable policy snapshot before first registration",
     ],
@@ -344,7 +393,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     description: "Check whether a wallet matches the on-chain channel registration.",
     fields: ["wallet", "network"],
     usage: "--wallet and --network",
-    help: ["Refreshes channel state through the workspace recovery index before reading registration metadata"],
+    help: ["Refreshes the local channel workspace through the saved recovery index before reading registration metadata when the scan fits the 10 second pre-command budget"],
   },
   {
     id: "wallet-list",
@@ -384,6 +433,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     description: "Move bridged funds into the channel L2 accounting balance.",
     fields: ["wallet", "network", "amount"],
     usage: "--wallet, --network, and --amount",
+    help: ["Refreshes the local channel workspace through the saved recovery index before proving the deposit when the scan fits the 10 second pre-command budget"],
   },
   {
     id: "wallet-withdraw-channel",
@@ -391,6 +441,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     description: "Move channel L2 balance back into the shared bridge vault.",
     fields: ["wallet", "network", "amount"],
     usage: "--wallet, --network, and --amount",
+    help: ["Refreshes the local channel workspace through the saved recovery index before proving the withdrawal when the scan fits the 10 second pre-command budget"],
   },
   {
     id: "wallet-get-channel-fund",
@@ -398,7 +449,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     description: "Read the current channel L2 accounting balance.",
     fields: ["wallet", "network"],
     usage: "--wallet and --network",
-    help: ["Refreshes channel state through the workspace recovery index before reading the L2 accounting balance"],
+    help: ["Refreshes the local channel workspace through the saved recovery index before reading the L2 accounting balance when the scan fits the 10 second pre-command budget"],
   },
   {
     id: "channel-exit",
@@ -406,6 +457,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     description: "Exit a channel. Both the CLI and bridge contract require a zero channel balance.",
     fields: ["wallet", "network"],
     usage: "--wallet and --network",
+    help: ["Refreshes the local channel workspace through the saved recovery index before checking the channel balance when the scan fits the 10 second pre-command budget"],
   },
   {
     id: "wallet-mint-notes",
@@ -413,7 +465,10 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     description: "Mint one or two private-state notes from the wallet's channel balance.",
     fields: ["wallet", "network", "amounts", "txSubmitter"],
     usage: "--wallet, --network, --amounts, and optional --tx-submitter",
-    help: ["Use --tx-submitter <ACCOUNT> to let a separate local L1 account pay gas for stronger transaction privacy"],
+    help: [
+      "Refreshes the local channel workspace through the saved recovery index before proving the mint when the scan fits the 10 second pre-command budget",
+      "Use --tx-submitter <ACCOUNT> to let a separate local L1 account pay gas for stronger transaction privacy",
+    ],
   },
   {
     id: "wallet-transfer-notes",
@@ -421,7 +476,10 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     description: "Spend input notes into the registered 1->1, 1->2, or 2->1 private transfer shapes.",
     fields: ["wallet", "network", "noteIds", "recipients", "amounts", "txSubmitter"],
     usage: "--wallet, --network, --note-ids, --recipients, --amounts, and optional --tx-submitter",
-    help: ["Use --tx-submitter <ACCOUNT> to let a separate local L1 account pay gas for stronger transaction privacy"],
+    help: [
+      "Refreshes the local channel workspace and received-note logs through saved recovery indexes before proving the transfer when scans fit the 10 second pre-command budget",
+      "Use --tx-submitter <ACCOUNT> to let a separate local L1 account pay gas for stronger transaction privacy",
+    ],
   },
   {
     id: "wallet-redeem-notes",
@@ -429,17 +487,21 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     description: "Redeem one tracked note back into the wallet's channel balance.",
     fields: ["wallet", "network", "noteIds", "txSubmitter"],
     usage: "--wallet, --network, --note-ids, and optional --tx-submitter",
-    help: ["Use --tx-submitter <ACCOUNT> to let a separate local L1 account pay gas for stronger transaction privacy"],
+    help: [
+      "Refreshes the local channel workspace and received-note logs through saved recovery indexes before proving the redeem when scans fit the 10 second pre-command budget",
+      "Use --tx-submitter <ACCOUNT> to let a separate local L1 account pay gas for stronger transaction privacy",
+    ],
   },
   {
     id: "wallet-get-notes",
     display: "wallet get-notes",
-    description: "Show the wallet's tracked note state and refresh received notes.",
+    description: "Refresh received notes when the saved recovery index is recent, then show tracked note state.",
     fields: ["wallet", "network"],
     usage: "--wallet and --network",
     help: [
-      "Refreshes channel state through the workspace recovery index before reading notes",
-      "Refreshes received-note logs through the wallet note recovery index",
+      "Refreshes the local channel workspace through the saved recovery index before reading notes when the scan fits the 10 second pre-command budget",
+      "Refreshes received-note logs through the saved wallet note recovery index when the scan fits the 10 second pre-command budget",
+      "Fails instead of replaying from genesis; run wallet recover-workspace --from-genesis when a genesis rebuild is required",
     ],
   },
 ]);

package/package.json

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