# Zig EVM - Complete Reference for AI Systems

> High-performance, embeddable Ethereum Virtual Machine implementation in Zig

## Project Overview

Zig EVM is a complete Ethereum Virtual Machine implementation written in the Zig programming language. It executes EVM bytecode with accurate gas metering, supports parallel transaction processing, and provides native FFI bindings for embedding in Python, Rust, JavaScript, and C applications.

The project is open source under the MIT license and hosted at https://github.com/cryptuon/zig-evm

## Architecture

The EVM implementation is centered around a core EVM struct containing:
- **Stack**: A LIFO stack with 256-bit word elements and a 1024-item maximum depth
- **Memory**: A dynamic byte array for temporary storage with automatic expansion and word-aligned operations (32-byte words)
- **Storage**: A persistent key-value store implemented as a HashMap
- **Gas tracking**: Per-opcode gas consumption with limit enforcement matching Ethereum specifications
- **Opcodes**: A HashMap registry of 96+ opcode implementations

Each opcode is implemented as a separate file in the `src/opcodes/` directory, following a consistent pattern where each file exports a `getImpl()` function returning the opcode code and implementation function.

## Opcode Categories

### Stack Operations (Complete)
PUSH1 through PUSH32, DUP1 through DUP16, SWAP1 through SWAP16, POP

### Arithmetic Operations (Complete basic set)
ADD, SUB, MUL, DIV, SDIV, MOD, SMOD, ADDMOD, MULMOD, EXP, SIGNEXTEND

### Comparison and Bitwise
LT, GT, SLT, SGT, EQ, ISZERO, AND, OR, XOR, NOT, BYTE, SHL, SHR, SAR

### Memory Operations
MLOAD, MSTORE, MSTORE8, MSIZE

### Flow Control
JUMP, JUMPI, JUMPDEST, PC, STOP, RETURN, REVERT

### Environmental
ADDRESS, BALANCE, ORIGIN, CALLER, CALLVALUE, CALLDATALOAD, CALLDATASIZE, CALLDATACOPY, CODESIZE, CODECOPY, GASPRICE, RETURNDATASIZE, RETURNDATACOPY

### Block Information
BLOCKHASH, COINBASE, TIMESTAMP, NUMBER, DIFFICULTY, GASLIMIT, CHAINID

## Parallel Execution

The project implements two parallel execution systems:

### Basic Parallel (src/parallel.zig)
- O(n^2) dependency analysis
- Simple thread pool
- Basic conflict detection based on address read/write conflicts

### Optimized Parallel (src/parallel_optimized.zig)
- O(n) hash-based dependency analysis (10-100x faster for large batches)
- Work-stealing thread pool
- Speculative execution with rollback capability
- Memory pool optimization for reduced allocation overhead

Both systems analyze transaction dependencies based on address conflicts (read/write), balance modifications, and nonce conflicts. Independent transactions are grouped into waves for concurrent execution.

### Performance Results
- 5-6x throughput improvement for independent transactions
- Linear scaling up to 8 threads
- Simple transfer: ~45,000 ops/sec (22μs average)
- Token transfer: ~38,000 ops/sec (26μs average)
- Complex contract: ~12,000 ops/sec (83μs average)
- Parallel 8-thread: ~250,000 ops/sec (4μs average)

## 256-bit Integer System (BigInt)

The BigInt system in `src/bigint.zig` implements 256-bit integers using 4×64-bit words. It provides:
- Full arithmetic operations (add, subtract, multiply, divide, modulo)
- Comparison operations
- Bitwise operations (AND, OR, XOR, NOT, shifts)
- Conversion utilities for EVM compatibility

## Gas System

Gas costs match Ethereum specifications:
- Base transaction cost: 21,000 gas
- Per-opcode costs defined in `getGasCost()` function
- Memory expansion gas calculated dynamically
- Out-of-gas protection prevents execution of expensive operations without sufficient gas
- Gas tracking is performed before opcode execution

## FFI Bindings

### Python (bindings/python/)
Uses ctypes for direct C FFI integration. Supports creating EVM instances, loading bytecode, and executing transactions.

### Rust (bindings/rust/)
Rust FFI bindings with safe wrappers around the C ABI exports.

### JavaScript (bindings/js/)
Node.js N-API bindings via the `zigevm` npm package. Supports Node.js >= 14.0.0.

### C (include/zigevm.h)
Direct C header for integration. The Zig implementation exports C ABI functions via `src/ffi.zig`.

## Transaction Execution Flow

1. Transaction validation: gas limit and balance checks
2. Opcode dispatch: lookup in opcodes HashMap
3. Gas consumption: deduct gas cost before execution
4. Stack/memory manipulation: execute opcode logic
5. State updates: apply account and storage changes

## Blog Articles Available

The Zig EVM blog covers these topics in depth:
- EVM Opcodes Explained: Complete reference guide to all EVM opcodes with examples
- How the Ethereum Virtual Machine Works: Architecture deep dive
- Understanding EVM Gas: Developer's guide to gas metering and optimization
- Why Zig for Blockchain Infrastructure: Language advantages for blockchain development
- Building an EVM from Scratch: Implementation lessons and architecture decisions
- EVM Bytecode from Solidity to Opcodes: Compilation pipeline explained
- Parallel EVM Execution: Concurrent transaction processing techniques
- Benchmarking EVM Implementations: Comparison of Zig EVM, revm, and evmone

## Quick Start

```bash
git clone https://github.com/cryptuon/zig-evm.git
cd zig-evm
zig build run        # Build and run
zig build test       # Run all tests
zig build web        # Start interactive playground server
zig build parallel   # Run parallel execution demo
zig build benchmark  # Run performance benchmarks
```

## Contact and Links

- GitHub: https://github.com/cryptuon/zig-evm
- Website: https://cryptuon.github.io/zig-evm/
- Blog: https://cryptuon.github.io/zig-evm/blog/
- Playground: https://cryptuon.github.io/zig-evm/playground/
- License: MIT