@circle-fin/bridge-kit 1.0.0

package/README.md

@@ -0,0 +1,478 @@
+# 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)
+
+**A strongly-typed SDK for seamless cross-chain stablecoin bridging**
+
+_Making cross-chain stablecoin (USDC, and soon more tokens) transfers 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)
+    - [Complete Example with All Options](#complete-example-with-all-options)
+    - [Bridge Speed Configuration](#bridge-speed-configuration)
+  - [Error Handling](#error-handling)
+  - [Examples](#examples)
+    - [Basic Bridge Operation](#basic-bridge-operation)
+    - [EVM to Non-EVM Bridge (EVM ↔ Solana)](#evm-to-non-evm-bridge-evm--solana)
+    - [Third-Party Recipient](#third-party-recipient)
+    - [Event Monitoring](#event-monitoring)
+  - [API Reference](#api-reference)
+    - [Core Methods](#core-methods)
+    - [Bridge Parameters](#bridge-parameters)
+  - [Development](#development)
+    - [Building](#building)
+    - [Testing](#testing)
+    - [Local Development](#local-development)
+  - [Contributing](#contributing)
+    - [Quick Contribution Steps](#quick-contribution-steps)
+  - [Community \& Support](#community--support)
+  - [License](#license)
+
+## Overview
+
+The Stablecoin 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 **34 chains** with **544 total bridge routes** through Circle's CCTPv2
+  - **Mainnet (17 chains)**: Arbitrum, Avalanche, Base, Codex, Ethereum, HyperEVM, Ink, Linea, OP Mainnet, Plume, Polygon PoS, Sei, Solana, Sonic, Unichain, World Chain, XDC
+  - **Testnet (17 chains)**: 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
+- **🎯 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
+
+## 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 @solana/spl-token
+# or
+yarn add @circle-fin/adapter-solana @solana/web3.js @solana/spl-token
+```
+
+## 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 { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+
+// Initialize the kit
+const kit = new BridgeKit()
+
+// Create ONE adapter that works across all chains!
+const adapter = createAdapterFromPrivateKey({
+  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 = createAdapterFromPrivateKey({
+  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
+
+```typescript
+import { createPublicClient, http } from 'viem'
+
+// Production-ready setup with custom RPC endpoints
+const adapter = createAdapterFromPrivateKey({
+  privateKey: process.env.PRIVATE_KEY as string,
+  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 RPC
+const result = await kit.bridge({
+  from: { adapter, chain: 'Ethereum' },
+  to: { adapter, chain: 'Base' },
+  amount: '10.50',
+})
+```
+
+### 🌐 Browser/Wallet Provider Support
+
+**Best for**: Browser applications, wallet integrations, user-controlled transactions
+
+```typescript
+import { createAdapterFromProvider } from '@circle-fin/adapter-viem-v2'
+
+// Create adapters from browser wallet providers
+const adapter = await createAdapterFromProvider({
+  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
+const rpcUrls = {
+  [Ethereum.id]: 'https://eth-mainnet.alchemyapi.io/v2/YOUR_KEY',
+  [Base.id]: '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 = createAdapterFromPrivateKey({...})
+
+// 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' },
+})
+```
+
+## 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 { createAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+
+const kit = new BridgeKit()
+const adapter = createAdapterFromPrivateKey({
+  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'),
+  )
+}
+```
+
+## API Reference
+
+### Core Methods
+
+- `kit.bridge(params)` - Execute cross-chain bridge operation
+- `kit.estimate(params)` - Get cost estimates before bridging
+- `kit.supportsRoute(source, destination, token)` - Check route support
+- `kit.on(event, handler)` - Listen to bridge events
+- `kit.off(event, handler)` - Removes the listener from bridge events
+
+### 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?: 'USDC' // Optional, defaults to 'USDC'
+  config?: BridgeConfig // Optional bridge configuration (e.g., transfer speed). If omitted, defaults will be used
+}
+
+// AdapterContext: Your blockchain connection (always explicit)
+type AdapterContext = { adapter: Adapter; chain: ChainIdentifier }
+
+// BridgeDestination: Where funds go
+type BridgeDestination =
+  | AdapterContext
+  | {
+      adapter: Adapter // Adapter for the destination chain
+      chain: ChainIdentifier // Chain identifier
+      recipientAddress: string // Custom recipient address
+    }
+```
+
+## 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 the project
+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>