@circle-fin/bridge-kit 1.5.0 → 1.6.1

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @circle-fin/bridge-kit
 
+## 1.6.1
+
+### Patch Changes
+
+- New error handling utilities for detecting rate-limit and service errors (`isRateLimitError`, `isServiceError`). Chain definitions now available via `@circle-fin/bridge-kit/chains` subpath import.
+
+## 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

package/QUICKSTART.md

@@ -4,7 +4,7 @@ Welcome to the Bridge Kit! This guide will help you understand the ecosystem and
 
 ## Table of Contents
 
-- [What is the Stablecoin Kit Ecosystem?](#what-is-the-stablecoin-kit-ecosystem)
+- [What is the App Kit Ecosystem?](#what-is-the-app-kit-ecosystem)
 - [Bring Your Own Infrastructure](#bring-your-own-infrastructure)
 - [Architecture Overview](#architecture-overview)
 - [Quick Setup](#quick-setup)
@@ -18,9 +18,9 @@ Welcome to the Bridge Kit! This guide will help you understand the ecosystem and
 - [Best Practices](#best-practices)
 - [Next Steps](#next-steps)
 
-## What is the Stablecoin Kit Ecosystem?
+## What is the App 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.
+The App 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.
 
@@ -876,7 +876,7 @@ kit.on('mint', (event) => {
 
 ## Supported Chains
 
-The Bridge Kit supports chains through Circle's Cross-Chain Transfer Protocol v2 (CCTPv2), enabling **544 total bridge routes** across networks:
+The Bridge Kit supports chains through Circle's Cross-Chain Transfer Protocol v2 (CCTPv2), enabling **578 total bridge routes** across networks:
 
 ### Mainnet Chains (17 chains = 272 routes)
 
@@ -884,9 +884,9 @@ The Bridge Kit supports chains through Circle's Cross-Chain Transfer Protocol v2
 
 **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)
+### Testnet Chains (18 chains = 306 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**
+**Arc Testnet**, **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
 

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,14 +57,12 @@ _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)
 
 ## 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 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
 
@@ -80,6 +81,8 @@ The Bridge Kit enables cross-chain stablecoin transfers via a type-safe, develop
 - **📡 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
 
@@ -122,9 +125,9 @@ npm install @circle-fin/adapter-ethers-v6
 yarn add @circle-fin/adapter-ethers-v6
 
 # For Solana
-npm install @circle-fin/adapter-solana @solana/web3.js @solana/spl-token
+npm install @circle-fin/adapter-solana @solana/web3.js
 # or
-yarn add @circle-fin/adapter-solana @solana/web3.js @solana/spl-token
+yarn add @circle-fin/adapter-solana @solana/web3.js
 ```
 
 ## Quick Start
@@ -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
     }
 ```