Tokamak-zk-EVM CLI

NPX-installable CLI package for Tokamak-zk-EVM proof generation and verification using pre-built binaries.

Features

🚀 One-command installation: npx create-tokamak-zk-evm
🔐 Zero-knowledge proof generation from transaction hashes
✅ Advanced proof verification with multiple modes:
- 🎯 Interactive mode: Select proofs from a list
- 🔄 Regenerate mode: Rebuild components before verification
- 📊 Detailed results: Format validation + cryptographic verification
🔧 Interactive trusted setup with arrow key navigation
📦 Automatic binary management with platform detection
🌐 Cross-platform support (macOS, Linux)
📊 Progress tracking and detailed logging
📁 Output management and export utilities

Quick Start

Installation

# Create a new project (will prompt for global installation)
npx create-tokamak-zk-evm my-zk-project
cd my-zk-project

# Or initialize in existing directory
npx create-tokamak-zk-evm

# Optional: Install globally for easier usage
npm install -g create-tokamak-zk-evm

Command Usage

If CLI is installed globally: Use tokamak-zk-evm directly
If CLI is not installed globally: Use npx tokamak-zk-evm or npm run scripts (in project directory)

Generate a Proof

# Simple proof generation (if RPC URL is configured)
tokamak-zk-evm prove 0x6c7903e420c5efb27639f5186a7474ef2137f12c786a90b4efdcb5d88dfdb002

# Generate proof with RPC URL
tokamak-zk-evm prove 0x6c7903e420c5efb27639f5186a7474ef2137f12c786a90b4efdcb5d88dfdb002 \
  --rpc-url https://mainnet.infura.io/v3/YOUR-PROJECT-ID \
  --verbose

# Generate proof with custom output directory
tokamak-zk-evm prove 0x6c7903e420c5efb27639f5186a7474ef2137f12c786a90b4efdcb5d88dfdb002 \
  --rpc-url https://mainnet.infura.io/v3/YOUR-PROJECT-ID \
  --output-dir ./my-proofs \
  --keep-intermediates

# Using npm scripts (in project directory)
npm run prove 0x6c7903e420c5efb27639f5186a7474ef2137f12c786a90b4efdcb5d88dfdb002

Verify a Proof

# Basic verification
tokamak-zk-evm verify ./tokamak-zk-evm-outputs/proof-0x6c7903e420-2024-01-15T10-30-00-000Z

# Interactive mode - select from available proofs
tokamak-zk-evm verify --interactive

# Regenerate mode - regenerate from proof.json and transaction_hash.txt
tokamak-zk-evm verify --regenerate ./path/to/proof-directory

# Using npm scripts (in project directory)
npm run verify -- --interactive

Export Outputs

# Export all outputs
tokamak-zk-evm export all ./exported-proof

# Export only proof files
tokamak-zk-evm export proof ./my-proof.json --format json

# Export specific type
tokamak-zk-evm export synthesizer ./synthesis-outputs

Commands

`init [project-name]`

Initialize a new Tokamak-zk-EVM project.

tokamak-zk-evm init my-project
tokamak-zk-evm init --network sepolia --skip-binary

Options:

--output-dir <dir>: Custom output directory
--network <network>: Target network (mainnet/sepolia)
--rpc-url <url>: RPC URL for blockchain connection
--skip-binary: Skip binary download during initialization
--setup-mode <mode>: Setup mode: "download", "local", "skip", or "ask" (default)

`prove <tx-hash>`

Generate a zero-knowledge proof for a transaction.

tokamak-zk-evm prove 0x123...abc --rpc-url https://mainnet.infura.io/v3/YOUR-PROJECT-ID

Options:

--output-dir <dir>: Custom output directory
--keep-intermediates: Keep intermediate files
--verbose: Show detailed output
--network <network>: Target network (mainnet/sepolia)
--skip-trusted-setup: Skip trusted setup (if already run)
--rpc-url <url>: RPC URL for transaction data (required)

`verify [proof-file]`

Verify a zero-knowledge proof with multiple modes.

