Skip to main content
Voltaire provides runtime safety without third-party validation libraries. Every primitive validates at construction, giving you type-safe, runtime-verified values.

​
The Problem

​
Type Confusion

TypeScript’s structural typing means types with the same structure are interchangeable: 
type Address = `0x${string}`;
type Bytecode = `0x${string}`;

function simulateTransfer(to: Address, bytecode: Bytecode) { }

const address: Address = "0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e";
const bytecode: Bytecode = "0x60806040";

// Arguments swapped - compiles fine, breaks at runtime!
simulateTransfer(bytecode, address); // ✓ No error

​
Casing Bugs

String-based addresses have casing inconsistencies: 
const addr1 = "0x742d35cc6634c0532925a3b844bc9e7595f51e3e"; // lowercase
const addr2 = "0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e"; // checksummed
addr1 === addr2; // false - same address!

​
The Solution

Branded types add compile-time tags that prevent mixing incompatible types: 
import { Address, Bytecode } from '@tevm/voltaire'

function simulateTransfer(to: Address, bytecode: Bytecode) { }

const address = Address('0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e')
const bytecode = Bytecode('0x60806040')

simulateTransfer(bytecode, address)
// Error: Type 'Bytecode' is not assignable to type 'Address'
For casing, Voltaire uses Uint8Array internally: 
const addr1 = Address('0x742d35cc6634c0532925a3b844bc9e7595f51e3e')
const addr2 = Address('0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e')
Address.equals(addr1, addr2) // true

​
Validation at Construction

Invalid inputs throw immediately: 
Address('0xnot_valid_hex')     // Error: Invalid hex character
Address('0x123')               // Error: Invalid address length
Address(new Uint8Array(10))    // Error: Address must be exactly 20 bytes

// For checksum validation, use ChecksummedAddress
ChecksummedAddress('0x742d35cc6634c0532925a3b844bc9e7595f51e3E')
// Error: Invalid checksum
If you see a branded type, it’s validated. Any AddressType value is guaranteed valid.

​
Benefits

Type Safety

Can’t mix Address with Hash or Bytecode

Zero Runtime Cost

Brand only exists in TypeScript’s type checker

LLM-Friendly

Compile errors help AI assistants self-correct

No Zod Needed

Validation built into constructors

​
Learn More

Branded Types Reference

Complete guide to branded types

Address Primitive

Complete Address API reference