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

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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.

package/README.md

@@ -22,7 +22,10 @@ the npm registry. To pin exact proof backend versions for a channel, pass explic
 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 with the same version as the selected Groth16 CLI.
+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:
@@ -147,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.6",
+  "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.2",
-    "@tokamak-zk-evm/cli": "^2.0.12",
+    "@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,6 +44,13 @@ 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 {
   resolveTokamakBlockInputConfig,
   resolveTokamakCliEntryPath,
@@ -65,6 +72,8 @@ 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,
@@ -967,7 +976,7 @@ async function handleInstallZkEvm({ args }) {
   const deploymentArtifacts = await installPrivateStateCliArtifacts({
     dappName: PRIVATE_STATE_DAPP_LABEL,
     localDeploymentBaseRoot,
-    groth16CrsVersion: selectedVersions.groth16,
+    groth16CrsVersion: groth16Runtime.compatibleBackendVersion,
   });
   const installManifest = writePrivateStateCliInstallManifest({
     dockerRequested: Boolean(args.docker),
@@ -3445,14 +3454,22 @@ async function assertChannelProofBackendVersionCompatibility({ context, operatio
     {
       label: "Groth16",
       packageName: GROTH16_PACKAGE_NAME,
-      channelVersion: channelVersions.groth16,
-      localVersion: localVersions.groth16,
+      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,
-      channelVersion: channelVersions.tokamak,
-      localVersion: localVersions.tokamak,
+      versionKind: "compatible backend version",
+      channelVersion: requireCanonicalCompatibleBackendVersion(
+        channelVersions.tokamak,
+        "channel Tokamak verifier compatibleBackendVersion",
+      ),
+      localVersion: localVersions.tokamak.compatibleBackendVersion,
     },
   ];
   const mismatches = checks.filter(({ channelVersion, localVersion }) => channelVersion !== localVersion);
@@ -3464,10 +3481,11 @@ async function assertChannelProofBackendVersionCompatibility({ context, operatio
     [
       `Channel proof backend version mismatch before ${operationName} proof generation.`,
       `Channel: ${context.workspace.channelName ?? context.workspaceName ?? context.workspace.channelId}.`,
-      ...mismatches.map(({ label, packageName, channelVersion, localVersion }) => (
-        `${label} verifier expects ${packageName} ${channelVersion}, but the local installed package version is ${localVersion}.`
+      ...mismatches.map(({ label, packageName, versionKind, channelVersion, localVersion }) => (
+        `${label} verifier expects ${packageName} ${versionKind} ${channelVersion}, `
+          + `but the local installed ${versionKind} is ${localVersion ?? "<missing>"}.`
       )),
-      "Install the matching CLI package versions before generating proofs for this channel.",
+      "Install proof backend runtimes compatible with this channel before generating proofs.",
     ].join(" "),
   );
 }
@@ -3500,28 +3518,44 @@ async function readChannelVerifierCompatibleBackendVersions(context) {
 }
 
 function readLocalProofBackendPackageVersions() {
+  const groth16Runtime = inspectGroth16Runtime();
+  const tokamakPackageReport = readTokamakCliPackageReport();
   return {
-    groth16: requirePackageReportVersion(
-      readPackageReport({
-        name: GROTH16_PACKAGE_NAME,
-        packageJsonPath: path.join(resolveActiveGroth16PackageRoot(), "package.json"),
-      }),
-    ),
-    tokamak: requirePackageReportVersion(readTokamakCliPackageReport()),
+    groth16: {
+      packageVersion: groth16Runtime.packageVersion,
+      compatibleBackendVersion: groth16Runtime.crsCompatibleBackendVersion
+        ?? groth16Runtime.compatibleBackendVersion,
+    },
+    tokamak: {
+      packageVersion: requirePackageReportVersion(tokamakPackageReport),
+      compatibleBackendVersion: requirePackageReportCompatibleBackendVersion(tokamakPackageReport),
+    },
   };
 }
 
-function readTokamakCliPackageReport() {
+function readTokamakCliPackageReport(packageRoot = null) {
   try {
-    return readPackageReport({
+    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: path.join(resolveActiveTokamakCliPackageRoot(), "package.json"),
+      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,
     };
@@ -3537,6 +3571,15 @@ function requirePackageReportVersion(report) {
   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.`);
@@ -3864,10 +3907,6 @@ function normalizeBytes16Hex(value) {
   return normalizeBytesHex(value, 16);
 }
 
-function normalizeBytes20Hex(value) {
-  return normalizeBytesHex(value, 20);
-}
-
 function normalizeBytes32Hex(hexValue) {
   return normalizeBytesHex(hexValue, 32);
 }
@@ -5198,11 +5237,7 @@ function expect(condition, message) {
 }
 
 function requireSemverVersion(value, label) {
-  const normalized = requireNonEmptyString(value, label);
-  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.]+)?(?:\+[0-9A-Za-z.]+)?$/.test(normalized)) {
-    throw new Error(`${label} must be an exact semantic version. Received: ${normalized}`);
-  }
-  return normalized;
+  return requireExactSemverVersion(value, label);
 }
 
 function resolveArtifactCacheBaseRoot(
@@ -5386,22 +5421,41 @@ function buildDoctorReport() {
 
 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,
-      ok: !selectedVersions?.tokamak || selectedVersions.tokamak === tokamakCli.packageVersion,
+      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
-          && selectedVersions.groth16 === groth16Runtime.crsVersion
+          && selectedGroth16CompatibleBackendVersion === groth16Runtime.compatibleBackendVersion
+          && selectedGroth16CompatibleBackendVersion === groth16Runtime.crsCompatibleBackendVersion
         ),
     },
   ];
@@ -5441,20 +5495,6 @@ async function resolveRequestedNpmPackageVersion({ packageName, requestedVersion
   return normalizedVersion;
 }
 
-async function fetchNpmPackageMetadata(packageName) {
-  const normalizedPackageName = requireNonEmptyString(packageName, "packageName");
-  const registryUrl = `https://registry.npmjs.org/${encodeURIComponent(normalizedPackageName)}`;
-  const response = await fetch(registryUrl, { redirect: "follow" });
-  if (!response.ok) {
-    throw new Error(`Failed to read npm package metadata for ${normalizedPackageName}: HTTP ${response.status}.`);
-  }
-  try {
-    return await response.json();
-  } catch (error) {
-    throw new Error(`npm package metadata for ${normalizedPackageName} is not valid JSON: ${error.message}`);
-  }
-}
-
 async function installTokamakCliRuntimeForPrivateState({ version, docker }) {
   const packageInstall = installManagedNpmPackage({
     packageName: TOKAMAK_ZKEVM_CLI_PACKAGE_NAME,
@@ -5471,6 +5511,7 @@ async function installTokamakCliRuntimeForPrivateState({ version, docker }) {
   });
   const doctorOutput = stripAnsi(`${doctor.stdout}${doctor.stderr}`);
   const runtimeRoot = parseRuntimeRootFromTokamakDoctorOutput(doctorOutput);
+  const compatibleBackendVersion = readTokamakCliPackageCompatibleBackendVersion(packageInstall.packageRoot);
   expect(
     doctor.status === 0 && runtimeRoot,
     [
@@ -5481,6 +5522,7 @@ async function installTokamakCliRuntimeForPrivateState({ version, docker }) {
   return {
     packageName: TOKAMAK_ZKEVM_CLI_PACKAGE_NAME,
     packageVersion: version,
+    compatibleBackendVersion,
     packageRoot: packageInstall.packageRoot,
     entryPath: invocation.entryPath,
     installPrefix: packageInstall.installPrefix,
@@ -5501,13 +5543,15 @@ async function installGroth16RuntimeForPrivateState({ version, docker }) {
     args.push("--docker");
   }
   run(process.execPath, args, { cwd: packageRoot });
-  const crsInstall = await installGroth16CrsForPrivateStateVersion(version);
+  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,
     packageName: GROTH16_PACKAGE_NAME,
     packageVersion: version,
+    compatibleBackendVersion,
     packageRoot,
     entryPath,
     installPrefix: packageInstall.installPrefix,
@@ -5625,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,
     };
@@ -5668,6 +5712,20 @@ 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"))) {
@@ -5692,17 +5750,24 @@ function inspectGroth16Runtime({ packageRoot = resolveActiveGroth16PackageRoot()
   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: workspaceManifest?.crs?.version ?? null,
+    crsVersion,
+    crsCompatibleBackendVersion,
     crs: workspaceManifest?.crs ?? null,
     checks: report?.checks ?? [],
     doctor: {
@@ -5746,6 +5811,7 @@ function requireActiveTokamakCliRuntimeRoot() {
 
 function inspectTokamakCliRuntime({ packageRoot = resolveActiveTokamakCliPackageRoot() } = {}) {
   const invocation = buildTokamakCliInvocationForPackageRoot(packageRoot);
+  const packageReport = readTokamakCliPackageReport(invocation.packageRoot);
   const doctor = runCaptured(invocation.command, [...invocation.args, "--doctor"], {
     cwd: invocation.packageRoot,
   });
@@ -5762,10 +5828,9 @@ function inspectTokamakCliRuntime({ packageRoot = resolveActiveTokamakCliPackage
     entryPath: invocation.entryPath,
     cacheRoot,
     runtimeRoot,
-    packageVersion: readPackageReport({
-      name: TOKAMAK_ZKEVM_CLI_PACKAGE_NAME,
-      packageJsonPath: path.join(invocation.packageRoot, "package.json"),
-    }).version,
+    packageVersion: packageReport.version,
+    compatibleBackendVersion: packageReport.compatibleBackendVersion,
+    packageError: packageReport.error,
     dockerModeInstalled,
     cudaCompatible,
     doctor: {