@circle-fin/bridge-kit 1.0.0

package/QUICKSTART.md

@@ -0,0 +1,1147 @@
+# Bridge Kit Quickstart Guide
+
+Welcome to the Bridge Kit! This guide will help you understand the ecosystem and get started with cross-chain USDC bridging quickly.
+
+## Table of Contents
+
+- [What is the Stablecoin Kit Ecosystem?](#what-is-the-stablecoin-kit-ecosystem)
+- [Bring Your Own Infrastructure](#bring-your-own-infrastructure)
+- [Architecture Overview](#architecture-overview)
+- [Quick Setup](#quick-setup)
+- [Understanding Bridge Parameters](#understanding-bridge-parameters)
+- [Examples](#examples)
+- [Event Handling](#event-handling)
+- [Supported Chains](#supported-chains)
+- [Error Handling](#error-handling)
+- [Troubleshooting](#troubleshooting)
+- [Best Practices](#best-practices)
+- [Next Steps](#next-steps)
+
+## What is the Stablecoin Kit Ecosystem?
+
+The Stablecoin Kit ecosystem is Circle's open-source initiative to streamline stablecoin development. Our SDKs are designed to be easy to use correctly and hard to misuse, with cross-framework compatibility (viem, ethers, solana-web3 etc.) that integrates cleanly into any stack. While opinionated with sensible defaults, they provide escape hatches when you need full control. The pluggable architecture ensures flexible implementation, and all kits are interoperable—allowing you to compose them together for a wide range of use cases.
+
+**This Bridge Kit specifically focuses on cross-chain stablecoin bridging.** Its goal is to abstract away the complexity of cross-chain bridging while maintaining security, type safety, and developer experience.
+
+The Bridge Kit can have any bridging provider plugged in, by implementing your own `BridgingProvider`, but comes by default with full CCTPv2 support.
+
+## Bring Your Own Infrastructure
+
+The Bridge Kit is designed to integrate seamlessly into your existing development infrastructure. Already have a Viem setup? Perfect! Simply pass your pre-configured clients to the `ViemAdapter` and instantly unlock all EVM chains.
+
+We put developers first by ensuring:
+
+- **🔧 Stack compatibility**: Use your existing Viem clients and configuration
+- **⚡ Instant integration**: No need to migrate to completely new infrastructure
+- **🎯 Meaningful defaults**: We provide helpful utilities to quickly initialize clients when needed
+- **🚀 Future-ready support**: Moving forward, we'll support more EVM frameworks like Ethers and Web3.js and other non-EVM frameworks to broaden compatibility
+
+## Understanding Address Context Modes
+
+Before diving into the examples, it's important to understand the two address context modes that determine how your adapter handles wallet addresses:
+
+### 🏠 **User-Controlled** (Default - Recommended for Most Use Cases)
+
+**What it means**: The adapter automatically manages the wallet address. You don't need to specify an address for operations - it's derived from your wallet/private key.
+
+**When to use**:
+
+- 🔑 **Private key wallets** - Server-side applications, scripts, bots
+- 🌐 **Browser wallets** - MetaMask, Coinbase Wallet, WalletConnect
+- 👤 **Single address scenarios** - One wallet, one address per chain
+- 🚀 **Getting started** - Simplest setup, less boilerplate
+
+**How it works**: The adapter calls `getAddress()` automatically when needed. You never pass address parameters.
+
+```typescript
+// User-controlled example - address resolved automatically
+const adapter = createAdapterFromPrivateKey({
+  privateKey: process.env.PRIVATE_KEY,
+  // addressContext: 'user-controlled' is the default
+})
+
+// Usage - no address needed, it's automatic!
+await kit.bridge({
+  from: { adapter, chain: 'Ethereum' }, // Address auto-resolved
+  to: { adapter, chain: 'Base' }, // Address auto-resolved
+  amount: '100',
+})
+```
+
+### 🏢 **Developer-Controlled** (For Enterprise/Multi-Address Systems)
+
+**What it means**: You must explicitly specify which address to use for each operation. The adapter doesn't assume which address you want to use.
+
+**When to use**:
+
+- 🏦 **Enterprise custody** - Fireblocks, Coinbase, Circle Wallets
+- 🔐 **Multi-signature wallets** - Different signers for different operations
+- 📊 **Multi-address management** - One provider, many addresses/vaults
+- 🎯 **Explicit control** - You want to specify exactly which address per operation
+
+**How it works**: You must pass an `address` parameter for every operation. TypeScript will enforce this at compile-time.
+
+```typescript
+// Developer-controlled example - explicit address control
+const adapter = createAdapterFromPrivateKey({
+  privateKey: process.env.PRIVATE_KEY,
+  capabilities: {
+    addressContext: 'developer-controlled',
+  },
+})
+
+// Usage - address required for each operation
+await kit.bridge({
+  from: {
+    adapter,
+    chain: 'Ethereum',
+    address: '0x123...', // Required! TypeScript error without this
+  },
+  to: {
+    adapter,
+    chain: 'Base',
+    address: '0x456...', // Can be different address
+  },
+  amount: '100',
+})
+```
+
+### 🤔 **How to Choose?**
+
+**Start with User-Controlled** unless you specifically need developer-controlled features:
+
+| Scenario               | Recommended Mode       | Why                                         |
+| ---------------------- | ---------------------- | ------------------------------------------- |
+| Private key script     | `user-controlled`      | Simpler API, one address per key            |
+| MetaMask integration   | `user-controlled`      | Browser wallet = one connected address      |
+| Fireblocks integration | `developer-controlled` | Multiple vaults, explicit vault selection   |
+| Multi-sig wallet       | `developer-controlled` | Different signers, explicit control         |
+| Getting started        | `user-controlled`      | Less complexity, easier to learn            |
+| Production dApp        | `user-controlled`      | Most dApps use one address per user         |
+| Enterprise custody     | `developer-controlled` | Multiple addresses, compliance requirements |
+
+**Rule of thumb**: If you're managing one address per adapter instance → use `user-controlled`. If you're managing multiple addresses through one provider → use `developer-controlled`.
+
+## Architecture Overview
+
+The ecosystem consists of three main components:
+
+### 1. **Adapter** - Your Blockchain Interface
+
+A `Adapter` is an abstraction that handles all blockchain-specific operations for a particular network. Think of it as your "wallet + connection" for a specific blockchain.
+
+**Available Adapters:**
+
+- [**`ViemAdapter`**](https://www.npmjs.com/package/@circle-fin/adapter-viem-v2) - For all EVM-compatible chains (Ethereum, Base, Arbitrum, Polygon, etc.)
+- [**`SolanaAdapter`**](https://www.npmjs.com/package/@circle-fin/adapter-solana) - For Solana blockchain
+- More coming soon 🚀
+
+#### What does an Adapter do?
+
+- 🔑 **Wallet operations**: Get addresses, sign transactions
+- ⛽ **Gas management**: Estimate fees, calculate transaction costs
+- 🔗 **Chain interaction**: Prepare, simulate, and execute transactions
+- 📍 **Chain identification**: Know which blockchain you're operating on
+
+### 2. **Provider** - Your Transfer Protocol
+
+A `Provider` implements a specific bridging protocol and defines which chains and tokens it supports.
+
+**Available Providers:**
+
+- **`CCTPV2BridgingProvider`**(<https://www.npmjs.com/package/@circle-fin/provider-cctp-v2>) - Circle's Cross-Chain Transfer Protocol v2 (CCTPv2)
+
+#### What does a Provider do?
+
+- 🛣️ **Route validation**: Check if a transfer path is supported
+- 💰 **Cost estimation**: Calculate gas and protocol fees
+- 🔄 **Transfer execution**: Handle the complete cross-chain flow
+- 📊 **Progress tracking**: Monitor transfer status and confirmations
+
+> **Note:** The Bridge Kit uses the `CCTPV2BridgingProvider` by default. Most developers will not need to think about or interact with any provider-specific logic unless they are building a custom provider, or until there are multiple providers to switch between.
+
+### 3. **Kit** - Your Developer Interface
+
+The `BridgeKit` orchestrates Adapters and Providers to create a unified, type-safe API.
+
+#### What does the Kit do?
+
+- 🎯 **Auto-routing**: Automatically selects the right provider for your transfer
+- ✅ **Validation**: Comprehensive parameter validation with helpful error messages
+- 🔧 **Resolution**: Automatically resolves chain definitions and addresses
+- 📡 **Events**: Real-time progress updates and error handling
+
+## Quick Setup
+
+### Installation
+
+```bash
+npm install @circle-fin/bridge-kit @circle-fin/adapter-viem-v2
+# or
+yarn add @circle-fin/bridge-kit @circle-fin/adapter-viem-v2
+```
+
+### 🚀 Easiest Setup with Factory Methods (Recommended)
+
+The factory methods make getting started incredibly simple. Plus, you can create just **one adapter** and use it across different chains!
+
+#### User-Controlled Setup (Most Common)
+
+```typescript
+import { BridgeKit } from '@circle-fin/bridge-kit'
+import { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+
+// Initialize the kit (CCTPv2 provider included by default)
+const kit = new BridgeKit()
+
+// Create ONE adapter that can work across chains!
+// Uses 'user-controlled' by default - addresses resolved automatically
+const adapter = createAdapterFromPrivateKey({
+  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
+})
+
+// Get cost estimate first
+const estimate = await kit.estimate({
+  from: { chain: 'Ethereum' },
+  to: { chain: 'Base' },
+  amount: '10.50',
+})
+console.log('Estimated fees:', estimate)
+
+// Execute a transfer - same adapter, different chains!
+// No addresses needed - they're resolved automatically from your private key
+const result = await kit.bridge({
+  from: { adapter, chain: 'Ethereum' }, // Source chain: Ethereum
+  to: { adapter, chain: 'Base' }, // Destination chain: Base
+  amount: '10.50', // 10.50 USDC
+})
+```
+
+#### Developer-Controlled Setup (Enterprise/Multi-Address)
+
+```typescript
+import { BridgeKit } from '@circle-fin/bridge-kit'
+import { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+
+const kit = new BridgeKit()
+
+// Create adapter with explicit address control
+const adapter = createAdapterFromPrivateKey({
+  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
+  capabilities: {
+    addressContext: 'developer-controlled', // Explicit address control
+  },
+})
+
+// Execute transfer with explicit addresses
+// TypeScript will require address fields - compile error if missing!
+const result = await kit.bridge({
+  from: {
+    adapter,
+    chain: 'Ethereum',
+    address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e', // Required!
+  },
+  to: {
+    adapter,
+    chain: 'Base',
+    address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e', // Can be different
+  },
+  amount: '10.50',
+})
+```
+
+### 🏭 Production Considerations
+
+> **⚠️ Important for Production**: The factory methods use Viem's default public RPC endpoints, which may have rate limits and lower reliability. For production applications, we strongly recommend using dedicated RPC providers like Alchemy, Infura, or QuickNode.
+
+```typescript
+import { BridgeKit } from '@circle-fin/bridge-kit'
+import { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+import { createPublicClient, http } from 'viem'
+
+const kit = new BridgeKit()
+
+// Production-ready setup with custom RPC endpoints
+const adapter = createAdapterFromPrivateKey({
+  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
+  capabilities: {
+    addressContext: 'user-controlled', // Explicit for clarity in production
+    supportedChains: [Ethereum, Base], // Restrict to your supported chains
+  },
+  getPublicClient: ({ chain }) =>
+    createPublicClient({
+      chain,
+      transport: http(
+        `https://eth-mainnet.alchemyapi.io/v2/${process.env.ALCHEMY_KEY}`,
+        {
+          retryCount: 3,
+          timeout: 10000,
+        },
+      ),
+    }),
+})
+
+// Same simple usage, but with production-grade infrastructure
+const result = await kit.bridge({
+  from: { adapter, chain: 'Ethereum' },
+  to: { adapter, chain: 'Base' },
+  amount: '10.50',
+})
+```
+
+### 🌐 Browser/Provider Support
+
+For browser environments with wallet providers like MetaMask:
+
+```typescript
+import { BridgeKit } from '@circle-fin/bridge-kit'
+import { createAdapterFromProvider } from '@circle-fin/adapter-viem-v2'
+
+const kit = new BridgeKit()
+
+// Create adapters from browser wallet providers
+// Browser wallets are typically user-controlled (one connected address)
+const adapter = await createAdapterFromProvider({
+  provider: window.ethereum,
+  capabilities: {
+    addressContext: 'user-controlled', // Browser wallets = user-controlled
+  },
+})
+
+// Execute a transfer
+const result = await kit.bridge({
+  from: { adapter, chain: 'Ethereum' },
+  to: { adapter, chain: 'Base' },
+  amount: '10.50',
+})
+```
+
+### 🔧 Advanced Setup (Custom Configuration)
+
+For advanced users who need custom RPC endpoints or client configuration:
+
+```typescript
+import { BridgeKit } from '@circle-fin/bridge-kit'
+import { ViemAdapter } from '@circle-fin/adapter-viem-v2'
+import { createPublicClient, createWalletClient, http } from 'viem'
+import { mainnet, base } from 'viem/chains'
+import { privateKeyToAccount } from 'viem/accounts'
+
+const kit = new BridgeKit()
+const account = privateKeyToAccount(process.env.PRIVATE_KEY)
+
+// Create adapters with custom configuration
+const ethereumAdapter = new ViemAdapter({
+  publicClient: createPublicClient({
+    chain: mainnet,
+    transport: http('https://your-custom-rpc.com'),
+  }),
+  walletClient: createWalletClient({
+    account,
+    chain: mainnet,
+    transport: http('https://your-custom-rpc.com'),
+  }),
+})
+
+const baseAdapter = new ViemAdapter({
+  publicClient: createPublicClient({ chain: base, transport: http() }),
+  walletClient: createWalletClient({ account, chain: base, transport: http() }),
+})
+
+// Execute a transfer
+const result = await kit.bridge({
+  from: { adapter: ethereumAdapter, chain: 'Ethereum' },
+  to: { adapter: baseAdapter, chain: 'Base' },
+  amount: '10.50',
+})
+```
+
+## Understanding Bridge Parameters
+
+The `BridgeParams` type is designed to be flexible and developer-friendly, with built-in type safety based on your adapter's address context:
+
+```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?: 'USDC' // Optional, defaults to 'USDC'
+  config?: BridgeConfig // Optional, defaults to FAST transfer
+}
+```
+
+### ⚡ **Type Safety Based on Address Context**
+
+The shape of `AdapterContext` changes based on your adapter's `addressContext` setting:
+
+#### User-Controlled Adapters
+
+```typescript
+// User-controlled - address forbidden (TypeScript error if provided)
+const userControlledContext = {
+  adapter: userAdapter,
+  chain: 'Ethereum',
+  // address: '0x...' // ❌ TypeScript error - not allowed!
+}
+```
+
+#### Developer-Controlled Adapters
+
+```typescript
+// Developer-controlled - address required (TypeScript error if missing)
+const devControlledContext = {
+  adapter: devAdapter,
+  chain: 'Ethereum',
+  address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e', // ✅ Required!
+}
+```
+
+This compile-time validation prevents common mistakes and ensures you're using the right pattern for your adapter type.
+
+### Configuration Types Explained
+
+#### 1. **AdapterContext** - Your Transfer Endpoint
+
+Represents where funds come from or go to:
+
+```typescript
+type AdapterContext = { adapter: Adapter; chain: ChainIdentifier }
+```
+
+**Chain-agnostic adapter creation**:
+
+```typescript
+const adapter = createAdapterFromPrivateKey({
+  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
+  chain: 'Ethereum',
+})
+```
+
+**Chain specification is required**:
+
+```typescript
+const adapterContext = { adapter, chain: 'Ethereum' }
+```
+
+#### 2. **BridgeDestination** - Where Funds Go
+
+Can be either a simple `AdapterContext` or include a custom recipient address:
+
+```typescript
+type BridgeDestination = AdapterContext | BridgeDestinationWithAddress
+
+interface BridgeDestinationWithAddress {
+  adapter: Adapter // Adapter for the destination chain
+  chain: ChainIdentifier // Chain identifier
+  recipientAddress: string // Custom recipient address
+}
+```
+
+**Send to adapter's own address**:
+
+```typescript
+const destination = { adapter, chain: 'Base' }
+```
+
+**Send to different address**:
+
+```typescript
+const destination = {
+  adapter,
+  chain: 'Base',
+  recipientAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
+}
+```
+
+### Address Resolution - Automatic vs Manual
+
+**When you use AdapterContext:**
+
+```typescript
+await kit.bridge({
+  from: { adapter: ethereumAdapter, chain: 'Ethereum' },
+  to: { adapter: baseAdapter, chain: 'Base' },
+  amount: '10.50',
+})
+```
+
+- The address is automatically derived from `adapter.getAddress()`
+- The chain is explicitly specified for clarity
+- Funds are sent from/to the adapter's own address
+
+**When you specify custom recipient address:**
+
+```typescript
+await kit.bridge({
+  from: { adapter: ethereumAdapter, chain: 'Ethereum' },
+  to: {
+    adapter: baseAdapter,
+    chain: 'Base',
+    recipientAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
+  },
+  amount: '10.50',
+})
+```
+
+- Uses the explicit address provided for the recipient
+- Chain must be specified along with adapter
+- Useful for sending to different recipients or custodial services
+
+### Chain Specification - Multiple Formats
+
+You can specify chains in multiple ways:
+
+```typescript
+// 1. Use the exported chain definition (recommended)
+import { Ethereum } from '@circle-fin/bridge-kit/chains'
+{ adapter: ethereumAdapter, chain: Ethereum }
+
+// 2. Use the blockchain enum
+import { Blockchain } from '@circle-fin/bridge-kit/chains'
+{ adapter: ethereumAdapter, chain: Blockchain.Ethereum }
+
+// 3. Use a string literal
+{ adapter: ethereumAdapter, chain: 'Ethereum' }
+
+// Note: Chain specification is required for clarity
+```
+
+## Transfer Configuration
+
+Customize your transfer behavior with the `config` parameter:
+
+```typescript
+interface BridgeConfig {
+  transferSpeed: 'FAST' | 'SLOW' // Default: 'FAST'
+  /**
+   * The maximum bridging fee you're willing to pay (in smallest units for that chain).
+   * You should only set this parameter if speed is set to FAST.
+   * If this value ends up being less than the protocol fee, the bridge flow will be executed as a SLOW transfer.
+   */
+  maxFee?: string // Optional: maximum fee in smallest units
+}
+```
+
+- **FAST**: Optimized for speed with potentially higher fees
+- **SLOW**: Optimized for cost with zero transfer fees but longer confirmation times
+
+## Examples
+
+### Example 1: EVM to EVM Transfer (Ethereum → Base)
+
+#### Standard User-Controlled Transfer
+
+```typescript
+import { BridgeKit } from '@circle-fin/bridge-kit'
+import { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+
+const kit = new BridgeKit()
+
+// Create ONE adapter that can work across chains
+// Uses user-controlled by default - addresses resolved automatically
+const adapter = createAdapterFromPrivateKey({
+  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
+})
+
+async function evmToEvmTransfer() {
+  try {
+    // Get cost estimate first
+    // Note: this is a completely optional pattern - you do not need to estimate the transaction costs ahead of time, but it can be useful if you want to see the gas fees and provider fees ahead of time
+    const estimate = await kit.estimate({
+      from: { chain: 'Ethereum' },
+      to: { chain: 'Base' },
+      amount: '25.0',
+      config: { transferSpeed: 'FAST' },
+    })
+
+    console.log('Estimated gas fees:', estimate.gasFees)
+    console.log('Protocol fees:', estimate.fees)
+
+    // Execute the transfer - same adapter, different chains
+    // No addresses needed - they're resolved automatically from your private key
+    const result = await kit.bridge({
+      from: { adapter, chain: 'Ethereum' },
+      to: { adapter, chain: 'Base' },
+      amount: '25.0',
+      config: { transferSpeed: 'FAST' },
+    })
+
+    console.log('Transfer completed!')
+    console.log('Steps:', result.steps)
+    console.log(
+      'Source tx:',
+      result.steps.find((s) => s.name === 'depositForBurn')?.txHash,
+    )
+    console.log(
+      'Destination tx:',
+      result.steps.find((s) => s.name === 'mint')?.txHash,
+    )
+  } catch (error) {
+    console.error('Transfer failed:', error)
+  }
+}
+```
+
+#### Enterprise Developer-Controlled Transfer
+
+```typescript
+import { BridgeKit } from '@circle-fin/bridge-kit'
+import { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+
+const kit = new BridgeKit()
+
+// Create adapter with explicit address control for enterprise use
+const adapter = createAdapterFromPrivateKey({
+  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
+  capabilities: {
+    addressContext: 'developer-controlled', // Enterprise/multi-address mode
+  },
+})
+
+async function enterpriseEvmToEvmTransfer() {
+  try {
+    // Execute transfer with explicit address control
+    // TypeScript enforces that addresses are provided
+    const result = await kit.bridge({
+      from: {
+        adapter,
+        chain: 'Ethereum',
+        address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e', // Vault A
+      },
+      to: {
+        adapter,
+        chain: 'Base',
+        address: '0x123d35Cc6634C0532925a3b844Bc454e4438f123', // Vault B (different!)
+      },
+      amount: '25.0',
+      config: { transferSpeed: 'FAST' },
+    })
+
+    console.log('Enterprise transfer completed!')
+    console.log('From vault:', result.source.address)
+    console.log('To vault:', result.destination.address)
+  } catch (error) {
+    console.error('Transfer failed:', error)
+  }
+}
+```
+
+### Example 2: EVM to Non-EVM Transfer (Ethereum → Solana)
+
+```typescript
+import { BridgeKit } from '@circle-fin/bridge-kit'
+import { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+import { SolanaAdapter } from '@circle-fin/adapter-solana'
+import { Connection, Keypair } from '@solana/web3.js'
+import bs58 from 'bs58'
+
+const kit = new BridgeKit()
+
+// Create EVM adapter (Ethereum) using factory method
+const ethereumAdapter = createAdapterFromPrivateKey({
+  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
+  chain: 'Ethereum',
+})
+
+// Create Solana adapter
+const solanaConnection = new Connection('https://api.mainnet-beta.solana.com')
+const solanaKeypair = Keypair.fromSecretKey(
+  bs58.decode(process.env.SOLANA_PRIVATE_KEY),
+)
+const solanaAdapter = new SolanaAdapter({
+  connection: solanaConnection,
+  signer: solanaKeypair,
+})
+
+async function evmToSolanaTransfer() {
+  try {
+    // Cross-chain bridge from Ethereum to Solana
+    const result = await kit.bridge({
+      from: { adapter: ethereumAdapter, chain: 'Ethereum' },
+      to: { adapter: solanaAdapter, chain: 'Solana' },
+      amount: '50.0',
+      config: { transferSpeed: 'SLOW' }, // Use slow for lower fees
+    })
+
+    console.log('Cross-chain bridge completed!')
+    console.log(
+      'Ethereum tx:',
+      result.steps.find((s) => s.name === 'depositForBurn')?.txHash,
+    )
+    console.log(
+      'Solana tx:',
+      result.steps.find((s) => s.name === 'mint')?.txHash,
+    )
+  } catch (error) {
+    console.error('Transfer failed:', error)
+  }
+}
+```
+
+### Example 3: Advanced Usage with Custom Addresses
+
+**This pattern is useful when you need to bridge funds to a wallet address that is different from the wallet that is signing the transactions.**
+
+```typescript
+import { BridgeKit } from '@circle-fin/bridge-kit'
+import { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+
+const kit = new BridgeKit()
+
+// Create ONE adapter that can work across chains
+const adapter = createAdapterFromPrivateKey({
+  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
+  chain: 'Ethereum',
+})
+
+// Send from your address to a different recipient on another chain
+const result = await kit.bridge({
+  from: { adapter, chain: 'Ethereum' }, // Source: your Ethereum address
+  to: {
+    adapter, // Same adapter, different chain
+    chain: 'Base',
+    recipientAddress: '0xRecipientAddress', // Send to a different address
+  },
+  amount: '100.0',
+})
+
+// More explicit configuration with custom settings
+const result2 = await kit.bridge({
+  from: { adapter, chain: 'Ethereum' },
+  to: {
+    adapter,
+    chain: 'Base',
+    recipientAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
+  },
+  amount: '100.0',
+  config: { transferSpeed: 'FAST', maxFee: '1000000' },
+})
+```
+
+> **💡 Pro Tip**: The single adapter pattern is especially powerful when you need to send to custom addresses. You can use the same adapter for both source and destination while specifying different addresses and chains for each side of the transfer!
+
+## Event Handling
+
+Events allow you to subscribe to different parts of the briding lifecycle and respond to them however you want. Events match up 1-1 to actions that are taken by the Bridge Kit: **'approve', 'burn', 'attestsion', and 'mint'** are the events you can subscribe to, or you can use **'\*'** to subscribe to all events.
+
+Each event can also be subscribed to multiple times with different callbacks.
+
+Monitor transfer progress in real-time:
+
+```typescript
+import { BridgeKit } from '@circle-fin/bridge-kit'
+
+const kit = new BridgeKit()
+
+// Listen to all events
+kit.on('*', (event) => {
+  console.log(`[${event.method}] ${event.protocol}:`, event.values)
+})
+
+// Listen to specific events
+kit.on('approve', (event) => {
+  console.log('Approval completed:', event.txHash)
+})
+
+kit.on('burn', (event) => {
+  console.log('Burn completed:', event.txHash)
+})
+
+kit.on('attestation', (event) => {
+  console.log('Attestation received:', event.attestation)
+})
+
+kit.on('mint', (event) => {
+  console.log('Mint completed:', event.txHash)
+})
+```
+
+## Supported Chains
+
+The Bridge Kit supports chains through Circle's Cross-Chain Transfer Protocol v2 (CCTPv2), enabling **544 total bridge routes** across networks:
+
+### Mainnet Chains (17 chains = 272 routes)
+
+> **Note**: The Bridge Kit stays in lockstep with CCTPv2 development. As Circle adds new chains to CCTPv2, they automatically become available in the Bridge Kit.
+
+**Arbitrum**, **Avalanche**, **Base**, **Codex**, **Ethereum**, **HyperEVM**, **Ink**, **Linea**, **OP Mainnet**, **Plume**, **Polygon PoS**, **Sei**, **Solana**, **Sonic**, **Unichain**, **World Chain**, **XDC**
+
+### Testnet Chains (17 chains = 272 routes)
+
+**Arbitrum Sepolia**, **Avalanche Fuji**, **Base Sepolia**, **Codex Testnet**, **Ethereum Sepolia**, **HyperEVM Testnet**, **Ink Testnet**, **Linea Sepolia**, **OP Sepolia**, **Plume Testnet**, **Polygon PoS Amoy**, **Sei Testnet**, **Solana Devnet**, **Sonic Testnet**, **Unichain Sepolia**, **World Chain Sepolia**, **XDC Apothem**
+
+## Error Handling
+
+The Bridge Kit uses the following error handling approach designed for developer control:
+
+### Hard Errors (Thrown)
+
+The kit only throws exceptions for "hard errors" that prevent execution:
+
+- **Validation errors**: Invalid parameters, unsupported routes, malformed data
+- **Configuration errors**: Missing required settings, invalid chain configurations
+- **Authentication errors**: Invalid signatures, insufficient permissions
+
+### Soft Errors (Returned)
+
+For recoverable issues during transfer execution, the kit returns a result object with partial success:
+
+- **Balance insufficient**: Returns successful steps completed before failure
+- **Network errors**: Provides transaction hashes and step details for manual recovery
+- **Timeout issues**: Returns progress made and allows for retry logic
+
+This approach gives you full control over recovery scenarios while preventing unexpected crashes.
+
+> **Note**: In the future, we will be adding capabilities to continue from a certain point in the bridging lifecycle to accomodate soft error cases.
+
+## Troubleshooting
+
+### Common Issues and Solutions
+
+#### "Route not supported" Error
+
+```typescript
+import { BridgeKit } from '@circle-fin/bridge-kit'
+
+const kit = new BridgeKit()
+
+// Check if your transfer route is supported
+const isSupported = kit.supportsRoute('Ethereum', 'Base', 'USDC')
+if (!isSupported) {
+  console.log('This route is not available through CCTPv2')
+}
+```
+
+**Solution**: Verify both chains are in the [supported chains list](#supported-chains). The kit currently, by default, only supports routes available through Circle's CCTPv2
+
+#### "Insufficient balance" Error
+
+**Check your USDC balance before transfer:**
+
+> **💡 Coming Soon**: The Kit will soon provide built-in balance checking methods. For now, you can check balances manually using the examples below.
+
+```typescript
+// On EVM chains (using viem)
+import { createPublicClient, http, getContract } from 'viem'
+import { mainnet } from 'viem/chains'
+import { formatUnits } from 'viem'
+import { Ethereum } from '@circle-fin/bridge-kit/chains'
+
+const publicClient = createPublicClient({ chain: mainnet, transport: http() })
+const usdcContract = getContract({
+  // Use the chain definitions from the kit to get the correct USDC address
+  address: Ethereum.usdcAddress,
+  abi: [
+    {
+      name: 'balanceOf',
+      type: 'function',
+      inputs: [{ name: 'account', type: 'address' }],
+      outputs: [{ name: '', type: 'uint256' }],
+    },
+  ],
+  publicClient,
+})
+
+const usdcBalance = await usdcContract.read.balanceOf([walletAddress])
+console.log('USDC Balance:', formatUnits(usdcBalance, 6))
+
+// On Solana (check ATA balance)
+import { Connection } from '@solana/web3.js'
+
+const connection = new Connection('https://api.mainnet-beta.solana.com')
+const ataBalance = await connection.getTokenAccountBalance(ataAddress)
+console.log('USDC Balance:', ataBalance.value.uiAmount)
+```
+
+#### Network RPC Issues
+
+**Symptoms**: Timeouts, connection errors, or slow responses
+
+**Solutions**:
+
+- Use reliable RPC endpoints (Alchemy, Infura, QuickNode)
+- Implement retry logic for network calls
+- Consider multiple RPC fallbacks
+
+```typescript
+import { createPublicClient, http, fallback } from 'viem'
+import { mainnet } from 'viem/chains'
+
+const publicClient = createPublicClient({
+  chain: mainnet,
+  transport: fallback([
+    http('https://eth-mainnet.alchemyapi.io/v2/your-key'),
+    http('https://mainnet.infura.io/v3/your-key'),
+    http(), // Default public RPC as fallback
+  ]),
+})
+```
+
+#### Transaction Stuck or Failed
+
+**For EVM chains**: Check transaction on the block explorer using the `txHash` from the result
+
+**For Solana**: Use Solana Explorer or SolScan
+
+**Recovery**: If a transfer fails mid-process, check the returned `result.steps` to see what completed successfully. See [Recovery from Soft Errors](#recovery-from-soft-errors) for detailed recovery patterns.
+
+### Recovery from Soft Errors
+
+When transfers encounter soft errors (network congestion, insufficient gas, RPC timeouts), you can recover by using the CCTPv2BridgingProvider directly to complete the remaining steps. The BridgeKit's transfer result contains enough information to resume from any point.
+
+> **🚀 Coming Soon**: We're working on built-in recovery functionality that will allow you to pass the current transfer state directly to `kit.resume(bridgeResult)` for automatic retry logic. For now, you can use the manual recovery patterns below.
+
+#### Understanding Transfer State
+
+Every CCTPv2 transfer follows these steps:
+
+1. **Approval** - Allow the contract to spend USDC
+2. **DepositForBurn** - Burns USDC on source chain, generates attestation
+3. **FetchAttestation** - Wait for Circle to sign the burn proof
+4. **Mint** - Mint USDC on destination chain using the attestation
+
+> **⚠️ Important**: The `result.source` and `result.destination` from `BridgeResult` only contain `address` and `blockchain` properties. To use provider methods for recovery, you must reconstruct full wallet contexts with `adapter` and `chain` properties as shown in the examples below.
+
+```typescript
+import { BridgeKit } from '@circle-fin/bridge-kit'
+import { CCTPV2BridgingProvider } from '@circle-fin/provider-cctp-v2'
+
+// Start a transfer that might fail
+const kit = new BridgeKit()
+const result = await kit.bridge({
+  from: sourceAdapter,
+  to: destAdapter,
+  amount: '100.0',
+})
+
+// Check which steps completed successfully
+console.log('Transfer state:', result.state)
+console.log('Steps:', result.steps)
+
+/*
+Expected output for partial failure:
+result.state: 'error'
+result.steps: [
+  { name: 'approve', state: 'success', txHash: '0x123...' },
+  { name: 'depositForBurn', state: 'success', txHash: '0x456...' },
+  { name: 'fetchAttestation', state: 'error', error: 'Network timeout' },
+  // mint step won't be present since fetchAttestation failed
+]
+*/
+
+// Helper function to find specific steps
+const getStep = (stepName: string) =>
+  result.steps.find((step) => step.name === stepName)
+const approveStep = getStep('approve')
+const burnStep = getStep('depositForBurn')
+const attestationStep = getStep('fetchAttestation')
+const mintStep = getStep('mint')
+```
+
+#### Recovery Pattern 1: Failed Attestation Fetch
+
+If the attestation fetch fails due to network issues but the burn completed, you can retry just the fetchAttestation step:
+
+> **Note**: In the future, we will be adding capabilities to continue from a certain point in the bridging lifecycle to accomodate soft error cases like this.
+
+```typescript
+import { CCTPV2BridgingProvider } from '@circle-fin/provider-cctp-v2'
+
+// Create provider instance for manual recovery
+const provider = new CCTPV2BridgingProvider()
+
+// Use existing contexts or reconstruct wallet contexts from the result and adapters
+const sourceContext = {
+  adapter: sourceAdapter,
+  address: result.source.address,
+  chain: 'Ethereum',
+}
+
+const destContext = {
+  adapter: destAdapter,
+  address: result.destination.address,
+  chain: 'Base',
+}
+
+// Check if fetchAttestation specifically failed
+const attestationStep = result.steps.find(
+  (step) => step.name === 'fetchAttestation',
+)
+const burnStep = result.steps.find((step) => step.name === 'depositForBurn')
+
+if (burnStep?.state === 'success' && attestationStep?.state === 'error') {
+  console.log('Burn completed but attestation fetch failed. Retrying...')
+
+  try {
+    // Retry fetching the attestation using the burn transaction hash
+    const attestationResult = await provider.fetchAttestation(
+      sourceContext, // proper wallet context with adapter
+      burnStep.txHash,
+    )
+    console.log('Attestation fetch retry successful')
+
+    // Continue with minting using the attestation data
+    const mintRequest = await provider.mint(
+      sourceContext, // proper source context
+      destContext, // proper destination context
+      attestationResult, // attestation data
+    )
+
+    // Execute the mint transaction
+    if (mintRequest.type !== 'noop') {
+      const mintTxHash = await mintRequest.execute()
+      const mintReceipt = await destAdapter.waitForTransaction(mintTxHash)
+      console.log('Recovery completed:', mintTxHash)
+    }
+  } catch (error) {
+    console.error('Attestation retry failed:', error)
+
+    // Implement exponential backoff for attestation fetching
+    const maxRetries = 5
+    let retryCount = 0
+    const baseDelay = 10000 // Start with 10 seconds
+
+    while (retryCount < maxRetries) {
+      try {
+        const delay = baseDelay * Math.pow(2, retryCount)
+        console.log(`Retry ${retryCount + 1}/${maxRetries} in ${delay}ms...`)
+        await new Promise((resolve) => setTimeout(resolve, delay))
+
+        const attestationResult = await provider.fetchAttestation(
+          sourceContext,
+          burnStep.txHash,
+        )
+        console.log('Attestation fetched on retry', retryCount + 1)
+        break
+      } catch (retryError) {
+        retryCount++
+        if (retryCount === maxRetries) {
+          console.error('All attestation retries failed')
+        }
+      }
+    }
+  }
+} else if (!burnStep || burnStep.state !== 'success') {
+  console.error(
+    'Cannot retry attestation: burn step not completed successfully',
+  )
+} else if (!attestationStep) {
+  console.error('Attestation step not found in transfer result')
+}
+```
+
+#### Recovery Pattern 2: Failed Mint Step
+
+If minting fails due to gas issues or network problems:
+
+> **Note**: In the future, we will be adding capabilities to continue from a certain point in the bridging lifecycle to accomodate soft error cases like this.
+
+```typescript
+import { parseGwei } from 'viem'
+import { CCTPV2BridgingProvider } from '@circle-fin/provider-cctp-v2'
+
+const provider = new CCTPV2BridgingProvider()
+
+// Use existing contexts or reconstruct wallet contexts from the result and adapters
+const sourceContext = {
+  adapter: sourceAdapter,
+  address: result.source.address,
+  chain: 'Ethereum'
+
+const destContext = {
+  adapter: destAdapter,
+  address: result.destination.address,
+  chain: 'Base''
+}
+
+// Check if attestation was fetched successfully but mint failed
+const attestationStep = result.steps.find(
+  (step) => step.name === 'fetchAttestation',
+)
+const mintStep = result.steps.find((step) => step.name === 'mint')
+
+if (attestationStep?.state === 'success' && mintStep?.state === 'error') {
+  try {
+    // Retry the mint with the attestation data
+    const mintRequest = await provider.mint(
+      sourceContext,
+      destContext,
+      attestationStep.data, // The attestation data from the successful step
+    )
+
+    // Execute with custom gas settings for the retry
+    if (mintRequest.type !== 'noop') {
+      // For EVM chains, you can modify gas settings on the adapter
+      if (result.destination.blockchain === 'evm') {
+        // Override gas price for the retry (EVM chains)
+        destAdapter.walletClient.gasPrice = parseGwei('25') // Higher gas price
+      }
+
+      const retryTxHash = await mintRequest.execute()
+      const receipt = await destAdapter.waitForTransaction(retryTxHash)
+      console.log('Mint retry successful:', retryTxHash)
+    }
+  } catch (error) {
+    console.error('Mint retry failed:', error)
+  }
+}
+```
+
+#### Recovery Best Practices
+
+1. **Save Transfer State**: Always persist the transfer result for recovery
+2. **Check Step Status**: Verify which steps completed before attempting recovery
+3. **Use Appropriate Timeouts**: Give network operations enough time to complete
+4. **Implement Exponential Backoff**: For retry logic, use increasing delays
+5. **Monitor Gas Prices**: Adjust gas settings during network congestion
+
+```typescript
+// Example: Robust retry with exponential backoff
+async function retryWithBackoff<T>(
+  operation: () => Promise<T>,
+  maxRetries = 3,
+  baseDelay = 1000,
+): Promise<T> {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      return await operation()
+    } catch (error) {
+      if (attempt === maxRetries) throw error
+
+      const delay = baseDelay * Math.pow(2, attempt - 1)
+      console.log(`Attempt ${attempt} failed, retrying in ${delay}ms...`)
+      await new Promise((resolve) => setTimeout(resolve, delay))
+    }
+  }
+  throw new Error('All retry attempts failed')
+}
+
+// Usage for resilient attestation fetching (requires sourceContext from above)
+const attestation = await retryWithBackoff(
+  () => provider.fetchAttestation(sourceContext, burnTxHash),
+  5, // 5 retries
+  2000, // Start with 2 second delay
+)
+```
+
+### Debugging Tips
+
+1. **Monitor gas prices**: High network congestion can cause failures
+2. **Test on testnets first**: Always test your integration on testnets before mainnet
+3. **Use block explorers**: Always verify transaction status on-chain
+4. **Save intermediate results**: Persist transfer state for recovery scenarios
+
+## Best Practices
+
+1. **Always estimate first**: Use `kit.estimate()` to show costs before transfers
+2. **Ensure sufficient gas tokens**: Verify you have enough native tokens (ETH, MATIC, AVAX, etc.) on both source and destination chains for transaction fees. The kit currently doesn't check gas balances pre-initialization - this convenience feature will be added in the future
+3. **Handle errors gracefully**: Network issues and validation errors are common
+4. **Monitor events**: Use event listeners for real-time progress updates
+5. **Validate inputs**: The kit validates automatically, but client-side validation improves UX
+
+## Next Steps
+
+- **Explore Examples**: Check out the [examples directory](https://github.com/circlefin/stablecoin-kits-private/tree/main/examples) for more detailed implementations
+- **Join the community**: Connect with other developers on [discord](https://discord.com/invite/buildoncircle) building on Circle's stablecoin infrastructure
+
+Ready to start bridging? Let's make cross-chain bridging as easy as a single function call! 🌉