Skip to main content

Documentation Index

Fetch the complete documentation index at: https://voltaire.tevm.sh/llms.txt

Use this file to discover all available pages before exploring further.

Try it Live

Run Address examples in the interactive playground

​
AddressType

Tree-shakeable functional API for Address operations with optimal bundle size.

​
Overview

AddressType is the functional layer underlying the Address class. It provides:
  • Zero-overhead branded type wrapping Uint8Array (20 bytes)
  • Tree-shakeable individual function exports
  • Data-first unopinionated methods taking address as first parameter
  • Bundle optimization through selective imports
Primary benefit: When using tree-shakeable imports and avoiding methods that use keccak256 or RLP, those implementations are excluded from bundle.

​
Type Definition

​
AddressType (Uint8Array)

The core Address type is a branded 20-byte Uint8Array: 
import type { brand } from 'tevm/brand';

export type AddressType = Uint8Array & {
  readonly [brand]: "Address";
};
Properties:
  • Size: Always 20 bytes (160 bits)
  • Branding: Uses Symbol branding via brand symbol
  • Conceptual relation: Represents a fixed 20-byte value (conceptually like BrandedBytes<20>)
  • Type safety: Prevents accidental mixing with other Uint8Arrays
Defined in: primitives/Address/AddressType/AddressType.ts Related: Bytes32 - Similar pattern for 32-byte fixed values

​
HexAddress Variants

Address also provides hex string variants that extend Hex.Sized<20>: 
import type { Sized } from 'tevm/primitives/Hex';
import type { brand } from 'tevm/brand';

// Base hex address (Hex.Sized<20>)
type HexAddress = Sized<20> & {
  readonly [brand]: "Hex";
  readonly size: 20;
};

// EIP-55 checksummed address
type ChecksumAddress = HexAddress & {
  readonly checksum: true;
};

// Lowercase hex address
type LowercaseAddress = HexAddress & {
  readonly lowercase: true;
};

// Uppercase hex address
type UppercaseAddress = HexAddress & {
  readonly uppercase: true;
};
Hex variants:
  • Base Hex.Sized<20>: 20-byte hex string type from Hex primitive using symbol branding
  • ChecksumAddress: EIP-55 checksummed (mixed case for integrity)
  • LowercaseAddress: All lowercase hex (e.g., "0x742d35cc...")
  • UppercaseAddress: All uppercase hex (e.g., "0x742D35CC...")
  • Symbol branding: Uses brand symbol (Symbol.for("type")) for nominal typing
See Hex for details on sized hex strings.

​
Available Functions

All Address functionality available as tree-shakeable functions:

​
Constructors

import {
  from,
  fromHex,
  fromBytes,
  fromNumber,
  fromPublicKey,
  fromPrivateKey,
  fromAbiEncoded,
  fromBase64,
  zero
} from 'tevm/Address'

const addr1 = from("0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e")
const addr2 = fromHex("0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e")
const addr3 = fromNumber(69n)
const addr4 = fromPublicKey(x, y)
const addr5 = fromPrivateKey(privateKeyBytes)
const zeroAddr = zero()
See Constructors for details.

​
Conversions

import {
  toHex,
  toChecksummed,
  toLowercase,
  toUppercase,
  toU256,
  toAbiEncoded,
  toShortHex
} from 'tevm/Address'

const hex = toHex(addr)                // "0x742d35cc..."
const checksummed = toChecksummed(addr) // "0x742d35Cc..." (uses keccak256)
const n = toU256(addr)                 // 69n
const short = toShortHex(addr)         // "0x742d35...1e3e"
See Conversions for details. Tree-shaking note: toChecksummed includes keccak256.

​
Comparisons

import {
  equals,
  compare,
  lessThan,
  greaterThan,
  isZero
} from 'tevm/Address'

equals(addr1, addr2)       // boolean
compare(addr1, addr2)      // -1 | 0 | 1
lessThan(addr1, addr2)     // boolean
greaterThan(addr1, addr2)  // boolean
isZero(addr)               // boolean
See Comparisons for details.

​
Validation

import {
  isValid,
  isValidChecksum,
  is
} from 'tevm/Address'

isValid("0x742d35Cc...")     // boolean
isValidChecksum("0x742d35Cc...") // boolean (uses keccak256)
is(value)                    // type guard
See Validation for details. Tree-shaking note: isValidChecksum includes keccak256.

​
Contract Addresses

import {
  calculateCreateAddress,
  calculateCreate2Address
} from 'tevm/Address'

const createAddr = calculateCreateAddress(deployerAddr, nonce)
// Uses keccak256 + RLP

const create2Addr = calculateCreate2Address(deployerAddr, saltBigInt, initCode)
// Uses keccak256
// Salt accepts bigint | Uint8Array
See Contract Addresses for details. Tree-shaking note: Both include keccak256. calculateCreateAddress also includes RLP.

​
Variants

import * as ChecksumAddress from 'tevm/Address/ChecksumAddress'
import * as LowercaseAddress from 'tevm/Address/LowercaseAddress'
import * as UppercaseAddress from 'tevm/Address/UppercaseAddress'

// Create hex string variants from AddressType (Uint8Array)
const checksummed = ChecksumAddress.from(addr) // uses keccak256
const lowercase = LowercaseAddress.from(addr)
const uppercase = UppercaseAddress.from(addr)

