Tokamak-zk-EVM

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

It's currently under development. In the near future, you can generate ZKPs off-chain and use them to replace on-chain Ethereum transactions.

Getting started

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

Note: We also provide Playground, a one-click application designed for non-developers (no prerequisite installation).

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 --setup <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 Docker_for_Windows -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

• 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

  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. Build and Setup (Build source code, 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. Prove (generate a proof for a transaction)

# Save to a custom directory (recommended)
./tokamak-cli --prove <TX_HASH> <PATH_TO_SAVE_PROOF?>

Notes

• If <PATH_TO_SAVE_PROOF> is omitted, the cli will use the default path: ./.your_proof
• Ensure your transaction hash is on the Ethereum Mainnet, matching the Alchemy RPC URL written in .env.

3. Verify (Verify a proof generated from the Prove command)

./tokamak-cli --verify <PATH_TO_PROOF>

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 --setup, 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	🔥 Alpha
synthesizer	Compiler that converts an Ethereum transaction into a circuit for Tokamak zk-SNARK	javascript	🔥 Alpha

Backend Packages

Package	Description	Language	Status
mpc-setup	Tokamak zk-SNARK's setup alogirhtm (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

Status as of Aug. 2025

• 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.
• The alpha release of our transaction-to-circuit compiler is ready to use:
  • Given honest input Ethereum state and an honest transaction, the circuit verifies that the output Ethereum state is derived exactly as specified in the transaction.

Future updates

• The beta release of our transactions-to-circuit compiler, which covers:
  • Signature verification of batch transactions,
  • Merkle proof verification of input Ethereum state,
  • Accurate derivation of output Ethereum state as specified by a sequence of transactions,
  • Merkle root update based on output Ethereum state.
• Off-chain tools for writing transactions and generating ZKPs.
• Ethereum bridge contracts that provide communication protocols between the Ethereum main network and off-chain.

Documentation

• Project Tokamak zk-EVM(Medium) (Last updated in Apr. 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 licensed under MPL-2.0.