Skip to main content

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

FilePurpose
build.zigZig build configuration
build.zig.zonZig dependencies
Cargo.tomlRust dependencies
Cargo.lockRust lockfile
package.jsonNode.js config
bun.lockbBun lockfile
tsconfig.jsonTypeScript config
biome.jsonFormatter/linter config
vitest.config.tsTest config
.gitmodulesGit submodules

File Naming Conventions

PatternPurposeExample
*.tsTypeScript types/wrappersAddressType.ts
*.jsJavaScript implementationAddress.js
*.zigZig implementationaddress.zig
*.test.tsTypeScript testsAddress.test.ts
*.bench.tsTypeScript benchmarksAddress.bench.ts
*.bench.zigZig benchmarksaddress.bench.zig
*.fuzz.zigFuzz testsaddress.fuzz.zig
*.wasm.tsWASM variantAddress.wasm.ts
*.wasm.test.tsWASM testsAddress.wasm.test.ts
*.mdxDocumentationaddress.mdx
index.tsModule exportsindex.ts
root.zigZig module entryroot.zig
Runtime support: The native/ bindings in the TypeScript package are supported on Bun. In Node.js, prefer the regular TypeScript API or the WASM modules.