tokamak-zk-evm verify --interactive
tokamak-zk-evm verify ./proof-directory --verbose
tokamak-zk-evm verify --regenerate ./proof-directory

Options:

--interactive: Interactive mode to select from list-outputs
--regenerate: Regenerate proof components from proof.json and transaction_hash.txt
--output-dir <dir>: Output directory to scan for proofs (default: ./tokamak-zk-evm-outputs)
--verbose: Show detailed output

Regenerate Mode Requirements:

Directory must contain proof.json file
Directory must contain transaction_hash.txt file
RPC URL must be configured in project

`setup [--mode <mode>]`

Configure trusted setup for proof generation with interactive mode.

tokamak-zk-evm setup                    # Interactive mode with arrow key navigation
tokamak-zk-evm setup --mode download   # Download pre-computed files
tokamak-zk-evm setup --mode local      # Run local trusted setup

Options:

--mode <mode>: Setup mode: "download", "local", or "skip"

Setup Modes:

download: Download pre-computed setup files from GitHub releases (recommended, faster)
local: Run trusted setup locally (more secure but takes several minutes)
skip: Skip setup for now (can run later when needed)

`export <type> <destination>`

Export proof outputs.

tokamak-zk-evm export all ./exported-proof
tokamak-zk-evm export proof ./proof.json --format json

Types: all, proof, synthesizer, preprocess, verify Formats: files (default), json

`status`

Show current CLI status and configuration.

tokamak-zk-evm status --verbose

Utility Commands

# List all proof outputs
tokamak-zk-evm list-outputs

# Configure trusted setup (interactive)
tokamak-zk-evm setup

# Show status
tokamak-zk-evm status

# Clean cache and temporary files
tokamak-zk-evm clean --all
tokamak-zk-evm clean --cache
tokamak-zk-evm clean --outputs

# Update binary to latest version
tokamak-zk-evm update

Configuration

Global Configuration

Global settings are stored in ~/.tokamak-zk-evm/config.json:

{
  "binaryVersion": "latest",
  "outputDir": "./tokamak-zk-evm-outputs",
  "keepIntermediates": false,
  "network": "mainnet",
  "cacheDir": "~/.tokamak-zk-evm",
  "rpcUrl": "https://mainnet.infura.io/v3/YOUR-PROJECT-ID"
}

Project Configuration

Create a tokamak.config.js file in your project:

module.exports = {
  network: 'mainnet', // or 'sepolia'
  outputDir: './tokamak-zk-evm-outputs',
  keepIntermediates: false,
  rpcUrl: 'https://mainnet.infura.io/v3/YOUR-PROJECT-ID',
  customScripts: {
    // postProve: './scripts/post-process.js',
  },
};

RPC Configuration

The synthesizer requires an RPC URL to fetch transaction data. You can provide it in several ways:

Command line option:

tokamak-zk-evm prove 0x123...abc --rpc-url https://mainnet.infura.io/v3/YOUR-PROJECT-ID

Project configuration:

// tokamak.config.js
module.exports = {
  rpcUrl: 'https://mainnet.infura.io/v3/YOUR-PROJECT-ID',
};

Environment variable:

export RPC_URL=https://mainnet.infura.io/v3/YOUR-PROJECT-ID
tokamak-zk-evm prove 0x123...abc

Supported RPC Providers

⚠️ Important: Your RPC endpoint MUST be a full archival node to access historical transaction data and state. Standard nodes may not have the complete historical data required for proof generation.

Infura: https://mainnet.infura.io/v3/YOUR-PROJECT-ID (Archive plan required)
Alchemy: https://eth-mainnet.alchemyapi.io/v2/YOUR-API-KEY (Archive tier required)
QuickNode: https://your-endpoint.quiknode.pro/YOUR-API-KEY/ (Archive add-on required)
Custom RPC: Any Ethereum-compatible full archival node endpoint

Binary Management

The CLI automatically downloads and manages Tokamak-zk-EVM binaries:

Automatic platform detection (macOS, Linux)
Latest release fetching from Tokamak-zk-EVM Release
Local caching in ~/.tokamak-zk-evm/binaries/
Version management and updates

