Developer Documentation

Complete guide for contributing to Voltaire - architecture, patterns, testing, and APIs

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

Module	Purpose	Languages
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 management	TS
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

• Check inline comments in source files
• Read test files for usage examples
• Reference the Yellow Paper and EIPs for spec details
• Zig docs: https://ziglang.org/documentation/0.15.1/