@tevm/voltaire

v0.1.42

Published

6 days ago

Ethereum primitives and cryptography library with TypeScript implementations and native Zig bindings via Bun FFI

0High
0Medium
0Low

fucory

ethereum primitives crypto zig bun ffi abi keccak eip191

Why Voltaire?

Modern Ethereum library built for TypeScript, Zig, Swift, and AI-assisted development.

import { Address, Wei, Gwei, Ether, Rlp, Abi, Keccak256, Hex } from '@tevm/voltaire'

// Type-safe addresses - casing bugs eliminated
const addr = Address('0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e')
Address.toChecksummed(addr) // "0x742d35Cc..."

// Denomination safety - can't accidentally mix Wei and Ether
const value = Wei(1000000000000000000n)
Wei.toEther(value)  // 1n
Wei.toGwei(value)   // 1000000000n

// Keccak256 hashing
const selector = Keccak256.selector('transfer(address,uint256)')
// Uint8Array(4) [0xa9, 0x05, 0x9c, 0xbb]

// RLP encoding
const encoded = Rlp.encode([addr, Hex.fromNumber(42n)])

// ABI encoding
const calldata = Abi.Function.encodeParams(transferAbi, [recipient, amount])

Branded Types = Type Safety

TypeScript's structural typing lets you pass a Hash where an Address is expected - both are just 0x${string}. Voltaire prevents this entire class of bugs:

// Traditional libraries - compiles fine, breaks at runtime
simulateTransfer(bytecode, address); // Wrong order - TypeScript can't catch it!

// Voltaire - compile-time error
simulateTransfer(bytecode, address);
// Error: Type 'Bytecode' is not assignable to parameter of type 'Address'

Zero runtime overhead. Brands exist only in TypeScript's type checker.

LLM-Optimized

APIs mirror Ethereum specifications. LLMs can leverage training data from official docs instead of learning library-specific abstractions.

MCP Server - claude mcp add --transport http voltaire https://voltaire.tevm.sh/mcp
Smart detection - Docs return markdown for AI, HTML for humans
Eval-tested - Comprehensive test suite validates AI can 1-shot implementations

Multiplatform

Same API across TypeScript, Zig, and C-FFI. Works in Node.js, Bun, browsers, and any language with FFI support.

const Address = @import("primitives").Address;

pub fn main() !void {
    const address = try Address.fromHex("0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e");
    _ = address.toChecksummed();
}

Tree-Shakeable

Data-first design. Import only what you need:

// Import specific functions - excludes unused code from bundle
import { fromHex, toChecksummed } from '@tevm/voltaire/Address'

Get Started

npm install @tevm/voltaire

Three Entrypoints

Voltaire provides three entrypoints with identical APIs:

import { Address, Keccak256 } from '@tevm/voltaire'        // JS (default)
import { Address, Keccak256 } from '@tevm/voltaire/wasm'   // WASM
import { Address, Keccak256 } from '@tevm/voltaire/native' // Native FFI (Bun)

| Entrypoint | Use Case | |------------|----------| | @tevm/voltaire | Universal compatibility - works everywhere | | @tevm/voltaire/wasm | Browser/edge crypto performance | | @tevm/voltaire/native | Maximum performance (Bun only) |

All entrypoints implement the same VoltaireAPI interface - switch by changing the import path.

Documentation | Playground | API Reference | TypeDoc API

What's Included

Primitives

| Primitive | Description | Key Features | | --------- | ----------- | ------------ | | Address | 20-byte Ethereum address | EIP-55 checksums, CREATE/CREATE2 calculation | | Transaction | All transaction types | Legacy, EIP-1559, EIP-4844, EIP-7702 | | ABI | Contract interface encoding | Functions, events, errors, constructors | | RLP | Recursive Length Prefix | Encoding/decoding for Ethereum data structures | | Hex | Hexadecimal encoding | Sized types, manipulation, conversion | | Uint | 256-bit unsigned integer | Wrapping arithmetic, bitwise operations | | Hash | 32-byte hash type | Constant-time operations | | Signature | ECDSA signatures | Secp256k1, P-256, Ed25519 | | Blob | EIP-4844 blob data | 128KB blobs for rollups | | Denomination | Ether denominations | Wei, gwei, ether conversions | | Ens | ENS name normalization | ENSIP-15 normalization | | SIWE | Sign-In with Ethereum | EIP-4361 authentication |

View all 23 primitives →

Cryptography

| Algorithm | Purpose | Key Operations | | --------- | ------- | -------------- | | Keccak256 | Primary Ethereum hash | Address derivation, selectors, topics | | Secp256k1 | ECDSA signing | Sign, verify, recover public key | | EIP-712 | Typed data signing | Domain separation, type hashing | | BN254 | zkSNARK verification | G1/G2 operations, pairing checks | | KZG | EIP-4844 blob commitments | Polynomial commitments, proofs | | BIP-39 | Mnemonic phrases | 12/24-word mnemonics, seed derivation | | HDWallet | HD wallets | BIP-32/44 key derivation |

Hash functions: SHA256, RIPEMD160, Blake2

Elliptic curves: Ed25519, X25519, P256

Encryption: AES-GCM

View all 17 crypto modules →

EVM & Precompiles

Low-level tree-shakable EVM utilities and all 19 precompiled contracts (0x01-0x13).

ecrecover (0x01) - ECDSA recovery
sha256 / ripemd160 (0x02-0x03) - Hash functions
modexp (0x05) - Modular exponentiation
BN254 (0x06-0x08) - zkSNARK verification
blake2f (0x09) - Blake2 compression
KZG (0x0A) - EIP-4844 verification
BLS12-381 (0x0B-0x13) - BLS signatures

Precompiles Guide →

Development

Install: pnpm install
Build: pnpm build (Zig + JS bundles + types)
Lint: pnpm lint:check (no warnings) and pnpm format
Test: pnpm test:run (single pass) or pnpm test:coverage
Package checks: pnpm lint:package

Documentation

Docs content lives in docs/ (Mintlify). Docs code samples are validated by tests in docs/**/*.test.ts.
API reference is generated from JSDoc/TypeScript via pnpm docs:api and written to docs/generated-api/.
TypeDoc Generated API Reference - auto-generated from source.

Security

Cryptography Implementation Status
Audited (Default): @noble/curves, @noble/hashes, arkworks, blst, c-kzg
Unaudited: Zig-native implementations available via build flags. Not recommended for production.

Language Support

| Language | Status | Installation | | -------- | ------ | ------------ | | TypeScript/JavaScript | Full support | npm install @tevm/voltaire | | Zig | Full support | Build from source | | Swift | C-FFI bindings | See swift/ directory | | Go, Python, Rust, Kotlin | Planned | Contribute → |

All languages can use Voltaire via the C-FFI interface (src/c_api.zig).

Dependencies

TypeScript: @noble/curves, @noble/hashes, @scure/bip32, @scure/bip39, abitype, ox, whatsabi

Native: blst, c-kzg-4844, arkworks