⚠️ Alpha Release - This library is under active development. APIs may change. Not recommended for production use yet.
Voltaire is a modern Ethereum library with Zig, TypeScript, and C-FFI support.
- Simple APIs - The minimal close-to-spec APIs needed for Ethereum development
- LLM-Optimized - API and documentation built and tested to perform well with LLMs
- High-performance - Opt-in WASM implementations for performance-critical operations
- Type-safe - Branded types provided for opt-in typesafety
- Multi-language - Currently supports TypeScript and Zig. Additional languages planned (see Language Support Wishlist below).
📚 Installation Guide | API Documentation
Note: Voltaire focuses on Ethereum primitives and cryptography. For additional functionality:
- JSON-RPC/Provider: evmts/chappe - Provider and JSON-RPC client library
- EVM Execution: evmts/guillotine - EVM-related functionality
- Solidity Compilation: evmts/compiler - Solidity compilation support
- Unified Library: evmts/tevm-monorepo - Complete Tevm ecosystem
| Primitive | Description | Key Features |
|---|---|---|
| ABI | Contract interface encoding | Functions, events, errors, constructors (ABI spec) |
| AccessList | EIP-2930 access list | EIP-2930 transaction access lists |
| Address | 20-byte Ethereum address | EIP-55 checksums, CREATE/CREATE2 calculation, validation |
| Authorization | EIP-7702 authorization | EIP-7702 account abstraction authorizations |
| Base64 | Base64 encoding | RFC 4648 encoding/decoding |
| BinaryTree | Binary tree structures | Merkle trees |
| Blob | EIP-4844 blob | EIP-4844 blob transactions |
| BloomFilter | Bloom filter | Log bloom filters |
| Bytecode | Contract bytecode | EVM bytecode manipulation, deployment |
| Chain | Chain configuration | Network configuration, chain parameters |
| ChainId | Network identifier | Mainnet, testnets, L2s (Optimism, Arbitrum, Base, etc.) |
| Denomination | Ether denominations | Wei, gwei, ether conversions |
| Ens | ENS name normalization | ENSIP-15 normalization, beautification, validation |
| EventLog | Transaction event log | Event parsing, filtering, decoding |
| FeeMarket | Fee market calculations | EIP-1559 base fee, priority fee |
| GasConstants | EVM gas costs | Yellow Paper gas constants |
| Hardfork | Network hardfork | Hardfork detection, feature flags |
| Hash | 32-byte hash type | Constant-time operations, random generation, formatting |
| Hex | Hexadecimal encoding | Sized types, manipulation, conversion, validation |
| Opcode | EVM opcodes | EVM.codes opcode reference |
| RLP | Recursive Length Prefix | Encoding/decoding for Ethereum data structures |
| Signature | ECDSA signatures | Secp256k1, P-256, Ed25519, canonical normalization, recovery |
| SIWE | Sign-In with Ethereum | EIP-4361 authentication |
| State | State management | Account state, storage slots |
| Transaction | All transaction types | Legacy, EIP-1559, EIP-4844, EIP-7702, serialization |
| Uint | 256-bit unsigned integer | Wrapping arithmetic, bitwise operations, comparisons |
Core Algorithms:
| Algorithm | Purpose | Key Operations |
|---|---|---|
| Keccak256 | Primary Ethereum hash function (FIPS 202) | Address derivation, function selectors, event topics |
| Secp256k1 | ECDSA transaction signing (SEC 2) | Sign, verify, recover public key, address derivation |
| EIP-712 | Typed structured data signing (EIP-712) | Domain separation, type hashing, signature verification |
| BN254 | zkSNARK verification (alt_bn128) | G1/G2 point operations, pairing checks for zero-knowledge proofs |
| KZG | EIP-4844 blob commitments (EIP-4844) | Polynomial commitments, trusted setup, proof generation/verification |
| BIP-39 | Mnemonic phrases (BIP-39) | 12/24-word mnemonics, seed derivation (PBKDF2) |
| HDWallet | Hierarchical deterministic wallets (BIP-32, BIP-44) | Key derivation, multi-account paths |
Hash Functions: SHA256 (FIPS 180-4), RIPEMD160 (RIPEMD-160), Blake2 (RFC 7693)
Elliptic Curves: Ed25519 (RFC 8032), X25519 (RFC 7748), P256 (FIPS 186-5)
Encryption: AES-GCM (NIST SP 800-38D)
Security Notice:
⚠️ Cryptography Implementation StatusVoltaire provides multiple implementation options for cryptographic operations:
- Audited (Recommended): @noble/curves, @noble/hashes, arkworks, blst, c-kzg, libwally-core - Security-audited implementations used by default
- Unaudited (Use at own risk): Zig-native implementations - Experimental, performance-optimized versions available for testing. Not recommended for production use with real funds.
The library defaults to audited implementations. Zig implementations can be enabled via build flags for development/testing purposes.
Voltaire provides low-level tree-shakable EVM utilities, types, and all 19 precompiled contracts (addresses 0x01-0x13). For complete spec-compliant EVM implementations, see evmts/guillotine and evmts/tevm-monorepo.
Precompiles:
- ecrecover (0x01) - ECDSA public key recovery
- sha256 (0x02) - SHA-256 hash function
- ripemd160 (0x03) - RIPEMD-160 hash function
- identity (0x04) - Identity function (datacopy)
- modexp (0x05) - Modular exponentiation (EIP-198)
- BN254 add (0x06), mul (0x07), pairing (0x08) - zkSNARK verification (EIP-196, EIP-197)
- blake2f (0x09) - Blake2 compression function (EIP-152)
- KZG point evaluation (0x0A) - EIP-4844 blob verification (EIP-4844)
- BLS12-381 operations (0x0B-0x13) - BLS signature verification (Prague+, EIP-2537)
📚 Precompiles Guide | EVM.codes
| Type | Size | Description | Key Methods | Subtypes |
|---|---|---|---|---|
| Address | 20 bytes | Ethereum address | from, toChecksummed, calculateCreate2Address | Checksummed, Uppercase, Lowercase |
| Hash | 32 bytes | 32-byte hash | from, toHex, equals | - |
| Hex | Variable | Hex encoding | fromBytes, toBytes, concat, slice | Sized<N>, Bytes<N> |
| Uint | 32 bytes | 256-bit unsigned int | from, plus, minus, times, dividedBy | Ether, Wei, Gwei |
| Signature | 64 bytes | ECDSA signature | from, toCompact, verify, normalize | - |
| PrivateKey | 32 bytes | Private key | from, toPublicKey, toAddress, sign | - |
| PublicKey | 64 bytes | Public key | from, fromPrivateKey, toAddress, verify | - |
| Nonce | Variable | Transaction nonce | from, toNumber, toBigInt, increment | - |
| ChainId | 4 bytes | Network identifier | from, toNumber, equals, isMainnet | - |
| RLP | Variable | RLP encoding | encode, decode | - |
| Transaction | Variable | Ethereum transactions | serialize, deserialize, hash, from | Legacy, EIP2930, EIP1559, EIP4844, EIP7702 |
| ABI | Variable | ABI encoding | Function.encode, Event.decode | Function, Event, Error, Constructor |
| Blob | 131072 bytes | EIP-4844 blob data | from, toHex, toVersionedHash | Commitment, Proof, VersionedHash |
| Bytecode | Variable | Contract bytecode | from, toHex, getDeployedBytecode | - |
| BloomFilter | 256 bytes | Log bloom filter | from, add, contains | - |
| Subtype | Description | Constructor Method |
|---|---|---|
| Checksummed | EIP-55 checksummed hex address | Address.toChecksummed() |
| Uppercase | Uppercase hex address (non-checksummed) | Address.toUppercase() |
| Lowercase | Lowercase hex address | Address.toLowercase() |
| Subtype | Size | Common Use Case |
|---|---|---|
| Hex.Bytes<4> | 4 bytes | Function selectors |
| Hex.Bytes<8> | 8 bytes | Uint64 values |
| Hex.Bytes<20> | 20 bytes | Addresses |
| Hex.Bytes<32> | 32 bytes | Hashes, Uint256 values |
| Hex.Bytes<N> | N bytes | Custom sized hex strings |
| Type | Unit | Wei Equivalent |
|---|---|---|
| Ether | ETH | 1 ether = 10^18 wei |
| Gwei | gwei | 1 gwei = 10^9 wei |
| Wei | wei | Base unit (1 wei) |
| Type | Description | Common Range |
|---|---|---|
| GasPrice | Gas price in wei per gas unit | 1-1000 gwei typical |
| GasLimit | Maximum gas allowed for transaction | 21000-30M gas |
| Nonce | Transaction sequence number | 0-2^64 |
| Type | EIP | Description |
|---|---|---|
| TransactionLegacy | - | Legacy transaction (pre-EIP-2718) |
| TransactionEIP2930 | EIP-2930 | Access list transaction |
| TransactionEIP1559 | EIP-1559 | Fee market transaction with base/priority fee |
| TransactionEIP4844 | EIP-4844 | Blob transaction (shard blob transactions) |
| TransactionEIP7702 | EIP-7702 | Set code transaction (account abstraction) |
| Type | Description | Key Methods |
|---|---|---|
| Function | Function signature and encoding | encode, decode, selector |
| Event | Event signature and log parsing | decode, getTopic |
| Error | Custom error encoding | encode, decode, selector |
| Constructor | Constructor signature and encoding | encode |
| Type | Size | Description |
|---|---|---|
| Blob | 131072 bytes | Raw blob data |
| Commitment | 48 bytes | KZG commitment to blob |
| Proof | 48 bytes | KZG proof for blob |
| VersionedHash | 32 bytes | Versioned hash of blob commitment |
| Type | Description | Key Methods |
|---|---|---|
| State | Account state with balance, nonce, code, storage | get, set, commit |
| StorageKey | Storage slot identifier (address + slot) | from, toHex |
| EventLog | Transaction event log entry | decode, matches |
| AccessList | EIP-2930 access list for state access | from, add, contains |
| Authorization | EIP-7702 code delegation authorization | from, sign, verify |
| Type | Description | Key Methods |
|---|---|---|
| Hardfork | Network upgrade identifier | from, isEnabled |
| ChainId | Network chain identifier | from, toNumber, equals |
| Opcode | EVM opcode byte | from, getName, getGasCost |
| Base64 | Base64 encoded data | encode, decode |
| BinaryTree | Binary tree structure for Merkle trees | from, getRoot, getProof |
| Type | Size | Description | Algorithm |
|---|---|---|---|
| PrivateKey | 32 bytes | Secp256k1 private key | Secp256k1 |
| PublicKey | 64 bytes | Secp256k1 public key (uncompressed) | Secp256k1 |
| Signature | 64 bytes | ECDSA signature (r, s, v) | Secp256k1 |
| ExtendedKey | Variable | BIP-32 hierarchical deterministic key | BIP-32/44 |
| Mnemonic | Variable | BIP-39 mnemonic phrase | BIP-39 |
| Seed | 64 bytes | BIP-39 seed derived from mnemonic | BIP-39 |
| P256PrivateKey | 32 bytes | NIST P-256 private key | P-256 |
| P256PublicKey | 64 bytes | NIST P-256 public key | P-256 |
| P256Signature | Variable | NIST P-256 ECDSA signature | P-256 |
| G1Point | 96 bytes | BN254/BLS12-381 G1 point | zkSNARK/BLS |
| G2Point | 192 bytes | BN254/BLS12-381 G2 point | zkSNARK/BLS |
| Function | Input | Output | Use Case |
|---|---|---|---|
| Keccak256.hash | Uint8Array | 32-byte Hash | General hashing, contract addresses |
| Secp256k1.sign | Hash, PrivateKey | Signature | Sign transactions/messages |
| Secp256k1.recover | Signature, Hash | PublicKey | Recover signer address |
| Secp256k1.generatePrivateKey | - | PrivateKey | Generate new private key |
| Ed25519.sign | Message, SecretKey | Signature | EdDSA signatures |
| Ed25519.verify | Signature, Message, PubKey | boolean | Verify EdDSA signatures |
| X25519.scalarmult | SecretKey, PublicKey | SharedSecret | ECDH key exchange |
| P256.sign | Hash, PrivateKey | Signature | NIST P-256 signatures |
| P256.verify | Signature, Hash, PubKey | boolean | Verify P-256 signatures |
| P256.ecdh | PrivateKey, PublicKey | SharedSecret | P-256 ECDH |
| EIP712.hash | Domain, Types, Message | Hash | Typed data signing |
| SHA256.hash | Uint8Array | 32-byte hash | Bitcoin compatibility |
| RIPEMD160.hash | Uint8Array | 20-byte hash | Bitcoin addresses |
| Blake2.hash | Uint8Array, size? | 1-64 byte hash | Zcash compatibility |
| BN254.add | G1Point, G1Point | G1Point | BN254 elliptic curve addition |
| BN254.mul | G1Point, scalar | G1Point | BN254 scalar multiplication |
| BN254.pairing | Point pairs | boolean | zkSNARK verification |
| KZG.blobToCommitment | Blob | Commitment | Create KZG commitment |
| KZG.computeProof | Blob, Commitment | Proof | Generate KZG proof |
| KZG.verify | Blob, Commitment, Proof | boolean | EIP-4844 blob verification |
| Bip39.generateMnemonic | strength (128-256) | Mnemonic | BIP-39 mnemonic generation |
| Bip39.mnemonicToSeed | Mnemonic, password? | Seed | Derive seed from mnemonic |
| HDWallet.fromSeed | Seed | ExtendedKey | Create master key from seed |
| HDWallet.derive | ExtendedKey, Path | ExtendedKey | BIP-32/BIP-44 key derivation |
| HDWallet.deriveEthereum | ExtendedKey, account, index | ExtendedKey | Derive Ethereum account (m/44'/60'/0'/0/n) |
| AesGcm.encrypt | Data, Key, Nonce | Ciphertext | AES-GCM authenticated encryption |
| AesGcm.decrypt | Ciphertext, Key, Nonce | Data | AES-GCM authenticated decryption |
All implementations optimized for production use:
- Native/WASM: Optional native bindings via Zig for 2-10x speedup on performance-critical operations
- Audited crypto: @noble/curves, c-kzg-4844, blst for security
- Minimal bundle: Tree-shakeable, only pay for what you use
- WASM modes: ReleaseSmall (size-optimized) and ReleaseFast (performance-optimized) builds available
- Alloy - High-performance Rust library (Zig FFI integration available)
- @noble/curves - Audited cryptographic library for pure JS implementations
Voltaire currently supports TypeScript/JavaScript and Zig. We are looking for help adding idiomatic, type-safe wrappers for additional languages:
- Go - Native Go bindings via cgo
- Python - Python bindings via ctypes/cffi
- Rust - Rust bindings via FFI
- Swift - Swift bindings for iOS/macOS development
- Kotlin - Kotlin bindings for Android/JVM development
Note: These languages can already use Voltaire today via the C-FFI interface (see src/c_api.zig and generated src/primitives.h header), but we aim to provide ergonomic, type-safe, idiomatic wrappers for each language.
Voltaire has minimal runtime dependencies:
- @scure/bip32 - BIP-32 hierarchical deterministic wallet key derivation
- @scure/bip39 - BIP-39 mnemonic phrase generation and validation
- @tevm/chains - Generated Ethereum chain configurations (mainnet, L2s, testnets)
- abitype - ABI type system utilities and type guards
- @adraffy/ens-normalize - ENSIP-15 compliant ENS name normalization and beautification
- @noble/curves - Audited elliptic curve cryptography (secp256k1, ed25519, p256)
- @noble/hashes - Audited cryptographic hash functions (keccak256, sha256, blake3, ripemd160)
- whatsabi - ABI detection and contract analysis
- ox - Ethereum utilities (used wherever appropriate to share peer dependencies with other TypeScript tools and amortize bundle size costs)
- z-ens-normalize - Zig port of ENSIP-15 ENS name normalization
- Zig std.crypto - Zig standard library cryptography (native/WASM builds only)
- c-kzg - KZG polynomial commitments for EIP-4844 blob verification
- libwally-core - Wallet utilities including BIP-32/39/44 implementations
- blst - BLS12-381 signature library for Ethereum consensus layer
- arkworks - Rust zkSNARK libraries (ark-bn254, ark-bls12-381, ark-ec, ark-ff) for BN254 operations
- keccak-asm - Assembly-optimized Keccak implementation (native builds)
- tiny-keccak - Pure Rust Keccak implementation (WASM builds)
All dependencies are actively maintained and security-audited where applicable.
MIT License - see LICENSE for details
- GitHub Repository - Source code and contributions
- GitHub Issues - Bug reports and feature requests
- NPM Package - Package registry
- Telegram - Community chat
- Twitter - Updates and announcements
- Voltaire Documentation - Complete API reference and guides
- Ethereum Developer Documentation
- EIP Repository - Ethereum Improvement Proposals
- EVM.codes - Opcode reference
- Ethereum Yellow Paper - Technical specification
- Solidity Documentation - Smart contract language
- Zig Documentation - Zig language reference