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

package/lib/runtime.mjs

@@ -52,6 +52,7 @@ import {
   deriveChannelTokenVaultLeafIndex,
   deriveLiquidBalanceStorageKey,
   fetchContractCodes,
+  getBlockInfoAt,
   normalizeBytesHex,
   normalizeBytes32Hex,
   serializeBigInts,
@@ -82,9 +83,12 @@ import {
   installPrivateStateCliArtifacts,
   installTokamakCliRuntimeForPrivateState,
   inspectGroth16Runtime,
+  normalizeInstallMode,
   parseJsonReport,
   printDoctorHumanReport,
+  privateStateCliArtifactRequiredFiles,
   privateStateCliArtifactPaths,
+  PRIVATE_STATE_INSTALL_MODES,
   readTokamakCliPackageReport,
   requireActiveTokamakCliRuntimeRoot,
   resolveActiveGroth16ProverRuntime,
@@ -99,6 +103,7 @@ import {
   PRIVATE_STATE_CLI_COMMANDS,
   PRIVATE_STATE_CLI_FIELD_CATALOG,
   privateStateCliCommandDisplay,
+  privateStateCliCommandInstallMode,
   privateStateCliCommandOptionKeys,
   privateStateCliCommandRequiredOptionKeys,
   privateStateCliCommandSynopsis,
@@ -299,7 +304,7 @@ const ACTION_IMPACT_SUMMARIES = Object.freeze({
       "No private note owner, value, salt, counterparty, or note provenance is created by this action.",
     ],
     noteProvenance: "Not applicable for this bridge-edge action.",
-    cexWarning: "Do not use a centralized-exchange controlled address as a self-custody bridge source.",
+    exchangeControlledAddressWarning: "Do not use an exchange-controlled address as a self-custody bridge source.",
     policy: "No channel policy is accepted by this action.",
   },
   "account-withdraw-bridge": {
@@ -316,7 +321,7 @@ const ACTION_IMPACT_SUMMARIES = Object.freeze({
       "The private note path that produced any prior channel balance is not reconstructed from this event alone.",
     ],
     noteProvenance: "Public observers cannot reconstruct prior internal note provenance from this withdrawal alone.",
-    cexWarning: "Do not use a centralized-exchange deposit address as the direct bridge withdrawal target unless the user has explicitly accepted the compliance implications. Prefer a self-custody L1 wallet.",
+    exchangeControlledAddressWarning: "Do not use an exchange deposit address as the direct bridge withdrawal target unless the user has explicitly accepted the compliance implications. Prefer a self-custody L1 wallet.",
     policy: "No channel policy is accepted by this action.",
   },
   "channel-join": {
@@ -472,8 +477,8 @@ function printActionImpactSummary(summary, details) {
     `- Secret recovery: Losing wallet secrets, viewing keys, or spending keys can prevent note discovery or note use. The CLI cannot recover lost secrets.`,
     `- Channel policy: ${summary.policy}`,
   ];
-  if (summary.cexWarning) {
-    lines.push(`- CEX address warning: ${summary.cexWarning}`);
+  if (summary.exchangeControlledAddressWarning) {
+    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"));
@@ -509,22 +514,36 @@ function normalizeDAppPolicySnapshot({
   };
 }
 
-async function prepareDeploymentArtifacts(chainId) {
+function prepareDeploymentArtifacts(chainId, { mode = PRIVATE_STATE_INSTALL_MODES.FULL } = {}) {
   const normalizedChainId = Number(chainId);
-  const existingPaths = flatDeploymentArtifactPathsByChainId.get(normalizedChainId);
-  if (existingPaths) {
-    return existingPaths.rootDir;
+  const normalizedMode = normalizeInstallMode(mode);
+  const existingEntry = flatDeploymentArtifactPathsByChainId.get(normalizedChainId);
+  if (existingEntry?.preparedModes.has(normalizedMode)) {
+    return existingEntry.paths.rootDir;
   }
 
   const cacheBaseRoot = resolveArtifactCacheBaseRoot();
-  const artifactPaths = privateStateCliArtifactPaths(cacheBaseRoot, normalizedChainId);
-  requireInstalledDeploymentArtifacts(artifactPaths, normalizedChainId);
-  flatDeploymentArtifactPathsByChainId.set(normalizedChainId, artifactPaths);
+  const artifactPaths = existingEntry?.paths ?? privateStateCliArtifactPaths(cacheBaseRoot, normalizedChainId);
+  requireInstalledDeploymentArtifacts(artifactPaths, normalizedChainId, normalizedMode);
+  const preparedModes = existingEntry?.preparedModes ?? new Set();
+  preparedModes.add(normalizedMode);
+  flatDeploymentArtifactPathsByChainId.set(normalizedChainId, {
+    paths: artifactPaths,
+    preparedModes,
+  });
   return artifactPaths.rootDir;
 }
 
+function prepareDeploymentArtifactsForCommand(commandId, chainId) {
+  const command = PRIVATE_STATE_CLI_COMMANDS.find((entry) => entry.id === commandId);
+  expect(command, `Missing CLI command metadata for ${commandId}.`);
+  const mode = privateStateCliCommandInstallMode(command);
+  expect(mode !== "none", `${privateStateCliCommandDisplay(command)} does not require installed deployment artifacts.`);
+  return prepareDeploymentArtifacts(chainId, { mode });
+}
+
 function flatDeploymentArtifactPathsForChainId(chainId) {
-  return flatDeploymentArtifactPathsByChainId.get(Number(chainId)) ?? null;
+  return flatDeploymentArtifactPathsByChainId.get(Number(chainId))?.paths ?? null;
 }
 
 function requireFlatDeploymentArtifactPathsForChainId(chainId) {
@@ -535,33 +554,26 @@ function requireFlatDeploymentArtifactPathsForChainId(chainId) {
   return paths;
 }
 
-function requireInstalledDeploymentArtifacts(artifactPaths, chainId) {
-  const requiredFiles = [
-    artifactPaths.bridgeDeploymentPath,
-    artifactPaths.bridgeAbiManifestPath,
-    artifactPaths.grothManifestPath,
-    artifactPaths.grothZkeyPath,
-    artifactPaths.dappDeploymentPath,
-    artifactPaths.dappStorageLayoutPath,
-    artifactPaths.privateStateControllerAbiPath,
-    artifactPaths.dappRegistrationPath,
-  ];
-  try {
-    for (const filePath of requiredFiles) {
-      if (!fs.existsSync(filePath)) {
-        throw new Error(`Missing ${filePath}.`);
-      }
-    }
-  } catch (error) {
-    throw cliError(
-      CLI_ERROR_CODES.MISSING_DEPLOYMENT_ARTIFACTS,
-      [
-        `Missing installed deployment artifacts for chain ${chainId} under ${artifactPaths.rootDir}.`,
-        "Run install before running private-state CLI commands for this network.",
-        `Original error: ${error.message}`,
-      ].join(" "),
-    );
+function requireInstalledDeploymentArtifacts(artifactPaths, chainId, mode) {
+  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 }) {
@@ -710,12 +722,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,
@@ -727,6 +741,7 @@ async function handleWorkspaceInit({ args, network, provider }) {
     useWorkspaceRecoveryIndex: true,
     fromGenesis: args.fromGenesis === true,
     recoverySource,
+    outputRawRpcCallHistory,
     progressAction: "channel recover-workspace",
   });
 
@@ -746,6 +761,7 @@ async function handleWorkspaceInit({ args, network, provider }) {
     recoveryLastScannedBlock: workspace.recoveryLastScannedBlock,
     recoveryRootVectorHash: workspace.recoveryRootVectorHash,
     recoveryScanRange: workspace.recoveryScanRange,
+    rpcCallHistory,
     workspaceMirror: workspace.workspaceMirror ?? null,
   });
 }
@@ -1957,6 +1973,7 @@ async function syncChannelWorkspace({
   useWorkspaceRecoveryIndex = false,
   fromGenesis = false,
   recoverySource = "rpc",
+  outputRawRpcCallHistory = false,
   minimumToBlock = null,
   progressAction = null,
 }) {
@@ -1982,8 +1999,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) {
@@ -1993,13 +2017,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));
@@ -2027,8 +2051,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)),
@@ -2143,6 +2167,10 @@ async function syncChannelWorkspace({
       });
     }
     : null;
+  rpcCallHistoryRecorder?.setScanRange({
+    fromBlock: selectedRecoveryIndex?.nextBlock ?? genesisBlockNumber,
+    toBlock: latestBlock,
+  });
   const reconstruction = localSnapshotReusable
     ? {
       currentSnapshot: existingArtifacts.stateSnapshot,
@@ -2162,7 +2190,7 @@ async function syncChannelWorkspace({
         },
       }
     : await reconstructChannelSnapshot({
-      provider,
+      provider: activeProvider,
       bridgeAbiManifest,
       channelInfo,
       channelManager,
@@ -2179,7 +2207,9 @@ async function syncChannelWorkspace({
       toBlock: latestBlock,
       progressAction,
       onCheckpoint: persistWorkspaceCheckpoint,
+      rpcCallHistoryRecorder,
     });
+  rpcCallHistoryRecorder?.setScanRange(reconstruction.scanRange);
   const currentSnapshot = reconstruction.currentSnapshot;
   const workspace = buildWorkspaceForSnapshot({
     currentSnapshot,
@@ -2204,6 +2234,7 @@ async function syncChannelWorkspace({
     blockInfo,
     contractCodes,
     cleanRebuildBackup,
+    rpcCallHistory: rpcCallHistoryRecorder?.finish() ?? null,
   };
 }
 
@@ -2450,22 +2481,33 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
 }
 
 async function handleInstallZkEvm({ args }) {
-  const selectedVersions = await resolvePrivateStateInstallRuntimeVersions(args);
-  const tokamakCliRuntime = await installTokamakCliRuntimeForPrivateState({
-    version: selectedVersions.tokamak,
-    docker: Boolean(args.docker),
-  });
-  const groth16Runtime = await installGroth16RuntimeForPrivateState({
-    version: selectedVersions.groth16,
-    docker: Boolean(args.docker),
-  });
+  const installMode = args.readOnly === true
+    ? PRIVATE_STATE_INSTALL_MODES.READ_ONLY
+    : PRIVATE_STATE_INSTALL_MODES.FULL;
+  const selectedVersions = installMode === PRIVATE_STATE_INSTALL_MODES.FULL
+    ? await resolvePrivateStateInstallRuntimeVersions(args)
+    : null;
+  const tokamakCliRuntime = installMode === PRIVATE_STATE_INSTALL_MODES.FULL
+    ? await installTokamakCliRuntimeForPrivateState({
+      version: selectedVersions.tokamak,
+      docker: Boolean(args.docker),
+    })
+    : null;
+  const groth16Runtime = installMode === PRIVATE_STATE_INSTALL_MODES.FULL
+    ? await installGroth16RuntimeForPrivateState({
+      version: selectedVersions.groth16,
+      docker: Boolean(args.docker),
+    })
+    : null;
   const localDeploymentBaseRoot = args.includeLocalArtifacts ? process.cwd() : null;
   const deploymentArtifacts = await installPrivateStateCliArtifacts({
     dappName: PRIVATE_STATE_DAPP_LABEL,
+    installMode,
     localDeploymentBaseRoot,
-    groth16CrsVersion: groth16Runtime.compatibleBackendVersion,
+    groth16CrsVersion: groth16Runtime?.compatibleBackendVersion ?? null,
   });
   const installManifest = writePrivateStateCliInstallManifest({
+    installMode,
     dockerRequested: Boolean(args.docker),
     includeLocalArtifacts: Boolean(args.includeLocalArtifacts),
     localDeploymentBaseRoot,
@@ -2476,9 +2518,10 @@ async function handleInstallZkEvm({ args }) {
   });
   printJson({
     action: "install",
+    installMode,
     selectedVersions,
-    tokamakCli: tokamakCliRuntime.entryPath,
-    runtimeRoot: tokamakCliRuntime.runtimeRoot,
+    tokamakCli: tokamakCliRuntime?.entryPath ?? null,
+    runtimeRoot: tokamakCliRuntime?.runtimeRoot ?? null,
     tokamakCliRuntime,
     groth16Runtime,
     docker: Boolean(args.docker),
@@ -2633,6 +2676,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;
@@ -3435,15 +3670,19 @@ async function handleGuide({ args }) {
   guide.state.deploymentArtifacts = artifactState;
   guide.checks.push(guideCheck(
     "installed deployment artifacts",
-    artifactState.installed ? "ok" : "missing",
+    artifactState.readOnlyInstalled ? "ok" : "missing",
     {
       chainId: networkRuntime.network.chainId,
       rootDir: artifactState.rootDir,
-      missingFiles: artifactState.missingFiles,
+      missingFiles: artifactState.readOnlyMissingFiles,
+      fullMissingFiles: artifactState.fullMissingFiles,
     },
   ));
-  if (artifactState.installed) {
-    flatDeploymentArtifactPathsByChainId.set(Number(networkRuntime.network.chainId), artifactState.paths);
+  if (artifactState.readOnlyInstalled) {
+    flatDeploymentArtifactPathsByChainId.set(Number(networkRuntime.network.chainId), {
+      paths: artifactState.paths,
+      preparedModes: new Set([PRIVATE_STATE_INSTALL_MODES.READ_ONLY]),
+    });
   }
 
   const provider = networkRuntime.provider;
@@ -3452,7 +3691,7 @@ async function handleGuide({ args }) {
       channelName: String(args.channelName),
       network: networkRuntime.network,
       provider,
-      artifactsInstalled: artifactState.installed,
+      artifactsInstalled: artifactState.readOnlyInstalled,
     });
     guide.checks.push(guideCheck(
       "channel",
@@ -3474,7 +3713,7 @@ async function handleGuide({ args }) {
       networkName,
       network: networkRuntime.network,
       provider,
-      artifactsInstalled: artifactState.installed,
+      artifactsInstalled: artifactState.readOnlyInstalled,
     });
     guide.checks.push(guideCheck(
       "local account secret",
@@ -3493,7 +3732,7 @@ async function handleGuide({ args }) {
       walletName: String(args.wallet),
       networkName,
       provider,
-      artifactsInstalled: artifactState.installed,
+      artifactsInstalled: artifactState.readOnlyInstalled,
     });
     guide.checks.push(guideCheck(
       "local wallet",
@@ -3596,21 +3835,18 @@ function inspectGuideNetworkRuntime(networkName) {
 
 function inspectGuideDeploymentArtifacts(chainId) {
   const paths = privateStateCliArtifactPaths(resolveArtifactCacheBaseRoot(), chainId);
-  const requiredFiles = [
-    paths.bridgeDeploymentPath,
-    paths.bridgeAbiManifestPath,
-    paths.grothManifestPath,
-    paths.grothZkeyPath,
-    paths.dappDeploymentPath,
-    paths.dappStorageLayoutPath,
-    paths.privateStateControllerAbiPath,
-    paths.dappRegistrationPath,
-  ];
-  const missingFiles = requiredFiles.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: missingFiles.length === 0,
+    installed: readOnlyMissingFiles.length === 0,
+    readOnlyInstalled: readOnlyMissingFiles.length === 0,
+    fullInstalled: fullMissingFiles.length === 0,
     rootDir: paths.rootDir,
-    missingFiles,
+    missingFiles: readOnlyMissingFiles,
+    readOnlyMissingFiles,
+    fullMissingFiles,
     paths,
   };
 }
@@ -8411,39 +8647,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,
@@ -8484,6 +8687,7 @@ async function fetchChannelRecoveryEventGroupsChunked({
   fromBlock,
   toBlock,
   progressAction = null,
+  rpcCallHistoryRecorder = null,
   onChunk,
 }) {
   const recoveryFilter = buildChannelRecoveryLogFilter({
@@ -8501,7 +8705,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,
@@ -8509,6 +8713,13 @@ async function fetchChannelRecoveryEventGroupsChunked({
         fromBlock: chunkFromBlock,
         toBlock: chunkToBlock,
       });
+      rpcCallHistoryRecorder?.recordEthGetLogs({
+        request,
+        logs,
+        groupedValues,
+        chunkFromBlock,
+        chunkToBlock,
+      });
       await onChunk?.({
         groupedValues,
         chunkFromBlock,
@@ -8565,6 +8776,7 @@ async function reconstructChannelSnapshot({
   toBlock = null,
   progressAction = null,
   onCheckpoint = null,
+  rpcCallHistoryRecorder = null,
 }) {
   let startingSnapshot = baseSnapshot;
   if (!startingSnapshot) {
@@ -8601,6 +8813,7 @@ async function reconstructChannelSnapshot({
     fromBlock: scanFromBlock,
     toBlock: latestBlock,
     progressAction,
+    rpcCallHistoryRecorder,
     onChunk: async ({ groupedValues, chunkFromBlock, chunkToBlock }) => {
       currentSnapshot = await applyChannelRecoveryEventGroupsToStateManager({
         stateManager,
@@ -8953,13 +9166,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,
@@ -8993,6 +9207,7 @@ async function fetchLogsChunked(provider, {
       totalBlocks,
       logsFound,
       chunkLogs: logs.length,
+      request,
       logs,
     });
     cursor = chunkToBlock + 1;
@@ -9976,6 +10191,20 @@ function assertWalletChannelMoveArgs(args, commandName) {
 
 function assertInstallZkEvmArgs(args) {
   assertAllowedCommandSchema(args, "install");
+  if (args.readOnly !== undefined && args.readOnly !== true) {
+    throw new Error("install option --read-only does not accept a value.");
+  }
+  if (args.readOnly === true && args.docker !== undefined) {
+    throw new Error("install --read-only does not accept --docker because proof runtimes are not installed.");
+  }
+  if (args.readOnly === true && args.groth16CliVersion !== undefined) {
+    throw new Error("install --read-only does not accept --groth16-cli-version because Groth16 is not installed.");
+  }
+  if (args.readOnly === true && args.tokamakZkEvmCliVersion !== undefined) {
+    throw new Error(
+      "install --read-only does not accept --tokamak-zk-evm-cli-version because Tokamak zk-EVM is not installed.",
+    );
+  }
   if (args.groth16CliVersion !== undefined) {
     requireSemverVersion(args.groth16CliVersion, "--groth16-cli-version");
   }
@@ -10114,10 +10343,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) {
@@ -10919,7 +11154,7 @@ function ensureDir(dirPath) {
   fs.mkdirSync(dirPath, { recursive: true });
 }
 
-function loadExplicitCommandRuntime(args, { staticNetwork = false } = {}) {
+function loadExplicitCommandRuntime(args, { staticNetwork = false, prepareArtifacts = false } = {}) {
   const networkName = requireNetworkName(args);
   const network = {
     ...resolveCliNetwork(networkName),
@@ -10930,6 +11165,7 @@ function loadExplicitCommandRuntime(args, { staticNetwork = false } = {}) {
   const provider = staticNetwork
     ? new JsonRpcProvider(rpcConfig.rpcUrl, Number(network.chainId), { staticNetwork: true })
     : new JsonRpcProvider(rpcConfig.rpcUrl);
+  if (prepareArtifacts) prepareDeploymentArtifactsForCommand(args.command, network.chainId);
   return {
     network,
     rpcUrl: rpcConfig.rpcUrl,
@@ -10950,7 +11186,7 @@ async function assertProviderChainIdMatchesNetwork({ provider, network, rpcUrl }
   );
 }
 
-function loadWalletCommandRuntime(args) {
+function loadWalletCommandRuntime(args, { prepareArtifacts = false } = {}) {
   const networkName = requireNetworkName(args);
   loadWalletMetadata(requireWalletName(args), networkName);
   const network = {
@@ -10959,6 +11195,7 @@ function loadWalletCommandRuntime(args) {
   };
   const rpcConfig = resolveCommandRpcConfig(args);
   setActiveRpcLogConfig(rpcConfig);
+  if (prepareArtifacts) prepareDeploymentArtifactsForCommand(args.command, network.chainId);
   return {
     network,
     rpcConfig,
@@ -11525,7 +11762,6 @@ export {
   handleJoinChannel,
   loadExplicitCommandRuntime,
   loadWalletCommandRuntime,
-  prepareDeploymentArtifacts,
   assertProviderChainIdMatchesNetwork,
   formatCliErrorForDisplay,
 };