@tokamak-private-dapps/private-state-cli 0.1.5 → 0.1.8

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.1.8 - 2026-04-30
+
+- Reused common proof backend version helpers for Tokamak and Groth16 compatibility checks.
+- Reused common npm registry metadata lookup during proof backend runtime installation.
+
+## 0.1.7 - 2026-04-29
+
+- Required Groth16 channel verifier and installed CRS compatibility versions to use canonical major.minor form.
+- Matched Groth16 channel verifier compatibility against the installed CRS major.minor compatibility version.
+- Required the Groth16 package version with verified public CRS archive selection.
+- Required Tokamak zk-EVM channel verifier and CLI package compatibility versions to use canonical major.minor form.
+
+## 0.1.6 - 2026-04-29
+
+- Added `--groth16-cli-version` and `--tokamak-zk-evm-cli-version` install options with npm latest defaults.
+- Installed selected proof backend package versions into managed runtime directories.
+- Downloaded Groth16 CRS artifacts matching the selected Groth16 CLI version.
+- Checked channel verifier compatible backend versions before local proof generation.
+- Reported selected proof backend runtime versions from `--doctor`.
+
 ## 0.1.5 - 2026-04-28
 
 - Switched channel balance proof generation to invoke `tokamak-groth16 --prove` instead of importing Groth16 proof internals directly.

package/README.md

