⚔️ Guillotine (Alpha)

<p align="center"> <a href="https://github.com/evmts/Guillotine/actions/workflows/ci.yml"> <img src="https://github.com/evmts/Guillotine/actions/workflows/ci.yml/badge.svg" alt="CI Status" /> </a> <a href="https://t.me/+ANThR9bHDLAwMjUx"> <img alt="Telegram" src="https://img.shields.io/badge/chat-telegram-blue.svg"> </a> <a href="https://deepwiki.com/evmts/Guillotine"> <img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"> </a> </p>

<a href="docs/pages"><img width="833" height="444" alt="Guillotine Logo" src="https://github.com/user-attachments/assets/1effa677-d931-4453-8e98-2a70372efd91" /></a>

The ultrafast EVM for every language and platform

---

🔄 Repository in Flux: This repo is currently undergoing significant refactoring as we prepare to release a new Zig library that will be like ethers.js or alloy for Zig. More updates coming soon!

---

🚧 Development Status (Early Alpha)

Current Status: DO NOT USE IN PRODUCTION

Guillotine is not suitable for production use at this time. Any use of Guillotine should be considered purely experimental.

📊 Ethereum Specification Test Results

Latest Test Run: 2251 tests executed

• ✅ 1165 passing (~52% pass rate)
• ❌ 1086 failing (~48% fail rate)

Most failures are in ecmul/BN254 elliptic curve tests. Run specs with: zig build specs

See specs/README.md for detailed instructions on running the test suite.

Current Development Focus: Our primary goal is achieving 100% Ethereum specification compliance while ensuring complete safety, debuggability, and observability through our tracer system (src/tracer/tracer.zig). The tracer provides comprehensive execution monitoring, differential testing against a reference implementation, and detailed error reporting for every opcode.

For an in-depth understanding of Guillotine's design and implementation, see our comprehensive Architecture Documentation. Follow the issue tracker for features planned for Beta.

Network Support: Currently only Ethereum Mainnet is supported. Planned for Beta:

• OP Stack support (Optimism, Base, etc.)
• Arbitrum Nitro support

---

✨ Features

🚧 = Coming soon. Consider opening a discussion if you have any API recommendations or requested features.

• ⚡ Extreme speed
• 🌐 Universal - Planned and experimental support for many languages and platforms
  • Golang - Available with FFI bindings
  • Zig
  • C
  • TypeScript - Wasm or Bun
  • Rust
  • Wasm
  • 🚧 Python - Looking for contributors
  • 🚧 Swift - Looking for contributors
  • 🚧 Kotlin - Looking for contributors
• 📦 Minimal bundle size
  • Zig comptime configuration means you only pay for features you actually use
  • Skip precompiles or use specific hard forks without bundle size or runtime overhead
• 📚 Well documented
• 🎨 Fun - Guillotine is a fun way to dive into Zig and fun/easy to contribute to
• 🤖 LLM-friendly
• 🧪 Robust - Guillotine takes testing and architecture very seriously with full unit tests for all files, a robust E2E test suite, fuzz testing, differential testing using MinimalEvm, and benchmark testing
• ✨ Useful - 🚧 Coming soon 🚧 Guillotine is building a powerful CLI and native app that you can think of as a local-first, Tenderly-like tool

---

🔨 Building from Source

Currently Supported: macOS Planned: Linux support

Prerequisites

• Zig 0.15.1 (exactly - use zvm to manage versions)
• Rust toolchain 1.75+ (for cryptographic dependencies)
• Git (with submodule support)

Build Steps

# 1. Clone with submodules
git clone --recursive https://github.com/evmts/Guillotine.git
cd Guillotine

# Or if already cloned:
git submodule update --init --recursive

# 2. Build the project
zig build

# 3. Verify the build
zig build test-opcodes

---

🧰 SDKs (Experimental)

All SDKs in this repo are vibecoded proof-of-concepts. APIs are unstable and may change without notice. We're actively seeking early users to try things out and tell us what APIs you want. Please open an issue or ping us on Telegram with feedback.

• Go — Go bindings with FFI to Zig EVM
• Bun — Native Bun bindings around the Zig EVM
• C — C/C++ FFI surface for embedding
• Rust — Idiomatic Rust wrapper over FFI
• TypeScript — WASM/TS APIs for Node, Bun, Browser

