@tokamak-private-dapps/private-state-cli 2.1.0 → 2.1.2

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

@@ -18,8 +18,34 @@ export const PRIVATE_STATE_CLI_FIELD_CATALOG = Object.freeze({
     type: "password",
     placeholder: "https://example-rpc",
     valueLabel: "<URL>",
-    hint: "Optional. When omitted, the CLI reads RPC_URL from ~/tokamak-private-channels/secrets/<network>/.env.",
+    hint: "Required by set rpc. Saved to ~/tokamak-private-channels/workspace/<network>/rpc-config.env.",
     option: "--rpc-url",
+  },
+  provider: {
+    label: "RPC Provider",
+    type: "select",
+    options: ["alchemy", "ankr", "chainstack", "chainnodes", "quicknode"],
+    valueLabel: "<PROVIDER>",
+    hint: "Optional for set rpc. Uses the built-in provider table for eth_getLogs request rate and block range cap.",
+    option: "--provider",
+    optional: true,
+  },
+  logRequestsPerSecond: {
+    label: "Log Requests Per Second",
+    type: "text",
+    placeholder: "7.497",
+    valueLabel: "<N>",
+    hint: "Optional for set rpc. Required with --block-range-cap when --provider is not used.",
+    option: "--log-requests-per-second",
+    optional: true,
+  },
+  blockRangeCap: {
+    label: "Block Range Cap",
+    type: "text",
+    placeholder: "10",
+    valueLabel: "<N>",
+    hint: "Optional for set rpc. Required with --log-requests-per-second when --provider is not used.",
+    option: "--block-range-cap",
     optional: true,
   },
   account: {
@@ -236,6 +262,18 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     fields: [],
     usage: "no options",
   },
+  {
+    id: "set-rpc",
+    display: "set rpc",
+    description: "Configure the network RPC URL and fixed eth_getLogs scan limits.",
+    fields: ["network", "rpcUrl", "provider", "logRequestsPerSecond", "blockRangeCap"],
+    usage: "--network, --rpc-url, and either --provider or both --log-requests-per-second and --block-range-cap",
+    help: [
+      "Writes ~/tokamak-private-channels/workspace/<network>/rpc-config.env",
+      "Built-in provider limits: ankr=27 calls/s and 3000 blocks, chainstack=22.5 calls/s and 100 blocks, chainnodes=22.5 calls/s and 20000 blocks, quicknode=13.5 calls/s and 5 blocks, alchemy=7.497 calls/s and 10 blocks",
+      "All bridge-facing and wallet commands read RPC settings from this file and do not accept --rpc-url",
+    ],
+  },
   {
     id: "help-commands",
     display: "help commands",
@@ -278,8 +316,8 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     id: "help-transaction-fees",
     display: "help transaction-fees",
     description: "Estimate ETH and USD fees for transaction-sending commands from packaged measured gas data and live network fee data.",
-    fields: ["network", "rpcUrl", "json"],
-    usage: "--network, optional --rpc-url, and optional --json",
+    fields: ["network", "json"],
+    usage: "--network and optional --json",
     help: [
       "Uses packages/apps/private-state/cli/assets/tx-fees.json as the measured gas source packaged with the CLI",
       "Reads live fee data from the selected network RPC and live ETH/USD from CoinGecko",
@@ -314,15 +352,15 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     id: "account-get-bridge-fund",
     display: "account get-bridge-fund",
     description: "Read the local account's current shared bridge vault balance.",
-    fields: ["network", "account", "rpcUrl"],
-    usage: "--network, --account, and optional --rpc-url",
+    fields: ["network", "account"],
+    usage: "--network, --account",
   },
   {
     id: "channel-create",
     display: "channel create",
     description: "Create a bridge channel and initialize its workspace.",
-    fields: ["channelName", "joinToll", "network", "account", "rpcUrl"],
-    usage: "--channel-name, --join-toll, --network, --account, and optional --rpc-url",
+    fields: ["channelName", "joinToll", "network", "account"],
+    usage: "--channel-name, --join-toll, --network, --account",
     help: [
       "Prints the immutable policy snapshot before sending the transaction",
       "Initializes the local channel workspace by replaying channel logs from channel genesis",
@@ -332,13 +370,16 @@ 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", "source", "fromGenesis", "rpcUrl"],
-    usage: "--channel-name, --network, optional --source, optional --from-genesis, and optional --rpc-url",
+    fields: ["channelName", "network", "source", "fromGenesis"],
+    usage: "--channel-name, --network, optional --source, optional --from-genesis",
     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",
+      "RPC recovery writes a usable channel workspace checkpoint after each RPC log chunk, so interrupted runs can resume from the last completed chunk",
+      "Mirror recovery uses a matching delta bundle when available; otherwise a newer verified full checkpoint replaces the local checkpoint before RPC catch-up",
       "Fails instead of falling back to genesis when no usable recovery index exists",
       "Use --source rpc --from-genesis to ignore the recovery index and replay logs from channel genesis",
+      "--from-genesis moves the existing local channel workspace to workspace-rebuild-backups before writing the current-format workspace; local secrets are preserved",
       "Prints RPC log scan progress while rebuilding the workspace",
     ],
   },
@@ -346,8 +387,8 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     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",
+    fields: ["channelName", "network", "account", "url"],
+    usage: "--channel-name, --network, --account, --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",
@@ -357,8 +398,8 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     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",
+    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",
@@ -370,15 +411,15 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     id: "channel-get-meta",
     display: "channel get-meta",
     description: "Read channel existence, manager, vault, toll, refund schedule, and immutable policy snapshot.",
-    fields: ["channelName", "network", "rpcUrl"],
-    usage: "--channel-name, --network, and optional --rpc-url",
+    fields: ["channelName", "network"],
+    usage: "--channel-name, --network",
   },
   {
     id: "account-deposit-bridge",
     display: "account deposit-bridge",
     description: "Deposit canonical tokens into the shared bridge vault.",
-    fields: ["amount", "network", "account", "acknowledgeActionImpact", "rpcUrl"],
-    usage: "--amount, --network, --account, --acknowledge-action-impact, and optional --rpc-url",
+    fields: ["amount", "network", "account", "acknowledgeActionImpact"],
+    usage: "--amount, --network, --account, --acknowledge-action-impact",
     help: [
       "Action impact: emits public L1 approval and bridge funding events that expose the local L1 account, bridge vault, amount, and transaction hashes.",
       "Private note state is not changed by this command.",
@@ -391,8 +432,8 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     id: "account-withdraw-bridge",
     display: "account withdraw-bridge",
     description: "Withdraw tokens from the shared bridge vault back to the wallet.",
-    fields: ["amount", "network", "account", "acknowledgeActionImpact", "rpcUrl"],
-    usage: "--amount, --network, --account, --acknowledge-action-impact, and optional --rpc-url",
+    fields: ["amount", "network", "account", "acknowledgeActionImpact"],
+    usage: "--amount, --network, --account, --acknowledge-action-impact",
     help: [
       "Action impact: emits a public L1 bridge withdrawal event that exposes the local L1 recipient, bridge vault, amount, and transaction hash.",
       "Private note state is not changed by this command; prior note provenance is not public by default.",
@@ -405,23 +446,24 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     id: "wallet-recover-workspace",
     display: "wallet recover-workspace",
     description: "Rebuild a recoverable local wallet from on-chain channel state.",
-    fields: ["channelName", "network", "account", "fromGenesis", "rpcUrl"],
-    usage: "--channel-name, --network, --account, optional --from-genesis, and optional --rpc-url",
+    fields: ["channelName", "network", "account", "fromGenesis"],
+    usage: "--channel-name, --network, --account, optional --from-genesis",
     help: [
       "Rebuilds backup metadata from channel state without recreating the spending key",
       "Derives and stores the viewing key when the local account signer can reproduce the registered viewing public key",
-      "By default, resumes RPC log scanning from the workspace recovery index when available",
-      "Fails instead of falling back to genesis when no usable recovery index exists",
-      "Use --from-genesis to ignore the recovery index and replay channel logs from channel genesis",
-      "Prints RPC log scan progress while rebuilding channel state and received-note state",
+      "Before wallet recovery, refreshes stale channel workspace state only when the saved recovery index delta fits the pre-command budget",
+      "Fails and asks for channel recover-workspace first when the channel workspace is missing, unusable, or too stale for automatic recovery",
+      "Use --from-genesis to restart received-note scanning from channel genesis; it does not rebuild the channel workspace from genesis",
+      "Received-note recovery checkpoints after each RPC log chunk during ordinary recovery; --from-genesis still starts received-note scanning from channel genesis",
+      "Prints RPC log scan progress while refreshing channel state and rebuilding received-note state",
     ],
   },
   {
     id: "channel-join",
     display: "channel join",
     description: "Pay the channel join toll and bind a wallet to a channel-specific L2 identity.",
-    fields: ["channelName", "network", "account", "walletSecretPath", "acknowledgeActionImpact", "rpcUrl"],
-    usage: "--channel-name, --network, --account, --wallet-secret-path, --acknowledge-action-impact, and optional --rpc-url",
+    fields: ["channelName", "network", "account", "walletSecretPath", "acknowledgeActionImpact"],
+    usage: "--channel-name, --network, --account, --wallet-secret-path, --acknowledge-action-impact",
     help: [
       "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",
@@ -564,6 +606,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     usage: "--wallet, --network, --amounts, --acknowledge-action-impact, and optional --tx-submitter",
     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",
+      "Requires both viewing and spending key capability so the accepted mint can be recovered through the normal note event path",
       "Use --tx-submitter <ACCOUNT> to let a separate local L1 account pay gas for stronger transaction privacy",
       "Action impact: emits public accepted-transition, commitment, encrypted note-delivery, root update, and transaction events.",
       "Private note state changes by creating local note plaintext and public commitments; note owner/value/salt are not public by default.",
@@ -619,7 +662,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     help: [
       "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",
+      "Fails instead of replaying from genesis; run wallet recover-workspace first when explicit wallet recovery is required",
       "Use --export-evidence <PATH> with --acknowledge-full-note-plaintext-export to write a local full-note evidence ZIP for private-state-cli investigator",
       "Evidence export includes all local epochs for the selected wallet, including exited epochs retained for dispute evidence",
     ],

package/lib/private-state-note-delivery.mjs

@@ -1,7 +1,12 @@
 import { randomBytes } from "node:crypto";
 import { AbiCoder, ethers } from "ethers";
-import { deriveL2KeysFromSignature, poseidon } from "tokamak-l2js";
+import { deriveL2KeysFromSignature } from "tokamak-l2js";
 import { jubjub } from "@noble/curves/jubjub";
+import {
+  normalizeBytesHex,
+  normalizeBytes32Hex,
+  poseidonHexFromBytes,
+} from "@tokamak-private-dapps/common-library/tokamak-l2-helpers";
 
 const abiCoder = AbiCoder.defaultAbiCoder();
 
@@ -42,18 +47,6 @@ function expect(condition, message) {
   }
 }
 
-function normalizeBytes32Hex(value) {
-  return ethers.hexlify(ethers.zeroPadValue(ethers.hexlify(value), 32)).toLowerCase();
-}
-
-function normalizeBytes16Hex(value) {
-  return ethers.hexlify(ethers.zeroPadValue(ethers.hexlify(value), 16)).toLowerCase();
-}
-
-function poseidonHexFromBytes(bytesLike) {
-  return ethers.hexlify(poseidon(ethers.getBytes(bytesLike))).toLowerCase();
-}
-
 function noteReceivePubKeyFromPoint(point) {
   const affine = point.toAffine();
   return {
@@ -371,7 +364,7 @@ function decryptFieldEncryptedNoteValue({
     encryptionInfo,
   });
   expect(
-    normalizeBytes16Hex(expectedTag) === normalizeBytes16Hex(normalized.tag),
+    normalizeBytesHex(expectedTag, 16) === normalizeBytesHex(normalized.tag, 16),
     "Encrypted note value integrity tag mismatch.",
   );
   const fieldMask = deriveFieldMask({

package/lib/private-state-runtime-management.mjs

@@ -9,7 +9,6 @@ import { fetchNpmPackageMetadata } from "@tokamak-private-dapps/common-library/n
 import {
   normalizePackageVersionToCompatibleBackendVersion,
   readTokamakZkEvmCompatibleBackendVersionFromPackageJson,
-  requireCanonicalCompatibleBackendVersion,
   requireExactSemverVersion,
 } from "@tokamak-private-dapps/common-library/proof-backend-versioning";
 import {