@@ -15,6 +15,18 @@ artifacts:
 private-state-cli --install
 ```
 
+By default, `--install` resolves the latest `@tokamak-zk-evm/cli` and `@tokamak-private-dapps/groth16` versions from
+the npm registry. To pin exact proof backend versions for a channel, pass explicit versions:
+
+```bash
+private-state-cli --install --tokamak-zk-evm-cli-version 2.0.8 --groth16-cli-version 0.1.1
+```
+
+The Groth16 installer downloads the public Google Drive CRS archive whose major.minor compatibility version matches the
+selected Groth16 CLI package version.
+The Tokamak zk-EVM installer requires the selected CLI package to declare
+`tokamakZkEvm.compatibleBackendVersion` as a canonical major.minor version matching the selected package version.
+
 `--install` downloads public deployment artifacts from the configured artifact index. It does not read repository-local
 `deployment/` outputs by default. Repository development workflows that need local anvil artifacts can opt in explicitly:
 
@@ -52,7 +64,7 @@ A common private-state flow is:
 Use `private-state-cli --help` for the full command list and required options.
 
 `private-state-cli --doctor` reports the CLI package version, dependency versions recorded by the last
-`private-state-cli --install`, current dependency versions through `tokamak-l2js`, and Tokamak zk-EVM runtime
+`private-state-cli --install`, selected proof backend runtime versions, current dependency versions through `tokamak-l2js`, and Tokamak zk-EVM runtime
 install mode, Docker mode, CUDA runtime metadata, live `nvidia-smi` and Docker GPU probe results, and Groth16
 runtime health. The doctor check fails when the Tokamak Docker `useGpus` metadata does not match the live GPU probes.
 
@@ -138,6 +150,8 @@ using bridge-facing commands on a new machine.
 Channel balance commands such as `deposit-channel` and `withdraw-channel` use the installed Groth16 runtime workspace
 directly. Proof generation writes to the fixed workspace paths under `~/tokamak-private-channels/groth16/proof`; the CLI
 does not pass custom `--zkey`, proof-output, or public-output paths to the Groth16 prover.
+Before proof generation, the CLI compares the target channel's verifier compatibility versions with the installed
+Tokamak zk-EVM and Groth16 major.minor compatibility versions.
 
 Release order matters for npm publication. `@tokamak-private-dapps/common-library` and
 `@tokamak-private-dapps/groth16` must be published before this package version.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamak-private-dapps/private-state-cli",
-  "version": "0.1.5",
+  "version": "0.1.8",
   "description": "Command-line client for the Tokamak private-state DApp.",
   "license": "MIT OR Apache-2.0",
   "author": "Tokamak Network",
@@ -41,10 +41,10 @@
   },
   "dependencies": {
     "@ethereumjs/util": "^10.1.1",
-    "@noble/curves": "^1.2.0",
-    "@tokamak-private-dapps/common-library": "^0.1.0",
-    "@tokamak-private-dapps/groth16": "^0.1.1",
-    "@tokamak-zk-evm/cli": "^2.0.8",
+    "@noble/curves": "1.9.7",
+    "@tokamak-private-dapps/common-library": "^0.1.1",
+    "@tokamak-private-dapps/groth16": "^0.1.4",
+    "@tokamak-zk-evm/cli": "^2.0.13",
     "ethers": "^6.14.1",
     "tokamak-l2js": "^0.1.3"
   },

package/private-state-bridge-cli.mjs

@@ -44,12 +44,17 @@ import {
   hexToBytes,
 } from "@ethereumjs/util";
 import { deriveRpcUrl, resolveCliNetwork } from "@tokamak-private-dapps/common-library/network-config";
+import { fetchNpmPackageMetadata } from "@tokamak-private-dapps/common-library/npm-registry";
+import {
+  normalizePackageVersionToCompatibleBackendVersion,
+  readTokamakZkEvmCompatibleBackendVersionFromPackageJson,
+  requireCanonicalCompatibleBackendVersion,
+  requireExactSemverVersion,
+} from "@tokamak-private-dapps/common-library/proof-backend-versioning";
 import {
-  buildTokamakCliInvocation,
   resolveTokamakBlockInputConfig,
-  resolveTokamakCliPackageRoot,
-  resolveTokamakCliResourceDir,
-  resolveTokamakCliRuntimeRoot,
+  resolveTokamakCliEntryPath,
+  resolveTokamakCliPackageRoot as resolveBundledTokamakCliPackageRoot,
 } from "@tokamak-private-dapps/common-library/tokamak-runtime-paths";
 import {
   DEFAULT_PUBLIC_ARTIFACT_INDEX_FILE_ID,
@@ -66,6 +71,9 @@ import { toGroth16SolidityProof } from "@tokamak-private-dapps/common-library/gr
 import {
   PUBLIC_GROTH16_MPC_DRIVE_FOLDER_ID,
   downloadLatestPublicGroth16MpcArtifacts,
+  downloadPublicGroth16MpcArtifactsByVersion,
+  readGroth16CompatibleBackendVersionFromPackageJson,
+  requireCanonicalGroth16CompatibleBackendVersion,
 } from "@tokamak-private-dapps/groth16/public-drive-crs";
 import {
   CHANNEL_BOUND_L2_DERIVATION_MODE,
@@ -85,17 +93,20 @@ const require = createRequire(import.meta.url);
 const defaultCommandCwd = process.cwd();
 const privateStateCliPackageRoot = path.dirname(require.resolve("./package.json"));
 const workspaceRoot = path.resolve(os.homedir(), "tokamak-private-channels", "workspace");
-const tokamakCliInvocation = buildTokamakCliInvocation();
-const tokamakCliCommand = tokamakCliInvocation.command;
-const tokamakCliBaseArgs = tokamakCliInvocation.args;
 const flatDeploymentArtifactPathsByChainId = new Map();
 const DOCKER_CUDA_PROBE_IMAGE = "nvidia/cuda:12.2.0-base-ubuntu22.04";
 const DOCTOR_GPU_PROBE_TIMEOUT_MS = 120000;
+const GROTH16_PACKAGE_NAME = "@tokamak-private-dapps/groth16";
+const TOKAMAK_ZKEVM_CLI_PACKAGE_NAME = "@tokamak-zk-evm/cli";
 
 const abiCoder = AbiCoder.defaultAbiCoder();
 const erc20MetadataAbi = [
   "function decimals() view returns (uint8)",
 ];
+const channelVerifierVersionAbi = [
+  "function grothVerifierCompatibleBackendVersion() view returns (string)",
+  "function tokamakVerifierCompatibleBackendVersion() view returns (string)",
+];
 const {
   aPubBlockLength: TOKAMAK_APUB_BLOCK_LENGTH,
   previousBlockHashCount: TOKAMAK_PREVIOUS_BLOCK_HASH_COUNT,
@@ -952,31 +963,36 @@ function clearWalletRecoveryArtifacts(walletDir) {
 }
 
 async function handleInstallZkEvm({ args }) {
-  const installArgs = [...tokamakCliBaseArgs, "--install"];
-  if (args.docker) {
-    installArgs.push("--docker");
-  }
-  run(tokamakCliCommand, installArgs);
-  const tokamakRuntimeRoot = resolveTokamakCliRuntimeRoot();
-  const groth16Runtime = installGroth16RuntimeForPrivateState({
+  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 localDeploymentBaseRoot = args.includeLocalArtifacts ? process.cwd() : null;
   const deploymentArtifacts = await installPrivateStateCliArtifacts({
     dappName: PRIVATE_STATE_DAPP_LABEL,
     localDeploymentBaseRoot,
+    groth16CrsVersion: groth16Runtime.compatibleBackendVersion,
   });
   const installManifest = writePrivateStateCliInstallManifest({
     dockerRequested: Boolean(args.docker),
     includeLocalArtifacts: Boolean(args.includeLocalArtifacts),
     localDeploymentBaseRoot,
     deploymentArtifacts,
+    selectedVersions,
+    tokamakCliRuntime,
     groth16Runtime,
   });
   printJson({
     action: "install",
-    tokamakCli: tokamakCliBaseArgs[0],
-    runtimeRoot: tokamakRuntimeRoot,
+    selectedVersions,
+    tokamakCli: tokamakCliRuntime.entryPath,
+    runtimeRoot: tokamakCliRuntime.runtimeRoot,
+    tokamakCliRuntime,
     groth16Runtime,
     docker: Boolean(args.docker),
     includeLocalArtifacts: Boolean(args.includeLocalArtifacts),
@@ -996,12 +1012,13 @@ async function handleInstallZkEvm({ args }) {
 
 async function handleUninstallZkEvm() {
   let runtimeRoot = null;
+  const invocation = buildTokamakCliInvocationForPackageRoot();
   try {
-    runtimeRoot = resolveTokamakCliRuntimeRoot();
+    runtimeRoot = inspectTokamakCliRuntime({ packageRoot: invocation.packageRoot }).runtimeRoot;
   } catch {
     runtimeRoot = null;
   }
-  run(tokamakCliCommand, [...tokamakCliBaseArgs, "--uninstall"]);
+  run(invocation.command, [...invocation.args, "--uninstall"], { cwd: invocation.packageRoot });
 
   printJson({
     action: "uninstall-zk-evm",
@@ -1309,10 +1326,16 @@ async function handleGrothVaultMove({ args, provider, direction }) {
   const contextResult = await loadPreferredWalletChannelContext({ walletContext, provider });
   const context = contextResult.context;
   const network = contextResult.network;
+  const operationName = args.command === "withdraw-channel"
+    ? "withdraw-channel"
+    : direction === "deposit"
+      ? "deposit-channel"
+      : "withdraw";
   expect(
     ethers.toBigInt(walletContext.wallet.channelId) === ethers.toBigInt(context.workspace.channelId),
     "The provided wallet does not belong to the selected channel.",
   );
+  await assertChannelProofBackendVersionCompatibility({ context, operationName });
 
   const { signer, l2Identity } = restoreWalletParticipant(walletContext, provider);
   const amountInput = requireArg(args.amount, "--amount");
@@ -1364,11 +1387,6 @@ async function handleGrothVaultMove({ args, provider, direction }) {
     nextValue = currentValue - amount;
   }
 
-  const operationName = args.command === "withdraw-channel"
-    ? "withdraw-channel"
-    : direction === "deposit"
-      ? "deposit-channel"
-      : "withdraw";
   const operationDir = createWalletOperationDir(
     walletContext.walletName,
     walletContext.wallet.network,
@@ -3057,6 +3075,7 @@ async function executeWalletTemplateSend({
 }) {
   await assertWorkspaceAlignedWithChain(context, signer.provider);
   assertWalletMatchesChannelContext(wallet, l2Identity, context);
+  await assertChannelProofBackendVersionCompatibility({ context, operationName });
 
   const controllerAbi = readJson(
     requireLatestDappDeployArtifactPath(context.workspace.chainId, path.basename(templatePayload.abiFile)),
@@ -3428,6 +3447,145 @@ async function assertWorkspaceAlignedWithChain(context) {
   );
 }
 
+async function assertChannelProofBackendVersionCompatibility({ context, operationName }) {
+  const channelVersions = await readChannelVerifierCompatibleBackendVersions(context);
+  const localVersions = readLocalProofBackendPackageVersions();
+  const checks = [
+    {
+      label: "Groth16",
+      packageName: GROTH16_PACKAGE_NAME,
+      versionKind: "compatible backend version",
+      channelVersion: requireCanonicalGroth16CompatibleBackendVersion(
+        channelVersions.groth16,
+        "channel Groth16 verifier compatibleBackendVersion",
+      ),
+      localVersion: localVersions.groth16.compatibleBackendVersion,
+    },
+    {
+      label: "Tokamak zk-EVM",
+      packageName: TOKAMAK_ZKEVM_CLI_PACKAGE_NAME,
+      versionKind: "compatible backend version",
+      channelVersion: requireCanonicalCompatibleBackendVersion(
+        channelVersions.tokamak,
+        "channel Tokamak verifier compatibleBackendVersion",
+      ),
+      localVersion: localVersions.tokamak.compatibleBackendVersion,
+    },
+  ];
+  const mismatches = checks.filter(({ channelVersion, localVersion }) => channelVersion !== localVersion);
+  if (mismatches.length === 0) {
+    return;
+  }
+
+  throw new Error(
+    [
+      `Channel proof backend version mismatch before ${operationName} proof generation.`,
+      `Channel: ${context.workspace.channelName ?? context.workspaceName ?? context.workspace.channelId}.`,
+      ...mismatches.map(({ label, packageName, versionKind, channelVersion, localVersion }) => (
+        `${label} verifier expects ${packageName} ${versionKind} ${channelVersion}, `
+          + `but the local installed ${versionKind} is ${localVersion ?? "<missing>"}.`
+      )),
+      "Install proof backend runtimes compatible with this channel before generating proofs.",
+    ].join(" "),
+  );
+}
+
+async function readChannelVerifierCompatibleBackendVersions(context) {
+  const channelManagerAddress = getAddress(context.workspace.channelManager);
+  const channelManager = new Contract(
+    channelManagerAddress,
+    channelVerifierVersionAbi,
+    context.channelManager.runner,
+  );
+  try {
+    const [groth16, tokamak] = await Promise.all([
+      channelManager.grothVerifierCompatibleBackendVersion(),
+      channelManager.tokamakVerifierCompatibleBackendVersion(),
+    ]);
+    return {
+      groth16: requireVersionString(groth16, "channel Groth16 verifier compatibleBackendVersion"),
+      tokamak: requireVersionString(tokamak, "channel Tokamak verifier compatibleBackendVersion"),
+    };
+  } catch (error) {
+    throw new Error(
+      [
+        `Unable to read verifier compatibleBackendVersion values from channel manager ${channelManagerAddress}.`,
+        "The target channel must expose grothVerifierCompatibleBackendVersion() and tokamakVerifierCompatibleBackendVersion().",
+      ].join(" "),
+      { cause: error },
+    );
+  }
+}
+
+function readLocalProofBackendPackageVersions() {
+  const groth16Runtime = inspectGroth16Runtime();
+  const tokamakPackageReport = readTokamakCliPackageReport();
+  return {
+    groth16: {
+      packageVersion: groth16Runtime.packageVersion,
+      compatibleBackendVersion: groth16Runtime.crsCompatibleBackendVersion
+        ?? groth16Runtime.compatibleBackendVersion,
+    },
+    tokamak: {
+      packageVersion: requirePackageReportVersion(tokamakPackageReport),
+      compatibleBackendVersion: requirePackageReportCompatibleBackendVersion(tokamakPackageReport),
+    },
+  };
+}
+
+function readTokamakCliPackageReport(packageRoot = null) {
+  try {
+    const resolvedPackageRoot = packageRoot ?? resolveActiveTokamakCliPackageRoot();
+    const packageJsonPath = path.join(resolvedPackageRoot, "package.json");
+    const packageJson = readJson(packageJsonPath);
+    const report = readPackageReport({
+      name: TOKAMAK_ZKEVM_CLI_PACKAGE_NAME,
+      packageJsonPath,
+      packageJson,
+    });
+    return {
+      ...report,
+      compatibleBackendVersion: readTokamakZkEvmCompatibleBackendVersionFromPackageJson(
+        packageJson,
+        TOKAMAK_ZKEVM_CLI_PACKAGE_NAME,
+      ),
+    };
+  } catch (error) {
+    return {
+      name: TOKAMAK_ZKEVM_CLI_PACKAGE_NAME,
+      version: null,
+      packageRoot: null,
+      compatibleBackendVersion: null,
+      error: error.message,
+      ok: false,
+    };
+  }
+}
+
+function requirePackageReportVersion(report) {
+  if (!report.version) {
+    throw new Error(
+      `Unable to determine local ${report.name} package version${report.error ? `: ${report.error}` : "."}`,
+    );
+  }
+  return requireVersionString(report.version, `${report.name} package version`);
+}
+
+function requirePackageReportCompatibleBackendVersion(report) {
+  if (!report.compatibleBackendVersion) {
+    throw new Error(
+      `Unable to determine local ${report.name} compatible backend version${report.error ? `: ${report.error}` : "."}`,
+    );
+  }
+  return requireVersionString(report.compatibleBackendVersion, `${report.name} compatible backend version`);
+}
+
+function requireVersionString(value, label) {
+  const normalized = String(value ?? "").trim();
+  expect(normalized.length > 0, `${label} is missing.`);
+  return normalized;
+}
+
 async function buildGrothTransition({ operationDir, workspace, stateManager, vaultAddress, keyHex, nextValue }) {
   const vaultAddressObj = createAddressFromString(vaultAddress);
   const keyBigInt = ethers.toBigInt(keyHex);
@@ -3504,7 +3662,7 @@ function runCaptured(command, args, { cwd = defaultCommandCwd, env = process.env
 }
 
 function runGroth16UpdateTreeProof(inputPath) {
-  const packageRoot = resolveGroth16PackageRoot();
+  const packageRoot = resolveActiveGroth16PackageRoot();
   const entryPath = resolveGroth16CliEntryPath(packageRoot);
   run(process.execPath, [entryPath, "--prove", inputPath], { cwd: packageRoot });
   const manifestPath = groth16ProofManifestPath();
@@ -3557,7 +3715,8 @@ function printLocalProofGenerationNotice(operationName) {
 }
 
 function runTokamakCliStage({ operationDir, stageName, args }) {
-  const result = runCaptured(tokamakCliCommand, [...tokamakCliBaseArgs, ...args]);
+  const invocation = buildTokamakCliInvocationForPackageRoot();
+  const result = runCaptured(invocation.command, [...invocation.args, ...args], { cwd: invocation.packageRoot });
   const logPath = writeTokamakCliStageLog(operationDir, stageName, result);
   if (result.status !== 0) {
     throw new Error(
@@ -3616,6 +3775,7 @@ function findTokamakConsoleError({ stdout, stderr }) {
 function copyTokamakOperationArtifacts(operationDir) {
   const resourceRoot = path.join(operationDir, "resource");
   fs.rmSync(resourceRoot, { recursive: true, force: true });
+  const runtimeRoot = requireActiveTokamakCliRuntimeRoot();
 
   const requiredFiles = [
     ["preprocess", "output", "preprocess.json"],
@@ -3625,7 +3785,7 @@ function copyTokamakOperationArtifacts(operationDir) {
   ];
 
   for (const segments of requiredFiles) {
-    const sourcePath = resolveTokamakCliResourceDir(...segments);
+    const sourcePath = resolveTokamakCliResourceDirForRuntimeRoot(runtimeRoot, ...segments);
     const targetPath = path.join(resourceRoot, ...segments);
     ensureDir(path.dirname(targetPath));
     fs.copyFileSync(sourcePath, targetPath);
@@ -3747,10 +3907,6 @@ function normalizeBytes16Hex(value) {
   return normalizeBytesHex(value, 16);
 }
 
-function normalizeBytes20Hex(value) {
-  return normalizeBytesHex(value, 20);
-}
-
 function normalizeBytes32Hex(hexValue) {
   return normalizeBytesHex(hexValue, 32);
 }
@@ -4589,9 +4745,23 @@ function assertInstallZkEvmArgs(args) {
   assertAllowedCommandKeys(
     args,
     "--install",
-    new Set(["command", "positional", "install", "docker", "includeLocalArtifacts"]),
-    "optional --docker and --include-local-artifacts",
+    new Set([
+      "command",
+      "positional",
+      "install",
+      "docker",
+      "includeLocalArtifacts",
+      "groth16CliVersion",
+      "tokamakZkEvmCliVersion",
+    ]),
+    "optional --docker, --include-local-artifacts, --groth16-cli-version, and --tokamak-zk-evm-cli-version",
   );
+  if (args.groth16CliVersion !== undefined) {
+    requireSemverVersion(args.groth16CliVersion, "--groth16-cli-version");
+  }
+  if (args.tokamakZkEvmCliVersion !== undefined) {
+    requireSemverVersion(args.tokamakZkEvmCliVersion, "--tokamak-zk-evm-cli-version");
+  }
 }
 
 function assertUninstallZkEvmArgs(args) {
@@ -4801,8 +4971,9 @@ function persistCurrentState(context) {
 function printHelp() {
   console.log(`
 Commands:
