@circle-fin/bridge-kit 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @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

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)
 
@@ -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
 
@@ -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
     }
 ```
 

package/chains.cjs

@@ -302,6 +302,10 @@ defineChain({
                 confirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: false,
+            destination: false,
+        },
     },
 });
 
@@ -335,6 +339,10 @@ defineChain({
                 confirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: false,
+            destination: false,
+        },
     },
 });
 
@@ -394,6 +402,10 @@ const ArcTestnet = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -438,6 +450,10 @@ const Arbitrum = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -482,6 +498,10 @@ const ArbitrumSepolia = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -526,6 +546,10 @@ const Avalanche = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -569,6 +593,10 @@ const AvalancheFuji = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     rpcEndpoints: ['https://api.avax-test.network/ext/bc/C/rpc'],
     kitContracts: {
@@ -614,6 +642,10 @@ const Base = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -658,6 +690,10 @@ const BaseSepolia = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -744,6 +780,10 @@ const Codex = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: false,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -782,6 +822,10 @@ const CodexTestnet = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: false,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -826,6 +870,10 @@ const Ethereum = defineChain({
                 fastConfirmations: 2,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -870,6 +918,10 @@ const EthereumSepolia = defineChain({
                 fastConfirmations: 2,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -956,6 +1008,10 @@ const HyperEVM = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -995,6 +1051,10 @@ const HyperEVMTestnet = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -1038,6 +1098,10 @@ const Ink = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -1080,6 +1144,10 @@ const InkTestnet = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -1118,6 +1186,10 @@ const Linea = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -1156,6 +1228,10 @@ const LineaSepolia = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -1196,6 +1272,10 @@ const Monad = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -1236,6 +1316,10 @@ const MonadTestnet = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -1317,6 +1401,10 @@ defineChain({
                 confirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: false,
+            destination: false,
+        },
     },
 });
 
@@ -1349,6 +1437,10 @@ defineChain({
                 confirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: false,
+            destination: false,
+        },
     },
 });
 
@@ -1390,6 +1482,10 @@ const Optimism = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -1434,6 +1530,10 @@ const OptimismSepolia = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -1474,6 +1574,10 @@ const Plume = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: false,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -1513,6 +1617,10 @@ const PlumeTestnet = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: false,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -1603,6 +1711,10 @@ const Polygon = defineChain({
                 fastConfirmations: 13,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -1647,6 +1759,10 @@ const PolygonAmoy = defineChain({
                 fastConfirmations: 13,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -1687,6 +1803,10 @@ const Sei = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -1726,6 +1846,10 @@ const SeiTestnet = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -1764,6 +1888,10 @@ const Sonic = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -1802,6 +1930,10 @@ const SonicTestnet = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -1845,6 +1977,10 @@ const Solana = defineChain({
                 fastConfirmations: 3,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: false,
+        },
     },
     kitContracts: {
         bridge: 'DFaauJEjmiHkPs1JG89A4p95hDWi9m9SAEERY1LQJiC3',
@@ -1887,6 +2023,10 @@ const SolanaDevnet = defineChain({
                 fastConfirmations: 3,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: false,
+        },
     },
     kitContracts: {
         bridge: 'DFaauJEjmiHkPs1JG89A4p95hDWi9m9SAEERY1LQJiC3',
@@ -1970,6 +2110,10 @@ defineChain({
                 confirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: false,
+            destination: false,
+        },
     },
 });
 
@@ -2003,6 +2147,10 @@ defineChain({
                 confirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: false,
+            destination: false,
+        },
     },
 });
 
@@ -2024,7 +2172,7 @@ const Unichain = defineChain({
     chainId: 130,
     isTestnet: false,
     explorerUrl: 'https://unichain.blockscout.com/tx/{hash}',
-    rpcEndpoints: ['https://rpc.unichain.org', 'https://mainnet.unichain.org'],
+    rpcEndpoints: ['https://mainnet.unichain.org'],
     eurcAddress: null,
     usdcAddress: '0x078D782b760474a361dDA0AF3839290b0EF57AD6',
     cctp: {
@@ -2044,6 +2192,10 @@ const Unichain = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -2088,6 +2240,10 @@ const UnichainSepolia = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -2114,7 +2270,7 @@ const WorldChain = defineChain({
     explorerUrl: 'https://worldscan.org/tx/{hash}',
     rpcEndpoints: ['https://worldchain-mainnet.g.alchemy.com/public'],
     eurcAddress: null,
-    usdcAddress: '0x79A02482A880bCe3F13E09da970dC34dB4cD24D1',
+    usdcAddress: '0x79A02482A880bCE3F13e09Da970dC34db4CD24d1',
     cctp: {
         domain: 14,
         contracts: {
@@ -2126,6 +2282,10 @@ const WorldChain = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -2167,6 +2327,10 @@ const WorldChainSepolia = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: true,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
@@ -2193,7 +2357,7 @@ const XDC = defineChain({
     chainId: 50,
     isTestnet: false,
     explorerUrl: 'https://xdcscan.io/tx/{hash}',
-    rpcEndpoints: ['https://erpc.xinfin.network'],
+    rpcEndpoints: ['https://erpc.xdcrpc.com', 'https://erpc.xinfin.network'],
     eurcAddress: null,
     usdcAddress: '0xfA2958CB79b0491CC627c1557F441eF849Ca8eb1',
     cctp: {
@@ -2207,6 +2371,10 @@ const XDC = defineChain({
                 fastConfirmations: 3,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: false,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
@@ -2245,6 +2413,10 @@ const XDCApothem = defineChain({
                 fastConfirmations: 1,
             },
         },
+        forwarderSupported: {
+            source: true,
+            destination: false,
+        },
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,