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

# Address.equals

> Compare two addresses for equality

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

<Warning>
  **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.
</Warning>

<Tip>
  View the complete executable example at [`playground/src/examples/primitives/address/equals.ts`](https://github.com/evmts/voltaire/blob/main/playground/src/examples/primitives/address/equals.ts).
</Tip>

<Tabs>
  <Tab title="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:**

    ```c theme={null}
    #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](https://github.com/evmts/voltaire/blob/main/src/primitives.h)
  </Tab>
</Tabs>

## Comparison Semantics

**Value equality:** Compares byte contents, not object identity.

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

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

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

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

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

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

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

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

```typescript theme={null}
addr1.toHex() === addr2.toHex()
```

**Bigint comparison:**

```typescript theme={null}
addr1.toU256() === addr2.toU256()
```

**Byte comparison:**

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

```typescript theme={null}
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](/primitives/address/compare) - Ordering comparison
* [isZero](/primitives/address/comparisons#iszerо) - Check if address is zero
* [lessThan](/primitives/address/comparisons#lessthan) - Less than comparison
* [greaterThan](/primitives/address/comparisons#greaterthan) - Greater than comparison