Looking for Contributors:

• Python — Help us build Python bindings and primitives
• Swift — Help us build Swift bindings for Apple platforms
• Kotlin — Help us build Kotlin/JVM bindings

See each SDK's README for install, quick start, and current API.

---

📊 Benchmarks & Bundle Size 🚧

Guillotine is fast.

Benchmarks so far look very promising.

• Guillotine shows measurable performance gains over REVM and performance on par with evmone.
• More major optimizations planned for Beta release

Overall Performance Summary (Per Run)

These benchmarks were taken using the evm-bench test cases with hyperfine.

• Benchmarking infra can be seen in previous commits but is currently being moved to its own dedicated repo.
• Looking for contributors to help set up easily reproducible benchmarks

| Test Case | evmone | Guillotine | REVM | Geth | | ----------------------- | -------- | ---------- | -------- | -------- | | erc20-approval-transfer | 1.56 ms | 1.59 ms | 1.67 ms | 3.65 ms | | erc20-mint | 4.26 ms | 4.28 ms | 5.76 ms | 12.84 ms | | erc20-transfer | 6.01 ms | 6.65 ms | 8.30 ms | 17.50 ms | | ten-thousand-hashes | 2.90 ms | 2.46 ms | 3.31 ms | 9.36 ms | | snailtracer | 27.15 ms | 26.41 ms | 39.01 ms | 86.02 ms |

---

Bundle size 🚧

WASM Bundle Sizes
┌───────────────────────────────────────────────────────────────────────────────────────────┐
│ Package         │ Size                                      │ Mode         │ Precompiles   │
├───────────────────────────────────────────────────────────────────────────────────────────┤
│ MinimalEvm     │ ▓▓▓ 56KB                                   │ ReleaseSmall │ ✗ Not included│
│ Guillotine EVM │ ▓▓▓▓▓▓ 119KB                              │ ReleaseSmall │ ✗ Not included│
│ Primitives     │ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ 687KB │ ReleaseSmall │ ✗ Not included│
│ Full Package   │ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ 1.1MB │ ReleaseFast  │ ✓ Included    │
└───────────────────────────────────────────────────────────────────────────────────────────┘

• MinimalEvm: Minimal implementation focused on tracing (57,641 bytes)
• Guillotine EVM: Core EVM implementation
• Primitives: Complete primitives library
• Full Package: All features including precompiles

Note: Smaller packages use ReleaseSmall optimization for size, while the full package uses ReleaseFast for performance. ReleaseSafe builds (recommended for alpha) are larger due to additional safety features and validation overhead.

---

How is Guillotine so fast?

Guillotine was built using data-oriented design with an emphasis on minimizing branch-prediction misses in the CPU. We studied every EVM implementation as well as Wasm, Lua, and Python interpreter implementations for the state of the art. Optimizations include, from most impactful to least impactful:

• An extremely optimized StackFrame and opcode dispatch data structure
• Indirect threading via tailcall recursion (for excellent CPU branch prediction)
• Highly microoptimized opcode instruction handlers
• Highly microoptimized EVM stack implementation
• Opcode fusions turning common opcode patterns into a single dispatch
• Assembly-optimized Keccak via keccak-asm
• Batching calculation of static gas costs and stack analysis
• Simple code that minimizes unnecessary abstractions, inline directives, and interfaces allowing the Zig compiler maximum freedom to optimize for performance or size
• Additional micro-optimizations not listed

Balanced tradeoffs

We focus on maintainable code and targeted optimizations where they matter. We do our best to write simple code the Zig compiler can optimize.

There are many more optimizations that have not been implemented yet. The biggest of which will be translating our stack-based EVM into a register-based EVM—a common technique used by interpreters like Lua and PyPy, and Cranelift-style designs—to achieve up to ~30% performance increases.

---

How is Guillotine so small?

• Zig avoids hidden control flow.
• This makes it really easy to write the most minimal simple code needed to get the job done.
• By minimizing unnecessary abstractions the compiler is able to do a great job optimizing for size.
• Zig comptime allows us to easily and surgically only include the minimum necessary code given the specific EVM and hard fork configuration. Code you don't use isn't included.

How is Guillotine so safe?

Guillotine is in early alpha, but we prioritize safety through multiple build modes and extensive testing:

Build Modes

• Debug: Full debugging symbols and runtime checks
• **ReleaseFa