How it works

Bytecode in. State out. In parallel.

Zig EVM is a stack machine that dispatches opcodes, charges gas and mutates state — with a parallel path that runs independent transactions concurrently for a measured 5-6x throughput gain over sequential execution. It is an embeddable execution core, not a chain. Here is the whole pipeline.

How it works

Bytecode in. State out.

Each transaction runs through opcode dispatch, gas accounting and the stack machine. Independent transactions are grouped into waves and executed in parallel.

Bytecode + calldata, gas EVM core Opcode dispatch (HashMap) Gas metering Stack 1024 × 256-bit Memory 32-byte words Storage persistent KV State updates accounts + return Parallel: wave-based dependency analysis · work-stealing pool → 5-6× throughput
See the full architecture →

The pipeline, stage by stage

01

Input

A transaction arrives as bytecode plus calldata and a gas limit. Validation checks the gas limit and account balance before anything executes.

02

Opcode dispatch

The interpreter reads one opcode at a time and looks up its implementation in a HashMap registry of 96+ opcodes. Each opcode lives in its own file exporting getImpl().

03

Gas metering

Before an opcode runs, its cost is deducted from the remaining gas. Costs match Ethereum specifications, memory-expansion gas is computed dynamically, and out-of-gas is caught up front.

04

Stack, memory & storage

Opcodes mutate the 256-bit LIFO stack (max 1024 items), a word-aligned dynamic memory array and a persistent key-value storage HashMap.

05

256-bit arithmetic

All numeric work uses the BigInt system — 256-bit integers made of 4×64-bit words — for add, sub, mul, div, mod, comparisons and bitwise operations.

06

State updates

Account changes, storage writes and return data are applied when the transaction completes, or reverted on REVERT / out-of-gas.

07

Parallel waves

Across a batch, dependency analysis (address read/write, balance and nonce conflicts) groups independent transactions into waves that run concurrently on a work-stealing thread pool with speculative execution and rollback — a measured 5-6x throughput gain over sequential execution on independent workloads. This is the parallel-EVM headroom that agent-driven, high-frequency workloads need; the speedup depends on the transaction conflict rate, so shared-state-heavy batches see less.

Run it in five steps

  1. 1

    Clone the repository

    git clone https://github.com/cryptuon/zig-evm.git and cd into the project directory.

  2. 2

    Build and run

    Run zig build run to compile the EVM and execute the sample program. You should see the EVM initialise with 96 opcodes and report gas used.

  3. 3

    Run the tests

    Run zig build test to exercise the suite covering BigInt, opcodes, arithmetic, stack, memory and parallel execution.

  4. 4

    Embed via FFI (optional)

    Use the Python, Rust, JavaScript or C bindings to create an EVM instance, load bytecode and execute transactions from your own application.

  5. 5

    Explore in the browser

    Open the playground to edit bytecode and watch disassembly, the stack and the execution trace update in real time.

Read the full docs Building an EVM from scratch →