@circle-fin/bridge-kit 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @circle-fin/bridge-kit
 
+## 1.6.0
+
+### Minor Changes
+
+- Add Circle Forwarder support for CCTP v2 bridging.
+
+  Forwarding is a relay-assisted mode where Circle observes the burn transaction,
+  retrieves attestation data, and submits the destination mint on the user's
+  behalf. This removes most destination-side orchestration from client code.
+
+  What this enables:
+  - Opt-in forwarding with `useForwarder: true` so Circle handles destination mint
+    submission.
+  - Forwarder-only destinations (no destination adapter required) using
+    `{ recipientAddress, chain, useForwarder: true }`.
+  - Forwarding-fee-aware estimation and max-fee calculation when `maxFee` is
+    auto-derived.
+  - New hook-based burn actions: `cctp.v2.depositForBurnWithHook` and
+    `cctp.v2.customBurnWithHook`.
+  - New forwarding helpers: `buildForwardingHookData` and
+    `buildForwardingHookDataBuffer`.
+  - Chain-level forwarding metadata via `cctp.forwarderSupported` for route
+    capability checks.
+
+  Compatibility:
+  - Existing non-forwarded bridge flows remain unchanged.
+  - If you set `config.maxFee` manually, include any expected forwarding fee.
+
+## 1.5.0
+
+### Minor Changes
+
+- **Monad support**: Bridge Kit now supports Monad mainnet and testnet. You can include Monad in cross-chain USDC transfer flows without additional configuration or changes to existing integrations.
+
+- **Automatic re-attestation for fast transfers**: When retrying a failed CCTP v2 fast transfer, the kit now automatically detects if the mint failed due to an expired attestation and triggers re-attestation. This eliminates manual intervention when attestations expire before the mint transaction completes.
+
 ## 1.4.0
 
 ### Minor Changes

package/QUICKSTART.md

@@ -273,7 +273,7 @@ const adapter = createViemAdapterFromPrivateKey({
     createPublicClient({
       chain,
       transport: http(
-        `https://eth-mainnet.alchemyapi.io/v2/${process.env.ALCHEMY_KEY}`,
+        `https://eth-mainnet.g.alchemy.com/v2/${process.env.ALCHEMY_KEY}`,
         {
           retryCount: 3,
           timeout: 10000,
@@ -1150,7 +1150,7 @@ import { mainnet } from 'viem/chains'
 const publicClient = createPublicClient({
   chain: mainnet,
   transport: fallback([
-    http('https://eth-mainnet.alchemyapi.io/v2/your-key'),
+    http('https://eth-mainnet.g.alchemy.com/v2/your-key'),
     http('https://mainnet.infura.io/v3/your-key'),
     http(), // Default public RPC as fallback
   ]),

package/README.md

@@ -34,19 +34,22 @@ _Making cross-chain stablecoin (USDC, and soon more tokens) transfers as simple
       - [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)
   - [Custom Fees](#custom-fees)
     - [How Custom Fees Work](#how-custom-fees-work)
-    - [1000 USDC Transfer Example](#1000-usdc-transfer-example)
+    - [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)
-  - [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)
+    - [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)
@@ -54,8 +57,6 @@ _Making cross-chain stablecoin (USDC, and soon more tokens) transfers as simple
     - [Building](#building)
     - [Testing](#testing)
     - [Local Development](#local-development)
-  - [Contributing](#contributing)
-    - [Quick Contribution Steps](#quick-contribution-steps)
   - [Community \& Support](#community--support)
   - [License](#license)
 
@@ -72,14 +73,16 @@ The Bridge Kit enables cross-chain stablecoin transfers via a type-safe, develop
 - **🔧 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
+- **🌍 Cross-chain bridging**: The Bridge Kit supports **37 chains** with **666 total bridge routes** through Circle's CCTPv2
+  - **Mainnet (18 chains)**: Arbitrum, Avalanche, Base, Codex, Ethereum, HyperEVM, Ink, Linea, Monad, OP Mainnet, Plume, Polygon PoS, Sei, Solana, Sonic, Unichain, World Chain, XDC
+  - **Testnet (19 chains)**: Arc Testnet, Arbitrum Sepolia, Avalanche Fuji, Base Sepolia, Codex Testnet, Ethereum Sepolia, HyperEVM Testnet, Ink Testnet, Linea Sepolia, Monad Testnet, 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
+- **🤖 Forwarder integration**: Circle's Orbit relayer handles attestation and mint automatically
+- **📭 Forwarder-only destinations**: No destination adapter required - just provide recipient address
 
 ## Architecture Flow
 
@@ -615,6 +618,93 @@ if (result.state === 'error') {
 
 > 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`.
+
 ## API Reference
 
 ### Core Methods
@@ -650,7 +740,14 @@ type BridgeDestination =
   | {
       adapter: Adapter // Adapter for the destination chain
       chain: ChainIdentifier // Chain identifier
-      recipientAddress: string // Custom recipient address
+      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
     }
 ```