@tokamak-private-dapps/private-state-cli 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.1.2 - 2026-04-28
+
+- Added `private-state-cli --doctor` to report CLI and install-time dependency versions through `tokamak-l2js`.
+- Reported Tokamak zk-EVM runtime install mode, Docker mode, and CUDA runtime metadata.
+
+## 0.1.1 - 2026-04-28
+
+- Updated channel balance proof generation to use the fixed Groth16 runtime workspace proof paths.
+
 ## 0.1.0 - 2026-04-27
 
 - Added the initial independently publishable private-state CLI package.

package/README.md

@@ -27,6 +27,12 @@ Run the CLI with:
 private-state-cli <command> ...
 ```
 
+Check the installed package and runtime state with:
+
+```bash
+private-state-cli --doctor
+```
+
 ## Commands
 
 The normal private-state flow is:
@@ -44,6 +50,10 @@ The normal 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
+install mode, Docker mode, and CUDA runtime metadata.
+
 ## Workspace
 
 The CLI stores user workspaces under:
@@ -59,6 +69,10 @@ Wallet data is encrypted with the password supplied to `join-channel` or `recove
 Proof-backed commands require installed bridge, DApp, and Groth16 artifacts. Run `private-state-cli --install` before
 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.
+
 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.0",
+  "version": "0.1.2",
   "description": "Command-line client for the Tokamak private-state DApp.",
   "license": "MIT OR Apache-2.0",
   "author": "Tokamak Network",

package/private-state-bridge-cli.mjs

@@ -5,6 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
 import {
   createCipheriv,
   createDecipheriv,
@@ -46,6 +47,7 @@ import { deriveRpcUrl, resolveCliNetwork } from "@tokamak-private-dapps/common-l
 import {
   buildTokamakCliInvocation,
   resolveTokamakBlockInputConfig,
+  resolveTokamakCliPackageRoot,
   resolveTokamakCliResourceDir,
   resolveTokamakCliRuntimeRoot,
 } from "@tokamak-private-dapps/common-library/tokamak-runtime-paths";
@@ -80,7 +82,9 @@ import {
   walletNameForChannelAndAddress,
 } from "./lib/private-state-cli-shared.mjs";
 
+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;
@@ -221,6 +225,12 @@ async function main() {
     return;
   }
 
+  if (args.command === "--doctor") {
+    assertDoctorArgs(args);
+    await handleDoctor({ args });
+    return;
+  }
+
   const walletCommandHandlers = {
     "mint-notes": {
       assert: assertMintNotesArgs,
@@ -937,6 +947,12 @@ async function handleInstallZkEvm({ args }) {
     dappName: PRIVATE_STATE_DAPP_LABEL,
     localDeploymentBaseRoot,
   });
+  const installManifest = writePrivateStateCliInstallManifest({
+    dockerRequested: Boolean(args.docker),
+    includeLocalArtifacts: Boolean(args.includeLocalArtifacts),
+    localDeploymentBaseRoot,
+    deploymentArtifacts,
+  });
   printJson({
     action: "install",
     tokamakCli: tokamakCliBaseArgs[0],
@@ -953,6 +969,7 @@ async function handleInstallZkEvm({ args }) {
       dappTimestamp: entry.dappTimestamp,
       artifactDir: entry.artifactDir,
     })),
+    installManifestPath: installManifest.manifestPath,
   });
 }
 
@@ -972,6 +989,14 @@ async function handleUninstallZkEvm() {
   });
 }
 
