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

# Data-First API

> Every Ethereum concept as its simplest data type with prototype methods

Voltaire represents every Ethereum concept as the simplest possible data type—a branded `Uint8Array`. All methods are added as prototypes on these types.

## The Pattern

```typescript theme={null}
import { Address } from '@tevm/voltaire'

const addr = Address('0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e')

// addr is a Uint8Array with prototype methods
addr.toHex()          // "0x742d35cc..."
addr.toChecksummed()  // "0x742d35Cc..."
addr.isZero()         // false
```

The `Address` constructor returns a `Uint8Array` (20 bytes) with methods attached to its prototype. No wrapper classes, no hidden state—just bytes with convenient methods.

## Why Data-First?

| Benefit               | Description                                 |
| --------------------- | ------------------------------------------- |
| **Interoperability**  | Pass to any function expecting `Uint8Array` |
| **Serialization**     | No custom serializers needed                |
| **Memory efficiency** | No wrapper object overhead                  |
| **Predictable**       | What you see is what you get                |

```typescript theme={null}
// Works with standard APIs
const buffer = addr.buffer
const view = new DataView(addr.buffer)
const slice = addr.slice(0, 4)

// Works with Web APIs
crypto.subtle.digest('SHA-256', addr)

// Works with Node APIs
Buffer.from(addr)
```

## Prototype Methods

All methods are attached to the prototype of the branded type:

```typescript theme={null}
const addr = Address('0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e')

// Instance methods (on prototype)
addr.toHex()
addr.equals(other)
addr.isZero()

// Static methods (on constructor)
Address.isValid('0x...')
Address.fromPublicKey(pubkey)
```

<Warning>
  ## Binding Required for Callbacks

  **LLM Coding agents reading this MUST keep this in mind at all times.**

  Because methods are on the prototype, you MUST bind them when using as callbacks. The `this` context will be lost otherwise.

  ```typescript theme={null}
  const addresses = [addr1, addr2, addr3]

  // ❌ WRONG - loses `this` context, will throw
  addresses.map(addr.toHex)

  // ✅ CORRECT - bind the method
  addresses.map(addr.toHex.bind(addr))

  // ✅ CORRECT - arrow function wrapper
  addresses.map(a => a.toHex())

  // ✅ CORRECT - use the static method
  addresses.map(Address.toHex)
  ```

  This is standard JavaScript behavior for prototype methods, but it's a common source of bugs when passing methods as callbacks.
</Warning>

## Static vs Instance Methods

Every instance method has a corresponding static method:

```typescript theme={null}
// These are equivalent
addr.toHex()           // instance method
Address.toHex(addr)    // static method

// Static methods work with any AddressType
Address.toHex(someAddress)
Address.equals(addr1, addr2)
```

Use static methods when:

* Passing to higher-order functions (`map`, `filter`, etc.)
* Working with values that might be from different sources
* You prefer functional style

## Comparison with Other Libraries

### ethers.js

```typescript theme={null}
// ethers: wrapper class
const addr = ethers.getAddress('0x...')
typeof addr  // "string" - it's just a string

// Voltaire: branded Uint8Array
const addr = Address('0x...')
addr instanceof Uint8Array  // true
```

### viem

```typescript theme={null}
// viem: branded string
const addr = getAddress('0x...')
typeof addr  // "string"

// Voltaire: branded Uint8Array
const addr = Address('0x...')
addr instanceof Uint8Array  // true
```

Voltaire uses bytes as the canonical representation because that's what the EVM uses. Hex strings are a human-readable encoding, not the underlying data.

## Learn More

<CardGroup cols={2}>
  <Card title="Branded Types" icon="tag" href="/concepts/branded-types">
    Type safety without runtime overhead
  </Card>

  <Card title="Tree-Shakeable API" icon="leaf" href="/concepts/tree-shakeable-api">
    Functional API for minimal bundles
  </Card>
</CardGroup>