Try it Live

Run Address examples in the interactive playground

Checksummed

EIP-55 checksummed address type providing mixed-case format for display and integrity verification.

Overview

Checksummed is a branded hex string type representing an Ethereum address with EIP-55 checksum encoding. Unlike AddressType (a Uint8Array), Checksummed is a string with mixed casing that encodes integrity verification in the character case. Key characteristics:

Type: Branded string (not Uint8Array)
Format: Mixed-case hex (e.g., 0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e)
Use cases: UI display, user input validation, QR codes, wallet integrations
Validation: Checksum encodes keccak256 hash for detecting typos

Type Definition

import type { Hex } from 'tevm'

type Checksummed = Hex.Sized<20> & {
  readonly __variant: 'Address'
  readonly __checksummed: true
}

Branded string with EIP-55 mixed-case checksum extending Hex.Sized<20>. Defined in: primitives/Address/AddressType/ChecksumAddress.js:8

ChecksumAddress API

Standard API
Tree-Shakeable Factory

`ChecksumAddress.from(value)`

Create checksummed address from any input format.Parameters:

value: number | bigint | string | Uint8Array - Input to convert

Returns: Checksummed - EIP-55 checksummed hex stringNote: Uses keccak256 internally. Import keccak256 hash function to use this API.Defined in: primitives/Address/AddressType/ChecksumAddress.js:23Example:

import * as ChecksumAddress from 'tevm/Address/ChecksumAddress'
import { hash as keccak256 } from 'tevm/crypto/Keccak256'

// Create factory function with crypto dependency
const from = ChecksumAddress.From({ keccak256 })

// Various input formats
from("0x742d35cc6634c0532925a3b844bc9e7595f51e3e")
// "0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e"

from(69n)
// "0x0000000000000000000000000000000000000045"

from(addr)  // AddressType
// "0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e"

`ChecksumAddress.From({ keccak256 })`

Factory function that creates a checksummed address converter with explicit crypto dependency.Parameters:

deps: { keccak256: (data: Uint8Array) => Uint8Array } - Crypto dependencies

Returns: (value: number | bigint | string | Uint8Array) => ChecksummedBundle size benefit: Crypto dependencies explicit - only bundled if you import them.Example:

import { From } from 'tevm/Address/ChecksumAddress'
import { hash as keccak256 } from 'tevm/crypto/Keccak256'

// Create factory with explicit crypto dependency
const from = From({ keccak256 })

// Use the created function
const checksummed = from("0x742d35cc6634c0532925a3b844bc9e7595f51e3e")
// "0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e"

Standard API
Tree-Shakeable Factory

`ChecksumAddress.isValid(str)`

Validate EIP-55 checksum of address string.Parameters:

str: string - Address string to validate

Returns: boolean - true if checksum is validNote: Uses keccak256 internally. Import keccak256 hash function to use this API.Defined in: primitives/Address/AddressType/ChecksumAddress.js:63EIP-55 Logic:

If all letters same case (all lower OR all upper), valid
If mixed case, each letter’s case must match keccak256-based checksum
Zero address with all same case always valid

Example:

import * as ChecksumAddress from 'tevm/Address/ChecksumAddress'
import { hash as keccak256 } from 'tevm/crypto/Keccak256'

// Create factory function with crypto dependency
const isValid = ChecksumAddress.IsValid({ keccak256 })

// Correct checksum
isValid("0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed")
// true

// Wrong case on one character
isValid("0x5aaeb6053F3E94C9b9A09f33669435E7Ef1BeAed")
// false (first 'A' should be uppercase)

// All lowercase (no mixed case = no checksum requirement)
isValid("0x5aaeb6053f3e94c9b9a09f33669435e7ef1beaed")
// true

// All uppercase (no mixed case = no checksum requirement)
isValid("0x5AAEB6053F3E94C9B9A09F33669435E7EF1BEAED")
// true

`ChecksumAddress.IsValid({ keccak256 })`

Factory function that creates a checksum validator with explicit crypto dependency.Parameters:

deps: { keccak256: (data: Uint8Array) => Uint8Array } - Crypto dependencies

Returns: (str: string) => booleanBundle size benefit: Crypto dependencies explicit - only bundled if you import them.Example:

