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

package/lib/runtime.mjs

@@ -82,9 +82,12 @@ import {
   installPrivateStateCliArtifacts,
   installTokamakCliRuntimeForPrivateState,
   inspectGroth16Runtime,
+  normalizeInstallMode,
   parseJsonReport,
   printDoctorHumanReport,
+  privateStateCliArtifactRequiredFiles,
   privateStateCliArtifactPaths,
+  PRIVATE_STATE_INSTALL_MODES,
   readTokamakCliPackageReport,
   requireActiveTokamakCliRuntimeRoot,
   resolveActiveGroth16ProverRuntime,
@@ -99,6 +102,7 @@ import {
   PRIVATE_STATE_CLI_COMMANDS,
   PRIVATE_STATE_CLI_FIELD_CATALOG,
   privateStateCliCommandDisplay,
+  privateStateCliCommandInstallMode,
   privateStateCliCommandOptionKeys,
   privateStateCliCommandRequiredOptionKeys,
   privateStateCliCommandSynopsis,
@@ -299,7 +303,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 +320,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 +476,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 +513,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,29 +553,22 @@ 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,
-  ];
+function requireInstalledDeploymentArtifacts(artifactPaths, chainId, mode) {
+  const requiredFiles = privateStateCliArtifactRequiredFiles(artifactPaths, mode);
   try {
-    for (const filePath of requiredFiles) {
-      if (!fs.existsSync(filePath)) {
-        throw new Error(`Missing ${filePath}.`);
+    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 installed deployment artifacts for chain ${chainId} under ${artifactPaths.rootDir}.`,
-        "Run install before running private-state CLI commands for this network.",
+        `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(" "),
     );
@@ -2450,22 +2461,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 +2498,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),
@@ -3435,15 +3458,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 +3479,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 +3501,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 +3520,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 +3623,20 @@ 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 = 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));
   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,
   };
 }
@@ -9976,6 +10002,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");
   }
@@ -10919,7 +10959,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 +10970,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 +10991,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 +11000,7 @@ function loadWalletCommandRuntime(args) {
   };
   const rpcConfig = resolveCommandRpcConfig(args);
   setActiveRpcLogConfig(rpcConfig);
+  if (prepareArtifacts) prepareDeploymentArtifactsForCommand(args.command, network.chainId);
   return {
     network,
     rpcConfig,
@@ -11525,7 +11567,6 @@ export {
   handleJoinChannel,
   loadExplicitCommandRuntime,
   loadWalletCommandRuntime,
-  prepareDeploymentArtifacts,
   assertProviderChainIdMatchesNetwork,
   formatCliErrorForDisplay,
 };

package/package.json

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