Codebase Map
Complete directory structure of the Voltaire repository.Root Directory
voltaire/
├── src/ # Source code
├── lib/ # Vendored C libraries
├── docs/ # Mintlify documentation
├── examples/ # Usage examples
├── scripts/ # Build and analysis scripts
├── wasm/ # WASM output and loader
├── native/ # Native FFI bindings
├── dist/ # JavaScript distribution
├── types/ # TypeScript declarations
├── zig-out/ # Zig build output
├── build.zig # Zig build configuration
├── build.zig.zon # Zig dependencies
├── Cargo.toml # Rust dependencies
├── package.json # Node.js configuration
├── tsconfig.json # TypeScript configuration
├── biome.json # Biome (formatter/linter) config
└── CLAUDE.md # AI assistant instructions
src/ - Source Code
src/primitives/
100+ Ethereum primitive types. Each in its own directory:src/primitives/
├── Address/ # 20-byte Ethereum address
│ ├── AddressType.ts # Type definition
│ ├── Address.ts # Main implementation
│ ├── Address.test.ts # Tests
│ ├── ChecksumAddress.ts # Checksummed variant
│ ├── index.ts # Exports
│ └── address.zig # Zig implementation
├── Hash/ # 32-byte hash
├── Hex/ # Hex encoding
├── Bytes32/ # Fixed 32 bytes
├── Uint256/ # 256-bit integers
│ └── (40+ utility files)
├── Rlp/ # RLP encoding
├── Abi/ # ABI encoding
│ ├── encode.ts
│ ├── decode.ts
│ ├── selector.ts
│ └── ...
├── Transaction/ # All tx types
│ ├── Transaction.ts
│ ├── Legacy.ts
│ ├── EIP1559.ts
│ ├── EIP4844.ts
│ └── ...
├── Signature/ # ECDSA signatures
├── Block/ # Block structure
├── Receipt/ # Transaction receipts
├── EventLog/ # Contract events
├── Bytecode/ # EVM bytecode
├── Opcode/ # EVM opcodes
├── Chain/ # Chain metadata
├── Hardfork/ # Hardfork enums
├── Denomination/ # Wei/Gwei/Ether
├── Siwe/ # Sign-In with Ethereum
├── Ens/ # ENS normalization
├── BloomFilter/ # Log bloom filter
├── Ssz/ # SSZ serialization
│ ├── basicTypes.ts
│ ├── container.ts
│ ├── merkle.ts
│ └── variableTypes.ts
├── UserOperation/ # ERC-4337
├── errors/ # Shared error types
├── index.ts # All exports
└── root.zig # Zig module entry
src/crypto/
Cryptographic functions:src/crypto/
├── Keccak256/ # Primary hash
│ ├── index.ts
│ ├── Keccak256.ts
│ └── Keccak256.test.ts
├── SHA256/ # SHA-256
├── Blake2/ # Blake2b
├── Ripemd160/ # RIPEMD-160
├── Secp256k1/ # ECDSA curve
│ ├── index.ts
│ ├── Secp256k1.ts
│ └── Secp256k1.test.ts
├── Ed25519/ # EdDSA
├── P256/ # NIST P-256
├── X25519/ # Key exchange
├── AesGcm/ # Encryption
├── Bip39/ # Mnemonics
├── HDWallet/ # HD derivation
├── EIP712/ # Typed data
├── KZG/ # Blob commitments
├── bn254/ # (lowercase - Zig files)
├── signers/ # Hardware wallet signers
│ ├── ledger.ts
│ └── trezor.ts
├── keccak256.zig # Zig hash impl
├── keccak256_accel.zig # Hardware accelerated
├── keccak_asm.zig # Assembly version
├── secp256k1.zig # Zig ECDSA
├── bn254.zig # Pure Zig BN254
├── bn254_arkworks.zig # Rust FFI wrapper
├── c_kzg.zig # C KZG bindings
├── lib.rs # Rust entry point
├── root.zig # Zig module entry
└── index.ts # All exports
src/evm/
EVM execution:src/evm/
├── precompiles/ # Precompile implementations
│ ├── ecrecover.zig # 0x01
│ ├── sha256.zig # 0x02
│ ├── ripemd160.zig # 0x03
│ ├── identity.zig # 0x04
│ ├── modexp.zig # 0x05
│ ├── bn254_add.zig # 0x06
│ ├── bn254_mul.zig # 0x07
│ ├── bn254_pairing.zig # 0x08
│ ├── blake2f.zig # 0x09
│ ├── point_evaluation.zig # 0x0A
│ ├── bls12_g1_add.zig # 0x0B
│ ├── bls12_g1_mul.zig # 0x0C
│ ├── bls12_g1_msm.zig # 0x0D
│ ├── bls12_g2_add.zig # 0x0E
│ ├── bls12_g2_mul.zig # 0x0F
│ ├── bls12_g2_msm.zig # 0x10
│ ├── bls12_pairing.zig # 0x11
│ ├── bls12_map_fp_to_g1.zig # 0x12
│ ├── bls12_map_fp2_to_g2.zig # 0x13
│ ├── common.zig # Shared utilities
│ ├── utils.zig # Helper functions
│ ├── root.zig # Module entry
│ ├── precompiles.ts # TypeScript wrapper
│ └── *.test.ts # Test files
├── instructions/ # EVM opcodes (WIP)
├── frame.ts # Execution frame
├── host.ts # Host interface
└── index.ts # Exports
src/wasm-loader/
WASM instantiation infrastructure:src/wasm-loader/
├── loader.ts # Main loader
├── memory.ts # Memory management
├── errors.ts # Error translation
└── index.ts # Exports
src/standards/
Token standards:src/standards/
├── erc20.ts # ERC-20
├── erc721.ts # ERC-721
├── erc1155.ts # ERC-1155
└── index.ts
src/jsonrpc/
JSON-RPC types:src/jsonrpc/
├── types.ts # Request/Response types
├── methods.ts # Method definitions
└── index.ts
lib/ - C Libraries
lib/
├── blst/ # BLS12-381 (vendored)
│ ├── src/
│ ├── bindings/
│ └── build/
├── c-kzg-4844/ # KZG commitments (vendored)
│ ├── src/
│ └── bindings/
└── libwally-core/ # Wallet utils (git submodule)
└── src/
docs/ - Documentation
docs/
├── dev/ # Developer documentation
│ ├── index.mdx
│ ├── architecture.mdx
│ ├── typescript-patterns.mdx
│ ├── zig-patterns.mdx
│ └── ...
├── primitives/ # Primitive docs
│ ├── address/
│ ├── hash/
│ └── ...
├── crypto/ # Crypto docs
│ ├── keccak256/
│ ├── secp256k1/
│ └── ...
├── evm/ # EVM docs
│ └── precompiles/
├── getting-started/ # Getting started guides
├── concepts/ # Core concepts
├── examples/ # Example docs
├── guides/ # Implementation guides
├── docs.json # Navigation config
└── index.mdx # Home page
examples/ - Usage Examples
examples/
├── getting-started/ # Basic examples
├── primitives/ # Primitive usage
│ ├── address/
│ ├── rlp/
│ └── transaction/
├── crypto/ # Crypto usage
│ ├── keccak256/
│ ├── secp256k1/
│ ├── bn254/
│ └── ...
├── precompiles/ # Precompile usage
│ ├── ecrecover/
│ ├── bn254/
│ └── ...
├── c/ # C API examples
│ └── basic_usage.c
├── hex.zig # Top-level Zig examples
├── rlp.zig
├── keccak256.zig
├── secp256k1.zig
├── transaction.zig
├── abi.zig
├── eip712.zig
├── eip4844_blob_transaction.zig
├── eip7702_authorization.zig
├── signature_recovery.zig
└── bls_operations.zig
Build Output Directories
zig-out/
Zig build artifacts:zig-out/
├── lib/ # Static libraries
│ ├── libblst.a
│ ├── libc_kzg.a
│ └── libcrypto_wrappers.a
├── native/ # Native FFI library
│ └── libprimitives_ts_native.dylib
└── wasm/ # WASM artifacts
├── primitives.wasm
└── primitives-fast.wasm
dist/
JavaScript distribution:dist/
├── index.js # ESM entry
├── index.cjs # CommonJS entry
├── primitives/ # Primitive modules
└── crypto/ # Crypto modules
types/
TypeScript declarations:types/
├── index.d.ts
├── primitives/
└── crypto/
wasm/
WASM loader and modules:wasm/
├── loader.ts
├── primitives.wasm
├── primitives-fast.wasm
└── crypto/ # Individual modules
├── keccak256.wasm
├── secp256k1.wasm
├── blake2.wasm
└── ...
native/
Platform-specific binaries:native/
├── darwin-arm64/
├── darwin-x64/
├── linux-arm64/
├── linux-x64/
└── win32-x64/
Scripts
scripts/
├── run-benchmarks.ts # Generate BENCHMARKING.md
├── measure-bundle-sizes.ts # Generate BUNDLE-SIZES.md
├── generate-comparisons.ts # Compare vs ethers/viem
├── compare-wasm-modes.ts # ReleaseSmall vs ReleaseFast
└── generate_c_header.zig # C API header generation
Configuration Files
| File | Purpose |
|---|---|
build.zig | Zig build configuration |
build.zig.zon | Zig dependencies |
Cargo.toml | Rust dependencies |
Cargo.lock | Rust lockfile |
package.json | Node.js config |
bun.lockb | Bun lockfile |
tsconfig.json | TypeScript config |
biome.json | Formatter/linter config |
vitest.config.ts | Test config |
.gitmodules | Git submodules |
File Naming Conventions
| Pattern | Purpose | Example |
|---|---|---|
*.ts | TypeScript types/wrappers | AddressType.ts |
*.js | JavaScript implementation | Address.js |
*.zig | Zig implementation | address.zig |
*.test.ts | TypeScript tests | Address.test.ts |
*.bench.ts | TypeScript benchmarks | Address.bench.ts |
*.bench.zig | Zig benchmarks | address.bench.zig |
*.fuzz.zig | Fuzz tests | address.fuzz.zig |
*.wasm.ts | WASM variant | Address.wasm.ts |
*.wasm.test.ts | WASM tests | Address.wasm.test.ts |
*.mdx | Documentation | address.mdx |
index.ts | Module exports | index.ts |
root.zig | Zig module entry | root.zig |
Runtime support: The
native/ bindings are supported on Bun. In Node.js, use the regular TypeScript API or the WASM modules.