import { IsValid } from 'tevm/Address/ChecksumAddress'
import { hash as keccak256 } from 'tevm/crypto/Keccak256'

// Create factory with explicit crypto dependency
const isValid = IsValid({ keccak256 })

// Validate checksummed addresses
isValid("0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed") // true
isValid("0x5aaeb6053F3E94C9b9A09f33669435E7Ef1BeAed") // false

EIP-55 Checksum Algorithm

The checksum encodes integrity verification in hexadecimal character casing:

Convert address to lowercase hex (without 0x prefix)
Compute keccak256 hash of lowercase hex string
For each hex character:
- If character is a letter (a-f):
  - If corresponding hash nibble >= 8: uppercase
  - Otherwise: lowercase
- If character is a digit (0-9): unchanged

Pseudocode:

lowercase = address.toHex().slice(2)  // Remove 0x
hash = keccak256(lowercase)
result = "0x"
for i in 0..39:
  char = lowercase[i]
  if char is letter:
    hashNibble = hash[i/2] nibble at position (i % 2)
    if hashNibble >= 8:
      result += char.toUpperCase()
    else:
      result += char.toLowerCase()
  else:
    result += char

Use Cases

UI Display

Display addresses with integrity verification:

import { Address } from 'tevm'

function AddressDisplay({ address }: { address: Address }) {
  const checksummed = address.toChecksummed()

  return (
    <div>
      <span className="font-mono">{checksummed}</span>
      <button onClick={() => navigator.clipboard.writeText(checksummed)}>
        Copy
      </button>
    </div>
  )
}

User Input Validation

Validate user-provided addresses and detect typos:

import { Address } from 'tevm'
import * as ChecksumAddress from 'tevm/Address/ChecksumAddress'

function validateUserInput(input: string): { valid: boolean; error?: string; address?: Address } {
  const trimmed = input.trim()

  // Check basic format
  if (!Address.isValid(trimmed)) {
    return { valid: false, error: "Invalid address format" }
  }

  // Check checksum if mixed case
  const hasMixedCase = trimmed !== trimmed.toLowerCase() && trimmed !== trimmed.toUpperCase()
  if (hasMixedCase && !ChecksumAddress.isValid(trimmed)) {
    // Provide correct checksummed version
    const addr = Address(trimmed)
    const correct = addr.toChecksummed()
    return {
      valid: false,
      error: `Invalid checksum. Did you mean: ${correct}?`
    }
  }

  const address = Address(trimmed)
  return { valid: true, address }
}

// Usage
const result = validateUserInput("0x742d35cc6634C0532925a3b844Bc9e7595f51e3e")
if (!result.valid) {
  console.error(result.error)
  // "Invalid checksum. Did you mean: 0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e?"
}

QR Codes

Use checksummed addresses in QR codes for error detection:

import { Address } from 'tevm'
import QRCode from 'qrcode'

async function generateAddressQR(address: Address): Promise<string> {
  const checksummed = address.toChecksummed()
  const qr = await QRCode.toDataURL(checksummed)
  return qr
}

// Usage
const addr = Address("0x742d35cc6634c0532925a3b844bc9e7595f51e3e")
const qrDataUrl = await generateAddressQR(addr)

Wallet Integrations

Wallets expect checksummed addresses:

import { Address } from 'tevm'

async function requestPayment(recipient: Address, amount: bigint) {
  const checksummed = recipient.toChecksummed()

  await ethereum.request({
    method: 'eth_sendTransaction',
    params: [{
      to: checksummed,
      value: `0x${amount.toString(16)}`
    }]
  })
}

Storage

Store addresses with checksums for verification on retrieval:

import { Address } from 'tevm'
import * as ChecksumAddress from 'tevm/Address/ChecksumAddress'

// Store
function saveAddress(key: string, address: Address) {
  const checksummed = address.toChecksummed()
  localStorage.setItem(key, checksummed)
}

// Retrieve with validation
function loadAddress(key: string): Address | null {
  const stored = localStorage.getItem(key)
  if (!stored) return null

  // Validate checksum to detect corruption
  if (!ChecksumAddress.isValid(stored)) {
    console.error("Stored address checksum invalid - possible corruption")
    return null
  }

  return Address(stored)
}

