<!--
Sitemap:
- [Interop SDK Documentation](/index): Build multichain TypeScript apps with interoperable addresses, cross-chain quotes, transfer execution, and order tracking across providers.
- [Install Interop SDK](/installation): Install @wonderland/interop-addresses and @wonderland/interop-cross-chain, then choose the package that fits your multichain app.
- [Addresses Module](/addresses/): Parse, encode, and resolve chain-aware addresses that combine an account, chain, and optional ENS name into one unambiguous identifier.
- [Addresses: Getting Started](/addresses/getting-started): Parse an interoperable address and extract its components — go from a human-readable name like vitalik.eth@eip155:1 to address and chain ID.
- [Addresses: Concepts](/addresses/concepts): How EIP-7930, ERC-7828, and CAIP-350 combine address and chain into a single, unambiguous, validated identifier for multichain apps.
- [Parsing an Interoperable Name](/addresses/example): Walkthrough for wallet developers — extract the raw address and chain ID from an interop address so legacy contracts keep working.
- [Addresses: Advanced Usage](/addresses/advanced-usage): Advanced patterns for interoperable addresses — checksums, validation, error handling, and round-trip conversions between formats.
- [Addresses: API Reference](/addresses/api): Function signatures and types for the interop-addresses package — high-level helpers, name-layer methods, and binary-layer primitives.
- [Cross-Chain Module](/cross-chain/): One open source integration for cross-chain actions — compare quotes across providers, execute orders, and track completion.
- [Cross-Chain: Getting Started](/cross-chain/getting-started): Execute a cross-chain token transfer end-to-end — create a provider, fetch a quote, send the transaction, and track the order to completion.
- [Cross-Chain: Concepts](/cross-chain/concepts): The intent-based architecture behind the cross-chain package and how the SDK unifies heterogeneous bridge providers behind a common interface.
- [Supported Providers](/cross-chain/providers): Supported cross-chain providers (Across, Relay, OIF, Bungee, LiFi Intents) and how to configure each via createCrossChainProvider.
- [Across Provider](/cross-chain/across-provider): Configure and use the Across Protocol provider for cross-chain token transfers via the Across bridge infrastructure.
- [Relay Provider](/cross-chain/relay-provider): Configure and use the Relay Protocol provider for cross-chain transfers, including opt-in gasless execution via EIP-3009 signatures.
- [OIF Provider](/cross-chain/oif-provider): Direct integration with any OIF-compliant solver — submission modes, resource locks, and configuration for Open Intents Framework backends.
- [Bungee Provider](/cross-chain/bungee-provider): Cross-chain token transfers via Bungee — onchain transactions, gasless permit2 flow, and tier-based API access for sandbox or production.
- [LiFi Intents Provider](/cross-chain/lifi-intents-provider): Cross-chain transfers through the LI.FI intent solver marketplace, where competing solvers fulfill deposits at the best available rate.
- [Cross-Chain: Full Example](/cross-chain/example): End-to-end example of executing a cross-chain transfer — setup, quote, approval handling, transaction submission, and order tracking.
- [Cross-Chain: Frontend Integration](/cross-chain/frontend-integration): Wire the cross-chain SDK into a React/Next.js app with wagmi v2 — a useCrossChainSwap hook covering quotes, approvals, and submission.
- [Order Tracking](/cross-chain/order-tracking): Track cross-chain orders from initiation to completion via OIF OrderStatus events, with both onchain and offchain observation strategies.
- [Cross-Chain: Advanced Usage](/cross-chain/advanced-usage): Aggregator patterns for cross-chain transfers — multi-provider quote fetching, sorting strategies, timeouts, and built-in order tracking.
- [Cross-Chain: API Reference](/cross-chain/api): Function signatures and types for the interop-cross-chain package — providers, aggregator, approval service, and order tracking.
-->

# Addresses: Getting Started

In this tutorial, you'll parse an interoperable address and extract its components. By the end, you'll know how to go from a human-readable name like `vitalik.eth@eip155:1` to its raw address and chain ID.

## Install the package

`viem` is a peer dependency (`^2.35.0`) — install it alongside the package:

```bash
npm install @wonderland/interop-addresses viem
# or
yarn add @wonderland/interop-addresses viem
# or
pnpm add @wonderland/interop-addresses viem
```

## Parse an interoperable name

An interoperable name encodes an address, a chain, and a checksum in a single string. Let's parse one:

```ts twoslash
import { isTextAddress, parseName } from "@wonderland/interop-addresses";

const result = await parseName("vitalik.eth@eip155:1");

if (isTextAddress(result.interoperableAddress)) {
    console.log(result.interoperableAddress.address);
    // "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

    console.log(result.interoperableAddress.chainReference);
    // "1" (Ethereum mainnet)

    console.log(result.interoperableAddress.chainType);
    // "eip155"
}

console.log(result.meta.isENS); // true — "vitalik.eth" was resolved via ENS
```

`parseName` resolves ENS names, resolves chain labels, and calculates the checksum — all in one call.

## Validate the checksum

Before using the parsed address, check that the checksum matches:

```typescript
if (result.meta.checksumMismatch) {
    console.warn("Checksum mismatch — address may have been tampered with!");
    console.warn(`Provided: ${result.meta.checksumMismatch.provided}`);
    console.warn(`Calculated: ${result.meta.checksumMismatch.calculated}`);
} else {
    console.log("Checksum valid:", result.meta.checksum); // "4CA88C9C"
}
```

## Extract individual components

If you only need the address or chain ID, use the convenience functions:

```ts twoslash
import { getAddress, getChainId } from "@wonderland/interop-addresses";

const address = await getAddress("vitalik.eth@eip155:1");
// "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

const chainId = await getChainId("vitalik.eth@eip155:1");
// "1"
```

## Work with binary addresses

If you already have a binary (serialized) address, you can decode it synchronously — no async needed:

```ts twoslash
import { decodeAddress, isTextAddress } from "@wonderland/interop-addresses";

const addr = decodeAddress("0x00010000010114d8da6bf26964af9d7eed9e03e53415d37aa96045");

if (isTextAddress(addr)) {
    console.log(addr.chainType); // "eip155"
    console.log(addr.chainReference); // "1"
    console.log(addr.address); // "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
}
```

## Convert between formats

The SDK supports three formats. Here's how they relate:

<Mermaid
  chart={`graph TD
  A[InteroperableName]
  C[InteroperableAddress]
  D[Binary Address]

  A -->|parseName async| C
  A -->|nameToBinary async| D
  C -->|encodeAddress sync| D
  C -->|formatName sync| A
  D -->|decodeAddress sync| C
  D -->|binaryToName sync| A`}
/>

```ts twoslash
import { binaryToName, nameToBinary } from "@wonderland/interop-addresses";

// Name → Binary (async, may resolve ENS)
const binary = await nameToBinary("vitalik.eth@eip155:1", { format: "hex" });

// Binary → Name (sync)
const name = binaryToName(binary);
```

## Chain resolution

The SDK resolves chain labels (like `eth` or `base`) to their CAIP-2 identifiers automatically:

```typescript
const result = await parseName("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045@eth");
// result.interoperableAddress.chainType === "eip155"
// result.interoperableAddress.chainReference === "1"
```

Resolution uses a two-tier strategy:

1. **Onchain**: Queries the `on.eth` ENS registry on mainnet
2. **Offchain fallback**: Uses chainid.network mappings

Fully-qualified identifiers (e.g., `eip155:10`) always work without any registry lookup.

## Which function should I use?

| I have...                                    | I need...                      | Use                               |
| -------------------------------------------- | ------------------------------ | --------------------------------- |
| A name like `vitalik.eth@eip155:1`           | The full parsed result         | `parseName()` (async)             |
| A name like `vitalik.eth@eip155:1`           | Just the address               | `getAddress()` (async)            |
| A name like `vitalik.eth@eip155:1`           | Just the chain ID              | `getChainId()` (async)            |
| A name like `vitalik.eth@eip155:1`           | The binary form for a contract | `nameToBinary()` (async)          |
| A binary address (`0x0001...`)               | The structured fields          | `decodeAddress()` (sync)          |
| A binary address (`0x0001...`)               | A human-readable name          | `binaryToName()` (sync)           |
| Structured fields (chainType, address, etc.) | A binary address               | `encodeAddress()` (sync)          |
| Structured fields (chainType, address, etc.) | A human-readable name          | `formatName()` (sync)             |
| Any address string                           | To check if it's valid         | `isValidInteropAddress()` (async) |

**Rule of thumb:** If your input contains ENS names or chain shortnames (like `ethereum` instead of `eip155:1`), use async functions — they resolve names over the network. If you already have structured data or raw binary, sync functions work.

## Next steps

* [Concepts](/addresses/concepts) — understand the two-layer architecture and the standards behind it
* [Advanced Usage](/addresses/advanced-usage) — validation, error handling, round-trip conversions, best practices
* [Parsing an Interoperable Name](/addresses/example) — a deeper walkthrough for wallet developers
* [API Reference](/addresses/api) — complete function signatures and types