Binary Structure

tokamak-zk-evm-{platform}/
├── bin/                    # Executable binaries
│   ├── preprocess
│   ├── prove
│   ├── synthesizer
│   ├── trusted-setup
│   └── verify
├── resource/               # Resource files
│   ├── qap-compiler/
│   └── setup/
└── *.sh                   # Execution scripts

Proof Generation Workflow

The proof generation follows this sequence:

Trusted Setup (one-time): 1_run-trusted-setup.sh
Synthesizer: 2_run-synthesizer.sh <tx-hash> (requires RPC URL)
Preprocessing: 3_run-preprocess.sh
Proof Generation: 4_run-prove.sh
Verification: 5_run-verify.sh

Output Structure

Generated proofs are organized as follows:

tokamak-zk-evm-outputs/
└── proof-{tx-hash-prefix}-{timestamp}/
    ├── summary.json        # Proof metadata
    ├── synthesizer/        # Synthesis outputs
    ├── preprocess/         # Preprocessing outputs
    ├── prove/              # Proof files
    │   ├── proof.json
    │   └── public_inputs.json
    └── verify/             # Verification results
        └── verification.json

Verification Results

The CLI provides clear verification results with two levels of validation:

1. Format Validation

✅ Proof format is VALID: The proof file is properly formatted and readable

2. Cryptographic Verification

✅ Verification result: TRUE: The proof is mathematically valid and cryptographically sound
❌ Verification result: FALSE: The proof is invalid or tampered with

Example Output

✅ Proof format is VALID
✅ Verification result: TRUE

🔍 Verification Details
=======================
Proof Status: ✅ Valid
Verification Result: TRUE
Verified At: 9/8/2025, 4:58:11 PM
Exit Code: 0
Message: Proof verification successful

Troubleshooting

Common Issues

Binary not found
```
tokamak-zk-evm init  # Download binary
```

Trusted setup files missing

tokamak-zk-evm setup  # Interactive setup configuration
# or
tokamak-zk-evm init --setup-mode download  # Download during init

RPC URL not set

tokamak-zk-evm prove 0x123...abc --rpc-url https://your-rpc-url

Platform not supported
- Only macOS and Linux (x64/arm64) are supported

Permission denied

chmod +x ~/.tokamak-zk-evm/binaries/*/bin/*
chmod +x ~/.tokamak-zk-evm/binaries/*/*.sh

Debug Mode

Enable detailed logging:

tokamak-zk-evm prove 0x123...abc --debug --verbose

Clean Installation

tokamak-zk-evm clean --all
tokamak-zk-evm init
tokamak-zk-evm setup  # Configure trusted setup

Requirements

Node.js: >= 20.0.0
Platform: macOS or Linux (x64/arm64)
RPC Access: Ethereum RPC endpoint for transaction data

License

MIT License - see LICENSE file for details.

Support

Issues: GitHub Issues
Community: Tokamak ZKP World Discord, Tokamak ZKP World X

Made with ❤️ by Tokamak Network

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
.cursor/rules		.cursor/rules
dist		dist
examples		examples
scripts		scripts
src		src
templates		templates
test-verify-project		test-verify-project
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.prettierrc		.prettierrc
LICENSE		LICENSE
README.md		README.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
tokamak.config.js		tokamak.config.js
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Tokamak-zk-EVM CLI

Features

Quick Start

Installation

Command Usage

Generate a Proof

Verify a Proof

Export Outputs

Commands

init [project-name]

prove <tx-hash>

verify [proof-file]

setup [--mode <mode>]

export <type> <destination>

status

Utility Commands

Configuration

Global Configuration

Project Configuration

RPC Configuration

Supported RPC Providers

Binary Management

Binary Structure

Proof Generation Workflow

Output Structure

Verification Results

1. Format Validation

2. Cryptographic Verification

Example Output

Troubleshooting

Common Issues

Debug Mode

Clean Installation

Requirements

License

Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`init [project-name]`

`prove <tx-hash>`

`verify [proof-file]`

`setup [--mode <mode>]`

`export <type> <destination>`

`status`

Packages