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

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.1.9 - 2026-05-03
+
+- Used the bundled Groth16 package version as the default `private-state-cli --install` Groth16 runtime version.
+- Treated stale local Groth16 CRS metadata without `compatibleBackendVersion` as a cache miss so the matching public CRS can be reinstalled.
+
+## 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

@@ -2,6 +2,10 @@
 
 Command-line client for the Tokamak private-state DApp.
 
+The full private-state DApp documentation is published with the repository:
+
+- https://github.com/tokamak-network/Tokamak-zk-EVM-contracts/tree/main/packages/apps/private-state/docs
+
 ## Install
 
 ```bash
@@ -15,14 +19,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:
+By default, `--install` resolves the latest `@tokamak-zk-evm/cli` from the npm registry and uses the bundled
+`@tokamak-private-dapps/groth16` dependency version selected by the installed private-state CLI package. 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
+private-state-cli --install --tokamak-zk-evm-cli-version 2.1.0 --groth16-cli-version 0.2.0
 ```
 
-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:
@@ -60,6 +68,19 @@ A common private-state flow is:
 
 Use `private-state-cli --help` for the full command list and required options.
 
+Channel policy warning:
+
+- `create-channel` commits to an immutable channel policy: verifier bindings, DApp execution metadata, function layout,
+  managed storage vector, and refund policy are fixed for that channel.
+- `join-channel` means the user accepts the channel's current policy. Later policy-level fixes require a new channel or
+  migration; the existing channel is intentionally not mutated in place without renewed user consent.
+- Before sending a channel-creation transaction or a first channel-registration transaction, the CLI prints the policy
+  snapshot that will be accepted: DApp metadata digest, digest schema, Groth16 verifier address, Groth16 compatible
+  backend version, Tokamak verifier address, and Tokamak compatible backend version.
+- Users and operators must review this snapshot before signing. If any digest, schema, verifier address, or compatible
+  backend version is unexpected or has not been reviewed, do not create or join the channel. A later correction creates
+  a new channel; it does not rewrite the policy of an already-created channel.
+
 `private-state-cli --doctor` reports the CLI package version, dependency versions recorded by the last
 `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
@@ -114,6 +135,9 @@ Operating rules:
   telling the user to move funds.
 - Explain that wallet names are local CLI identifiers, while private transfers use notes owned by L2 addresses
   registered in the channel.
+- Before guiding a user through `create-channel` or `join-channel`, explain that channel policy is immutable after
+  creation and that joining a channel means accepting its current verifier, DApp metadata, function layout, managed
+  storage vector, and refund policy.
 - Do not present one fixed command sequence as universally correct. Some flows start from an existing channel or wallet,
   while others require creating or joining a channel first.
 - When the user asks for a transfer, first determine whether the sender has minted notes available. If not, guide them
@@ -147,6 +171,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/cli-assistant.html

@@ -400,6 +400,11 @@
                 case, you lose ownership of all notes because you can no longer use them, and that ownership cannot be
                 recovered.
               </li>
+              <li>
+                Channel policy is immutable after creation. Joining a channel means accepting its verifier bindings,
+                DApp metadata, function layout, managed storage vector, and refund policy; later policy-level fixes
+                require a new channel or migration.
+              </li>
             </ul>
           </div>
         </section>
@@ -521,12 +526,12 @@
       const commands = [
         { id: "install-zk-evm", description: "Install the local Tokamak zk-EVM toolchain. Optionally forward --docker for Linux-host Docker installs.", fields: ["docker"] },
         { id: "uninstall-zk-evm", description: "Remove the Tokamak zk-EVM CLI runtime workspace.", fields: [] },
-        { id: "create-channel", description: "Create the bridge channel and initialize its workspace.", fields: ["channelName", "network", "privateKey", "alchemyApiKey"] },
+        { id: "create-channel", description: "Create a channel with an immutable operating policy and initialize its workspace.", fields: ["channelName", "network", "privateKey", "alchemyApiKey"] },
         { id: "recover-workspace", description: "Rebuild the saved channel workspace from bridge state.", fields: ["channelName", "network", "alchemyApiKey"] },
         { id: "deposit-bridge", description: "Deposit canonical tokens into the shared bridge vault.", fields: ["amount", "network", "privateKey", "alchemyApiKey"] },
         { id: "withdraw-bridge", description: "Withdraw shared bridge-vault funds back to the L1 wallet.", fields: ["amount", "network", "privateKey", "alchemyApiKey"] },
         { id: "get-my-bridge-fund", description: "Read the current bridge-vault balance.", fields: ["network", "privateKey", "alchemyApiKey"] },
-        { id: "join-channel", description: "Bind the caller to a channel-specific L2 identity.", fields: ["channelName", "password", "network", "privateKey", "alchemyApiKey"] },
+        { id: "join-channel", description: "Accept the channel policy and bind the caller to a channel-specific L2 identity.", fields: ["channelName", "password", "network", "privateKey", "alchemyApiKey"] },
         { id: "recover-wallet", description: "Rebuild the recoverable portion of a wallet.", fields: ["channelName", "password", "network", "privateKey", "alchemyApiKey"] },
         { id: "get-my-wallet-meta", description: "Check whether a saved wallet matches on-chain registration.", fields: ["wallet", "password", "network"] },
         { id: "get-my-l1-address", description: "Derive the L1 address for a private key.", fields: ["privateKey"] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamak-private-dapps/private-state-cli",
-  "version": "0.1.6",
+  "version": "0.1.9",
   "description": "Command-line client for the Tokamak private-state DApp.",
   "license": "MIT OR Apache-2.0",
   "author": "Tokamak Network",
@@ -41,12 +41,12 @@
   },
   "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.2.0",
+    "@tokamak-zk-evm/cli": "^2.1.0",
     "ethers": "^6.14.1",
-    "tokamak-l2js": "^0.1.3"
+    "tokamak-l2js": "^0.1.4"
   },
   "engines": {
     "node": ">=18"

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,
@@ -157,6 +166,68 @@ const DEFAULT_LOG_REQUESTS_PER_SECOND = 5;
 const LOG_REQUEST_INTERVAL_MS = Math.ceil(1000 / DEFAULT_LOG_REQUESTS_PER_SECOND);
 let lastLogRequestStartedAtMs = 0;
 
+function printImmutableChannelPolicyWarning({
+  action,
+  channelName,
+  channelId,
+  channelManager = null,
+  policySnapshot = null,
+}) {
+  const details = [
+    `WARNING: ${action} commits to an immutable channel policy.`,
+    `Channel: ${channelName} (${channelId.toString()})`,
+  ];
+  if (channelManager) {
+    details.push(`ChannelManager: ${channelManager}`);
+  }
+  details.push(
+    "The channel verifier bindings, DApp execution metadata, function layout, managed storage vector, and refund policy are fixed for this channel.",
+    "Those policy fields are intentionally not upgraded in place without channel-user consent.",
+    "If a policy bug is discovered later, the expected mitigation is creating or joining a new channel, not mutating this channel.",
+    "Review the DApp digest, digest schema, verifier addresses, and compatible backend versions before signing.",
+  );
+  if (policySnapshot) {
+    details.push(
+      "Channel policy snapshot:",
+      `  DApp id: ${policySnapshot.dappId}`,
+      `  DApp metadata digest schema: ${policySnapshot.dappMetadataDigestSchema}`,
+      `  DApp metadata digest: ${policySnapshot.dappMetadataDigest}`,
+      `  DApp function root: ${policySnapshot.functionRoot}`,
+      `  Groth16 verifier: ${policySnapshot.grothVerifier}`,
+      `  Groth16 compatible backend version: ${policySnapshot.grothVerifierCompatibleBackendVersion}`,
+      `  Tokamak verifier: ${policySnapshot.tokamakVerifier}`,
+      `  Tokamak compatible backend version: ${policySnapshot.tokamakVerifierCompatibleBackendVersion}`,
+      "Do not sign if any snapshot value is unexpected or has not been reviewed.",
+    );
+  }
+  console.error(details.join("\n"));
+}
+
+function normalizeDAppPolicySnapshot({
+  dappId,
+  metadataDigest,
+  metadataDigestSchema,
+  functionRoot,
+  verifierSnapshot,
+}) {
+  return {
+    dappId: Number(dappId),
+    dappMetadataDigestSchema: normalizeBytes32Hex(metadataDigestSchema),
+    dappMetadataDigest: normalizeBytes32Hex(metadataDigest),
+    functionRoot: normalizeBytes32Hex(functionRoot),
+    grothVerifier: getAddress(verifierSnapshot.grothVerifier),
+    grothVerifierCompatibleBackendVersion: requireVersionString(
+      verifierSnapshot.grothVerifierCompatibleBackendVersion,
+      "registered DApp Groth16 verifier compatibleBackendVersion",
+    ),
+    tokamakVerifier: getAddress(verifierSnapshot.tokamakVerifier),
+    tokamakVerifierCompatibleBackendVersion: requireVersionString(
+      verifierSnapshot.tokamakVerifierCompatibleBackendVersion,
+      "registered DApp Tokamak verifier compatibleBackendVersion",
+    ),
+  };
+}
+
 async function prepareDeploymentArtifacts(chainId) {
   const normalizedChainId = Number(chainId);
   const existingPaths = flatDeploymentArtifactPathsByChainId.get(normalizedChainId);
@@ -364,16 +435,25 @@ async function handleChannelCreate({ args, network, provider }) {
   );
   const canonicalAsset = getAddress(await bridgeCore.canonicalAsset());
   const canonicalAssetDecimals = await fetchTokenDecimals(provider, canonicalAsset);
-  const joinFeeInput = requireArg(args.joinFee, "--join-fee");
-  const joinFee = parseTokenAmount(joinFeeInput, canonicalAssetDecimals);
+  const joinTollInput = requireArg(args.joinToll, "--join-toll");
+  const joinToll = parseTokenAmount(joinTollInput, canonicalAssetDecimals);
   const channelId = deriveChannelIdFromName(channelName);
-  const dappId = await resolveDAppIdByLabel({
+  const dapp = await resolveDAppIdByLabel({
     provider,
     bridgeResources,
     dappLabel: PRIVATE_STATE_DAPP_LABEL,
   });
+  const dappId = dapp.dappId;
+  const policySnapshot = dapp.policySnapshot;
 
-  const receipt = await waitForReceipt(await bridgeCore.createChannel(channelId, dappId, leader, joinFee));
+  printImmutableChannelPolicyWarning({
+    action: "create-channel",
+    channelName,
+    channelId,
+    policySnapshot,
+  });
+  const receipt =
+    await waitForReceipt(await bridgeCore.createChannel(channelId, dappId, joinToll, dapp.metadataDigest));
   const channelInfo = await bridgeCore.getChannel(channelId);
 
   const workspaceResult = await initializeChannelWorkspace({
@@ -390,9 +470,12 @@ async function handleChannelCreate({ args, network, provider }) {
     channelName,
     channelId: channelId.toString(),
     dappId,
+    dappMetadataDigest: dapp.metadataDigest,
+    dappMetadataDigestSchema: dapp.metadataDigestSchema,
+    policySnapshot,
     leader,
-    joinFeeBaseUnits: joinFee.toString(),
-    joinFeeTokens: ethers.formatUnits(joinFee, canonicalAssetDecimals),
+    joinTollBaseUnits: joinToll.toString(),
+    joinTollTokens: ethers.formatUnits(joinToll, canonicalAssetDecimals),
     canonicalAsset,
     canonicalAssetDecimals,
     asset: channelInfo.asset,
@@ -417,9 +500,21 @@ async function resolveDAppIdByLabel({ provider, bridgeResources, dappLabel }) {
   const manifestLabel = typeof manifest.dappLabel === "string" ? manifest.dappLabel : null;
   const manifestDappId = manifest.dappId;
   const manifestManager = typeof manifest.dAppManager === "string" ? getAddress(manifest.dAppManager) : null;
+  const manifestMetadataDigest = normalizeBytes32Hex(manifest.registration?.metadataDigest);
+  const manifestMetadataDigestSchema = normalizeBytes32Hex(manifest.registration?.metadataDigestSchema);
+  const manifestFunctionRoot = normalizeBytes32Hex(manifest.registration?.functionRoot);
 
   expect(manifestLabel === dappLabel, `DApp registration manifest label mismatch in ${manifestPath}.`);
   expect(Number.isInteger(manifestDappId), `DApp registration manifest is missing an integer dappId: ${manifestPath}.`);
+  expect(manifestMetadataDigest !== null, `DApp registration manifest is missing registration.metadataDigest: ${manifestPath}.`);
+  expect(
+    manifestMetadataDigestSchema !== null,
+    `DApp registration manifest is missing registration.metadataDigestSchema: ${manifestPath}.`,
+  );
+  expect(
+    manifestFunctionRoot !== null,
+    `DApp registration manifest is missing registration.functionRoot: ${manifestPath}.`,
+  );
   expect(
     manifestManager !== null
       && ethers.toBigInt(manifestManager) === ethers.toBigInt(getAddress(bridgeResources.bridgeDeployment.dAppManager)),
@@ -432,7 +527,36 @@ async function resolveDAppIdByLabel({ provider, bridgeResources, dappLabel }) {
     ethers.toBigInt(normalizeBytes32Hex(info.labelHash)) === ethers.toBigInt(expectedLabelHash),
     `DApp id ${manifestDappId} from ${manifestPath} does not match label ${dappLabel} on-chain.`,
   );
-  return Number(manifestDappId);
+  const onchainMetadataDigest = normalizeBytes32Hex(info.metadataDigest);
+  const onchainMetadataDigestSchema = normalizeBytes32Hex(info.metadataDigestSchema);
+  const onchainFunctionRoot = normalizeBytes32Hex(info.functionRoot);
+  const verifierSnapshot = await dAppManager.getDAppVerifierSnapshot(manifestDappId);
+  const policySnapshot = normalizeDAppPolicySnapshot({
+    dappId: manifestDappId,
+    metadataDigest: onchainMetadataDigest,
+    metadataDigestSchema: onchainMetadataDigestSchema,
+    functionRoot: onchainFunctionRoot,
+    verifierSnapshot,
+  });
+  expect(
+    ethers.toBigInt(onchainMetadataDigest) === ethers.toBigInt(manifestMetadataDigest),
+    `DApp id ${manifestDappId} metadata digest ${onchainMetadataDigest} does not match ${manifestMetadataDigest} from ${manifestPath}.`,
+  );
+  expect(
+    ethers.toBigInt(onchainMetadataDigestSchema) === ethers.toBigInt(manifestMetadataDigestSchema),
+    `DApp id ${manifestDappId} metadata digest schema ${onchainMetadataDigestSchema} does not match ${manifestMetadataDigestSchema} from ${manifestPath}.`,
+  );
+  expect(
+    ethers.toBigInt(onchainFunctionRoot) === ethers.toBigInt(manifestFunctionRoot),
+    `DApp id ${manifestDappId} function root ${onchainFunctionRoot} does not match ${manifestFunctionRoot} from ${manifestPath}.`,
+  );
+  return {
+    dappId: Number(manifestDappId),
+    metadataDigest: onchainMetadataDigest,
+    metadataDigestSchema: onchainMetadataDigestSchema,
+    functionRoot: onchainFunctionRoot,
+    policySnapshot,
+  };
 }
 
 async function handleWorkspaceInit({ args, network, provider }) {
@@ -505,6 +629,10 @@ async function initializeChannelWorkspace({
   const currentRootVectorHash = normalizeBytes32Hex(await channelManager.currentRootVectorHash());
   const genesisBlockNumber = Number(await channelManager.genesisBlockNumber());
   const managedStorageAddresses = normalizedAddressVector(await channelManager.getManagedStorageAddresses());
+  const policySnapshot = await readChannelPolicySnapshot({
+    channelManager,
+    dappId: Number(channelInfo.dappId),
+  });
   const deploymentManifestPath = dappDeploymentManifestPath(network.chainId);
   const storageLayoutManifestPath = dappStorageLayoutManifestPath(network.chainId);
   const deploymentManifest = readJson(deploymentManifestPath);
@@ -571,6 +699,10 @@ async function initializeChannelWorkspace({
     controller: controllerAddress,
     l2AccountingVault: l2AccountingVaultAddress,
     aPubBlockHash: normalizeBytes32Hex(channelInfo.aPubBlockHash),
+    dappMetadataDigestSchema: policySnapshot.dappMetadataDigestSchema,
+    dappMetadataDigest: policySnapshot.dappMetadataDigest,
+    functionRoot: policySnapshot.functionRoot,
+    policySnapshot,
     managedStorageAddresses,
     liquidBalancesSlot: liquidBalancesSlot.toString(),
   };
@@ -967,7 +1099,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),
@@ -1185,20 +1317,27 @@ async function handleJoinChannel({ args, network, provider, rpcUrl }) {
   let resolvedLeafIndex = leafIndex;
   let approveReceipt = null;
   let receipt = null;
-  let joinFee = 0n;
+  let joinToll = 0n;
   let status = null;
 
   if (!existingRegistration.exists) {
-    joinFee = ethers.toBigInt(await context.channelManager.joinFee());
+    joinToll = ethers.toBigInt(await context.channelManager.joinToll());
     const asset = new Contract(
       context.workspace.canonicalAsset,
       context.bridgeAbiManifest.contracts.erc20.abi,
       signer,
     );
     let nextNonce = await provider.getTransactionCount(signer.address, "pending");
-    if (joinFee !== 0n) {
+    printImmutableChannelPolicyWarning({
+      action: "join-channel",
+      channelName: context.workspace.channelName,
+      channelId: ethers.toBigInt(context.workspace.channelId),
+      channelManager: context.workspace.channelManager,
+      policySnapshot: context.workspace.policySnapshot,
+    });
+    if (joinToll !== 0n) {
       approveReceipt = await waitForReceipt(
-        await asset.approve(context.workspace.bridgeTokenVault, joinFee, { nonce: nextNonce++ }),
+        await asset.approve(context.workspace.bridgeTokenVault, joinToll, { nonce: nextNonce++ }),
       );
     }
     receipt = await waitForReceipt(
@@ -1232,7 +1371,7 @@ async function handleJoinChannel({ args, network, provider, rpcUrl }) {
       "The existing note-receive public key parity does not match the derived note-receive public key.",
     );
     resolvedLeafIndex = existingRegistration.leafIndex;
-    joinFee = ethers.toBigInt(existingRegistration.joinFeePaid);
+    joinToll = ethers.toBigInt(existingRegistration.joinTollPaid);
     status = "already-registered";
   }
 
@@ -1258,9 +1397,10 @@ async function handleJoinChannel({ args, network, provider, rpcUrl }) {
     l2Address: l2Identity.l2Address,
     l2StorageKey: storageKey,
     leafIndex: resolvedLeafIndex.toString(),
-    joinFeeBaseUnits: joinFee.toString(),
-    joinFeeTokens: ethers.formatUnits(joinFee, Number(context.workspace.canonicalAssetDecimals)),
+    joinTollBaseUnits: joinToll.toString(),
+    joinTollTokens: ethers.formatUnits(joinToll, Number(context.workspace.canonicalAssetDecimals)),
     noteReceivePubKey: noteReceiveKeyMaterial.noteReceivePubKey,
+    policySnapshot: context.workspace.policySnapshot,
     approveGasUsed: approveReceipt ? receiptGasUsed(approveReceipt) : null,
     gasUsed: receipt ? receiptGasUsed(receipt) : null,
     approveTxUrl: approveReceipt ? explorerTxUrl(network, approveReceipt.hash) : null,
@@ -1287,7 +1427,7 @@ async function handleExitChannel({ args, provider }) {
       "Run withdraw-channel first, or rerun exit-channel with --force to bypass this CLI check.",
     ].join(" "),
   );
-  const [refundAmount, refundBps] = await context.channelManager.getExitFeeRefundQuote(signer.address);
+  const [refundAmount, refundBps] = await context.channelManager.getExitTollRefundQuote(signer.address);
   const receipt = await waitForReceipt(
     await context.bridgeTokenVault.connect(signer).exitChannel(ethers.toBigInt(context.workspace.channelId)),
   );
@@ -1393,8 +1533,9 @@ async function handleGrothVaultMove({ args, provider, direction }) {
     nextValue,
   });
 
+  const methodName = direction === "deposit" ? "depositToChannelVault" : "withdrawFromChannelVault";
   const receipt = await waitForReceipt(
-    await bridgeTokenVault[direction](ethers.toBigInt(context.workspace.channelId), transition.proof, transition.update),
+    await bridgeTokenVault[methodName](ethers.toBigInt(context.workspace.channelId), transition.proof, transition.update),
   );
   const onchainRootVectorHash = normalizeBytes32Hex(await context.channelManager.currentRootVectorHash());
   expect(
@@ -1453,6 +1594,63 @@ async function handleWithdrawBridge({ args, network, provider }) {
   });
 }
 
+function resolveFunctionMetadataProofForExecution({
+  chainId,
+  controllerAddress,
+  functionSelector,
+  preprocessInputHash,
+  expectedFunctionRoot,
+}) {
+  const manifestPath = requireFlatDeploymentArtifactPathsForChainId(chainId).dappRegistrationPath;
+  const manifest = readJson(manifestPath);
+  const proofRoot = normalizeBytes32Hex(manifest.functionMetadataProofs?.root);
+  const expectedRoot = normalizeBytes32Hex(expectedFunctionRoot);
+  expect(
+    ethers.toBigInt(proofRoot) === ethers.toBigInt(expectedRoot),
+    `DApp function proof root ${proofRoot} does not match channel function root ${expectedRoot}.`,
+  );
+
+  const functions = manifest.functionMetadataProofs?.functions;
+  expect(Array.isArray(functions), `DApp registration manifest is missing functionMetadataProofs.functions: ${manifestPath}.`);
+  const normalizedController = getAddress(controllerAddress);
+  const normalizedSelector = normalizeBytesHex(functionSelector, 4);
+  const normalizedPreprocessInputHash = normalizeBytes32Hex(preprocessInputHash);
+  const entry = functions.find((candidate) => {
+    const metadata = candidate?.metadata;
+    return metadata
+      && getAddress(metadata.entryContract) === normalizedController
+      && normalizeBytesHex(metadata.functionSig, 4) === normalizedSelector
+      && normalizeBytes32Hex(metadata.preprocessInputHash) === normalizedPreprocessInputHash;
+  });
+  expect(
+    entry !== undefined,
+    [
+      `No DApp function metadata proof found for ${normalizedController} ${normalizedSelector}.`,
+      `Expected preprocess input hash: ${normalizedPreprocessInputHash}.`,
+      `Manifest: ${manifestPath}.`,
+    ].join(" "),
+  );
+
+  return {
+    metadata: {
+      entryContract: getAddress(entry.metadata.entryContract),
+      functionSig: normalizeBytesHex(entry.metadata.functionSig, 4),
+      preprocessInputHash: normalizeBytes32Hex(entry.metadata.preprocessInputHash),
+      instanceLayout: {
+        entryContractOffsetWords: Number(entry.metadata.instanceLayout.entryContractOffsetWords),
+        functionSigOffsetWords: Number(entry.metadata.instanceLayout.functionSigOffsetWords),
+        currentRootVectorOffsetWords: Number(entry.metadata.instanceLayout.currentRootVectorOffsetWords),
+        updatedRootVectorOffsetWords: Number(entry.metadata.instanceLayout.updatedRootVectorOffsetWords),
+        eventLogs: entry.metadata.instanceLayout.eventLogs.map((eventLog) => ({
+          startOffsetWords: Number(eventLog.startOffsetWords),
+          topicCount: Number(eventLog.topicCount),
+        })),
+      },
+    },
+    siblings: entry.merkleProof.map((sibling) => normalizeBytes32Hex(sibling)),
+  };
+}
+
 async function handleMintNotes({ args, provider }) {
   const { wallet } = loadUnlockedWalletWithMetadata(args);
   const canonicalAssetDecimals = Number(wallet.wallet.canonicalAssetDecimals);
@@ -3109,6 +3307,16 @@ async function executeWalletTemplateSend({
   writeJson(path.join(operationDir, "resource", "synthesizer", "output", "state_snapshot.normalized.json"), nextSnapshot);
 
   const payload = loadTokamakPayloadFromStep(operationDir);
+  const functionProof = resolveFunctionMetadataProofForExecution({
+    chainId: context.workspace.chainId,
+    controllerAddress: context.workspace.controller,
+    functionSelector: calldata.slice(0, 10),
+    preprocessInputHash: hashTokamakPointEncoding(
+      payload.functionPreprocessPart1,
+      payload.functionPreprocessPart2,
+    ),
+    expectedFunctionRoot: context.workspace.functionRoot ?? context.workspace.policySnapshot?.functionRoot,
+  });
   const noteLifecycle = extractControllerStorageDelta({
     previousSnapshot: context.currentSnapshot,
     nextSnapshot,
@@ -3123,7 +3331,9 @@ async function executeWalletTemplateSend({
   );
 
   const receipt =
-    await waitForReceipt(await context.channelManager.connect(signer).executeChannelTransaction(payload));
+    await waitForReceipt(
+      await context.channelManager.connect(signer).executeChannelTransaction(payload, functionProof),
+    );
 
   const onchainRootVectorHash = normalizeBytes32Hex(await context.channelManager.currentRootVectorHash());
   expect(
@@ -3445,14 +3655,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 +3682,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(" "),
   );
 }
@@ -3499,29 +3718,92 @@ async function readChannelVerifierCompatibleBackendVersions(context) {
   }
 }
 
+async function readChannelPolicySnapshot({ channelManager, dappId }) {
+  const channelManagerAddress = getAddress(await channelManager.getAddress());
+  try {
+    const [
+      dappMetadataDigestSchema,
+      dappMetadataDigest,
+      functionRoot,
+      grothVerifier,
+      grothVerifierCompatibleBackendVersion,
+      tokamakVerifier,
+      tokamakVerifierCompatibleBackendVersion,
+    ] = await Promise.all([
+      channelManager.dappMetadataDigestSchema(),
+      channelManager.dappMetadataDigest(),
+      channelManager.functionRoot(),
+      channelManager.grothVerifier(),
+      channelManager.grothVerifierCompatibleBackendVersion(),
+      channelManager.tokamakVerifier(),
+      channelManager.tokamakVerifierCompatibleBackendVersion(),
+    ]);
+    return {
+      dappId: Number(dappId),
+      dappMetadataDigestSchema: normalizeBytes32Hex(dappMetadataDigestSchema),
+      dappMetadataDigest: normalizeBytes32Hex(dappMetadataDigest),
+      functionRoot: normalizeBytes32Hex(functionRoot),
+      grothVerifier: getAddress(grothVerifier),
+      grothVerifierCompatibleBackendVersion: requireVersionString(
+        grothVerifierCompatibleBackendVersion,
+        "channel Groth16 verifier compatibleBackendVersion",
+      ),
+      tokamakVerifier: getAddress(tokamakVerifier),
+      tokamakVerifierCompatibleBackendVersion: requireVersionString(
+        tokamakVerifierCompatibleBackendVersion,
+        "channel Tokamak verifier compatibleBackendVersion",
+      ),
+    };
+  } catch (error) {
+    throw new Error(
+      [
+        `Unable to read immutable policy snapshot from channel manager ${channelManagerAddress}.`,
+        "The target channel must expose DApp digest, verifier address, and compatibleBackendVersion getters.",
+      ].join(" "),
+      { cause: error },
+    );
+  }
+}
+
 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 +3819,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 +4155,6 @@ function normalizeBytes16Hex(value) {
   return normalizeBytesHex(value, 16);
 }
 
-function normalizeBytes20Hex(value) {
-  return normalizeBytesHex(value, 20);
-}
-
 function normalizeBytes32Hex(hexValue) {
   return normalizeBytesHex(hexValue, 32);
 }
@@ -3888,6 +4175,10 @@ function hashTokamakPublicInputs(values) {
   return keccak256(abiCoder.encode(["uint256[]"], [values]));
 }
 
+function hashTokamakPointEncoding(part1, part2) {
+  return keccak256(abiCoder.encode(["uint128[]", "uint256[]"], [part1, part2]));
+}
+
 function encodeTokamakBlockInfo(blockInfo) {
   const values = new Array(TOKAMAK_APUB_BLOCK_LENGTH).fill(0n);
   appendSplitWord(values, 0, ethers.toBigInt(blockInfo.coinBase));
@@ -4774,15 +5065,15 @@ function assertGetMyNotesArgs(args) {
 
 function assertCreateChannelArgs(args) {
   requireArg(args.channelName, "--channel-name");
-  requireArg(args.joinFee, "--join-fee");
+  requireArg(args.joinToll, "--join-toll");
   requireNetworkName(args);
   requireAlchemyApiKeyForPublicNetwork(args, "create-channel");
   requireArg(args.privateKey, "--private-key");
   assertAllowedCommandKeys(
     args,
     "create-channel",
-    new Set(["command", "positional", "channelName", "joinFee", "network", "alchemyApiKey", "privateKey"]),
-    "--channel-name, --join-fee, --network, --private-key, and --alchemy-api-key on public networks",
+    new Set(["command", "positional", "channelName", "joinToll", "network", "alchemyApiKey", "privateKey"]),
+    "--channel-name, --join-toll, --network, --private-key, and --alchemy-api-key on public networks",
   );
 }
 
@@ -4944,8 +5235,9 @@ Commands:
   --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-channel --channel-name <NAME> --join-toll <TOKENS> --network <NAME> --private-key <HEX> --alchemy-api-key <KEY>
       Create a bridge channel and initialize its workspace
+      Prints the immutable policy snapshot before sending the transaction
 
   recover-workspace --channel-name <NAME> --network <NAME> --alchemy-api-key <KEY>
       Rebuild the local channel workspace from bridge state
@@ -4963,7 +5255,8 @@ Commands:
       Rebuild a recoverable local wallet from on-chain channel state
 
   join-channel --channel-name <NAME> --password <PASSWORD> --network <NAME> --private-key <HEX> --alchemy-api-key <KEY>
-      Pay the channel join fee and bind a wallet to a channel-specific L2 identity
+      Pay the channel join toll and bind a wallet to a channel-specific L2 identity
+      Prints the immutable policy snapshot before first registration
 
   get-my-wallet-meta --wallet <NAME> --password <PASSWORD> --network <NAME>
       Check whether a wallet matches the on-chain channel registration
@@ -5198,11 +5491,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 +5675,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
         ),
     },
   ];
@@ -5414,11 +5722,7 @@ function buildSelectedRuntimeVersionCheck({ installManifest, tokamakCli, groth16
 
 async function resolvePrivateStateInstallRuntimeVersions(args) {
   const [groth16, tokamak] = await Promise.all([
-    resolveRequestedNpmPackageVersion({
-      packageName: GROTH16_PACKAGE_NAME,
-      requestedVersion: args.groth16CliVersion,
-      optionName: "--groth16-cli-version",
-    }),
+    resolveRequestedGroth16PackageVersion(args.groth16CliVersion),
     resolveRequestedNpmPackageVersion({
       packageName: TOKAMAK_ZKEVM_CLI_PACKAGE_NAME,
       requestedVersion: args.tokamakZkEvmCliVersion,
@@ -5428,6 +5732,19 @@ async function resolvePrivateStateInstallRuntimeVersions(args) {
   return { groth16, tokamak };
 }
 
+async function resolveRequestedGroth16PackageVersion(requestedVersion) {
+  if (requestedVersion !== undefined && requestedVersion !== null) {
+    return resolveRequestedNpmPackageVersion({
+      packageName: GROTH16_PACKAGE_NAME,
+      requestedVersion,
+      optionName: "--groth16-cli-version",
+    });
+  }
+
+  const bundledPackageJson = readJson(path.join(resolveGroth16PackageRoot(), "package.json"));
+  return requireSemverVersion(bundledPackageJson.version, `${GROTH16_PACKAGE_NAME} bundled package version`);
+}
+
 async function resolveRequestedNpmPackageVersion({ packageName, requestedVersion, optionName }) {
   const metadata = await fetchNpmPackageMetadata(packageName);
   if (requestedVersion === undefined || requestedVersion === null) {
@@ -5441,20 +5758,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 +5774,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 +5785,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,
@@ -5490,10 +5795,7 @@ async function installTokamakCliRuntimeForPrivateState({ version, docker }) {
 }
 
 async function installGroth16RuntimeForPrivateState({ version, docker }) {
-  const packageInstall = installManagedNpmPackage({
-    packageName: GROTH16_PACKAGE_NAME,
-    version,
-  });
+  const packageInstall = resolveGroth16RuntimePackageInstall(version);
   const packageRoot = packageInstall.packageRoot;
   const entryPath = resolveGroth16CliEntryPath(packageRoot);
   const args = [entryPath, "--install", "--no-setup"];
@@ -5501,13 +5803,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,
@@ -5517,9 +5821,32 @@ async function installGroth16RuntimeForPrivateState({ version, docker }) {
   };
 }
 
+function resolveGroth16RuntimePackageInstall(version) {
+  const normalizedVersion = requireSemverVersion(version, `${GROTH16_PACKAGE_NAME} version`);
+  const bundledPackageRoot = resolveGroth16PackageRoot();
+  const bundledPackageJson = readJson(path.join(bundledPackageRoot, "package.json"));
+  if (bundledPackageJson.name === GROTH16_PACKAGE_NAME && bundledPackageJson.version === normalizedVersion) {
+    return {
+      packageName: GROTH16_PACKAGE_NAME,
+      version: normalizedVersion,
+      installPrefix: null,
+      packageRoot: bundledPackageRoot,
+    };
+  }
+
+  return installManagedNpmPackage({
+    packageName: GROTH16_PACKAGE_NAME,
+    version: normalizedVersion,
+  });
+}
+
 async function installGroth16CrsForPrivateStateVersion(version) {
   const workspaceRoot = defaultGroth16WorkspaceRoot();
   const crsDir = path.join(workspaceRoot, "crs");
+  const existingInstall = readExistingGroth16CrsInstall({ version, crsDir });
+  if (existingInstall) {
+    return existingInstall;
+  }
   const crsInstall = await downloadPublicGroth16MpcArtifactsByVersion({
     version,
     outputDir: crsDir,
@@ -5541,6 +5868,56 @@ async function installGroth16CrsForPrivateStateVersion(version) {
   return crsInstall;
 }
 
+function readExistingGroth16CrsInstall({ version, crsDir }) {
+  const normalizedVersion = requireCanonicalGroth16CompatibleBackendVersion(version, "Groth16 MPC CRS version");
+  const selectedFiles = [
+    "circuit_final.zkey",
+    "verification_key.json",
+    "metadata.json",
+    "zkey_provenance.json",
+  ];
+  const targetPaths = selectedFiles.map((fileName) => path.join(crsDir, fileName));
+  if (!targetPaths.every((targetPath) => fs.existsSync(targetPath))) {
+    return null;
+  }
+  const metadata = readJson(path.join(crsDir, "metadata.json"));
+  let metadataVersion;
+  try {
+    metadataVersion = requireCanonicalGroth16CompatibleBackendVersion(
+      metadata.compatibleBackendVersion,
+      "installed Groth16 MPC CRS version",
+    );
+  } catch {
+    return null;
+  }
+  if (metadataVersion !== normalizedVersion) {
+    return null;
+  }
+  const provenance = readJson(path.join(crsDir, "zkey_provenance.json"));
+  return {
+    source: "local-cache",
+    archiveName: provenance.published_archive_name ?? null,
+    archiveFileId: parseDriveFileIdFromDownloadUrl(provenance.zkey_download_url),
+    folderUrl: provenance.published_folder_url ?? null,
+    version: normalizedVersion,
+    installedFiles: selectedFiles.map((archivePath, index) => ({
+      archivePath,
+      targetPath: targetPaths[index],
+    })),
+  };
+}
+
+function parseDriveFileIdFromDownloadUrl(value) {
+  if (typeof value !== "string" || value.length === 0) {
+    return null;
+  }
+  try {
+    return new URL(value).searchParams.get("id");
+  } catch {
+    return null;
+  }
+}
+
 function installManagedNpmPackage({ packageName, version, cacheBaseRoot = resolveArtifactCacheBaseRoot() }) {
   const normalizedPackageName = requireNonEmptyString(packageName, "packageName");
   const normalizedVersion = requireSemverVersion(version, `${normalizedPackageName} version`);
@@ -5625,15 +6002,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 +6045,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 +6083,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 +6144,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 +6161,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: {