zk-evm - SKILL.md Agent Skill

name: zk-evm description: > Activate when the user works with Tokamak zk-EVM, tokamak-cli, zero-knowledge proofs for Ethereum transactions, the Synthesizer, QAP compiler, subcircuits, Circom circuits, zk-SNARK backend, trusted setup, placementVariables, permutation, or TokamakL2JS. license: MIT metadata: author: tokamak-network version: "1.0.0"

Tokamak zk-EVM

Converts Tokamak L2 transactions into zero-knowledge proofs. The system has two halves: a frontend (TypeScript, compiles transactions → circuits) and a backend (Rust, proves and verifies circuits).

Source: https://github.com/tokamak-network/Tokamak-zk-EVM

Architecture

tokamak-cli (entry point)
│
├── Frontend (compilers)
│   ├── qap-compiler     — Circom subcircuit library for EVM opcodes
│   │                       Output: subcircuits/library/
│   └── synthesizer      — Converts a transaction batch into a circuit
│                           Output: placementVariables.json, instance.json,
│                                   instance_description.json, permutation.json
│
└── Backend (Rust)
    ├── trusted-setup     — Generates reference string from subcircuit library
    │                       Output: combined_sigma.rkyv, sigma_verify.rkyv
    ├── prover            — Generates zk proof from circuit + setup outputs
    │                       Output: zk proof file
    └── verify            — Accepts or rejects the proof

tokamak-cli Commands

The main entry point. All commands run from the repo root:

# 1. Install: deps, compile circuits, trusted setup
./tokamak-cli --install <ALCHEMY_API_KEY | RPC_URL>

# 2. Synthesize: transaction → circuit artifacts
./tokamak-cli --synthesize <path/to/input.json>

# 3. Preprocess: backend preprocess stage
./tokamak-cli --preprocess

# 4. Prove: generate zk proof
./tokamak-cli --prove

# 5. Verify: check proof validity
./tokamak-cli --verify

# 6. Extract proof bundle (optional)
./tokamak-cli --extract-proof <output.zip>

Monorepo Structure

Tokamak-zk-EVM/
├── tokamak-cli              # Bash wrapper → scripts/tokamak-cli-core
├── packages/
│   ├── frontend/
│   │   ├── qap-compiler/    # Circom subcircuits (ALU1-5, crypto primitives)
│   │   │   ├── subcircuits/circom/   # Source .circom files
│   │   │   ├── subcircuits/library/  # Compiled output
│   │   │   └── scripts/compile.sh    # Build script
│   │   └── synthesizer/     # TypeScript, converts tx → circuit
│   │       ├── src/
│   │       │   ├── synthesizer/       # EVM opcode hooking
│   │       │   ├── circuitGenerator/  # Witness/permutation generation
│   │       │   ├── interface/         # Input helpers (RPC, state)
│   │       │   └── TokamakL2JS/      # L2-specific primitives
│   │       ├── examples/             # L2TONTransfer, L2StateChannel
│   │       └── outputs/              # Generated circuit artifacts
│   └── backend/
│       ├── setup/           # trusted-setup (Rust) + mpc-setup (Rust)
│       ├── prove/           # Prover (Rust, ICICLE GPU acceleration)
│       └── verify/          # Verifier (Rust + Solidity)
├── synthesizer-input-template/  # Template input.json
├── config/                  # Lerna/TS configs
└── docs/                    # Team formatting rules

Synthesizer Input Format

The transaction config JSON (input.json):

{
  "privateKeySeedsL2": ["sender seed", "recipient seed", ...],
  "addressListL1": ["0x...", "0x...", ...],
  "userStorageSlots": [0],
  "senderIndex": 0,
  "recipientIndex": 1,
  "initStorageKey": "0x07",
  "txNonce": 0,
  "blockNumber": 23224548,
  "contractAddress": "0x2be5e8c109e2197D077D13A82dAead6a9b3433C5",
  "amount": "0x4563918244f400000",
  "transferSelector": "0xa9059cbb"
}

Template: synthesizer-input-template/input.json

Synthesizer Outputs

After --synthesize, the outputs/ directory contains:

File	Description	Used By
`placementVariables.json`	Subcircuit instances with wire values	Prover
`instance.json`	Public + private input values	Prover, Verifier
`instance_description.json`	Human-readable description of public inputs	Documentation
`permutation.json`	Copy constraints (wiring between subcircuits)	Prover

QAP Compiler: Subcircuit Library

5 ALUs handle 256-bit EVM operations:

ALU	Operations
ALU1	ADD, MUL, SUB, SubExp, EQ, ISZERO, NOT
ALU2	DIV, SDIV, MOD, SMOD, ADDMOD, MULMOD
ALU3	SHL, SHR, SAR
ALU4	LT, GT, SLT, SGT
ALU5	SIGNEXTEND, BYTE

Crypto primitives: Poseidon hash, EdDSA (jubjub + Poseidon) signatures, Merkle tree proofs.

Build the subcircuit library:

cd packages/frontend/qap-compiler
npm install
./scripts/compile.sh

Prerequisites

Dependency	Purpose
Node.js >= 18	Synthesizer, CLI
Circom	Subcircuit compilation
Rust	Backend (setup, prove, verify)
CMake	Backend build
Bun	Synthesizer binary build
dos2unix	Line ending conversion
Alchemy API key	Ethereum RPC for state queries

macOS auto-setup: ./scripts/setup-macos.sh

Common Mistakes

Mistake	Fix
Running without `--install` first	Always run `--install` before other commands
CRLF line endings on tokamak-cli	`dos2unix tokamak-cli && chmod +x tokamak-cli`
Forgetting `.env` with RPC URL	Create `packages/frontend/synthesizer/.env` with `RPC_URL=...`
Insufficient buffer sizes in qap-compiler	Increase buffer subcircuit sizes, recompile
Committing `.env` with API key	Delete `.env` after use, rotate key if exposed

Code Style

120 char line width (not 80)
Compact code preferred — one info unit = one line
Prettier: printWidth: 120, semi: true, singleQuote: true, arrowParens: "avoid"
Format: npm run format

Full formatting rules: See references/formatting-rules.md

Supported / Unsupported Opcodes

Supported: ADD–SAR, EXP, SIGNEXTEND, ADDRESS–BASEFEE, POP, MLOAD/MSTORE, SLOAD/SSTORE, PUSH0–PUSH32, DUP/SWAP, LOG0–LOG4, CALL/CALLCODE/DELEGATECALL/STATICCALL, RETURN, REVERT

Not supported: KECCAK256, BLOBHASH, BLOBBASEFEE, TLOAD, TSTORE, CREATE, CREATE2, SELFDESTRUCT

Related Skills

tokamak-contracts: Contract addresses used in synthesizer inputs
thanos-l2: Thanos L2 where zk-EVM proofs are verified