// Validate hex string checksum
ChecksumAddress.isValid("0x742d35Cc...") // uses keccak256
These functions convert from AddressType (Uint8Array) to hex string variants (ChecksumAddress, LowercaseAddress, UppercaseAddress). See Variants for details.

​
Data-First Pattern

All AddressType functions follow data-first pattern: 
// AddressType: address is first parameter
toHex(addr)
equals(addr1, addr2)
calculateCreateAddress(deployerAddr, nonce)

// vs Address class: address is implicit (this)
addr.toHex()
addr1.equals(addr2)
deployerAddr.calculateCreateAddress(nonce)
This enables functional composition and partial application: 
import { toHex, equals, isZero } from 'tevm/Address'

// Function composition
const formatAddress = (addr: AddressType) => toHex(addr).toUpperCase()

// Partial application
const isEqualToZero = (addr: AddressType) => equals(addr, zero())

// Array methods
addresses.map(toHex)
addresses.filter(addr => !isZero(addr))
addresses.some(addr => equals(addr, target))

​
Tree-Shaking Benefits

Primary benefit: Selective inclusion of crypto dependencies

​
Example 1: Minimal Bundle (No Crypto)

import { from, toHex, equals, toU256 } from 'tevm/Address'

const addr = from("0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e")
const hex = toHex(addr)
const n = toU256(addr)
const isEqual = equals(addr, otherAddr)
Bundle: No keccak256, no RLP. Only basic conversions and comparisons.

​
Example 2: With Checksum (Keccak256 Only)

import { from, toHex, toChecksummed } from 'tevm/Address'

const addr = from("0x742d35cc6634c0532925a3b844bc9e7595f51e3e")
const checksummed = toChecksummed(addr)
Bundle: Includes keccak256 for checksumming. No RLP.

​
Example 3: With CREATE (Keccak256 + RLP)

import { from, calculateCreateAddress } from 'tevm/Address'

const deployer = from("0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e")
const contractAddr = calculateCreateAddress(deployer, 0n)
Bundle: Includes both keccak256 and RLP encoder.

​
Example 4: Address Class (Everything)

import { Address } from 'tevm'

const addr = Address("0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e")
Bundle: Includes all Address methods, keccak256, and RLP (due to prototype methods).

​
Dependency Table

Method/FunctionKeccak256Secp256k1RLPNotes
from, fromHex, fromBytes, fromNumber✗✗✗Pure conversions
fromPublicKey✓✗✗Derives address from pubkey
fromPrivateKey✓✓✗Derives address from privkey
toHex, toU256, toLowercase, toUppercase✗✗✗Pure conversions
toChecksummed✓✗✗EIP-55 checksumming
isValidChecksum✓✗✗EIP-55 validation
ChecksumAddress.from, ChecksumAddress.isValid✓✗✗EIP-55 operations
equals, compare, lessThan, greaterThan✗✗✗Byte comparisons
isZero, isValid, is✗✗✗Basic validation
calculateCreateAddress✓✗✓CREATE opcode
calculateCreate2Address✓✗✗CREATE2 opcode
Address class✓✓✓All methods on prototype

​
When to Use AddressType vs Address

​
Use AddressType When:

  • Bundle size critical (mobile, embedded)
  • Avoiding crypto dependencies
  • Functional style preferred
  • Selective imports desired
  • Composing functions heavily

​
Use Address Class When:

  • OOP style preferred
  • Ergonomics over bundle size
  • Using many methods (crypto already in bundle)
  • Type safety with prototype methods
  • Traditional API expected

​
Interoperability

​
AddressType and Address Class

AddressType and Address are fully compatible: 
import { Address } from 'tevm'
import { toHex, equals } from 'tevm/Address'
import type { AddressType } from 'tevm/Address'

// Address IS a AddressType
const addr = Address(69n)
const hex = toHex(addr) // ✓ works

// AddressType works with Address static methods
const branded: AddressType = addr
const checksummed = Address.toChecksummed(branded) // ✓ works

​
AddressType and Hex Variants

AddressType (Uint8Array) and hex string variants are separate types with conversion functions: 
import type { AddressType } from 'tevm/Address'
import type { ChecksumAddress, LowercaseAddress } from 'tevm/Address'

// AddressType = Uint8Array & { [brand]: "Address" }
const addr: AddressType = Address.from("0x742d35Cc...")

// ChecksumAddress = Hex.Sized<20> & { __variant: 'Address', [Symbol.for('checksum')]: boolean }
const checksumHex: ChecksumAddress = ChecksumAddress.from(addr)

// Convert between them
const backToBytes: AddressType = Address.from(checksumHex) // hex string → Uint8Array
Type relationship:
  • AddressType: 20-byte Uint8Array (runtime data)
  • HexAddress variants: Hex.Sized (20-byte) strings (display/serialization)

​
Constants

import { SIZE, HEX_SIZE } from 'tevm/Address'

SIZE      // 20 (bytes)
HEX_SIZE  // 42 (characters, including "0x")
Address Documentation: Related Primitives:
  • Hex - Hex string types (Hex.Sized<20> used by hex variants)
  • Bytes32 - Similar pattern for 32-byte fixed values
  • Bytes16 - Similar pattern for 16-byte fixed values