Address.equals

Compare two addresses for equality

Try it Live

Run Address examples in the interactive playground

This page is a placeholder. All examples on this page are currently AI-generated and are not correct. This documentation will be completed in the future with accurate, tested examples.

View the complete executable example at playground/src/examples/primitives/address/equals.ts.

C

bool primitives_address_equals(const PrimitivesAddress *a, const PrimitivesAddress *b)

Compare two address instances for equality.

Parameters:

• a: const PrimitivesAddress * - First address
• b: const PrimitivesAddress * - Second address

Returns: bool - true if addresses are equal

Example:

#include "tevm.h"

uint8_t bytes1[20] = {0x00, 0x00, ..., 0x45};  // 0x...45 (69)
uint8_t bytes2[20] = {0x00, 0x00, ..., 0x45};  // 0x...45 (69)
uint8_t bytes3[20] = {0x00, 0x00, ..., 0x2A};  // 0x...2A (42)

PrimitivesAddress addr1, addr2, addr3;
memcpy(addr1.bytes, bytes1, 20);
memcpy(addr2.bytes, bytes2, 20);
memcpy(addr3.bytes, bytes3, 20);

bool equal1 = primitives_address_equals(&addr1, &addr2);
bool equal2 = primitives_address_equals(&addr1, &addr3);

printf("%d\n", equal1);  // 1 (true)
printf("%d\n", equal2);  // 0 (false)

Defined in: src/primitives.h

Comparison Semantics

Value equality: Compares byte contents, not object identity.

Case insensitive: Addresses created from different case formats are equal:

import { Address } from '@tevm/voltaire'

const lowercase = Address("0x742d35cc6634c0532925a3b844bc9e7595f51e3e")
const uppercase = Address("0x742D35CC6634C0532925A3B844BC9E7595F51E3E")
const checksummed = Address("0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e")

console.log(lowercase.equals(uppercase))     // true
console.log(lowercase.equals(checksummed))   // true
console.log(uppercase.equals(checksummed))   // true

Format independent: Different construction methods producing same address are equal:

import { Address } from '@tevm/voltaire'

const fromHex = Address("0x0000000000000000000000000000000000000045")
const fromNumber = Address(69n)
const fromBytes = Address(new Uint8Array([0, 0, ..., 0x45]))

console.log(fromHex.equals(fromNumber))  // true (69 = 0x45)
console.log(fromHex.equals(fromBytes))   // true

Use Cases

Validation

Check if address matches expected value:

import { Address } from '@tevm/voltaire'

const OWNER = Address("0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e")

function requireOwner(caller: Address) {
  if (!caller.equals(OWNER)) {
    throw new Error('Caller is not owner')
  }
}

Filtering

Filter transactions by address:

import { Address } from '@tevm/voltaire'

interface Transaction {
  from: Address
  to: Address
  value: bigint
}

function getTransactionsFrom(txs: Transaction[], address: Address) {
  return txs.filter(tx => tx.from.equals(address))
}

function getTransactionsTo(txs: Transaction[], address: Address) {
  return txs.filter(tx => tx.to.equals(address))
}

Deduplication

Remove duplicate addresses:

import { Address } from '@tevm/voltaire'

function deduplicateAddresses(addresses: Address[]): Address[] {
  const unique: Address[] = []

  for (const addr of addresses) {
    if (!unique.some(u => u.equals(addr))) {
      unique.push(addr)
    }
  }

  return unique
}

// More efficient with Set (requires hex conversion)
function deduplicateAddressesOptimized(addresses: Address[]): Address[] {
  const seen = new Set<string>()
  const unique: Address[] = []

  for (const addr of addresses) {
    const hex = addr.toHex()
    if (!seen.has(hex)) {
      seen.add(hex)
      unique.push(addr)
    }
  }

  return unique
}

Lookups

Check membership in address list:

import { Address } from '@tevm/voltaire'

const WHITELIST = [
  Address("0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e"),
  Address("0x1234567890123456789012345678901234567890"),
  // ...
]

function isWhitelisted(address: Address): boolean {
  return WHITELIST.some(addr => addr.equals(address))
}

Performance Considerations

Direct comparison: equals() converts to hex and uses string comparison internally.

For repeated comparisons, convert to hex once and use string comparison:

import { Address } from '@tevm/voltaire'

// Less efficient (converts to hex each time)
for (const addr of addresses) {
  if (addr.equals(target)) {
    // ...
  }
}

// More efficient (converts once)
const targetHex = target.toHex()
for (const addr of addresses) {
  if (addr.toHex() === targetHex) {
    // ...
  }
}

// Most efficient (use Map/Set)
const addressSet = new Set(addresses.map(a => a.toHex()))
if (addressSet.has(target.toHex())) {
  // ...
}

Alternative Comparisons

String comparison:

addr1.toHex() === addr2.toHex()

Bigint comparison:

addr1.toU256() === addr2.toU256()

Byte comparison:

// Manual byte-by-byte
addr1.every((byte, i) => byte === addr2[i])

Recommendation: Use equals() for clarity. It handles the comparison efficiently.

Relation to Other Comparisons

import { Address } from '@tevm/voltaire'

const addr1 = Address(10n)
const addr2 = Address(20n)
const addr3 = Address(10n)

// Equality
console.log(addr1.equals(addr2))  // false
console.log(addr1.equals(addr3))  // true

// Ordering
console.log(addr1.compare(addr2)) // -1 (less than)
console.log(addr1.compare(addr3)) // 0  (equal)

// Shorthand comparisons
console.log(addr1.lessThan(addr2))    // true
console.log(addr1.greaterThan(addr2)) // false

See Also

• compare - Ordering comparison
• isZero - Check if address is zero
• lessThan - Less than comparison
• greaterThan - Greater than comparison