Branded Types

// 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' }

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

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)

// 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

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

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
}