-  --install [--docker] [--include-local-artifacts]
+  --install [--docker] [--include-local-artifacts] [--groth16-cli-version <VERSION>] [--tokamak-zk-evm-cli-version <VERSION>]
       Install the Tokamak zk-EVM CLI runtime, Groth16 runtime, and private-state deployment artifacts
+      Version options install exact CLI package versions; omitted versions resolve to npm registry latest
       Use --docker on Linux to forward Docker mode to the Tokamak zk-EVM and Groth16 runtimes
       Use --include-local-artifacts to also install local deployment/ artifacts from the current working directory
 
@@ -5065,6 +5236,10 @@ function expect(condition, message) {
   }
 }
 
+function requireSemverVersion(value, label) {
+  return requireExactSemverVersion(value, label);
+}
+
 function resolveArtifactCacheBaseRoot(
   cacheBaseRoot = process.env.PRIVATE_STATE_ARTIFACT_CACHE_ROOT
     ?? process.env.TOKAMAK_PRIVATE_CHANNELS_ROOT
@@ -5077,6 +5252,10 @@ function privateStateCliArtifactRoot(cacheBaseRoot = resolveArtifactCacheBaseRoo
   return path.join(resolveArtifactCacheBaseRoot(cacheBaseRoot), "dapps", "private-state");
 }
 
+function privateStateCliRuntimeRoot(cacheBaseRoot = resolveArtifactCacheBaseRoot()) {
+  return path.join(privateStateCliArtifactRoot(cacheBaseRoot), "runtimes");
+}
+
 function privateStateCliArtifactChainDir(cacheBaseRoot = resolveArtifactCacheBaseRoot(), chainId) {
   return path.join(privateStateCliArtifactRoot(cacheBaseRoot), `chain-id-${requireChainId(chainId)}`);
 }
@@ -5101,11 +5280,17 @@ function privateStateCliInstallManifestPath(cacheBaseRoot = resolveArtifactCache
   return path.join(privateStateCliArtifactRoot(cacheBaseRoot), "install-manifest.json");
 }
 
+function readPrivateStateCliInstallManifest(cacheBaseRoot = resolveArtifactCacheBaseRoot()) {
+  return readJsonIfExists(privateStateCliInstallManifestPath(cacheBaseRoot));
+}
+
 function writePrivateStateCliInstallManifest({
   dockerRequested,
   includeLocalArtifacts,
   localDeploymentBaseRoot,
   deploymentArtifacts,
+  selectedVersions,
+  tokamakCliRuntime,
   groth16Runtime,
 }) {
   const manifestPath = privateStateCliInstallManifestPath(deploymentArtifacts.cacheBaseRoot);
@@ -5121,6 +5306,8 @@ function writePrivateStateCliInstallManifest({
       includeLocalArtifacts,
       localDeploymentBaseRoot,
       artifactCacheRoot: deploymentArtifacts.cacheBaseRoot,
+      selectedVersions,
+      tokamakCliRuntime,
       groth16Runtime,
       installedDeploymentArtifacts: deploymentArtifacts.installed.map((entry) => ({
         chainId: entry.chainId,
@@ -5149,6 +5336,11 @@ function buildDoctorReport() {
   const tokamakCli = inspectTokamakCliRuntime();
   const groth16Runtime = inspectGroth16Runtime();
   const gpuDockerReadiness = inspectGpuDockerReadiness(tokamakCli);
+  const selectedRuntimeVersionCheck = buildSelectedRuntimeVersionCheck({
+    installManifest,
+    tokamakCli,
+    groth16Runtime,
+  });
   const checks = [
     {
       name: "dependency package versions",
@@ -5161,6 +5353,7 @@ function buildDoctorReport() {
         error: entry.error,
       })),
     },
+    selectedRuntimeVersionCheck,
     {
       name: "tokamak zk-evm runtime",
       ok: tokamakCli.installed,
@@ -5214,6 +5407,9 @@ function buildDoctorReport() {
       installedAt: installManifest?.installedAt ?? null,
       dockerRequested: installManifest?.install?.dockerRequested ?? null,
       includeLocalArtifacts: installManifest?.install?.includeLocalArtifacts ?? null,
+      selectedVersions: installManifest?.install?.selectedVersions ?? null,
+      tokamakCliRuntime: installManifest?.install?.tokamakCliRuntime ?? null,
+      groth16Runtime: installManifest?.install?.groth16Runtime ?? null,
     },
     dependencies: dependencyReports,
     tokamakCli,
@@ -5223,17 +5419,221 @@ function buildDoctorReport() {
   };
 }
 
-function installGroth16RuntimeForPrivateState({ docker }) {
-  const packageRoot = resolveGroth16PackageRoot();
+function buildSelectedRuntimeVersionCheck({ installManifest, tokamakCli, groth16Runtime }) {
+  const selectedVersions = installManifest?.install?.selectedVersions ?? null;
+  const selectedTokamakCompatibleBackendVersion = selectedVersions?.tokamak
+    ? normalizePackageVersionToCompatibleBackendVersion(
+      selectedVersions.tokamak,
+      "selected Tokamak zk-EVM CLI version",
+    )
+    : null;
+  const selectedGroth16CompatibleBackendVersion = selectedVersions?.groth16
+    ? normalizePackageVersionToCompatibleBackendVersion(selectedVersions.groth16, "selected Groth16 CLI version")
+    : null;
+  const details = [
+    {
+      name: TOKAMAK_ZKEVM_CLI_PACKAGE_NAME,
+      selectedVersion: selectedVersions?.tokamak ?? null,
+      selectedCompatibleBackendVersion: selectedTokamakCompatibleBackendVersion,
+      installedVersion: tokamakCli.packageVersion ?? null,
+      compatibleBackendVersion: tokamakCli.compatibleBackendVersion ?? null,
+      ok: !selectedVersions?.tokamak
+        || (
+          selectedVersions.tokamak === tokamakCli.packageVersion
+          && selectedTokamakCompatibleBackendVersion === tokamakCli.compatibleBackendVersion
+        ),
+    },
+    {
+      name: GROTH16_PACKAGE_NAME,
+      selectedVersion: selectedVersions?.groth16 ?? null,
+      selectedCompatibleBackendVersion: selectedGroth16CompatibleBackendVersion,
+      installedVersion: groth16Runtime.packageVersion ?? null,
+      compatibleBackendVersion: groth16Runtime.compatibleBackendVersion ?? null,
+      crsVersion: groth16Runtime.crsVersion ?? null,
+      crsCompatibleBackendVersion: groth16Runtime.crsCompatibleBackendVersion ?? null,
+      ok: !selectedVersions?.groth16
+        || (
+          selectedVersions.groth16 === groth16Runtime.packageVersion
+          && selectedGroth16CompatibleBackendVersion === groth16Runtime.compatibleBackendVersion
+          && selectedGroth16CompatibleBackendVersion === groth16Runtime.crsCompatibleBackendVersion
+        ),
+    },
+  ];
+  return {
+    name: "selected proof backend runtime versions",
+    ok: details.every((entry) => entry.ok),
+    details,
+  };
+}
+
+async function resolvePrivateStateInstallRuntimeVersions(args) {
+  const [groth16, tokamak] = await Promise.all([
+    resolveRequestedNpmPackageVersion({
+      packageName: GROTH16_PACKAGE_NAME,
+      requestedVersion: args.groth16CliVersion,
+      optionName: "--groth16-cli-version",
+    }),
+    resolveRequestedNpmPackageVersion({
+      packageName: TOKAMAK_ZKEVM_CLI_PACKAGE_NAME,
+      requestedVersion: args.tokamakZkEvmCliVersion,
+      optionName: "--tokamak-zk-evm-cli-version",
+    }),
+  ]);
+  return { groth16, tokamak };
+}
+
+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`);
+  }
+
+  const normalizedVersion = requireSemverVersion(requestedVersion, optionName);
+  if (!metadata.versions?.[normalizedVersion]) {
+    throw new Error(`npm package ${packageName} does not contain version ${normalizedVersion}.`);
+  }
+  return normalizedVersion;
+}
+
+async function installTokamakCliRuntimeForPrivateState({ version, docker }) {
+  const packageInstall = installManagedNpmPackage({
+    packageName: TOKAMAK_ZKEVM_CLI_PACKAGE_NAME,
+    version,
+  });
+  const invocation = buildTokamakCliInvocationForPackageRoot(packageInstall.packageRoot);
+  const installArgs = [...invocation.args, "--install"];
+  if (docker) {
+    installArgs.push("--docker");
+  }
+  run(invocation.command, installArgs, { cwd: packageInstall.packageRoot });
+  const doctor = runCaptured(invocation.command, [...invocation.args, "--doctor"], {
+    cwd: packageInstall.packageRoot,
+  });
+  const doctorOutput = stripAnsi(`${doctor.stdout}${doctor.stderr}`);
+  const runtimeRoot = parseRuntimeRootFromTokamakDoctorOutput(doctorOutput);
+  const compatibleBackendVersion = readTokamakCliPackageCompatibleBackendVersion(packageInstall.packageRoot);
+  expect(
+    doctor.status === 0 && runtimeRoot,
+    [
+      "Tokamak zk-EVM CLI install completed, but tokamak-cli --doctor did not report a healthy runtime.",
+      doctorOutput.trim(),
+    ].filter(Boolean).join(" "),
+  );
+  return {
+    packageName: TOKAMAK_ZKEVM_CLI_PACKAGE_NAME,
+    packageVersion: version,
+    compatibleBackendVersion,
+    packageRoot: packageInstall.packageRoot,
+    entryPath: invocation.entryPath,
+    installPrefix: packageInstall.installPrefix,
+    runtimeRoot,
+    dockerRequested: Boolean(docker),
+  };
+}
+
+async function installGroth16RuntimeForPrivateState({ version, docker }) {
+  const packageInstall = installManagedNpmPackage({
+    packageName: GROTH16_PACKAGE_NAME,
+    version,
+  });
+  const packageRoot = packageInstall.packageRoot;
   const entryPath = resolveGroth16CliEntryPath(packageRoot);
-  const args = [entryPath, "--install"];
+  const args = [entryPath, "--install", "--no-setup"];
   if (docker) {
     args.push("--docker");
   }
   run(process.execPath, args, { cwd: packageRoot });
-  const runtime = inspectGroth16Runtime();
+  const compatibleBackendVersion = readGroth16PackageCompatibleBackendVersion(packageRoot);
+  const crsInstall = await installGroth16CrsForPrivateStateVersion(compatibleBackendVersion);
+  const runtime = inspectGroth16Runtime({ packageRoot });
   expect(runtime.installed, "Groth16 runtime install completed, but tokamak-groth16 --doctor still reports an unhealthy runtime.");
-  return runtime;
+  return {
+    ...runtime,
+    packageName: GROTH16_PACKAGE_NAME,
+    packageVersion: version,
+    compatibleBackendVersion,
+    packageRoot,
+    entryPath,
+    installPrefix: packageInstall.installPrefix,
+    crsVersion: crsInstall.version,
+    crs: crsInstall,
+    dockerRequested: Boolean(docker),
+  };
+}
+
+async function installGroth16CrsForPrivateStateVersion(version) {
+  const workspaceRoot = defaultGroth16WorkspaceRoot();
+  const crsDir = path.join(workspaceRoot, "crs");
+  const crsInstall = await downloadPublicGroth16MpcArtifactsByVersion({
+    version,
+    outputDir: crsDir,
+    selectedFiles: [
+      "circuit_final.zkey",
+      "verification_key.json",
+      "metadata.json",
+      "zkey_provenance.json",
+    ],
+  });
+  const manifestPath = path.join(workspaceRoot, "install-manifest.json");
+  const manifest = readJsonIfExists(manifestPath) ?? {};
+  writeJson(manifestPath, {
+    ...manifest,
+    workspaceRoot,
+    crsSource: "public-drive-mpc",
+    crs: crsInstall,
+  });
+  return crsInstall;
+}
+
+function installManagedNpmPackage({ packageName, version, cacheBaseRoot = resolveArtifactCacheBaseRoot() }) {
+  const normalizedPackageName = requireNonEmptyString(packageName, "packageName");
+  const normalizedVersion = requireSemverVersion(version, `${normalizedPackageName} version`);
+  const installPrefix = managedNpmPackageInstallPrefix({
+    packageName: normalizedPackageName,
+    version: normalizedVersion,
+    cacheBaseRoot,
+  });
+  fs.mkdirSync(installPrefix, { recursive: true });
+  run("npm", [
+    "install",
+    "--prefix",
+    installPrefix,
+    "--omit=dev",
+    "--no-audit",
+    "--fund=false",
+    `${normalizedPackageName}@${normalizedVersion}`,
+  ]);
+  const packageRoot = path.join(installPrefix, "node_modules", ...normalizedPackageName.split("/"));
+  const packageJsonPath = path.join(packageRoot, "package.json");
+  const packageJson = readJson(packageJsonPath);
+  expect(
+    packageJson.name === normalizedPackageName && packageJson.version === normalizedVersion,
+    `Installed package ${packageJsonPath} does not match ${normalizedPackageName}@${normalizedVersion}.`,
+  );
+  return {
+    packageName: normalizedPackageName,
+    version: normalizedVersion,
+    installPrefix,
+    packageRoot,
+  };
+}
+
+function managedNpmPackageInstallPrefix({ packageName, version, cacheBaseRoot = resolveArtifactCacheBaseRoot() }) {
+  const safePackageName = requireNonEmptyString(packageName, "packageName")
+    .replace(/^@/, "")
+    .replace(/[^A-Za-z0-9._-]+/g, "__");
+  return path.join(privateStateCliRuntimeRoot(cacheBaseRoot), "npm", safePackageName, requireSemverVersion(version, "version"));
+}
+
+async function downloadGroth16CrsArtifactsForPrivateState({
+  version,
+  outputDir,
+  selectedFiles,
+}) {
+  if (version === undefined || version === null) {
+    return downloadLatestPublicGroth16MpcArtifacts({ outputDir, selectedFiles });
+  }
+  return downloadPublicGroth16MpcArtifactsByVersion({ version, outputDir, selectedFiles });
 }
 
 function collectDependencyPackageReports(installManifest = null) {
@@ -5244,11 +5644,11 @@ function collectDependencyPackageReports(installManifest = null) {
   );
   const targets = [
     {
-      name: "@tokamak-zk-evm/cli",
-      packageJsonPath: path.join(resolveTokamakCliPackageRoot(), "package.json"),
+      name: TOKAMAK_ZKEVM_CLI_PACKAGE_NAME,
+      packageJsonPath: path.join(resolveBundledTokamakCliPackageRoot(), "package.json"),
     },
     {
-      name: "@tokamak-private-dapps/groth16",
+      name: GROTH16_PACKAGE_NAME,
       resolveTarget: "@tokamak-private-dapps/groth16/public-drive-crs",
     },
     {
@@ -5269,15 +5669,15 @@ function collectDependencyPackageReports(installManifest = null) {
   });
 }
 
-function readPackageReport({ name, packageJsonPath = null, resolveTarget = null }) {
+function readPackageReport({ name, packageJsonPath = null, packageJson = null, resolveTarget = null }) {
   try {
     const resolvedPackageJsonPath = packageJsonPath
       ? path.resolve(packageJsonPath)
       : findPackageJsonForName(path.dirname(require.resolve(resolveTarget ?? name)), name);
-    const packageJson = readJson(resolvedPackageJsonPath);
+    const resolvedPackageJson = packageJson ?? readJson(resolvedPackageJsonPath);
     return {
-      name: packageJson.name ?? name,
-      version: packageJson.version ?? null,
+      name: resolvedPackageJson.name ?? name,
+      version: resolvedPackageJson.version ?? null,
       packageRoot: path.dirname(resolvedPackageJsonPath),
       error: null,
     };
@@ -5312,21 +5712,63 @@ function resolveGroth16PackageRoot() {
   return path.dirname(findPackageJsonForName(path.dirname(publicDriveCrsPath), "@tokamak-private-dapps/groth16"));
 }
 
+function readGroth16PackageCompatibleBackendVersion(packageRoot = resolveActiveGroth16PackageRoot()) {
+  return readGroth16CompatibleBackendVersionFromPackageJson(
+    readJson(path.join(packageRoot, "package.json")),
+    GROTH16_PACKAGE_NAME,
+  );
+}
+
+function readTokamakCliPackageCompatibleBackendVersion(packageRoot = resolveActiveTokamakCliPackageRoot()) {
+  return readTokamakZkEvmCompatibleBackendVersionFromPackageJson(
+    readJson(path.join(packageRoot, "package.json")),
+    TOKAMAK_ZKEVM_CLI_PACKAGE_NAME,
+  );
+}
+
+function resolveActiveGroth16PackageRoot() {
+  const manifestPackageRoot = readPrivateStateCliInstallManifest()?.install?.groth16Runtime?.packageRoot;
+  if (manifestPackageRoot && fs.existsSync(path.join(manifestPackageRoot, "package.json"))) {
+    return manifestPackageRoot;
+  }
+  return resolveGroth16PackageRoot();
+}
+
 function resolveGroth16CliEntryPath(packageRoot = resolveGroth16PackageRoot()) {
   return path.join(packageRoot, "cli", "tokamak-groth16-cli.mjs");
 }
 
-function inspectGroth16Runtime() {
-  const packageRoot = resolveGroth16PackageRoot();
+function defaultGroth16WorkspaceRoot() {
+  return path.join(os.homedir(), "tokamak-private-channels", "groth16");
+}
+
+function inspectGroth16Runtime({ packageRoot = resolveActiveGroth16PackageRoot() } = {}) {
   const entryPath = resolveGroth16CliEntryPath(packageRoot);
   const doctor = runCaptured(process.execPath, [entryPath, "--doctor", "--verbose"], { cwd: packageRoot });
   const stdout = stripAnsi(doctor.stdout).trim();
   const stderr = stripAnsi(doctor.stderr).trim();
   const report = parseJsonReport(stdout);
+  const workspaceRoot = report?.workspaceRoot ?? defaultGroth16WorkspaceRoot();
+  const workspaceManifest = readJsonIfExists(path.join(workspaceRoot, "install-manifest.json"));
+  const crsVersion = workspaceManifest?.crs?.version ?? null;
+  const packageReport = readPackageReport({
+    name: GROTH16_PACKAGE_NAME,
+    packageJsonPath: path.join(packageRoot, "package.json"),
+  });
+  const compatibleBackendVersion = readGroth16PackageCompatibleBackendVersion(packageRoot);
+  const crsCompatibleBackendVersion = crsVersion
+    ? requireCanonicalGroth16CompatibleBackendVersion(crsVersion, "installed Groth16 CRS version")
+    : null;
   return {
     installed: doctor.status === 0 && report?.ok === true,
+    packageVersion: packageReport.version,
+    compatibleBackendVersion,
     packageRoot,
+    entryPath,
     workspaceRoot: report?.workspaceRoot ?? null,
+    crsVersion,
+    crsCompatibleBackendVersion,
+    crs: workspaceManifest?.crs ?? null,
     checks: report?.checks ?? [],
     doctor: {
       status: doctor.status,
@@ -5336,9 +5778,42 @@ function inspectGroth16Runtime() {
   };
 }
 
-function inspectTokamakCliRuntime() {
-  const doctor = runCaptured(tokamakCliCommand, [...tokamakCliBaseArgs, "--doctor"], {
-    cwd: resolveTokamakCliPackageRoot(),
+function resolveActiveTokamakCliPackageRoot() {
+  const manifestPackageRoot = readPrivateStateCliInstallManifest()?.install?.tokamakCliRuntime?.packageRoot;
+  if (manifestPackageRoot && fs.existsSync(path.join(manifestPackageRoot, "package.json"))) {
+    return manifestPackageRoot;
+  }
+  return resolveBundledTokamakCliPackageRoot();
+}
+
+function buildTokamakCliInvocationForPackageRoot(packageRoot = resolveActiveTokamakCliPackageRoot()) {
+  const resolvedPackageRoot = path.resolve(packageRoot);
+  const entryPath = resolvedPackageRoot === resolveBundledTokamakCliPackageRoot()
+    ? resolveTokamakCliEntryPath()
+    : path.join(resolvedPackageRoot, "dist", "cli.js");
+  return {
+    command: process.execPath,
+    args: [entryPath],
+    entryPath,
+    packageRoot: resolvedPackageRoot,
+  };
+}
+
+function resolveTokamakCliResourceDirForRuntimeRoot(runtimeRoot, ...segments) {
+  return path.join(runtimeRoot, "resource", ...segments);
+}
+
+function requireActiveTokamakCliRuntimeRoot() {
+  const runtime = inspectTokamakCliRuntime();
+  expect(runtime.runtimeRoot, "Unable to resolve the installed Tokamak zk-EVM runtime root. Run --install first.");
+  return runtime.runtimeRoot;
+}
+
+function inspectTokamakCliRuntime({ packageRoot = resolveActiveTokamakCliPackageRoot() } = {}) {
+  const invocation = buildTokamakCliInvocationForPackageRoot(packageRoot);
+  const packageReport = readTokamakCliPackageReport(invocation.packageRoot);
+  const doctor = runCaptured(invocation.command, [...invocation.args, "--doctor"], {
+    cwd: invocation.packageRoot,
   });
   const doctorOutput = stripAnsi(`${doctor.stdout}${doctor.stderr}`);
   const runtimeRoot = parseRuntimeRootFromTokamakDoctorOutput(doctorOutput);
@@ -5349,13 +5824,13 @@ function inspectTokamakCliRuntime() {
 
   return {
     installed: doctor.status === 0 || installations.length > 0,
-    packageRoot: resolveTokamakCliPackageRoot(),
+    packageRoot: invocation.packageRoot,
+    entryPath: invocation.entryPath,
     cacheRoot,
     runtimeRoot,
-    packageVersion: readPackageReport({
-      name: "@tokamak-zk-evm/cli",
-      packageJsonPath: path.join(resolveTokamakCliPackageRoot(), "package.json"),
-    }).version,
+    packageVersion: packageReport.version,
+    compatibleBackendVersion: packageReport.compatibleBackendVersion,
+    packageError: packageReport.error,
     dockerModeInstalled,
     cudaCompatible,
     doctor: {
@@ -5495,6 +5970,7 @@ async function installPrivateStateCliArtifacts({
   cacheBaseRoot,
   localDeploymentBaseRoot,
   localChainIds = [31337],
+  groth16CrsVersion,
 } = {}) {
   const normalizedDappName = requireNonEmptyString(dappName, "dappName");
   const normalizedCacheBaseRoot = resolveArtifactCacheBaseRoot(cacheBaseRoot);
@@ -5515,6 +5991,7 @@ async function installPrivateStateCliArtifacts({
       dappName: normalizedDappName,
       cacheBaseRoot: normalizedCacheBaseRoot,
       source: "drive",
+      groth16CrsVersion,
     }));
   }
 
@@ -5525,6 +6002,7 @@ async function installPrivateStateCliArtifacts({
         dappName: normalizedDappName,
         cacheBaseRoot: normalizedCacheBaseRoot,
         localDeploymentBaseRoot: normalizedLocalDeploymentBaseRoot,
+        groth16CrsVersion,
       }));
     }
   }
@@ -5546,6 +6024,7 @@ async function materializePrivateStateCliDeployment({
   dappName,
   cacheBaseRoot,
   source,
+  groth16CrsVersion,
 }) {
   const normalizedChainId = String(requireChainId(chainId));
   const normalizedDappName = requireNonEmptyString(dappName, "dappName");
@@ -5577,7 +6056,8 @@ async function materializePrivateStateCliDeployment({
       [`groth16.${normalizedChainId}.latest.json`, path.basename(paths.grothManifestPath)],
     ],
   });
-  await downloadLatestPublicGroth16MpcArtifacts({
+  await downloadGroth16CrsArtifactsForPrivateState({
+    version: groth16CrsVersion,
     outputDir: paths.rootDir,
     selectedFiles: [
       ["circuit_final.zkey", path.basename(paths.grothZkeyPath)],
@@ -5609,6 +6089,7 @@ async function materializeLocalPrivateStateCliDeployment({
   dappName,
   cacheBaseRoot,
   localDeploymentBaseRoot,
+  groth16CrsVersion,
 }) {
   const normalizedChainId = String(requireChainId(chainId));
   const normalizedDappName = requireNonEmptyString(dappName, "dappName");
@@ -5645,7 +6126,8 @@ async function materializeLocalPrivateStateCliDeployment({
       [path.join(dappDir, `dapp-registration.${normalizedChainId}.json`), path.basename(paths.dappRegistrationPath)],
     ],
   });
-  await downloadLatestPublicGroth16MpcArtifacts({
+  await downloadGroth16CrsArtifactsForPrivateState({
+    version: groth16CrsVersion,
     outputDir: paths.rootDir,
     selectedFiles: [
       ["circuit_final.zkey", path.basename(paths.grothZkeyPath)],