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

package/CHANGELOG.md

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

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,11 +19,12 @@ 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 whose major.minor compatibility version matches the
@@ -63,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
@@ -117,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

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.8",
+  "version": "0.1.9",
   "description": "Command-line client for the Tokamak private-state DApp.",
   "license": "MIT OR Apache-2.0",
   "author": "Tokamak Network",
@@ -43,10 +43,10 @@
     "@ethereumjs/util": "^10.1.1",
     "@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",
+    "@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

@@ -166,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);
@@ -373,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({
@@ -399,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,
@@ -426,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)),
@@ -441,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 }) {
@@ -514,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);
@@ -580,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(),
   };
@@ -1194,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(
@@ -1241,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";
   }
 
@@ -1267,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,
@@ -1296,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)),
   );
@@ -1402,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(
@@ -1462,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);
@@ -3118,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,
@@ -3132,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(
@@ -3517,6 +3718,53 @@ 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();
@@ -3927,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));
@@ -4813,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",
   );
 }
 
@@ -4983,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
@@ -5002,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
@@ -5468,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,
@@ -5482,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) {
@@ -5532,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"];
@@ -5561,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,
@@ -5585,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`);