# Bridge Kit

<div align="center">

[![npm version](https://badge.fury.io/js/@circle-fin%2Fbridge-kit.svg)](https://badge.fury.io/js/@circle-fin%2Fbridge-kit)
[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Discord](https://img.shields.io/discord/473781666251538452?label=Discord&logo=discord)](https://discord.com/invite/buildoncircle)

**Official Circle SDK for seamless cross-chain USDC bridging**

_Bridge Kit is the recommended integration surface for USDC bridging between EVM and non-EVM chains, making bridging as simple as a single function call_

</div>

## Table of Contents

- [Bridge Kit](#bridge-kit)
  - [Table of Contents](#table-of-contents)
  - [Overview](#overview)
    - [Why Bridge Kit?](#why-bridge-kit)
  - [Architecture Flow](#architecture-flow)
  - [Installation](#installation)
    - [Adapters](#adapters)
  - [Quick Start](#quick-start)
    - [🚀 Easiest Setup: Single Adapter, Multiple Chains](#-easiest-setup-single-adapter-multiple-chains)
    - [🎯 Send to Different Address](#-send-to-different-address)
    - [🏭 Production Setup: Custom RPC Providers](#-production-setup-custom-rpc-providers)
    - [🌐 Browser/Wallet Provider Support](#-browserwallet-provider-support)
    - [🔧 Advanced Setup: Full Control](#-advanced-setup-full-control)
    - [📊 Cost Estimation](#-cost-estimation)
  - [Configuration](#configuration)
    - [Bridge Configuration Types](#bridge-configuration-types)
      - [1. **AdapterContext** - Your Transfer Endpoint](#1-adaptercontext---your-transfer-endpoint)
      - [2. **BridgeDestination** - Where Funds Go](#2-bridgedestination---where-funds-go)
      - [3. **BridgeConfig** - Transfer Settings](#3-bridgeconfig---transfer-settings)
    - [Bridge Speed Configuration](#bridge-speed-configuration)
  - [Custom Fees](#custom-fees)
    - [How Custom Fees Work](#how-custom-fees-work)
    - [1,000 USDC Transfer Example](#1000-usdc-transfer-example)
    - [Kit-Level Fee Policies](#kit-level-fee-policies)
  - [Error Handling](#error-handling)
  - [Retrying Failed Transfers](#retrying-failed-transfers)
    - [Method signature](#method-signature)
    - [Basic usage (EVM → EVM)](#basic-usage-evm--evm)
    - [When to retry vs manual intervention](#when-to-retry-vs-manual-intervention)
    - [Limitations](#limitations)
    - [Performance and best practices](#performance-and-best-practices)
    - [Troubleshooting](#troubleshooting)
  - [Forwarder Integration](#forwarder-integration)
    - [Standard Bridge with Forwarder](#standard-bridge-with-forwarder)
    - [Forwarder-Only Destination (No Destination Adapter)](#forwarder-only-destination-no-destination-adapter)
  - [API Reference](#api-reference)
    - [Core Methods](#core-methods)
    - [Bridge Parameters](#bridge-parameters)
  - [Development](#development)
    - [Building](#building)
    - [Testing](#testing)
    - [Local Development](#local-development)
  - [Community \& Support](#community--support)
  - [License](#license)

## Overview

The App Kit ecosystem is Circle’s open-source effort to streamline stablecoin development with SDKs that are easy to use correctly and hard to misuse. Kits are cross-framework (viem, ethers, @solana/web3) and integrate cleanly into any stack. They’re opinionated with sensible defaults, but offer escape hatches for full control. A pluggable architecture makes implementation flexible, and all kits are interoperable, so they can be composed to suit a wide range of use cases.

The Bridge Kit enables cross-chain stablecoin transfers via a type-safe, developer-friendly interface with robust runtime validation. The Kit can have any bridging provider plugged in, by implementing your own BridgingProvider, but comes by default with full CCTPv2 support

### Why Bridge Kit?

- **🌉 Bridge-first design**: All abstractions revolve around _source_ ↔ _destination_ chain pairs
- **⚡ Zero-config defaults**: Built-in reliable RPC endpoints - start building right away
- **🔧 Bring your own infrastructure**: Seamlessly integrate with your existing setup when needed
- **🔒 Production-ready security**: Leverages Circle's CCTPv2 with deterministic quotes and finality tracking
- **🚀 Developer experience**: Complete TypeScript support, comprehensive validation, and instant connectivity
- **🌍 Cross-chain bridging**: The Bridge Kit supports **52 chains** with **1300 total bridge routes** through Circle's CCTPv2
  - **Mainnet (26 chains)**: Arbitrum, Arc, Avalanche, Base, Codex, Cronos, Edge, Ethereum, HyperEVM, Injective, Ink, Linea, Monad, Morph, OP Mainnet, Pharos, Plasma, Plume, Polygon PoS, Sei, Solana, Sonic, Unichain, World Chain, XDC, X Layer
  - **Testnet (26 chains)**: Arc Testnet, Arbitrum Sepolia, Avalanche Fuji, Base Sepolia, Codex Testnet, Cronos Testnet, Edge Testnet, Ethereum Sepolia, HyperEVM Testnet, Injective Testnet, Ink Testnet, Linea Sepolia, Monad Testnet, Morph Testnet, OP Sepolia, Pharos Atlantic, Plasma Testnet, Plume Testnet, Polygon PoS Amoy, Sei Testnet, Solana Devnet, Sonic Testnet, Unichain Sepolia, World Chain Sepolia, XDC Apothem, X Layer Testnet
- **🎯 Flexible adapters**: Supporting EVM (Viem, Ethers) and Solana (@solana/web3)
- **⚙️ Configurable bridge speeds**: FAST/SLOW options with fee optimization
- **📡 Real-time event monitoring**: Track progress throughout the transfer lifecycle
- **🛡️ Robust error handling**: Graceful partial success recovery
- **✈️ Pre-flight validation**: Verify transfers with cost estimation before execution
- **🤖 Forwarder integration**: Circle's Orbit relayer handles attestation and mint automatically
- **📭 Forwarder-only destinations**: No destination adapter required - just provide recipient address

## Developer Documentation

- [Bridge Kit Documentation](https://developers.circle.com/bridge-kit)

## Architecture Flow

The Bridge Kit follows a three-layer architecture designed for flexibility and type safety:

```text
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Bridge Kit    │────│     Provider     │────│   Adapter       │
│  (Orchestrator) │    │   (Protocol)     │    │ (Blockchain)    │
└─────────────────┘    └──────────────────┘    └─────────────────┘
```

1. **Adapter**: Handles blockchain-specific operations (wallets, transactions, gas) and enables you to use whatever framework you're comfortable with (viem, ethers, @solana/web3, and more coming soon)
2. **Provider**: Implements bridging protocols (currently CCTPv2)
3. **BridgeKit**: Orchestrates adapters and providers with auto-routing and validation

This separation ensures that each component has a single responsibility while maintaining seamless integration across the entire cross-chain bridging lifecycle.

## Installation

```bash
npm install @circle-fin/bridge-kit
# or
yarn add @circle-fin/bridge-kit
```

### Adapters

Choose the appropriate adapter for your target chains:

```bash
# For EVM chains (Ethereum, Base, Arbitrum, etc.)
npm install @circle-fin/adapter-viem-v2 viem
# or
yarn add @circle-fin/adapter-viem-v2 viem

# For EVM chains using Ethers.js
npm install @circle-fin/adapter-ethers-v6
# or
yarn add @circle-fin/adapter-ethers-v6

# For Solana
npm install @circle-fin/adapter-solana @solana/web3.js
# or
yarn add @circle-fin/adapter-solana @solana/web3.js
```

## Quick Start

### 🚀 Easiest Setup: Single Adapter, Multiple Chains

**Best for**: Getting started quickly, simple transfers using one wallet across chains

The factory methods make it incredibly easy to get started with **built-in reliable RPC endpoints**. No need to research providers or configure endpoints - just start building! Create **one adapter** and use it across different chains!

```typescript
import { BridgeKit } from '@circle-fin/bridge-kit'
import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'

// Initialize the kit
const kit = new BridgeKit()

// Create ONE adapter that works across all chains!
const adapter = createViemAdapterFromPrivateKey({
  privateKey: process.env.PRIVATE_KEY as string,
})

const result = await kit.bridge({
  from: { adapter, chain: 'Ethereum' },
  to: { adapter, chain: 'Base' },
  amount: '10.50',
})
```

**✨ Key Feature**: All supported chains include reliable default RPC endpoints.

### 🎯 Send to Different Address

**Best for**: Sending funds to someone else's wallet, custodial services

Use `BridgeDestinationWithAddress` when the recipient is different from your adapter's address:

```typescript
// Send to a different address on the destination chain
const result = await kit.bridge({
  from: { adapter, chain: 'Ethereum' },
  to: {
    adapter,
    chain: 'Base',
    recipientAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  },
  amount: '10.50',
})

// Or use a different adapter for the destination chain
const baseAdapter = createViemAdapterFromPrivateKey({
  privateKey: process.env.PRIVATE_KEY as string,
})

const resultWithDifferentAdapter = await kit.bridge({
  from: { adapter, chain: 'Ethereum' },
  to: {
    adapter: baseAdapter,
    chain: 'Base',
    recipientAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  },
  amount: '10.50',
})
```

### 🏭 Production Setup: Custom RPC Providers

**Best for**: Production applications, better reliability, custom configuration

Bridging involves **two chains** (source and destination), and both require properly configured RPC endpoints. Use dynamic RPC mapping by chain ID to support multiple chains in a single adapter:

```typescript
import 'dotenv/config'
import { BridgeKit } from '@circle-fin/bridge-kit'
import { Ethereum, Base } from '@circle-fin/bridge-kit/chains'
import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
import { createPublicClient, http, fallback } from 'viem'

// Define RPCs mapped by chain ID
const RPC_BY_CHAIN_ID: Record<number, string[]> = {
  // The array allows providing multiple RPC URLs for fallback, e.g.,
  // `[ "https://primary-rpc-url.com/...", "https://secondary-rpc-url.com/..." ]`
  [Ethereum.chainId]: [
    `https://eth-mainnet.g.alchemy.com/v2/${process.env.ALCHEMY_KEY}`,
  ],
  [Base.chainId]: [
    `https://base-mainnet.g.alchemy.com/v2/${process.env.ALCHEMY_KEY}`,
  ],
}

const adapter = createViemAdapterFromPrivateKey({
  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
  getPublicClient: ({ chain }) => {
    const rpcUrls = RPC_BY_CHAIN_ID[chain.id]
    if (!rpcUrls) {
      throw new Error(`No RPC configured for chainId=${chain.id}`)
    }
    return createPublicClient({
      chain,
      transport: fallback(
        rpcUrls.map((url) =>
          http(url, {
            timeout: 10_000,
            retryCount: 3,
          }),
        ),
      ),
    })
  },
})

const kit = new BridgeKit()

const result = await kit.bridge({
  from: { adapter, chain: 'Ethereum' },
  to: { adapter, chain: 'Base' },
  amount: '10.50',
})
```

**Best practices:**

- **Use paid RPC providers** (Alchemy, Infura, QuickNode) for improved reliability
- **Implement `fallback()` transport** for automatic failover between endpoints
- **Configure timeout and retry options** to handle network variability

### 🌐 Browser/Wallet Provider Support

**Best for**: Browser applications, wallet integrations, user-controlled transactions

```typescript
import { BridgeKit } from '@circle-fin/bridge-kit'
import { createViemAdapterFromProvider } from '@circle-fin/adapter-viem-v2'

const kit = new BridgeKit()

// Create adapters from browser wallet providers
const adapter = await createViemAdapterFromProvider({
  provider: window.ethereum,
})

// Execute bridge operation
const result = await kit.bridge({
  from: { adapter, chain: 'Ethereum' },
  to: { adapter, chain: 'Base' },
  amount: '10.50',
})
```

### 🔧 Advanced Setup: Full Control

**Best for**: Advanced users, custom client configuration, specific RPC requirements

```typescript
import { BridgeKit } from '@circle-fin/bridge-kit'
import { Ethereum, Base } from '@circle-fin/bridge-kit/chains'
import { ViemAdapter } from '@circle-fin/adapter-viem-v2'
import { createPublicClient, createWalletClient, http } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'

const account = privateKeyToAccount(process.env.PRIVATE_KEY as string)

// Chain-specific RPC URLs mapped by chain ID
const rpcUrls: Record<number, string> = {
  [Ethereum.chainId]: 'https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY',
  [Base.chainId]: 'https://base-mainnet.g.alchemy.com/v2/YOUR_KEY',
}

// Create one multi-chain adapter with chain-specific RPC configuration
const adapter = new ViemAdapter(
  {
    getPublicClient: ({ chain }) =>
      createPublicClient({
        chain,
        transport: http(rpcUrls[chain.id]),
      }),
    getWalletClient: ({ chain }) =>
      createWalletClient({
        account,
        chain,
        transport: http(rpcUrls[chain.id]),
      }),
  },
  {
    addressContext: 'user-controlled',
    supportedChains: [Ethereum, Base], // Support multiple chains!
  },
)

const kit = new BridgeKit()
// Execute bridge operation using the same adapter for both chains
const result = await kit.bridge({
  from: { adapter, chain: 'Ethereum' },
  to: { adapter, chain: 'Base' },
  amount: '10.50',
})
```

### 📊 Cost Estimation

**Best for**: Showing users fees upfront, budget planning

```typescript
// Get cost estimate before bridging
const estimate = await kit.estimate({
  from: { adapter, chain: 'Ethereum' },
  to: { adapter, chain: 'Base' },
  amount: '10.50',
})

console.log('Estimated fees:', estimate.fees)
console.log('Estimated gas:', estimate.gasFees)
```

## Configuration

### Bridge Configuration Types

The Bridge Kit supports different configuration patterns to match your use case:

#### 1. **AdapterContext** - Your Transfer Endpoint

```typescript
// Create chain-agnostic adapter
const adapter = createViemAdapterFromPrivateKey({...})

// Always specify chain explicitly for clarity
const adapterContext = { adapter, chain: 'Ethereum' }
```

#### 2. **BridgeDestination** - Where Funds Go

```typescript
// Same as AdapterContext (adapter receives the funds)
const destination = { adapter, chain: 'Base' }

// Or with explicit recipient address
const destination = {
  adapter,
  chain: 'Base',
  recipientAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
}
```

#### 3. **BridgeConfig** - Transfer Settings

```typescript
// FAST: Optimized for speed with higher fees
// SLOW: Optimized for lower fees with longer processing time
const config = { transferSpeed: 'FAST' }
```

### Bridge Speed Configuration

```typescript
// Fast transfer (higher fees, faster completion)
const result = await kit.bridge({
  from: { adapter, chain: 'Ethereum' },
  to: { adapter, chain: 'Base' },
  amount: '100.0',
  config: { transferSpeed: 'FAST' },
})

// Slow transfer (lower fees, slower completion)
const result = await kit.bridge({
  from: { adapter, chain: 'Ethereum' },
  to: { adapter, chain: 'Base' },
  amount: '100.0',
  config: { transferSpeed: 'SLOW' },
})
```

## Custom Fees

Bridge Kit allows you to charge custom developer fees on cross-chain USDC transfers. Understanding how these fees interact with wallet debits and CCTPv2 protocol fees is crucial for correct implementation.

### How Custom Fees Work

Custom fees are **added on top of the transfer amount**, not taken out of it. The wallet signs for `transfer amount + custom fee`, so the user must have enough balance for both values. The entire transfer amount continues through CCTPv2 unchanged, while the custom fee is split on the source chain:

- **10%** of the custom fee is automatically routed to Circle.
- **90%** is sent to your `recipientAddress`.
- **Important:** Circle only takes the 10% share when a custom fee is actually charged. If you omit a custom fee, Circle does not collect anything beyond the protocol fee.

After the custom fee is collected, the transfer amount (e.g., 1,000 USDC) proceeds through CCTPv2, where the protocol applies its own fee (1–14 bps in FAST mode, 0% in STANDARD).

**Fee Flow (1,000 USDC transfer + 10 USDC custom fee):**

```
┌───────────────────────────────────────────────────────────────┐
│ User signs: 1,000 USDC transfer + 10 USDC custom fee = 1,010  │
└──────────────────────┬────────────────────────────────────────┘
                       │
                       ▼
┌───────────────────────────────────────────────────────────────┐
│ Custom fee distribution (source chain)                        │
│  - 1 USDC (10%) → Circle                                      │
│  - 9 USDC (90%) → Your fee recipient                          │
└──────────────────────┬────────────────────────────────────────┘
                       │
                       ▼
┌───────────────────────────────────────────────────────────────┐
│ CCTPv2 processes full transfer amount (1,000 USDC)            │
│  - Protocol fee example (FAST 1 bps): 0.1 USDC                │
│  - Destination receives: 999.9 USDC                           │
└───────────────────────────────────────────────────────────────┘
```

### 1,000 USDC Transfer Example

**Scenario:** Transfer 1,000 USDC from Ethereum to Base with a 10 USDC custom fee.

```typescript
import { BridgeKit } from '@circle-fin/bridge-kit'
import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'

const kit = new BridgeKit()
const adapter = createViemAdapterFromPrivateKey({
  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
})

await kit.bridge({
  from: { adapter, chain: 'Ethereum' },
  to: { adapter, chain: 'Base' },
  amount: '1000', // Transfer amount forwarded to CCTPv2
  config: {
    customFee: {
      value: '10', // Additional debit charged on top of the transfer amount
      recipientAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0',
    },
  },
})
```

**What happens on-chain:**

| Stage                         | Amount     | Description                                            |
| ----------------------------- | ---------- | ------------------------------------------------------ |
| **Transfer amount**           | 1,000 USDC | Forwarded to CCTPv2 without reduction                  |
| **Custom fee debit**          | +10 USDC   | Wallet signs for 1,010 USDC total                      |
| **Custom fee → Circle (10%)** | 1 USDC     | Automatically routed to Circle                         |
| **Custom fee → You (90%)**    | 9 USDC     | Sent to `0x742d35Cc...bEb0` (your fee recipient)       |
| **CCTPv2 fee (FAST 1 bps)\*** | -0.1 USDC  | Protocol fee taken from the 1,000 USDC transfer amount |
| **Destination receives**      | 999.9 USDC | Amount minted on Base after protocol fee               |

\* \_CCTPv2 FAST transfers charge 1–14 bps depending on the route; STANDARD transfers charge 0 bps.

### Kit-Level Fee Policies

For dynamic fee calculation across all transfers, use kit-level policies:

```typescript
import { BridgeKit } from '@circle-fin/bridge-kit'
import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'

const kit = new BridgeKit()
const adapter = createViemAdapterFromPrivateKey({
  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
})

kit.setCustomFeePolicy({
  computeFee: (params) => {
    const amount = parseFloat(params.amount)

    const feePercentage = 0.01 // 1%
    const calculatedFee = amount * feePercentage

    // Return human-readable fee (e.g., '10' for 10 USDC)
    return calculatedFee.toFixed(6)
  },
  resolveFeeRecipientAddress: (feePayoutChain) => {
    // Return appropriate address for source chain
    return feePayoutChain.type === 'solana'
      ? 'SolanaAddressBase58...'
      : '0xEvmAddress...'
  },
})

// All subsequent bridges will use this policy
await kit.bridge({
  from: { adapter, chain: 'Ethereum' },
  to: { adapter, chain: 'Base' },
  amount: '1000', // Custom fee calculated automatically
})
```

> **Note**: The `calculateFee` function is deprecated. Use `computeFee` instead, which receives human-readable amounts (e.g., `'100'` for 100 USDC) rather than smallest-unit amounts.

## Error Handling

The kit uses a thoughtful error handling approach:

- **Hard errors** (thrown): Validation, configuration, and authentication errors
- **Soft errors** (returned): Recoverable issues like insufficient balance or network errors

```typescript
import { BridgeKit } from '@circle-fin/bridge-kit'
import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'

const kit = new BridgeKit()
const adapter = createViemAdapterFromPrivateKey({
  privateKey: process.env.PRIVATE_KEY as string,
})

const params = {
  from: { adapter, chain: 'Ethereum' },
  to: { adapter, chain: 'Base' },
  amount: '100.0',
}

const result = await kit.bridge(params)

if (result.state === 'success') {
  console.log('Bridge successful!')
} else {
  // Handle partial completion with recovery information
  console.log(
    'Successful steps:',
    result.steps.filter((s) => s.state === 'success'),
  )
}
```

## Retrying Failed Transfers

Use `BridgeKit.retry` to resume failed or incomplete bridge operations when the failure is actionable (e.g., transient RPC issues, dropped transactions, or a failed step in a multi-step flow). The kit delegates retry to the original provider (CCTPv2 supports actionable retries) and continues from the appropriate step.

### Method signature

```typescript
retry<
  TFromAdapterCapabilities extends AdapterCapabilities,
  TToAdapterCapabilities extends AdapterCapabilities
>(
  result: BridgeResult,
  context: RetryContext<TFromAdapterCapabilities, TToAdapterCapabilities>
): Promise<BridgeResult>
```

### Basic usage (EVM → EVM)

```typescript
import { BridgeKit } from '@circle-fin/bridge-kit'
import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'

const kit = new BridgeKit()
const adapter = createViemAdapterFromPrivateKey({
  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
})

const result = await kit.bridge({
  from: { adapter, chain: 'Ethereum_Sepolia' },
  to: { adapter, chain: 'Base_Sepolia' },
  amount: '1',
})

if (result.state === 'error') {
  try {
    const retryResult = await kit.retry(result, { from: adapter, to: adapter })
    console.log('Retry state:', retryResult.state)
  } catch (error) {
    console.error('Retry failed:', error)
  }
}
```

### When to retry vs manual intervention

- Retry: transient network/RPC errors, gas repricing/dropped txs, step failure with progress recorded.
- Manual: insufficient funds, incorrect recipient, unsupported route, or errors indicating non-actionable state.

### Limitations

- Only actionable failures can be retried; some failures require user action first.
- Source and destination chains must still be supported by the provider (CCTPv2).
- Provide valid adapters for both `from` and `to` contexts.

### Performance and best practices

- Use exponential backoff on transient failures; avoid rapid replay.
- Reprice gas sensibly on congested networks.
- Persist `result.steps` and tx hashes to aid observability and support.

### Troubleshooting

- "Retry not supported for this result, requires user action": fix balances/addresses/attestation issues and try again.
- "Provider not found": ensure the same provider (e.g., CCTPv2) is present in `BridgeKit` configuration.

> See a runnable example at `examples/basic-usdc-transfer/src/retry.ts` (script: `yarn start:retry`).

## Forwarder Integration

The Bridge Kit supports Circle's Orbit relayer for automated attestation and mint handling.
When enabled, the relayer automatically fetches the attestation and submits the mint transaction on the destination chain, simplifying the bridging process.

### Standard Bridge with Forwarder

Use `useForwarder: true` when you have adapters for both chains but want Circle to handle the mint transaction:

```typescript
import { BridgeKit } from '@circle-fin/bridge-kit'
import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'

const kit = new BridgeKit()
const adapter = createViemAdapterFromPrivateKey({
  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
})

const result = await kit.bridge({
  from: { adapter, chain: 'Ethereum' },
  to: {
    adapter,
    chain: 'Base',
    useForwarder: true, // Circle handles attestation + mint
  },
  amount: '100.50',
})
```

**Benefits:**

- No manual attestation polling or destination mint submission
- Relayer handles destination mint transaction automatically
- Simplified flow with fewer client-side operations

### Forwarder-Only Destination (No Destination Adapter)

When you don't have access to a wallet on the destination chain, use forwarder-only mode.
This is ideal for server-side transfers, custodial services, or when users don't have a wallet on the destination chain:

```typescript
const result = await kit.bridge({
  from: { adapter, chain: 'Ethereum' },
  to: {
    recipientAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e', // Recipient on destination
    chain: 'Base',
    useForwarder: true, // Required for forwarder-only
  },
  amount: '100.50',
})
```

**Key differences from standard bridging:**

- No destination adapter required
- Mint confirmation is based on IRIS API response (not on-chain receipt)
- Mint step's `data` field will be `undefined`

**Relay fee handling:**

- Relay fee is automatically included in `maxFee` estimate
- Fee is deducted from the minted USDC at mint time
- Net received = burn amount - relay fee

```typescript
// Estimate includes relay fee when forwarder is enabled
const estimate = await kit.estimate({
  from: { adapter, chain: 'Ethereum' },
  to: {
    recipientAddress: '0x...',
    chain: 'Base',
    useForwarder: true,
  },
  amount: '100.50',
})

console.log(estimate.maxFee) // Includes both burn fee and relay fee
```

> If you provide `config.maxFee` manually, include forwarder fees yourself.
> Auto-inclusion applies when the kit computes fees from route/speed.
>
> You can discover forwarder-capable chains with
> `kit.getSupportedChains({ forwarderSupported: true })`.
>
> See runnable examples at `examples/basic-usdc-transfer/src/forwarder-*.ts`.

### Receive-exact forwarding with source-paid fees

Opt in with `config.feePayment: 'source'` when the recipient must receive the
exact requested amount. Bridge Kit obtains a short-lived signed Fee Service
quote, approves `amount + feeTotal` in source-chain USDC, and burns exactly
`amount` through `TokenMessengerWithFees`. The destination mint is not reduced.

`useForwarder: true` remains required. Omitting `feePayment` preserves the
existing destination-paid behavior.

```typescript
const params = {
  from: { adapter, chain: 'Ethereum' },
  to: {
    chain: 'Base',
    recipientAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
    useForwarder: true,
  },
  amount: '100',
  config: {
    transferSpeed: 'FAST',
    feePayment: 'source',
  },
} as const

const estimate = await kit.estimate(params)
if ('amountReceived' in estimate) {
  console.log('Recipient receives:', estimate.amountReceived) // 100 USDC
  console.log('Source wallet pays:', estimate.totalDebit) // e.g. 100.42 USDC
  console.log('Quote expires:', estimate.quoteExpiry)

  const result = await kit.bridge({
    ...params,
    quote: estimate.quote,
  })
  console.log(result.state)
}
```

Treat `quote` as opaque and never log it. Bridge Kit validates a supplied quote
against the exact transfer parameters before approval and again immediately
before burning. If it is invalid, mismatched, expired, or too close to expiry,
the bridge fails and you must estimate again. Omit `quote` to let Bridge Kit
fetch a fresh quote automatically.

The initial release supports EVM sources, EVM destinations, and source-chain
USDC fee payment. Custom developer fees are not supported in this mode. On a
429 response, retry the estimate or bridge call with caller-managed exponential
backoff. `503 SERVICE_NOT_ENABLED` means the source route is disabled and should
not be retried.

## API Reference

### Core Methods

- `kit.bridge(params)` - Execute cross-chain bridge operation
- `kit.estimate(params)` - Get cost estimates before bridging
- `kit.retry(result, context)` - Resume actionable failed/partial transfers
- `kit.getSupportedChains(options?)` - Query supported chains with optional filters
- `kit.setCustomFeePolicy(policy)` - Set a dynamic custom fee policy
- `kit.removeCustomFeePolicy()` - Remove the configured custom fee policy
- `kit.on(event, handler)` - Listen to bridge events
- `kit.off(event, handler)` - Removes the listener from bridge events

`bridge` and `estimate` are not limited to USDC. Omitting `token` (or passing
`'USDC'`) bridges USDC via CCTP v2; passing a non-USDC symbol such as `cirBTC`,
`wETH` or `EURC`, or a bytes32 `0x…` token id, bridges that token via CCTPx.
See [Bridge Parameters](#bridge-parameters) for the accepted forms.

### Bridge Parameters

```typescript
interface BridgeParams {
  from: AdapterContext // Source wallet and chain
  to: BridgeDestination // Destination wallet/address and chain
  amount: string // Amount to transfer (e.g., '10.50')
  token?: BridgeToken // 'USDC', a known CCTPx symbol, or a bytes32 token id
  config?: BridgeConfig // Optional bridge configuration (e.g., transfer speed). If omitted, defaults will be used
}

type BridgeToken =
  | 'USDC'
  | 'cirBTC'
  | 'wETH'
  | 'EURC'
  | `0x${string}` // runtime: 0x + exactly 64 hex characters

// AdapterContext: Your blockchain connection
type AdapterContext = {
  adapter: Adapter
  chain: ChainIdentifier
  address?: string // Required for developer-controlled adapters; forbidden for user-controlled
}

// BridgeDestination: Where funds go
type BridgeDestination =
  | AdapterContext
  | {
      adapter: Adapter // Adapter for the destination chain
      chain: ChainIdentifier // Chain identifier
      recipientAddress?: string // Custom recipient address
      useForwarder?: boolean // Enable Circle's Orbit relayer
    }
  | {
      // Forwarder-only destination (no adapter required)
      recipientAddress: string // Required: where to receive USDC
      chain: ChainIdentifier // Chain identifier
      useForwarder: true // Required: must be true
    }
```

## Development

### Building

```bash
# From the root of the monorepo
nx build @circle-fin/bridge-kit
```

### Testing

```bash
# From the root of the monorepo
nx test @circle-fin/bridge-kit
```

### Local Development

```bash
# Install dependencies
yarn install

# Build all packages
yarn build

# Build the bridge-kit specifically
nx build @circle-fin/bridge-kit

# Run tests
nx test @circle-fin/bridge-kit
```

## Community & Support

- **💬 Discord**: [Join our community](https://discord.com/invite/buildoncircle)

## License

This project is licensed under the Apache 2.0 License. Contact [support](https://help.circle.com/s/submit-ticket) for details.

---

<div align="center">

**Ready to start bridging?**

[Join Discord](https://discord.com/invite/buildoncircle)

_Built with ❤️ by Circle_

</div>