Branded Types

Zero-overhead type safety for Ethereum primitives

Voltaire uses branded types to prevent common bugs like passing a Hash where an Address is expected. The brand exists only at compile time - at runtime, it’s just a Uint8Array.

What is a Branded Type?

A branded type adds a compile-time tag to a base type:

// The brand symbol (shared across all primitives)
declare const brand: unique symbol

// AddressType is a Uint8Array with an invisible brand tag
type AddressType = Uint8Array & { readonly [brand]: 'Address' }

// HashType is also a Uint8Array, but with a different brand
type HashType = Uint8Array & { readonly [brand]: 'Hash' }

At runtime, both are plain Uint8Array. TypeScript prevents you from mixing them up:

import { Address, Hash } from '@tevm/voltaire'

function transfer(to: AddressType, txHash: HashType) { /* ... */ }

const addr = Address('0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e')
const hash = Hash('0x1234567890abcdef...')

transfer(addr, hash)  // OK
transfer(hash, addr)  // Type error: HashType is not assignable to AddressType

Zero Runtime Overhead

The brand is a phantom type - it exists only in TypeScript’s type system:

const addr = Address('0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e')

// At runtime, it's just a Uint8Array
console.log(addr instanceof Uint8Array)  // true
console.log(addr.length)                  // 20
console.log(addr[0])                      // First byte as number

// All Uint8Array methods work
addr.slice(0, 4)
addr.subarray(12, 20)
new DataView(addr.buffer)

Validation at Construction

Branded types are validated when created. If you have an AddressType, it’s valid:

// These throw on invalid input
Address('0xnot_valid')           // Error: Invalid hex
Address('0x123')                 // Error: Must be 20 bytes
Address(new Uint8Array(10))      // Error: Must be 20 bytes

// If construction succeeds, the value is valid
const addr = Address('0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e')
// addr is guaranteed to be exactly 20 bytes of valid data

Console Formatting

Branded types display nicely when logged:

const addr = Address('0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e')
console.log(addr)
// Address("0x742d35cc6634c0532925a3b844bc9e7595f51e3e")

Using Branded Types in Function Signatures

Use branded types in your function parameters:

import type { AddressType } from '@tevm/voltaire/Address'
import type { HashType } from '@tevm/voltaire/Hash'

// Type-safe function - cannot swap arguments by accident
function verifyTransaction(from: AddressType, to: AddressType, txHash: HashType) {
  // No runtime validation needed - types guarantee validity
}

API Documentation Note

All Voltaire documentation shows the recommended API using constructors like Address(), Hash(), etc. These return instances with prototype methods.

For bundle-size optimization, Voltaire also provides a tree-shakeable functional API with the same method signatures but imported as standalone functions.

All Branded Types

Type	Size	Description
AddressType	20 bytes	Ethereum address
HashType	32 bytes	Keccak256 hash
BytecodeType	Variable	EVM bytecode
BlobType	128 KB	EIP-4844 blob
HexType	Variable	Hex string (0x...)
Uint8Type	1 byte	8-bit unsigned integer
Uint16Type	2 bytes	16-bit unsigned integer
Uint32Type	4 bytes	32-bit unsigned integer
Uint64Type	8 bytes	64-bit unsigned integer
Uint128Type	16 bytes	128-bit unsigned integer
Uint256Type	32 bytes	256-bit unsigned integer
Int8Type	1 byte	8-bit signed integer
Int16Type	2 bytes	16-bit signed integer
Int32Type	4 bytes	32-bit signed integer
Int64Type	8 bytes	64-bit signed integer
Int128Type	16 bytes	128-bit signed integer
Int256Type	32 bytes	256-bit signed integer
Bytes1-32	1-32 bytes	Fixed-size byte arrays
Bytes64	64 bytes	64-byte array (signatures)
WeiType	bigint	Wei denomination
GweiType	bigint	Gwei denomination
EtherType	bigint	Ether denomination
AccessListType	Variable	EIP-2930 access list
AuthorizationType	Variable	EIP-7702 authorization
SignatureType	64-65 bytes	ECDSA/Ed25519 signature
SelectorType	4 bytes	Function selector
CallDataType	Variable	Contract call data
EventLogType	Variable	Event log entry
ReceiptType	Variable	Transaction receipt
NonceType	bigint	Account nonce
BlockNumberType	bigint	Block number
TransactionHashType	32 bytes	Transaction hash
BlockHashType	32 bytes	Block hash
GasLimitType	bigint	Gas limit
GasPriceType	bigint	Gas price
PrivateKeyType	32 bytes	Private key
PublicKeyType	64 bytes	Uncompressed public key
Base64Type	Variable	Base64 encoded string
RlpType	Variable	RLP encoded data
ChainIdType	number	Chain identifier
OpcodeType	number	EVM opcode

Schema Annotations

When using Effect Schema, annotate schemas with metadata for better error messages, JSON Schema generation, and form integration:

import * as S from "effect/Schema"

const AddressHex = S.String.pipe(
  S.pattern(/^0x[a-fA-F0-9]{40}$/),
  S.brand("Address")
).annotations({
  identifier: "Address.Hex",
  title: "Ethereum Address",
  description: "A 20-byte Ethereum address as a checksummed hex string",
  examples: [
    "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
  ],
  message: () => "Expected a valid Ethereum address (40 hex characters with 0x prefix)"
})

Benefits:

• Better errors: Custom message replaces raw parse errors
• JSON Schema: JSONSchema.make() generates OpenAPI-compatible specs
• Form labels: title and description for UI integration
• IDE support: Annotations surface in hover information

See Schema Annotations for complete documentation.

Learn More

Schema Annotations

Annotate schemas for better DX

Tree-Shakeable API

Functional API for minimal bundle size

Address Primitive

Complete Address API reference