Tokamak-zk-EVM

Tokamak zk-EVM is a tool that converts TokamakL2JS transactions into ZKPs.

TokamakL2JS, which is a variant of EthereumJS, specifies a layer 2 protocol of Tokamak Network.

If you are interested in converting Ethereum transactions to ZKP, check out branch "archive-airdrop-Sep25" (incomplete development).

Getting started

This section describes how to use the main CLI named tokamak-cli.

Prerequisites

Alchemy API key

1. Create an Alchemy account and log in to the dashboard (https://dashboard.alchemy.com/).
2. Create a new app/project for Ethereum Mainnet.
3. Copy the API Key (the short token).
   You will pass this key to the CLI as --install <API_KEY>.

Note: You can paste the full RPC URL obtained from any provider other than Alchemy.

For Windows users

1. Install Docker Desktop for Windows – https://docs.docker.com/desktop/install/windows-install/
2. (If you want to use CUDA/GPU) Install NVIDIA GPU driver on Windows and verify Docker GPU pass-through.
   • Install the latest NVIDIA driver.
   • Ensure Docker Desktop is using Linux containers with the WSL 2 backend.
   • (Optional) Test that CUDA is visible inside containers (at the host):

     nvidia-smi
     
     docker run --rm --gpus all nvidia/cuda:12.2.0-runtime-ubuntu22.04 nvidia-smi
     

3. Run Docker
   • Make sure that you are in the root directory, Tokamak-zk-EVM.

     docker build -f dockerfile -t tokamak-zkevm:win .
     
     # If you will use CUDA/GPU
     docker run --gpus all --rm -it -v "$(cygpath -m "$PWD"):/workspace" tokamak-zkevm:win bash 
     # Else
     docker run --rm -it -v "$(cygpath -m "$PWD"):/workspace" tokamak-zkevm:win bash 

For macOS users

Option 1: Automatic Setup (Recommended)

Run the setup script to automatically check and install all prerequisites:

./scripts/setup-macos.sh

This script will detect the following dependencies and install any missing automatically.

Option 2: Manual Installation

• Install Node.js – https://nodejs.org/
• Install Circom – https://docs.circom.io/getting-started/installation/
• Install Rust – https://www.rust-lang.org/tools/install
• Install CMake – https://cmake.org/download/
• Install Bun – https://bun.sh/ (required for Synthesizer binary build)
• Install dos2unix

  brew install dos2unix

For Linux users

• Install Node.js – https://nodejs.org/
• Install Circom – https://docs.circom.io/getting-started/installation/
• Install Rust – https://www.rust-lang.org/tools/install
• Install CMake – https://cmake.org/download/
• Install dos2unix
  • For example, Ubuntu/Debian:

    sudo apt-get update && sudo apt-get install -y dos2unix

• If you want to use CUDA for GPU acceleration:
  1. Install the NVIDIA GPU driver appropriate for your distro (verify with nvidia-smi).
     Docs: https://docs.nvidia.com/cuda/
  2. Install CUDA runtime libraries (matching your driver’s supported CUDA version).
     Follow the CUDA Installation Guide for Linux in the docs above.
  3. (Optional) Quick checks:

     nvidia-smi
     ldconfig -p | grep -E 'libcudart|libcublas|libcudnn' || true

Before first run (line endings & permissions)

To avoid compatibility/permission issues on the main script itself:

• Convert CRLF → LF on the CLI script:

  # Run from the repo root
  dos2unix tokamak-cli

• Make the CLI executable:

  chmod +x tokamak-cli

How to run (for all platforms)

From the repository root:

1. Install (Install deps, compile circuits, write RPC URL using your Alchemy API key, run trusted setup, then run OS-specific backend packaging)

./tokamak-cli --install <YOUR_ALCHEMY_API_KEY | FULL_RPC_URL>

2. Synthesize (prepare inputs using a transaction config JSON)

./tokamak-cli --synthesize <PATH_TO_CONFIG_JSON>

A template for the config JSON lives in synthesizer-input-template/.

3. Preprocess (backend preprocess stage)

./tokamak-cli --preprocess

4. Prove (backend prove stage; outputs stay under dist/<platform>/resource/prove/output)

./tokamak-cli --prove

5. Verify (verify proof artifacts in dist; optional resource overlay path)

# Uses dist/<platform>/resource by default
./tokamak-cli --verify

# Or provide a directory containing a resource/ folder to overlay into dist before verifying
./tokamak-cli --verify <PATH_WITH_RESOURCE>

6. Extract proof bundle (optional; zip key artifacts)

./tokamak-cli --extract-proof <OUTPUT_DIR>

Disclaimer

• The Tokamak‑zk‑EVM project and its maintainers are not responsible for any leakage or misuse of your API keys or credentials.
• For local testing, use a free, non‑sensitive Alchemy API key. Do not use production or paid keys, or keys tied to sensitive data.
• During --install, the CLI writes your RPC endpoint to packages/frontend/synthesizer/.env. We recommend deleting .env after use (or rotating the key) and ensuring it is not committed to version control.

Package Composition

Frontend Packages (compilers)

Package	Description	Language	Status
qap-compiler	Library of subcircuits for basic EVM operations	Circom	🧪 Beta
synthesizer	Compiler that converts an Ethereum transaction into a circuit for Tokamak zk-SNARK	TypeScript	🧪 Beta

Backend Packages

Package	Description	Language	Status
mpc-setup	Tokamak zk-SNARK's setup algorithm (multi-party computation version)	Rust	🧪 Beta
trusted-setup	Tokamak zk-SNARK's setup algorithm (trusted single entity version)	Rust	🧪 Beta
prover	Tokamak zk-SNARK's proving algorithm	Rust	🧪 Beta
verify	Tokamak zk-SNARK's verifying algorithm	Rust, Solidity	🧪 Beta

Notes:

• 🔥 Alpha: Initial proof-of-concept for testing
• 🧪 Beta: Fully featured, but unstable and unoptimized
• ⭐️ Stable (v1.0.0): Fully featured, stable, and optimized

Development status

Sep. 2025

• Archived in branch "archive-airdrop-Sep25".
• Incomplete conversion of Ethereum transactions into ZKPs.
• What does "incomplete" mean? ZKPs only include the execution of a transaction's opcodes. Verification of input state and the transaction signature, as well as reconstruction of output state, are excluded.
• The Tokamak zk-SNARK backend is ready to use:
  • MSM and NTT are accelerated by ICICLE APIs.
  • It requires < 10GB memory.
  • A ZKP can be generated in 1-2 mins on CUDA or Apple silicon.

Jan. 2026

• The current main branch.
• Complete conversion of Tokamak Layer 2 transactions into ZKPs, which covers:
  • Verification of transaction signatures,
  • Verification of input state,
  • Execution of transaction opcodes,
  • Reconstruction of output state.
• Compatible with Tokamak Private App Channels.

Documentation

• Project Tokamak Network ZKP (Medium) (Last updated in Nov. 2025)
• Project Tokamak zk-EVM(Slide) (Last updated in Jul. 2025)
• Tokamak zk-SNARK Paper (Last updated in Apr. 2025)
• Frontend - Synthesizer (work in progress)

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

License

This project is dual-licensed under:

• MIT License
• Apache License 2.0

You may choose either license when using this software. This dual-licensing approach is standard in the Rust ecosystem and provides maximum compatibility with other open-source projects.