+async function handleDoctor() {
+  const report = buildDoctorReport();
+  printJson(report);
+  if (!report.ok) {
+    process.exitCode = 1;
+  }
+}
+
 async function handleGetMyAddress({ args, provider }) {
   const { wallet, walletMetadata } = loadUnlockedWalletWithMetadata(args);
   const { signer, l2Identity } = restoreWalletParticipant(wallet, provider);
@@ -3351,7 +3376,6 @@ async function assertWorkspaceAlignedWithChain(context) {
 }
 
 async function buildGrothTransition({ operationDir, workspace, stateManager, vaultAddress, keyHex, nextValue }) {
-  const grothArtifacts = loadGroth16UpdateTreeArtifacts(Number(workspace.chainId));
   const vaultAddressObj = createAddressFromString(vaultAddress);
   const keyBigInt = ethers.toBigInt(keyHex);
   const proof = stateManager.merkleTrees.getProof(vaultAddressObj, keyBigInt);
@@ -3378,22 +3402,14 @@ async function buildGrothTransition({ operationDir, workspace, stateManager, vau
   };
 
   const inputPath = path.join(operationDir, "input.json");
-  const proofOutputPath = path.join(operationDir, "proof.json");
-  const publicOutputPath = path.join(operationDir, "public.json");
   writeJson(inputPath, input);
-  await generateUpdateTreeProof([
+  const proofManifest = await generateUpdateTreeProof([
     "--input",
     inputPath,
-    "--zkey",
-    grothArtifacts.zkeyPath,
-    "--proof-output",
-    proofOutputPath,
-    "--public-output",
-    publicOutputPath,
   ]);
 
-  const proofJson = readJson(proofOutputPath);
-  const publicSignals = readJson(publicOutputPath);
+  const proofJson = readJson(proofManifest.proofPath);
+  const publicSignals = readJson(proofManifest.publicPath);
 
   return {
     input,
@@ -4153,42 +4169,6 @@ function networkNameFromChainId(chainId) {
   throw new Error(`Unsupported chain ID for private-state bridge CLI: ${chainId}`);
 }
 
-function groth16UpdateTreeManifestPath(chainId) {
-  return requireFlatDeploymentArtifactPathsForChainId(chainId).grothManifestPath;
-}
-
-function resolveDeployManifestArtifactPath(manifestPath, artifactPath) {
-  expect(
-    typeof artifactPath === "string" && artifactPath.length > 0,
-    `Invalid artifact path entry in ${manifestPath}.`,
-  );
-  return path.isAbsolute(artifactPath)
-    ? artifactPath
-    : path.resolve(path.dirname(manifestPath), artifactPath);
-}
-
-function loadGroth16UpdateTreeArtifacts(chainId) {
-  const manifestPath = groth16UpdateTreeManifestPath(chainId);
-  expect(
-    fs.existsSync(manifestPath),
-    `Missing Groth16 updateTree manifest for chain ${chainId}: ${manifestPath}.`,
-  );
-
-  const manifest = readJson(manifestPath);
-  const zkeyPath = resolveDeployManifestArtifactPath(manifestPath, manifest.artifacts?.zkeyPath);
-
-  for (const [label, artifactPath] of [
-    ["Groth16 updateTree proving key", zkeyPath],
-  ]) {
-    expect(fs.existsSync(artifactPath), `Missing ${label} for chain ${chainId}: ${artifactPath}.`);
-  }
-
-  return {
-    manifestPath,
-    zkeyPath,
-  };
-}
-
 function findStorageSlot(storageLayoutManifest, contractName, label) {
   const contract = storageLayoutManifest.contracts[contractName];
   if (!contract) {
@@ -4262,6 +4242,10 @@ function parseArgs(argv) {
     parsed.command = "--install";
     parsed.positional = ["--install"];
   }
+  if (!parsed.command && parsed.doctor === true) {
+    parsed.command = "--doctor";
+    parsed.positional = ["--doctor"];
+  }
   return parsed;
 }
 
@@ -4466,6 +4450,10 @@ function assertUninstallZkEvmArgs(args) {
   assertAllowedCommandKeys(args, "uninstall-zk-evm", new Set(["command", "positional"]), "no options");
 }
 
+function assertDoctorArgs(args) {
+  assertAllowedCommandKeys(args, "--doctor", new Set(["command", "positional", "doctor"]), "no options");
+}
+
 function assertMintNotesArgs(args) {
   requireArg(args.amounts, "--amounts");
   assertWalletPasswordArgs(args, "mint-notes", ["amounts"], "--wallet, --password, --network, and --amounts");
@@ -4648,6 +4636,9 @@ Commands:
   uninstall-zk-evm
       Remove the Tokamak zk-EVM CLI runtime workspace
 
+  --doctor
+      Check private-state CLI package versions, runtime install state, Docker mode, CUDA mode, and deployment artifacts
+
   create-channel --channel-name <NAME> --join-fee <TOKENS> --network <NAME> --private-key <HEX> --alchemy-api-key <KEY>
       Create a bridge channel and initialize its workspace
 
@@ -4927,6 +4918,248 @@ function privateStateCliArtifactPaths(cacheBaseRoot = resolveArtifactCacheBaseRo
   };
 }
 
+function privateStateCliInstallManifestPath(cacheBaseRoot = resolveArtifactCacheBaseRoot()) {
+  return path.join(privateStateCliArtifactRoot(cacheBaseRoot), "install-manifest.json");
+}
+
+function writePrivateStateCliInstallManifest({
+  dockerRequested,
+  includeLocalArtifacts,
+  localDeploymentBaseRoot,
+  deploymentArtifacts,
+}) {
+  const manifestPath = privateStateCliInstallManifestPath(deploymentArtifacts.cacheBaseRoot);
+  const manifest = {
+    installedAt: new Date().toISOString(),
+    package: summarizePackageReport(readPackageReport({
+      name: "@tokamak-private-dapps/private-state-cli",
+      packageJsonPath: path.join(privateStateCliPackageRoot, "package.json"),
+    })),
+    dependencies: collectDependencyPackageReports().map(summarizePackageReport),
+    install: {
+      dockerRequested,
+      includeLocalArtifacts,
+      localDeploymentBaseRoot,
+      artifactCacheRoot: deploymentArtifacts.cacheBaseRoot,
+      installedDeploymentArtifacts: deploymentArtifacts.installed.map((entry) => ({
+        chainId: entry.chainId,
+        source: entry.source,
+        bridgeTimestamp: entry.bridgeTimestamp,
+        dappTimestamp: entry.dappTimestamp,
+      })),
+    },
+  };
+  writeJson(manifestPath, manifest);
+  return { manifestPath, manifest };
+}
+
+function summarizePackageReport(report) {
+  return {
+    name: report.name,
+    version: report.version,
+  };
+}
+
+function buildDoctorReport() {
+  const cacheBaseRoot = resolveArtifactCacheBaseRoot();
+  const installManifestPath = privateStateCliInstallManifestPath(cacheBaseRoot);
+  const installManifest = readJsonIfExists(installManifestPath);
+  const dependencyReports = collectDependencyPackageReports(installManifest);
+  const tokamakCli = inspectTokamakCliRuntime();
+  const checks = [
+    {
+      name: "dependency package versions",
+      ok: dependencyReports.every((entry) => entry.ok),
+      details: dependencyReports.map((entry) => ({
+        name: entry.name,
+        currentVersion: entry.version,
+        installVersion: entry.installVersion,
+        ok: entry.ok,
+        error: entry.error,
+      })),
+    },
+    {
+      name: "tokamak zk-evm runtime",
+      ok: tokamakCli.installed,
+      details: {
+        doctorStatus: tokamakCli.doctor.status,
+        runtimeRoot: tokamakCli.runtimeRoot,
+        installations: tokamakCli.installations.map(({ platform, installMode, packageVersion, docker }) => ({
+          platform,
+          installMode,
+          packageVersion,
+          dockerEnvironment: docker?.dockerEnvironment ?? null,
+          useGpus: docker?.useGpus ?? null,
+        })),
+      },
+    },
+  ];
+
+  return {
+    action: "doctor",
+    ok: checks.every((check) => check.ok),
+    generatedAt: new Date().toISOString(),
+    package: readPackageReport({
+      name: "@tokamak-private-dapps/private-state-cli",
+      packageJsonPath: path.join(privateStateCliPackageRoot, "package.json"),
+    }),
+    installManifest: {
+      path: installManifestPath,
+      exists: Boolean(installManifest),
+      installedAt: installManifest?.installedAt ?? null,
+      dockerRequested: installManifest?.install?.dockerRequested ?? null,
+      includeLocalArtifacts: installManifest?.install?.includeLocalArtifacts ?? null,
+    },
+    dependencies: dependencyReports,
+    tokamakCli,
+    checks,
+  };
+}
+
+function collectDependencyPackageReports(installManifest = null) {
+  const installVersions = new Map(
+    Array.isArray(installManifest?.dependencies)
+      ? installManifest.dependencies.map((entry) => [entry.name, entry.version])
+      : [],
+  );
+  const targets = [
+    {
+      name: "@tokamak-zk-evm/cli",
+      packageJsonPath: path.join(resolveTokamakCliPackageRoot(), "package.json"),
+    },
+    {
+      name: "@tokamak-private-dapps/groth16",
+      resolveTarget: "@tokamak-private-dapps/groth16/public-drive-crs",
+    },
+    {
+      name: "@tokamak-private-dapps/common-library",
+      resolveTarget: "@tokamak-private-dapps/common-library/artifact-cache",
+    },
+    { name: "tokamak-l2js", resolveTarget: "tokamak-l2js" },
+  ];
+
+  return targets.map((target) => {
+    const report = readPackageReport(target);
+    const installVersion = installVersions.get(report.name) ?? null;
+    return {
+      ...report,
+      installVersion,
+      ok: Boolean(report.version) && (installVersion === null || installVersion === report.version),
+    };
+  });
+}
+
+function readPackageReport({ name, packageJsonPath = null, resolveTarget = null }) {
+  try {
+    const resolvedPackageJsonPath = packageJsonPath
+      ? path.resolve(packageJsonPath)
+      : findPackageJsonForName(path.dirname(require.resolve(resolveTarget ?? name)), name);
+    const packageJson = readJson(resolvedPackageJsonPath);
+    return {
+      name: packageJson.name ?? name,
+      version: packageJson.version ?? null,
+      packageRoot: path.dirname(resolvedPackageJsonPath),
+      error: null,
+    };
+  } catch (error) {
+    return {
+      name,
+      version: null,
+      packageRoot: null,
+      error: error.message,
+      ok: false,
+    };
+  }
+}
+
+function findPackageJsonForName(startDir, expectedName) {
+  let current = path.resolve(startDir);
+  while (current !== path.dirname(current)) {
+    const candidate = path.join(current, "package.json");
+    if (fs.existsSync(candidate)) {
+      const packageJson = readJson(candidate);
+      if (packageJson.name === expectedName) {
+        return candidate;
+      }
+    }
+    current = path.dirname(current);
+  }
+  throw new Error(`Cannot locate package.json for ${expectedName} above ${startDir}.`);
+}
+
+function inspectTokamakCliRuntime() {
+  const doctor = runCaptured(tokamakCliCommand, [...tokamakCliBaseArgs, "--doctor"], {
+    cwd: resolveTokamakCliPackageRoot(),
+  });
+  const doctorOutput = stripAnsi(`${doctor.stdout}${doctor.stderr}`);
+  const runtimeRoot = parseRuntimeRootFromTokamakDoctorOutput(doctorOutput);
+  const cacheRoot = resolveTokamakCliCacheRoot();
+  const installations = readTokamakCliInstallations(cacheRoot);
+  const dockerModeInstalled = installations.some((entry) => entry.installMode === "docker" || entry.docker);
+  const cudaCompatible = installations.some((entry) => entry.docker?.useGpus === true);
+
+  return {
+    installed: doctor.status === 0 || installations.length > 0,
+    packageRoot: resolveTokamakCliPackageRoot(),
+    cacheRoot,
+    runtimeRoot,
+    packageVersion: readPackageReport({
+      name: "@tokamak-zk-evm/cli",
+      packageJsonPath: path.join(resolveTokamakCliPackageRoot(), "package.json"),
+    }).version,
+    dockerModeInstalled,
+    cudaCompatible,
+    doctor: {
+      status: doctor.status,
+      stdout: stripAnsi(doctor.stdout).trim(),
+      stderr: stripAnsi(doctor.stderr).trim(),
+    },
+    installations,
+  };
+}
+
+function resolveTokamakCliCacheRoot() {
+  return path.resolve(process.env.TOKAMAK_ZKEVM_CLI_CACHE_DIR ?? path.join(os.homedir(), ".tokamak-zk-evm"));
+}
+
+function readTokamakCliInstallations(cacheRoot) {
+  if (!fs.existsSync(cacheRoot)) {
+    return [];
+  }
+  return fs.readdirSync(cacheRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => {
+      const platformDir = path.join(cacheRoot, entry.name);
+      const statePath = path.join(platformDir, "installation.json");
+      if (!fs.existsSync(statePath)) {
+        return null;
+      }
+      const state = readJsonIfExists(statePath);
+      const dockerBootstrapPath = path.join(platformDir, "docker", "bootstrap.json");
+      const docker = readJsonIfExists(dockerBootstrapPath);
+      return {
+        platform: entry.name,
+        statePath,
+        runtimeRoot: path.join(platformDir, "runtime"),
+        installMode: state?.installMode ?? (docker ? "docker" : null),
+        packageVersion: state?.packageVersion ?? docker?.packageVersion ?? null,
+        installedAt: state?.installedAt ?? null,
+        dockerBootstrapPath,
+        docker,
+      };
+    })
+    .filter(Boolean);
+}
+
+function parseRuntimeRootFromTokamakDoctorOutput(output) {
+  const match = String(output ?? "").match(/^\[ ok \] Runtime workspace:\s*(.+)$/m);
+  return match ? path.resolve(match[1].trim()) : null;
+}
+
+function stripAnsi(value) {
+  return String(value ?? "").replace(/\u001b\[[0-9;]*m/g, "");
+}
+
 async function installPrivateStateCliArtifacts({
   dappName,
   indexFileId = process.env.PRIVATE_STATE_DRIVE_ARTIFACT_INDEX_FILE_ID