> ## 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.

# AddressType

> Tree-shakeable functional API for Address operations

<Card title="Try it Live" icon="play" href="https://playground.tevm.sh?example=primitives/address.ts">
  Run Address examples in the interactive playground
</Card>

# 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](/getting-started/branded-types) 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`:

```typescript theme={null}
import type { brand } from 'tevm/brand';

export type AddressType = Uint8Array & {
  readonly [brand]: "Address";
};
```

**Properties:**

* **Size:** Always 20 bytes (160 bits)
* **Branding:** Uses [Symbol branding](/getting-started/branded-types) 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](https://github.com/evmts/voltaire/blob/main/src/primitives/Address/AddressType/AddressType.ts)

Related: [Bytes32](/primitives/bytes/bytes32) - Similar pattern for 32-byte fixed values

### HexAddress Variants

Address also provides hex string variants that extend `Hex.Sized<20>`:

```typescript theme={null}
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](/primitives/hex) for details on sized hex strings.

## Available Functions

All Address functionality available as tree-shakeable functions:

### Constructors

```typescript theme={null}
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](/primitives/address/constructors) for details.

### Conversions

```typescript theme={null}
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](/primitives/address/conversions) for details.

**Tree-shaking note:** `toChecksummed` includes keccak256.

### Comparisons

```typescript theme={null}
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](/primitives/address/comparisons) for details.

### Validation

```typescript theme={null}
import {
  isValid,
  isValidChecksum,
  is
} from 'tevm/Address'

isValid("0x742d35Cc...")     // boolean
isValidChecksum("0x742d35Cc...") // boolean (uses keccak256)
is(value)                    // type guard
```

See [Validation](/primitives/address/validation) for details.

**Tree-shaking note:** `isValidChecksum` includes keccak256.

### Contract Addresses

```typescript theme={null}
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](/primitives/address/contract-addresses) for details.

**Tree-shaking note:** Both include keccak256. `calculateCreateAddress` also includes RLP.

### Variants

```typescript theme={null}
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](/primitives/address/variants) for details.

## Data-First Pattern

All AddressType functions follow data-first pattern:

```typescript theme={null}
// 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:

```typescript theme={null}
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)

```typescript theme={null}
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)

```typescript theme={null}
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)

```typescript theme={null}
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)

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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

```typescript theme={null}
import { SIZE, HEX_SIZE } from 'tevm/Address'

SIZE      // 20 (bytes)
HEX_SIZE  // 42 (characters, including "0x")
```

## Related

**Address Documentation:**

* [Address](/primitives/address) - Main Address class documentation
* [Constructors](/primitives/address/constructors) - Creating addresses
* [Conversions](/primitives/address/conversions) - Format conversions
* [Comparisons](/primitives/address/comparisons) - Equality and ordering
* [Validation](/primitives/address/validation) - Input validation
* [Contract Addresses](/primitives/address/contract-addresses) - CREATE/CREATE2
* [Variants](/primitives/address/variants) - Checksummed/Lowercase/Uppercase

**Related Primitives:**

* [Hex](/primitives/hex) - Hex string types (Hex.Sized\<20> used by hex variants)
* [Bytes32](/primitives/bytes/bytes32) - Similar pattern for 32-byte fixed values
* [Bytes16](/primitives/bytes/bytes16) - Similar pattern for 16-byte fixed values