Address - Voltaire

Ethereum addresses are 20-byte identifiers for accounts and contracts. The Address primitive provides type-safe construction, validation, EIP-55 checksumming, and contract address derivation.

Overview

Address is a branded Uint8Array type representing Ethereum addresses. It provides compile-time type safety while maintaining zero runtime overhead.

Type Definition
Constants

type AddressType = Uint8Array & {
  readonly __tag: "Address";
};

SIZE = 20;                    // Address size in bytes
HEX_SIZE = 42;                // Hex string size (including 0x)

// ERC-7528 Native Asset Address
NATIVE_ASSET_ADDRESS = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";

Quick Start

Create Address
Convert & Format
Checksum (EIP-55)

import * as Address from '@tevm/voltaire/Address';

// From hex string
const addr = Address("0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e");

// From bytes
const fromBytes = Address.fromBytes(new Uint8Array(20));

// From number/bigint
const fromNumber = Address.fromNumber(0x123n);

// Zero address
const zero = Address.zero();

import * as Address from '@tevm/voltaire/Address';

const addr = Address("0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e");

// Hex representations
addr.toHex();           // "0x742d35cc6634c0532925a3b844bc9e7595f51e3e"
addr.toLowercase();     // "0x742d35cc6634c0532925a3b844bc9e7595f51e3e"
addr.toUppercase();     // "0x742D35CC6634C0532925A3B844BC9E7595F51E3E"
addr.toShortHex();      // "0x742d...1e3e"

// Numeric representation
addr.toU256();          // bigint (left-padded to 256 bits)

// ABI encoding
addr.toAbiEncoded();    // 32-byte Uint8Array (left-padded)

import * as Address from '@tevm/voltaire/Address';
import { keccak256 } from '@tevm/voltaire/Keccak256';

// Create with crypto dependency for checksum methods
const addr = Address(
  "0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e",
  { keccak256 }
);

// Get checksummed representation
addr.toChecksummed();  // "0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e"

// Validate checksum
Address.isValidChecksum("0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e"); // true
Address.isValidChecksum("0x742d35cc6634c0532925a3b844bc9e7595f51e3e"); // false

Why keccak256 Must Be Passed Explicitly

Voltaire requires you to pass keccak256 explicitly for checksumming and contract address derivation. This is intentional: Tree-shaking: Keccak256 adds ~5-10 KB to your bundle. By requiring explicit injection, bundlers can eliminate this code entirely if you never use checksum methods. Libraries that hardcode crypto dependencies force you to ship code you may never use. No global crypto dependencies: Voltaire avoids global singletons and hidden imports. Every dependency is explicit in your code, making the dependency graph predictable and auditable. Flexibility: You can inject any keccak256 implementation - the native Zig/WASM version, a pure JS fallback, or a Web Crypto wrapper. Your choice.

import * as Address from '@tevm/voltaire/Address';
import { keccak256 } from '@tevm/voltaire/Keccak256';

// Methods that DON'T need keccak256 - no injection required
const addr = Address("0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e");
addr.toHex();        // works
addr.toLowercase();  // works
addr.equals(other);  // works

// Methods that DO need keccak256 - inject via options
const addrWithCrypto = Address(
  "0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e",
  { keccak256 }
);
addrWithCrypto.toChecksummed();           // works
addrWithCrypto.calculateCreate2Address(); // works

API Reference

Constructors

Method	Description
`Address(value)`	Primary constructor - create from hex string, bytes, or number
`Address.fromHex(hex)`	Create from hex string
`Address.fromBytes(bytes)`	Create from Uint8Array
`Address.fromNumber(n)`	Create from number or bigint
`Address.fromBase64(b64)`	Create from Base64 string
`Address.fromAbiEncoded(data)`	Create from 32-byte ABI-encoded data
`Address.fromPublicKey(pubKey)`	Derive from secp256k1 public key
`Address.fromPrivateKey(privKey)`	Derive from secp256k1 private key
`Address.zero()`	Create zero address (0x000…000)
`Address.of(...bytes)`	Create from individual byte values

Conversion Methods

Method	Description
`toHex()`	Convert to lowercase hex string
`toLowercase()`	Convert to lowercase hex string
`toUppercase()`	Convert to uppercase hex string
`toChecksummed()`	Convert to EIP-55 checksummed hex (requires keccak256)
`toShortHex(start?, end?)`	Abbreviated hex (e.g., “0x742d…1e3e”)
`toU256()`	Convert to bigint (left-padded to 256 bits)
`toAbiEncoded()`	Convert to 32-byte ABI encoding
`toBytes()`	Get underlying Uint8Array
`clone()`	Create a copy

Comparison Methods

Method	Description
`equals(other)`	Check equality
`compare(other)`	Compare (-1, 0, 1) for sorting
`lessThan(other)`	Check if less than other
`greaterThan(other)`	Check if greater than other
`isZero()`	Check if zero address

Validation Methods

Method	Description
`Address.is(value)`	Type guard for AddressType
`Address.isValid(value)`	Check if value is valid address format
`Address.isValidChecksum(hex)`	Validate EIP-55 checksum
`Address.assert(value)`	Throw if invalid

