Tokamak Groth16 zkSNARK Package

This directory is the @tokamak-private-dapps/groth16 npm package. It contains the Groth16 circuit, Dusk-backed MPC setup tooling, and proof generation helpers used by Tokamak private DApps.

Architecture

The package currently supports the updateTree circuit. The circuit proves one channelTokenVault leaf update against the fixed-depth Tokamak managed-storage tree used by the bridge. The generated entrypoint renders updateTree(MT_DEPTH) from the locally installed tokamak-l2js package; the current generated depth is 36.

The proof binds five public values:

• root_before
• root_after
• storage_key
• storage_value_before
• storage_value_after

The witness provides the derived leaf index and Merkle sibling path. The circuit constrains the leaf index to the lower MT_DEPTH bits of storage_key, verifies the before-root path with storage_value_before, verifies the after-root path with storage_value_after, and requires the before and after values to differ. This lets bridge contracts verify channel-token-vault accounting updates without storing the full tree on-chain.

CLI

The package exposes a standalone Groth16 runtime CLI:

tokamak-groth16 --install
tokamak-groth16 --prove packages/groth16/prover/updateTree/input_example.json
tokamak-groth16 --verify
tokamak-groth16 --extract-proof ./update-tree-proof.zip
tokamak-groth16 --doctor

The fixed workspace is:

~/tokamak-private-channels/groth16/

--install downloads the latest public Groth16 MPC CRS archive from the hard-coded Groth16 CRS Drive folder, installs circuit_final.zkey, verification_key.json, metadata.json, and zkey_provenance.json, renders the updateTree circuit from package-local templates, and compiles the circuit WASM/R1CS into the workspace build directory.

--install --trusted-setup does not copy any package-local CRS. It renders and compiles the workspace circuit, runs a local snarkjs powers-of-tau and Groth16 setup, and writes the generated CRS only under the fixed workspace:

~/tokamak-private-channels/groth16/crs/circuit_final.zkey
~/tokamak-private-channels/groth16/crs/verification_key.json
~/tokamak-private-channels/groth16/crs/metadata.json
~/tokamak-private-channels/groth16/crs/zkey_provenance.json

--install --docker is supported on Linux hosts and Windows hosts with Docker Desktop. It builds the packaged Ubuntu 22 Docker image, mounts the fixed Groth16 workspace into the container, runs the install flow there, and stores Docker bootstrap files under:

~/tokamak-private-channels/groth16/docker/

After a Docker install, --prove and --verify run snarkjs through the saved Docker bootstrap when Docker is available. Linux hosts can fall back to native snarkjs when Docker is not running. Windows hosts require Docker Desktop because native Groth16 runtime execution is not supported there. macOS hosts should use the native install path.

--prove <INPUT_JSON> runs the proving flow only: witness generation, proof generation, and public signal generation. It always writes proof artifacts to fixed workspace paths:

~/tokamak-private-channels/groth16/proof/input.json
~/tokamak-private-channels/groth16/proof/proof.json
~/tokamak-private-channels/groth16/proof/public.json
~/tokamak-private-channels/groth16/proof/proof-manifest.json

--verify [<PROOF_ZIP|DIR>] verifies an existing proof.json and public.json against the installed workspace verification key. Running --prove does not verify the proof.

--extract-proof <OUTPUT_ZIP_PATH> is the only Groth16 CLI command that lets the user choose an output file path. It exports the fixed workspace proof artifacts into the requested zip file.

Generating Proofs with snarkjs

Prerequisites

1. Install snarkjs globally:

npm install -g snarkjs

2. Run tokamak-groth16 --install or tokamak-groth16 --install --trusted-setup so the workspace contains:
   • Circuit WASM file: ~/tokamak-private-channels/groth16/build/circuit_updateTree.wasm
   • Final proving key: ~/tokamak-private-channels/groth16/crs/circuit_final.zkey
   • Verification key: ~/tokamak-private-channels/groth16/crs/verification_key.json

Input Format

Create an input JSON file for one leaf update:

{
  "root_before": "1",
  "root_after": "2",
  "leaf_index": "3",
  "storage_key": "3",
  "storage_value_before": "100",
  "storage_value_after": "200",
  "proof": ["<36 sibling values>"]
}

The proof array must contain one sibling value per tree level. For the current generated MT_DEPTH = 36 circuit, it therefore contains 36 entries. For a runnable local example, use packages/groth16/prover/updateTree/input_example.json; it is generated from the installed tokamak-l2js tree helper and matches the current circuit depth.

Generate a Proof

1. Calculate witness:

snarkjs wtns calculate ~/tokamak-private-channels/groth16/build/circuit_updateTree.wasm input.json witness.wtns

This generates witness.wtns - a binary file containing all the intermediate values (witness) computed by the circuit for your specific input.

2. Generate the proof:

snarkjs groth16 prove ~/tokamak-private-channels/groth16/crs/circuit_final.zkey witness.wtns proof.json public.json

This creates:

• proof.json: The zero-knowledge proof
• public.json: Public inputs/outputs

Verify a Proof

Verify the proof using the verification key:

snarkjs groth16 verify ~/tokamak-private-channels/groth16/crs/verification_key.json public.json proof.json

Example Workflow

# 1. Create input file from the bundled deterministic example
cp packages/groth16/prover/updateTree/input_example.json input.json

# 2. Calculate witness
snarkjs wtns calculate ~/tokamak-private-channels/groth16/build/circuit_updateTree.wasm input.json witness.wtns

# 3. Generate proof
snarkjs groth16 prove ~/tokamak-private-channels/groth16/crs/circuit_final.zkey witness.wtns proof.json public.json

# 4. Verify proof
snarkjs groth16 verify ~/tokamak-private-channels/groth16/crs/verification_key.json public.json proof.json

Proof Format

The generated proof follows the Groth16 format for BLS12-381:

{
  "pi_a": ["...", "...", "1"],
  "pi_b": [["...", "..."], ["...", "..."], ["1", "0"]],
  "pi_c": ["...", "...", "1"],
  "protocol": "groth16",
  "curve": "bls12381"
}

Integration with Smart Contracts

The verification key and proofs are compatible with Ethereum smart contracts using a generated Solidity verifier. In this repository, the bridge owns the generated verifier source under bridge/src/generated/Groth16Verifier.sol.