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

# Cross-Chain: Concepts

This page explains the ideas behind the `cross-chain` package — the architecture and the design decisions that shape how cross-chain transfers work.

## Intent-based architecture

Traditional bridges require users to interact directly with bridge-specific contracts on the origin chain. Each bridge has its own interface, token support, and fee structure, forcing developers to build per-bridge integrations.

The Interop SDK takes an **intent-based** approach instead. The user declares *what* they want (e.g., "send 100 USDC from Ethereum to Arbitrum"), and the SDK handles *how* to accomplish it:

1. **Quote**: The SDK asks one or more providers for pricing and execution details
2. **Execute**: The user signs a message or sends a transaction to commit to the transfer
3. **Track**: The SDK monitors the order from initiation to completion

This separation of intent from execution means the same code works across different bridge protocols without provider-specific logic.

## The transfer flow

<Mermaid
  chart={`sequenceDiagram
  participant dev as Your App
  participant sdk as Interop SDK
  participant provider as Provider
  participant rpc as Blockchain
  participant tracker as Order Tracker

  Note over dev,tracker: 1. Quote
  dev->>+sdk: getQuotes(request)
  sdk->>+provider: getQuotes(request)
  provider-->>-sdk: ExecutableQuote[]
  sdk-->>-dev: { quotes, errors }

  Note over dev,tracker: 2. Execute
  dev->>+rpc: sendTransaction / signTypedData
  rpc-->>-dev: Transaction Hash

  Note over dev,tracker: 3. Track
  dev->>+tracker: watchOrder(txHash, chains)
  loop Until Finalized / Failed / Refunded (or SDK timeout)
      tracker->>tracker: Parse open event (origin RPC)
      tracker->>tracker: Check fill (destination RPC or provider API)
      tracker-->>dev: Status Update
  end
  tracker-->>-dev: Final Status (OrderStatus)`}
/>

## Execution modes

Quotes can contain two types of steps, depending on the provider and order type:

### Protocol mode (gasless)

The user signs an EIP-712 typed data message. A solver picks up the signed intent and executes the transfer on the user's behalf. The user pays no gas.

Use `isSignatureOnlyOrder(quote.order)` to detect this mode, and `getSignatureSteps()` to extract the signing payloads.

### User mode (user pays gas)

The user sends a transaction directly to a bridge contract on the origin chain. The user pays gas for the origin-chain transaction.

Use `getTransactionSteps()` to extract the transaction parameters.

## Providers

A provider is an adapter that translates the SDK's standardized `QuoteRequest` into a specific bridge protocol's API. Each provider handles:

* Fetching quotes from the protocol's API
* Formatting orders with the correct step types
* Configuring tracking for that protocol

### Available providers

| Provider                                           | Status | Execution Modes                         | Tracking                        |
| -------------------------------------------------- | ------ | --------------------------------------- | ------------------------------- |
| [Across](/cross-chain/across-provider)             | Active | User (transaction)                      | API (mainnet), Events (testnet) |
| [Relay](/cross-chain/relay-provider)               | Active | User (transaction)                      | API-based                       |
| [OIF](/cross-chain/oif-provider)                   | Active | Protocol + User                         | Event-based                     |
| [Bungee](/cross-chain/bungee-provider)             | Active | User (transaction) + Protocol (permit2) | API-based                       |
| [LiFi Intents](/cross-chain/lifi-intents-provider) | Active | User (transaction)                      | Custom event + API              |

### Choosing a provider

* **Relay** is a good default — active on mainnet, API-based tracking (no extra RPC URLs needed), automatic transaction notification.
* **Across** is well-established and active on both mainnet and testnet. Mainnet uses API tracking; testnet requires RPC URLs for event-based tracking.
* **OIF** offers the most flexibility — supports both gasless (protocol) and user-pays-gas execution modes. Requires access to an OIF-compliant solver endpoint.
* **Bungee** supports both gasless (permit2 signatures) and user-pays-gas (onchain transactions, default). The onchain flow works for native tokens and ERC20s. API-based tracking, no extra RPC URLs needed.
* **LiFi Intents** routes through the LI.FI intent solver marketplace. Transaction-based only (ERC-20 inputs, exact-input swaps). Requires an `orderServerUrl`. Uses custom event parsing on the origin chain plus API-based fill tracking — origin-chain RPC URL required.

## Aggregation and sorting

The `Aggregator` fetches quotes from multiple providers in parallel and returns them sorted by best output amount (highest first). Additional sorting strategies may be added in future releases.

The aggregator also collects errors from individual providers, so you can show partial results even when some providers fail.

Optionally, the aggregator can enrich sorted quotes with ERC-20 approval steps: configure an `approvalService` and every quote returned will already have any required `approve` `TransactionStep` prepended to `order.steps`. See [Automatic ERC-20 Approvals](/cross-chain/advanced-usage#automatic-erc-20-approvals).

## Order tracking

After a transaction is submitted, the SDK can monitor the order through its lifecycle:

**Pending** → **Executing** → **Settling** → **Finalized**

Or: **Failed** / **Refunded**

Tracking works through two mechanisms:

* **Event-based**: Parse an event on the origin chain to detect that the order opened. Fill detection may be on-chain or API-based depending on the provider, so an origin-chain RPC URL is always required, but a destination-chain RPC URL is only needed when the provider uses an on-chain fill watcher (e.g. Across testnet).
* **API-based**: Poll a provider's status endpoint. Simpler setup, no destination-chain RPC needed.

The tracking mechanism is determined by the provider. See [Order Tracking](/cross-chain/order-tracking) for usage details.