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")

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

Overview

Getting Started

Core Concepts

Skills

JSONRPCProvider

Contract

Primitives

Cryptography

EVM

Utils

Guides

Examples

Swift

Zig

Developer Documentation

Generated API (TypeDoc)

Try it Live

​AddressType

​Overview

​Type Definition

​AddressType (Uint8Array)

​HexAddress Variants

​Available Functions

​Constructors

​Conversions

​Comparisons

​Validation

​Contract Addresses

​Variants

​Data-First Pattern

​Tree-Shaking Benefits

​Example 1: Minimal Bundle (No Crypto)

​Example 2: With Checksum (Keccak256 Only)

​Example 3: With CREATE (Keccak256 + RLP)

​Example 4: Address Class (Everything)

​Dependency Table

​When to Use AddressType vs Address

​Use AddressType When:

​Use Address Class When:

​Interoperability

​AddressType and Address Class

​AddressType and Hex Variants

​Constants

​Related

AddressType

Overview

Type Definition

AddressType (Uint8Array)

HexAddress Variants

Available Functions

Constructors

Conversions

Comparisons

Validation

Contract Addresses

Variants

Data-First Pattern

Tree-Shaking Benefits

Example 1: Minimal Bundle (No Crypto)

Example 2: With Checksum (Keccak256 Only)

Example 3: With CREATE (Keccak256 + RLP)

Example 4: Address Class (Everything)

Dependency Table

When to Use AddressType vs Address

Use AddressType When:

Use Address Class When:

Interoperability

AddressType and Address Class

AddressType and Hex Variants

Constants

Related