Skip to main content

​
Developer Documentation

Everything you need to understand and contribute to Voltaire.

​
Quick Start

# Clone and install
git clone https://github.com/evmts/voltaire
cd tevm
bun install
git submodule update --init

# Build everything
zig build

# Run all tests
zig build test && bun run test:run

# Start docs dev server
bun run docs:dev

​
Documentation Structure

Architecture

Module structure, import rules, colocated files

TypeScript Patterns

Branded types, namespace exports, dual APIs

Zig Patterns

Style guide, memory management, inline tests

Build System

zig build commands, bun scripts, outputs

Testing

Test organization, commands, TDD workflow

Adding Primitives

Step-by-step guide to add new primitive types

Adding Crypto

How to add cryptographic functions

WASM

WASM compilation, modes, and integration

Multi-Language

TypeScript, Zig, Rust, C integration

​
Key Principles

​
Every Line Correct

No stubs, no commented tests, no placeholders. Code is complete or it doesn’t exist.

​
WIP Status

Library not yet released. No breaking changes concept - refactor freely.

​
TDD Workflow

Run zig build && zig build test constantly. Know immediately when something breaks.

​
Data-First Design

Primitives are branded Uint8Arrays with namespace methods. Zero runtime overhead, full type safety.

​
Module Overview

ModulePurposeLanguages
primitives/Ethereum types (Address, Hash, Uint, RLP, ABI, Transaction)TS + Zig
crypto/Cryptography (Keccak, secp256k1, BLS12-381, BN254, KZG)TS + Zig + Rust + C
evm/precompiles/EVM precompile implementations (21 total)Zig
wasm-loader/WASM instantiation and memory managementTS
lib/C libraries (blst, c-kzg-4844, libwally-core)C

​
Import Rules

Always use module imports, never relative paths.
// ✅ Correct
const primitives = @import("primitives");
const crypto = @import("crypto");
const precompiles = @import("precompiles");

// ❌ Wrong
const address = @import("../primitives/address.zig");

​
File Colocation

Each primitive lives in a single folder with paired implementations: 
src/primitives/Address/
├── AddressType.ts     # Type definition
├── Address.js         # Implementation (.js, not .ts!)
├── Address.test.ts    # Tests (separate file)
├── index.ts           # Dual exports
├── address.zig        # Zig implementation
├── address.bench.zig  # Benchmarks
└── address.mdx        # Documentation

​
Essential Commands

# Core workflow
zig build                    # Full build
zig build test               # All Zig tests
bun run test:run             # All TS tests
zig build check              # Quick validation

# Development
zig build -Dtest-filter=addr # Filter tests
bun run test -- address      # Filter TS tests
bun run docs:dev             # Docs at localhost:3000

​
Getting Help