AddressType

Tree-shakeable functional API for Address operations

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/Function	Keccak256	Secp256k1	RLP	Notes
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")

Related

Address Documentation:

• Address - Main Address class documentation
• Constructors - Creating addresses
• Conversions - Format conversions
• Comparisons - Equality and ordering
• Validation - Input validation
• Contract Addresses - CREATE/CREATE2
• Variants - Checksummed/Lowercase/Uppercase

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