Comparison with Other Formats

import { Address } from 'tevm'

const addr = Address("0x742d35cc6634c0532925a3b844bc9e7595f51e3e")

// Lowercase (toHex)
addr.toHex()
// "0x742d35cc6634c0532925a3b844bc9e7595f51e3e"

// Checksummed (toChecksummed)
addr.toChecksummed()
// "0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e"

// Uppercase (toUppercase)
addr.toUppercase()
// "0x742D35CC6634C0532925A3B844BC9E7595F51E3E"

// All represent the same address
Address(addr.toHex()).equals(Address(addr.toChecksummed()))
// true

Example Walkthrough

import { Address } from 'tevm'

// Input address (lowercase)
const addr = Address("0x5aaeb6053f3e94c9b9a09f33669435e7ef1beaed")

// Generate checksummed output
console.log(addr.toChecksummed())
// "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed"
//     ^  ^     ^  ^ ^^     ^  ^             ^
//     Letters capitalized based on keccak256 hash

Breakdown:

Lowercase hex: 5aaeb6053f3e94c9b9a09f33669435e7ef1beaed
Keccak256 hash of lowercase: ce1b9e8e5e10a90a16c6c3ae3f56c5cf99d82e39c703c1a2adcdf2bd7ad9d685
For each letter character:
- a at position 1: hash nibble = c (12) >= 8 → A
- a at position 2: hash nibble = e (14) >= 8 → A
- e at position 3: hash nibble = 1 (1) < 8 → e
- And so on…

Performance

Time complexity: O(n) where n = 20 bytes (constant time) Overhead: One keccak256 hash computation For repeated conversions, consider caching:

import { Address } from 'tevm'
import type { Checksummed } from 'tevm/Address/ChecksumAddress'

class CachedAddress {
  private _checksumCache?: Checksummed

  constructor(private address: Address) {}

  toChecksummed(): Checksummed {
    if (!this._checksumCache) {
      this._checksumCache = this.address.toChecksummed()
    }
    return this._checksumCache
  }
}

Bundle Size Considerations

With the factory pattern, keccak256 is only bundled if you explicitly import it. Crypto dependencies are now explicit and tree-shakeable.

Tree-shaking:

ChecksumAddress.From({ keccak256 }) → Crypto dependencies explicit - only bundled if imported
ChecksumAddress.IsValid({ keccak256 }) → Crypto dependencies explicit - only bundled if imported
Address.toLowercase() → No crypto dependencies
Address.toUppercase() → No crypto dependencies

Selective imports for optimal bundle size:

// Minimal bundle (no crypto)
import { from, toHex } from 'tevm/Address'

// With checksumming - explicit crypto import
import { From } from 'tevm/Address/ChecksumAddress'
import { hash as keccak256 } from 'tevm/crypto/Keccak256'

const from = From({ keccak256 })

Address - Main Address class documentation
toChecksummed - Convert address to checksummed format
isValidChecksum - Validate EIP-55 checksum
Variants - Overview of all address variants
AddressType - Functional API and tree-shaking
EIP-55: Mixed-case checksum - Specification
Keccak256 - Keccak256 hash function

Try it Live

​Checksummed

​Overview

​Type Definition

​ChecksumAddress API

​ChecksumAddress.from(value)

​ChecksumAddress.From({ keccak256 })

​ChecksumAddress.isValid(str)

​ChecksumAddress.IsValid({ keccak256 })

​EIP-55 Checksum Algorithm

​Use Cases

​UI Display

​User Input Validation

​QR Codes

​Wallet Integrations

​Storage

​Comparison with Other Formats

​Example Walkthrough

​Performance

​Bundle Size Considerations

​Related

Checksummed

Overview

Type Definition

ChecksumAddress API

`ChecksumAddress.from(value)`

`ChecksumAddress.From({ keccak256 })`

`ChecksumAddress.isValid(str)`

`ChecksumAddress.IsValid({ keccak256 })`

EIP-55 Checksum Algorithm

Use Cases

UI Display

User Input Validation

QR Codes

Wallet Integrations

Storage

Comparison with Other Formats

Example Walkthrough

Performance

Bundle Size Considerations

Related