Contract Address Derivation

Method	Description
`calculateCreateAddress(nonce)`	Derive CREATE address (requires keccak256 + rlpEncode)
`calculateCreate2Address(salt, initCode)`	Derive CREATE2 address (requires keccak256)

Batch Operations

Method	Description
`Address.sortAddresses(addresses)`	Sort array of addresses
`Address.deduplicateAddresses(addresses)`	Remove duplicates

Constants

Constant	Value	Description
`SIZE`	`20`	Address size in bytes
`HEX_SIZE`	`42`	Hex string length (with 0x)
`NATIVE_ASSET_ADDRESS`	`0xEeee...EEeE`	ERC-7528 native ETH address

Practical Examples

Deriving Contract Addresses

import * as Address from '@tevm/voltaire/Address';
import { keccak256 } from '@tevm/voltaire/Keccak256';
import { rlpEncode } from '@tevm/voltaire/Rlp';

// Create address with full crypto support
const deployer = Address(
  "0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e",
  { keccak256, rlpEncode }
);

// CREATE address (deployed via regular transaction)
const contractAddr = deployer.calculateCreateAddress(0n);
const secondContract = deployer.calculateCreateAddress(1n);

// CREATE2 address (deterministic deployment)
import * as Hash from '@tevm/voltaire/Hash';
import * as Bytecode from '@tevm/voltaire/Bytecode';

const salt = Hash("0x" + "00".repeat(32));
const initCode = Bytecode("0x6080604052...");
const create2Addr = deployer.calculateCreate2Address(salt, initCode);

Comparing and Sorting Addresses

import * as Address from '@tevm/voltaire/Address';

const addr1 = Address("0x1111111111111111111111111111111111111111");
const addr2 = Address("0x2222222222222222222222222222222222222222");

// Direct comparison
addr1.equals(addr2);      // false
addr1.lessThan(addr2);    // true
addr1.greaterThan(addr2); // false
addr1.compare(addr2);     // -1

// Sort array of addresses
const addresses = [addr2, addr1];
const sorted = Address.sortAddresses(addresses);
// [addr1, addr2]

// Remove duplicates
const unique = Address.deduplicateAddresses([addr1, addr1, addr2]);
// [addr1, addr2]

ABI Encoding for Contract Calls

import * as Address from '@tevm/voltaire/Address';

const recipient = Address("0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e");

// Left-padded to 32 bytes for ABI encoding
const encoded = recipient.toAbiEncoded();
// Uint8Array(32) [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0x74, 0x2d, ...]

// Decode ABI-encoded address
const decoded = Address.fromAbiEncoded(encoded);

Deriving from Keys

import * as Address from '@tevm/voltaire/Address';

// From 65-byte uncompressed public key (0x04 prefix + 64 bytes)
const pubKey = new Uint8Array(65);
pubKey[0] = 0x04;
// ... set x and y coordinates
const fromPubKey = Address.fromPublicKey(pubKey);

// From 32-byte private key
const privateKey = new Uint8Array(32);
// ... fill with private key bytes
const fromPrivKey = Address.fromPrivateKey(privateKey);

// From x,y coordinates as bigints
const x = 0x1234...n;
const y = 0x5678...n;
const fromCoords = Address.fromPublicKey(x, y);

Error Handling

import * as Address from '@tevm/voltaire/Address';
import {
  InvalidHexFormatError,
  InvalidAddressLengthError,
  InvalidChecksumError
} from '@tevm/voltaire/Address';

try {
  // Invalid hex format
  Address("not-an-address");
} catch (e) {
  if (e instanceof InvalidHexFormatError) {
    console.log(e.code);     // "INVALID_HEX_FORMAT"
    console.log(e.expected); // "0x-prefixed hex string"
  }
}

try {
  // Wrong length
  Address("0x1234");
} catch (e) {
  if (e instanceof InvalidAddressLengthError) {
    console.log(e.expected); // "20 bytes"
  }
}

Type Safety

The branded type prevents mixing addresses with other byte arrays:

import * as Address from '@tevm/voltaire/Address';
import * as Hash from '@tevm/voltaire/Hash';

const addr: AddressType = Address("0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e");
const hash: HashType = Hash("0x" + "ab".repeat(32));

// TypeScript error: Address and Hash are incompatible
// even though both are Uint8Array at runtime
function processAddress(a: AddressType) { ... }
processAddress(hash); // Error!

Keccak256

Required for checksumming and contract address derivation

RLP

Required for CREATE address derivation

Signature

Recover addresses from signatures

Branded Types

Type-safe primitives with zero overhead

Documentation Index

​Overview

​Quick Start

​Why keccak256 Must Be Passed Explicitly

​API Reference

​Constructors

​Conversion Methods

​Comparison Methods

​Validation Methods

​Contract Address Derivation

​Batch Operations

​Constants

​Practical Examples

​Deriving Contract Addresses

​Comparing and Sorting Addresses

​ABI Encoding for Contract Calls

​Deriving from Keys

​Error Handling

​Type Safety

​Related