@tokamak-private-dapps/private-state-cli 2.2.0 → 2.3.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 2.3.0 - 2026-05-20
+
+- Added `help observer` to print the deployed public observer URL for the private-state monitoring
+  surface.
+- Documented the deployed public observer in the monitoring audit packet and observability matrix.
+
+## 2.2.1 - 2026-05-18
+
+- Added `channel recover-workspace --source rpc --output-raw` to append raw JSON-RPC request and response history
+  to method-specific JSON files under the channel workspace `rpcCallHistory/` directory, with `eth_getLogs` split by event.
+  Indexed recovery appends to existing history; `--from-genesis` overwrites it with one full genesis-to-latest scan.
+
 ## 2.2.0 - 2026-05-18
 
 - Added `install --read-only` for channel-state read commands and commands that do not depend on channel state. This

package/README.md

@@ -192,6 +192,12 @@ run is interrupted, the next non-`--from-genesis` RPC recovery resumes from the
 can also start from that local checkpoint: it uses a matching delta bundle when one is available, otherwise a newer
 verified full mirror checkpoint replaces the local checkpoint before RPC catch-up.
 
+Use `channel recover-workspace --source rpc --output-raw` when you need to preserve the raw JSON-RPC request and
+response history for inspection. The CLI appends calls to method-specific JSON files, and splits `eth_getLogs` into
+event-specific files such as `eth_getLogs.CurrentRootVectorObserved.json`, under
+`~/tokamak-private-channels/workspace/<network>/<channel>/channel/rpcCallHistory/`. Indexed recovery appends to the
+existing history, while `--from-genesis` overwrites it with one full genesis-to-latest scan.
+
 `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.
 

package/commands/system.mjs

@@ -1,6 +1,7 @@
 import {
   assertDoctorArgs,
   assertGuideArgs,
+  assertObserverArgs,
   assertInstallZkEvmArgs,
   assertSetRpcArgs,
   assertTransactionFeesArgs,
@@ -8,6 +9,7 @@ import {
   assertUpdateArgs,
   handleDoctor,
   handleGuide,
+  handleObserver,
   handleInstallZkEvm,
   handleSetRpc,
   handleTransactionFees,
@@ -41,6 +43,10 @@ export const systemCommands = Object.freeze({
     assertGuideArgs(args);
     await handleGuide({ args });
   },
+  "help-observer": async (args) => {
+    assertObserverArgs(args);
+    handleObserver();
+  },
   "help-transaction-fees": async (args) => {
     assertTransactionFeesArgs(args);
     const { network, provider, rpcUrl } = loadExplicitCommandRuntime(args);

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

@@ -202,6 +202,13 @@ export const PRIVATE_STATE_CLI_FIELD_CATALOG = Object.freeze({
     option: "--from-genesis",
     optional: true,
   },
+  outputRaw: {
+    label: "Output Raw RPC History",
+    type: "checkbox",
+    hint: "With channel recover-workspace --source rpc, preserve raw JSON-RPC request and response history under the channel workspace.",
+    option: "--output-raw",
+    optional: true,
+  },
   source: {
     label: "Recovery Source",
     type: "select",
@@ -322,6 +329,17 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     usage: "optional --network, --channel-name, --account, and --wallet",
     help: ["Does not accept --rpc-url and never writes RPC configuration"],
   },
+  {
+    id: "help-observer",
+    display: "help observer",
+    description: "Show the deployed public observer URL.",
+    fields: [],
+    usage: "no options",
+    help: [
+      "Prints the deployed observer URL so terminals can present it as a clickable link",
+      "The observer is a public monitoring surface; it is not a wallet, key manager, or disclosure authority",
+    ],
+  },
   {
     id: "help-transaction-fees",
     display: "help transaction-fees",
@@ -383,8 +401,8 @@ 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"],
-    usage: "--channel-name, --network, optional --source, optional --from-genesis",
+    fields: ["channelName", "network", "source", "fromGenesis", "outputRaw"],
+    usage: "--channel-name, --network, optional --source, optional --from-genesis, optional --output-raw",
     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",
@@ -392,6 +410,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
       "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",
+      "--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",
       "Prints RPC log scan progress while rebuilding the workspace",
     ],
@@ -731,7 +750,7 @@ export function privateStateCliCommandSynopsis(command) {
         return null;
       }
       const valueLabel = field.valueLabel ?? field.placeholderLabel ?? `<${field.label?.toUpperCase().replace(/\s+/g, "_") ?? "VALUE"}>`;
-      const option = field.type === "checkbox" || fieldKey === "fromGenesis"
+      const option = field.type === "checkbox"
         ? field.option
         : `${field.option} ${valueLabel}`;
       return field.optional || optionalFields.has(fieldKey) ? `[${option}]` : option;

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

@@ -108,10 +108,6 @@ function runCaptured(command, args, { cwd = defaultCommandCwd, env = process.env
   };
 }
 
-function requireSemverVersion(value, label) {
-  return requireExactSemverVersion(value, label);
-}
-
 function readTokamakCliPackageReport(packageRoot = null) {
   try {
     const resolvedPackageRoot = packageRoot ?? resolveActiveTokamakCliPackageRoot();
@@ -234,19 +230,17 @@ function buildDoctorHumanRows(report) {
       check: `${report.installManifest.mode} deployment artifacts`,
       status: doctorStatus(report.checks.find((check) => check.name === `${report.installManifest.mode} deployment artifacts`)?.ok),
       detail: [
-        `readOnlyChains=${report.deploymentArtifacts.chains
-          .filter((entry) => entry.modes[PRIVATE_STATE_INSTALL_MODES.READ_ONLY].ok)
-          .map((entry) => entry.chainId)
-          .join(",") || "none"}`,
-        `fullChains=${report.deploymentArtifacts.chains
-          .filter((entry) => entry.modes[PRIVATE_STATE_INSTALL_MODES.FULL].ok)
-          .map((entry) => entry.chainId)
-          .join(",") || "none"}`,
+        `readOnlyChains=${formatInstalledArtifactChains(report.deploymentArtifacts, PRIVATE_STATE_INSTALL_MODES.READ_ONLY)}`,
+        `fullChains=${formatInstalledArtifactChains(report.deploymentArtifacts, PRIVATE_STATE_INSTALL_MODES.FULL)}`,
       ].join(" "),
     },
   ];
 }
 
+function formatInstalledArtifactChains(artifactReadiness, mode) {
+  return installedArtifactChainIds(artifactReadiness, mode).join(",") || "none";
+}
+
 function formatDoctorTable(rows) {
   const headers = ["Check", "Status", "Detail"];
   const checkWidth = Math.max(headers[0].length, ...rows.map((row) => row.check.length));
@@ -660,19 +654,20 @@ function buildCommandAvailability({ artifactReadiness, installMode, tokamakCli,
       requiredInstallMode,
       available,
       chains: requiredInstallMode === PRIVATE_STATE_INSTALL_MODES.FULL
-        ? artifactReadiness.chains
-          .filter((entry) => entry.modes[PRIVATE_STATE_INSTALL_MODES.FULL].ok)
-          .map((entry) => entry.chainId)
-        : requiredInstallMode === PRIVATE_STATE_INSTALL_MODES.READ_ONLY
-          ? artifactReadiness.chains
-            .filter((entry) => entry.modes[PRIVATE_STATE_INSTALL_MODES.READ_ONLY].ok)
-            .map((entry) => entry.chainId)
-          : [],
+        || requiredInstallMode === PRIVATE_STATE_INSTALL_MODES.READ_ONLY
+        ? installedArtifactChainIds(artifactReadiness, requiredInstallMode)
+        : [],
       reasons,
     };
   });
 }
 
+function installedArtifactChainIds(artifactReadiness, mode) {
+  return artifactReadiness.chains
+    .filter((entry) => entry.modes[mode]?.ok)
+    .map((entry) => entry.chainId);
+}
+
 function buildSelectedRuntimeVersionCheck({ installManifest, installMode, tokamakCli, groth16Runtime }) {
   if (installMode === PRIVATE_STATE_INSTALL_MODES.READ_ONLY) {
     return {
@@ -752,16 +747,16 @@ async function resolveRequestedGroth16PackageVersion(requestedVersion) {
   }
 
   const bundledPackageJson = readJson(path.join(resolveGroth16PackageRoot(), "package.json"));
-  return requireSemverVersion(bundledPackageJson.version, `${GROTH16_PACKAGE_NAME} bundled package version`);
+  return requireExactSemverVersion(bundledPackageJson.version, `${GROTH16_PACKAGE_NAME} bundled package version`);
 }
 
 async function resolveRequestedNpmPackageVersion({ packageName, requestedVersion, optionName }) {
   const metadata = await fetchNpmPackageMetadata(packageName);
   if (requestedVersion === undefined || requestedVersion === null) {
-    return requireSemverVersion(metadata?.["dist-tags"]?.latest, `${packageName} npm latest version`);
+    return requireExactSemverVersion(metadata?.["dist-tags"]?.latest, `${packageName} npm latest version`);
   }
 
-  const normalizedVersion = requireSemverVersion(requestedVersion, optionName);
+  const normalizedVersion = requireExactSemverVersion(requestedVersion, optionName);
   if (!metadata.versions?.[normalizedVersion]) {
     throw new Error(`npm package ${packageName} does not contain version ${normalizedVersion}.`);
   }
@@ -832,7 +827,7 @@ async function installGroth16RuntimeForPrivateState({ version, docker }) {
 }
 
 function resolveGroth16RuntimePackageInstall(version) {
-  const normalizedVersion = requireSemverVersion(version, `${GROTH16_PACKAGE_NAME} version`);
+  const normalizedVersion = requireExactSemverVersion(version, `${GROTH16_PACKAGE_NAME} version`);
   const bundledPackageRoot = resolveGroth16PackageRoot();
   const bundledPackageJson = readJson(path.join(bundledPackageRoot, "package.json"));
   if (bundledPackageJson.name === GROTH16_PACKAGE_NAME && bundledPackageJson.version === normalizedVersion) {
@@ -930,7 +925,7 @@ function parseDriveFileIdFromDownloadUrl(value) {
 
 function installManagedNpmPackage({ packageName, version, cacheBaseRoot = resolveArtifactCacheBaseRoot() }) {
   const normalizedPackageName = requireNonEmptyString(packageName, "packageName");
-  const normalizedVersion = requireSemverVersion(version, `${normalizedPackageName} version`);
+  const normalizedVersion = requireExactSemverVersion(version, `${normalizedPackageName} version`);
   const installPrefix = managedNpmPackageInstallPrefix({
     packageName: normalizedPackageName,
     version: normalizedVersion,
@@ -965,7 +960,7 @@ function managedNpmPackageInstallPrefix({ packageName, version, cacheBaseRoot =
   const safePackageName = requireNonEmptyString(packageName, "packageName")
     .replace(/^@/, "")
     .replace(/[^A-Za-z0-9._-]+/g, "__");
-  return path.join(privateStateCliRuntimeRoot(cacheBaseRoot), "npm", safePackageName, requireSemverVersion(version, "version"));
+  return path.join(privateStateCliRuntimeRoot(cacheBaseRoot), "npm", safePackageName, requireExactSemverVersion(version, "version"));
 }
 
 async function downloadGroth16CrsArtifactsForPrivateState({

package/lib/runtime.mjs

@@ -52,6 +52,7 @@ import {
   deriveChannelTokenVaultLeafIndex,
   deriveLiquidBalanceStorageKey,
   fetchContractCodes,
+  getBlockInfoAt,
   normalizeBytesHex,
   normalizeBytes32Hex,
   serializeBigInts,
@@ -136,6 +137,7 @@ const PRIVATE_STATE_UNINSTALL_CONFIRMATION =
 const ACTION_IMPACT_CONFIRMATION =
   "I understand the public and private impact of this action";
 const PRIVATE_STATE_CLI_PACKAGE_NAME = privateStateCliPackageJson.name;
+const PRIVATE_STATE_OBSERVER_URL = "https://project-scw1r.vercel.app";
 const GROTH16_PACKAGE_NAME = "@tokamak-private-dapps/groth16";
 const TOKAMAK_ZKEVM_CLI_PACKAGE_NAME = "@tokamak-zk-evm/cli";
 const WALLET_BACKUP_EXPORT_FORMAT = "tokamak-private-state-wallet-backup-export";
@@ -554,25 +556,25 @@ function requireFlatDeploymentArtifactPathsForChainId(chainId) {
 }
 
 function requireInstalledDeploymentArtifacts(artifactPaths, chainId, mode) {
-  const requiredFiles = privateStateCliArtifactRequiredFiles(artifactPaths, mode);
-  try {
-    for (const entry of requiredFiles) {
-      if (!fs.existsSync(entry.path)) {
-        throw new Error(`Missing ${entry.label}: ${entry.path}.`);
-      }
-    }
-  } catch (error) {
-    throw cliError(
-      CLI_ERROR_CODES.MISSING_DEPLOYMENT_ARTIFACTS,
-      [
-        `Missing ${mode} installed deployment artifacts for chain ${chainId} under ${artifactPaths.rootDir}.`,
-        mode === PRIVATE_STATE_INSTALL_MODES.FULL
-          ? "Run install before running private-state CLI commands that write channel state."
-          : "Run install --read-only before running private-state CLI commands that read channel state.",
-        `Original error: ${error.message}`,
-      ].join(" "),
-    );
+  const missingFiles = missingInstalledDeploymentArtifactFiles(artifactPaths, mode);
+  if (missingFiles.length === 0) {
+    return;
   }
+  throw cliError(
+    CLI_ERROR_CODES.MISSING_DEPLOYMENT_ARTIFACTS,
+    [
+      `Missing ${mode} installed deployment artifacts for chain ${chainId} under ${artifactPaths.rootDir}.`,
+      mode === PRIVATE_STATE_INSTALL_MODES.FULL
+        ? "Run install before running private-state CLI commands that write channel state."
+        : "Run install --read-only before running private-state CLI commands that read channel state.",
+      `Original error: ${missingFiles.map((entry) => `Missing ${entry.label}: ${entry.path}.`).join(" ")}`,
+    ].join(" "),
+  );
+}
+
+function missingInstalledDeploymentArtifactFiles(artifactPaths, mode) {
+  return privateStateCliArtifactRequiredFiles(artifactPaths, mode)
+    .filter((entry) => !fs.existsSync(entry.path));
 }
 
 async function handleChannelCreate({ args, network, provider }) {
@@ -721,12 +723,14 @@ async function handleWorkspaceInit({ args, network, provider }) {
   const workspaceName = channelName;
   const bridgeResources = loadBridgeResources({ chainId: network.chainId });
   const recoverySource = resolveWorkspaceRecoverySource(args);
+  const outputRawRpcCallHistory = args.outputRaw === true;
 
   const {
     workspaceDir,
     workspace,
     currentSnapshot,
     cleanRebuildBackup,
+    rpcCallHistory,
   } = await syncChannelWorkspace({
     workspaceName,
     channelName,
@@ -738,6 +742,7 @@ async function handleWorkspaceInit({ args, network, provider }) {
     useWorkspaceRecoveryIndex: true,
     fromGenesis: args.fromGenesis === true,
     recoverySource,
+    outputRawRpcCallHistory,
     progressAction: "channel recover-workspace",
   });
 
@@ -757,6 +762,7 @@ async function handleWorkspaceInit({ args, network, provider }) {
     recoveryLastScannedBlock: workspace.recoveryLastScannedBlock,
     recoveryRootVectorHash: workspace.recoveryRootVectorHash,
     recoveryScanRange: workspace.recoveryScanRange,
+    rpcCallHistory,
     workspaceMirror: workspace.workspaceMirror ?? null,
   });
 }
@@ -1968,6 +1974,7 @@ async function syncChannelWorkspace({
   useWorkspaceRecoveryIndex = false,
   fromGenesis = false,
   recoverySource = "rpc",
+  outputRawRpcCallHistory = false,
   minimumToBlock = null,
   progressAction = null,
 }) {
@@ -1993,8 +2000,15 @@ async function syncChannelWorkspace({
     });
   }
 
+  const rpcCallHistoryRecorder = outputRawRpcCallHistory
+    ? createRpcCallHistoryRecorder({ workspaceDir })
+    : null;
+  const activeProvider = rpcCallHistoryRecorder
+    ? attachRpcCallHistoryRecorderToProvider(provider, rpcCallHistoryRecorder)
+    : provider;
+
   const { bridgeDeployment, bridgeAbiManifest } = bridgeResources;
-  const bridgeCore = new Contract(bridgeDeployment.bridgeCore, bridgeAbiManifest.contracts.bridgeCore.abi, provider);
+  const bridgeCore = new Contract(bridgeDeployment.bridgeCore, bridgeAbiManifest.contracts.bridgeCore.abi, activeProvider);
   const channelId = deriveChannelIdFromName(channelName);
   const channelInfo = await bridgeCore.getChannel(channelId);
   if (!channelInfo.exists) {
@@ -2004,13 +2018,13 @@ async function syncChannelWorkspace({
   const channelManager = new Contract(
     channelInfo.manager,
     bridgeAbiManifest.contracts.channelManager.abi,
-    provider,
+    activeProvider,
   );
   const canonicalAsset = getAddress(channelInfo.asset);
-  const canonicalAssetDecimals = await fetchTokenDecimals(provider, canonicalAsset);
+  const canonicalAssetDecimals = await fetchTokenDecimals(activeProvider, canonicalAsset);
   const currentRootVectorHash = normalizeBytes32Hex(await channelManager.currentRootVectorHash());
   const genesisBlockNumber = Number(await channelManager.genesisBlockNumber());
-  const observedLatestBlock = await provider.getBlockNumber();
+  const observedLatestBlock = await activeProvider.getBlockNumber();
   const latestBlock = minimumToBlock === null
     ? observedLatestBlock
     : Math.max(observedLatestBlock, Number(minimumToBlock));
@@ -2038,8 +2052,8 @@ async function syncChannelWorkspace({
     `Managed storage vector does not include L2 accounting vault ${l2AccountingVaultAddress}.`,
   );
 
-  const contractCodes = await fetchContractCodes(provider, managedStorageAddresses);
-  const blockInfo = await fetchChannelBlockInfo(provider, genesisBlockNumber);
+  const contractCodes = await fetchContractCodes(activeProvider, managedStorageAddresses);
+  const blockInfo = await getBlockInfoAt(activeProvider, genesisBlockNumber);
   const derivedAPubBlockHash = normalizeBytes32Hex(hashTokamakPublicInputs(encodeTokamakBlockInfo(blockInfo)));
   expect(
     ethers.toBigInt(derivedAPubBlockHash) === ethers.toBigInt(normalizeBytes32Hex(channelInfo.aPubBlockHash)),
@@ -2154,6 +2168,10 @@ async function syncChannelWorkspace({
       });
     }
     : null;
+  rpcCallHistoryRecorder?.setScanRange({
+    fromBlock: selectedRecoveryIndex?.nextBlock ?? genesisBlockNumber,
+    toBlock: latestBlock,
+  });
   const reconstruction = localSnapshotReusable
     ? {
       currentSnapshot: existingArtifacts.stateSnapshot,
@@ -2173,7 +2191,7 @@ async function syncChannelWorkspace({
         },
       }
     : await reconstructChannelSnapshot({
-      provider,
+      provider: activeProvider,
       bridgeAbiManifest,
       channelInfo,
       channelManager,
@@ -2190,7 +2208,9 @@ async function syncChannelWorkspace({
       toBlock: latestBlock,
       progressAction,
       onCheckpoint: persistWorkspaceCheckpoint,
+      rpcCallHistoryRecorder,
     });
+  rpcCallHistoryRecorder?.setScanRange(reconstruction.scanRange);
   const currentSnapshot = reconstruction.currentSnapshot;
   const workspace = buildWorkspaceForSnapshot({
     currentSnapshot,
@@ -2215,6 +2235,7 @@ async function syncChannelWorkspace({
     blockInfo,
     contractCodes,
     cleanRebuildBackup,
+    rpcCallHistory: rpcCallHistoryRecorder?.finish() ?? null,
   };
 }
 
@@ -2656,6 +2677,198 @@ function persistChannelWorkspaceFiles({
   writeJsonIfChanged(channelWorkspaceConfigPath(workspaceDir), workspace);
 }
 
+function channelWorkspaceRpcCallHistoryPath(workspaceDir) {
+  return path.join(channelDataPath(workspaceDir), "rpcCallHistory");
+}
+
+function createRpcCallHistoryRecorder({ workspaceDir }) {
+  const historyDir = channelWorkspaceRpcCallHistoryPath(workspaceDir);
+  const entriesByFile = new Map();
+  let scanRange = null;
+  let callCount = 0;
+  ensureDir(historyDir);
+
+  const pushEntry = ({ method, eventName = null, entry }) => {
+    const file = rpcCallHistoryFileName(method, eventName);
+    const entries = entriesByFile.get(file) ?? [];
+    entries.push({
+      method,
+      ...(eventName ? { event: eventName } : {}),
+      ...entry,
+    });
+    entriesByFile.set(file, entries);
+  };
+
+  return {
+    historyDir,
+    setScanRange(nextScanRange) {
+      scanRange = {
+        fromBlock: Number(nextScanRange.fromBlock),
+        toBlock: Number(nextScanRange.toBlock),
+        ...(nextScanRange.mode ? { mode: nextScanRange.mode } : {}),
+      };
+    },
+    recordRpcCall({ method, params, response, error = null }) {
+      if (method === "eth_getLogs") {
+        return;
+      }
+      callCount += 1;
+      pushEntry({
+        method,
+        entry: {
+          recordedAt: new Date().toISOString(),
+          request: buildRawJsonRpcRequest(method, params),
+          ...(error ? { error } : { response }),
+        },
+      });
+    },
+    recordEthGetLogs({ request, logs, groupedValues, chunkFromBlock, chunkToBlock }) {
+      callCount += 1;
+      const eventBuckets = groupRawEthGetLogsByRecoveryEvent({ logs, groupedValues });
+      for (const [eventName, response] of eventBuckets.entries()) {
+        pushEntry({
+          method: "eth_getLogs",
+          eventName,
+          entry: {
+            recordedAt: new Date().toISOString(),
+            chunkRange: { fromBlock: Number(chunkFromBlock), toBlock: Number(chunkToBlock) },
+            request: buildRawEthGetLogsRequest(request),
+            response,
+          },
+        });
+      }
+    },
+    finish() {
+      const files = [...entriesByFile.entries()].map(([file, entries]) =>
+        appendRpcCallHistoryEntries({
+          historyDir,
+          file,
+          entries: entries.map((entry) => ({ scanRange, ...entry })),
+        }));
+      return {
+        historyDir,
+        scanRange,
+        callCount,
+        files: files.sort((left, right) => left.file.localeCompare(right.file)),
+      };
+    },
+  };
+}
+
+function attachRpcCallHistoryRecorderToProvider(provider, recorder) {
+  const send = provider.send.bind(provider);
+  provider.send = async (method, params) => {
+    try {
+      const response = await send(method, params);
+      recorder.recordRpcCall({ method, params, response });
+      return response;
+    } catch (error) {
+      recorder.recordRpcCall({ method, params, error: normalizeRpcCallHistoryError(error) });
+      throw error;
+    }
+  };
+  return provider;
+}
+
+function normalizeRpcCallHistoryError(error) {
+  return {
+    name: error?.name ?? "Error",
+    code: error?.code ?? null,
+    message: error?.message ?? String(error),
+  };
+}
+
+function appendRpcCallHistoryEntries({ historyDir, file, entries }) {
+  const filePath = path.join(historyDir, file);
+  const { method, event: eventName = null } = entries[0];
+  const current = readJsonIfExists(filePath) ?? {
+    method,
+    ...(eventName ? { event: eventName } : {}),
+    entries: [],
+  };
+  expect(current.method === method, `RPC call history file method mismatch: ${filePath}.`);
+  expect(Array.isArray(current.entries), `RPC call history file entries must be an array: ${filePath}.`);
+  if (eventName) {
+    expect(current.event === eventName, `RPC call history file event mismatch: ${filePath}.`);
+  }
+  current.updatedAt = new Date().toISOString();
+  current.entries.push(...entries);
+  writeJson(filePath, current);
+  return {
+    method,
+    ...(eventName ? { event: eventName } : {}),
+    file,
+    path: filePath,
+    entriesAdded: entries.length,
+    totalEntries: current.entries.length,
+  };
+}
+
+function buildRawJsonRpcRequest(method, params = []) {
+  return {
+    jsonrpc: "2.0",
+    method,
+    params: params ?? [],
+  };
+}
+
+function rpcCallHistoryFileName(method, eventName = null) {
+  const suffix = eventName ? `.${safeRpcCallHistoryFileToken(eventName)}` : "";
+  return `${safeRpcCallHistoryFileToken(method)}${suffix}.json`;
+}
+
+function safeRpcCallHistoryFileToken(value) {
+  return String(value).replace(/[^A-Za-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "") || "unknown";
+}
+
+function groupRawEthGetLogsByRecoveryEvent({ logs, groupedValues }) {
+  if (logs.length === 0) {
+    return new Map([["noLogs", []]]);
+  }
+  const eventNamesByLog = new Map();
+  for (const group of groupedValues) {
+    for (const event of group) {
+      eventNamesByLog.set(recoveryLogHistoryKey(event), channelRecoveryEventName(event));
+    }
+  }
+  const buckets = new Map();
+  for (const log of logs) {
+    const eventName = eventNamesByLog.get(recoveryLogHistoryKey(log)) ?? "unknown";
+    const bucket = buckets.get(eventName) ?? [];
+    bucket.push(log);
+    buckets.set(eventName, bucket);
+  }
+  return buckets;
+}
+
+function recoveryLogHistoryKey(log) {
+  return `${normalizeBytes32Hex(log.transactionHash)}:${Number(log.index ?? log.logIndex)}`;
+}
+
+function channelRecoveryEventName(event) {
+  if (event.fragment?.name) {
+    return event.fragment.name;
+  }
+  const topic0 = event.topics[0] ? normalizeBytes32Hex(event.topics[0]) : null;
+  if (topic0 === normalizeBytes32Hex(CONTROLLER_STORAGE_KEY_OBSERVED_TOPIC)) {
+    return "StorageKeyObserved";
+  }
+  if (topic0 === normalizeBytes32Hex(VAULT_STORAGE_WRITE_OBSERVED_TOPIC)) {
+    return "LiquidBalanceStorageWriteObserved";
+  }
+  return "unknown";
+}
+
+function buildRawEthGetLogsRequest(request) {
+  const filter = {
+    address: request.address,
+    topics: request.topics,
+    fromBlock: ethers.toQuantity(request.fromBlock),
+    toBlock: ethers.toQuantity(request.toBlock),
+  };
+  return buildRawJsonRpcRequest("eth_getLogs", [filter]);
+}
+
 function nextAvailablePath(basePath) {
   if (!fs.existsSync(basePath)) {
     return basePath;
@@ -2866,6 +3079,18 @@ async function handleDoctor({ args }) {
   }
 }
 
+function handleObserver() {
+  printJson({
+    action: "observer",
+    url: PRIVATE_STATE_OBSERVER_URL,
+    scope: "Public monitoring observer for Tokamak Private App Channels and the private-state DApp.",
+    notes: [
+      "The observer helps users and reviewers inspect public monitoring surfaces.",
+      "The observer does not receive wallet secrets, spending keys, viewing keys, or private note plaintext.",
+    ],
+  });
+}
+
 function handleInvestigator() {
   const htmlPath = resolveInvestigatorIndexPath();
   const fileUrl = pathToFileURL(htmlPath).href;
@@ -3623,12 +3848,10 @@ function inspectGuideNetworkRuntime(networkName) {
 
 function inspectGuideDeploymentArtifacts(chainId) {
   const paths = privateStateCliArtifactPaths(resolveArtifactCacheBaseRoot(), chainId);
-  const readOnlyMissingFiles = privateStateCliArtifactRequiredFiles(paths, PRIVATE_STATE_INSTALL_MODES.READ_ONLY)
-    .map((entry) => entry.path)
-    .filter((filePath) => !fs.existsSync(filePath));
-  const fullMissingFiles = privateStateCliArtifactRequiredFiles(paths, PRIVATE_STATE_INSTALL_MODES.FULL)
-    .map((entry) => entry.path)
-    .filter((filePath) => !fs.existsSync(filePath));
+  const readOnlyMissingFiles = missingInstalledDeploymentArtifactFiles(paths, PRIVATE_STATE_INSTALL_MODES.READ_ONLY)
+    .map((entry) => entry.path);
+  const fullMissingFiles = missingInstalledDeploymentArtifactFiles(paths, PRIVATE_STATE_INSTALL_MODES.FULL)
+    .map((entry) => entry.path);
   return {
     installed: readOnlyMissingFiles.length === 0,
     readOnlyInstalled: readOnlyMissingFiles.length === 0,
@@ -8437,39 +8660,6 @@ function appendSplitWord(target, startIndex, value) {
   target[startIndex + 1] = normalized >> 128n;
 }
 
-async function fetchChannelBlockInfo(provider, blockNumber) {
-  const blockTag = ethers.toQuantity(blockNumber);
-  const block = await provider.send("eth_getBlockByNumber", [blockTag, false]);
-  if (!block) {
-    throw new Error(`Unable to fetch channel genesis block ${blockNumber}.`);
-  }
-
-  const prevBlockHashes = [];
-  for (let offset = 1; offset <= TOKAMAK_PREVIOUS_BLOCK_HASH_COUNT; offset += 1) {
-    if (blockNumber <= offset) {
-      prevBlockHashes.push("0x0");
-      continue;
-    }
-    const previousBlock = await provider.send("eth_getBlockByNumber", [ethers.toQuantity(blockNumber - offset), false]);
-    if (!previousBlock) {
-      throw new Error(`Unable to fetch previous block hash for block ${blockNumber - offset}.`);
-    }
-    prevBlockHashes.push(previousBlock.hash);
-  }
-
-  return {
-    coinBase: block.miner,
-    timeStamp: block.timestamp,
-    blockNumber: block.number,
-    prevRanDao: block.prevRandao ?? block.mixHash ?? block.difficulty ?? "0x0",
-    gasLimit: block.gasLimit,
-    chainId: await provider.send("eth_chainId", []),
-    selfBalance: "0x0",
-    baseFee: block.baseFeePerGas ?? "0x0",
-    prevBlockHashes,
-  };
-}
-
 async function fetchChannelRecoveryLogs({
   provider,
   bridgeAbiManifest,
@@ -8510,6 +8700,7 @@ async function fetchChannelRecoveryEventGroupsChunked({
   fromBlock,
   toBlock,
   progressAction = null,
+  rpcCallHistoryRecorder = null,
   onChunk,
 }) {
   const recoveryFilter = buildChannelRecoveryLogFilter({
@@ -8527,7 +8718,7 @@ async function fetchChannelRecoveryEventGroupsChunked({
     onProgress: progressAction
       ? createRpcLogScanProgress({ action: progressAction, label: "channel-recovery chunks" })
       : null,
-    onChunk: async ({ logs, chunkFromBlock, chunkToBlock }) => {
+    onChunk: async ({ request, logs, chunkFromBlock, chunkToBlock }) => {
       const groupedValues = normalizeWorkspaceMirrorDeltaEventGroups({
         logs,
         channelInfo,
@@ -8535,6 +8726,13 @@ async function fetchChannelRecoveryEventGroupsChunked({
         fromBlock: chunkFromBlock,
         toBlock: chunkToBlock,
       });
+      rpcCallHistoryRecorder?.recordEthGetLogs({
+        request,
+        logs,
+        groupedValues,
+        chunkFromBlock,
+        chunkToBlock,
+      });
       await onChunk?.({
         groupedValues,
         chunkFromBlock,
@@ -8591,6 +8789,7 @@ async function reconstructChannelSnapshot({
   toBlock = null,
   progressAction = null,
   onCheckpoint = null,
+  rpcCallHistoryRecorder = null,
 }) {
   let startingSnapshot = baseSnapshot;
   if (!startingSnapshot) {
@@ -8627,6 +8826,7 @@ async function reconstructChannelSnapshot({
     fromBlock: scanFromBlock,
     toBlock: latestBlock,
     progressAction,
+    rpcCallHistoryRecorder,
     onChunk: async ({ groupedValues, chunkFromBlock, chunkToBlock }) => {
       currentSnapshot = await applyChannelRecoveryEventGroupsToStateManager({
         stateManager,
@@ -8979,13 +9179,14 @@ async function fetchLogsChunked(provider, {
   while (cursor <= resolvedToBlock) {
     const chunkToBlock = Math.min(resolvedToBlock, cursor + chunkSize - 1);
     let logs;
+    const request = {
+      address,
+      topics,
+      fromBlock: cursor,
+      toBlock: chunkToBlock,
+    };
     try {
-      logs = await fetchLogsRateLimited(provider, {
-        address,
-        topics,
-        fromBlock: cursor,
-        toBlock: chunkToBlock,
-      });
+      logs = await fetchLogsRateLimited(provider, request);
     } catch (error) {
       throw buildRpcLogQueryConfigError({
         error,
@@ -9019,6 +9220,7 @@ async function fetchLogsChunked(provider, {
       totalBlocks,
       logsFound,
       chunkLogs: logs.length,
+      request,
       logs,
     });
     cursor = chunkToBlock + 1;
@@ -10066,6 +10268,10 @@ function assertGuideArgs(args) {
   assertAllowedCommandSchema(args, "help-guide");
 }
 
+function assertObserverArgs(args) {
+  assertAllowedCommandSchema(args, "help-observer");
+}
+
 function assertTransactionFeesArgs(args) {
   assertAllowedCommandSchema(args, "help-transaction-fees");
 }
@@ -10154,10 +10360,16 @@ function assertCreateChannelArgs(args) {
 
 function assertRecoverWorkspaceArgs(args) {
   assertAllowedCommandSchema(args, "channel-recover-workspace");
-  resolveWorkspaceRecoverySource(args);
+  const source = resolveWorkspaceRecoverySource(args);
   if (args.fromGenesis !== undefined && args.fromGenesis !== true) {
     throw new Error("channel recover-workspace option --from-genesis does not accept a value.");
   }
+  if (args.outputRaw !== undefined && args.outputRaw !== true) {
+    throw new Error("channel recover-workspace option --output-raw does not accept a value.");
+  }
+  if (args.outputRaw === true && source !== "rpc") {
+    throw new Error("channel recover-workspace option --output-raw requires --source rpc.");
+  }
 }
 
 function assertGetChannelArgs(args) {
@@ -11011,6 +11223,7 @@ function loadWalletCommandRuntime(args, { prepareArtifacts = false } = {}) {
 const HUMAN_RESULT_RENDERERS = Object.freeze({
   guide: printGuideHumanResult,
   investigator: printInvestigatorHumanResult,
+  observer: printObserverHumanResult,
   "transaction-fees": printTransactionFeesHumanResult,
   update: printUpdateHumanResult,
 });
@@ -11093,6 +11306,24 @@ function printInvestigatorHumanResult(result) {
   console.log(lines.join("\n"));
 }
 
+function printObserverHumanResult(result) {
+  const lines = [
+    "Private-State Public Observer",
+    `URL: ${formatHumanValue(result.url)}`,
+  ];
+  if (result.scope) {
+    lines.push(`Scope: ${formatHumanValue(result.scope)}`);
+  }
+  if (Array.isArray(result.notes) && result.notes.length > 0) {
+    lines.push(
+      "",
+      "Notes",
+      ...result.notes.map((note) => `- ${note}`),
+    );
+  }
+  console.log(lines.join("\n"));
+}
+
 function printTransactionFeesHumanResult(report) {
   const lines = [
     "Transaction Fees",
@@ -11505,6 +11736,7 @@ export {
   assertUpdateArgs,
   assertDoctorArgs,
   assertGuideArgs,
+  assertObserverArgs,
   assertTransactionFeesArgs,
   assertInvestigatorArgs,
   assertAccountGetL1AddressArgs,
@@ -11538,6 +11770,7 @@ export {
   handleUpdate,
   handleDoctor,
   handleGuide,
+  handleObserver,
   handleTransactionFees,
   handleInvestigator,
   handleAccountGetL1Address,

package/package.json

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