@circle-fin/provider-cctp-v2 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @circle-fin/provider-cctp-v2
 
+## 1.4.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.3.1
+
+### Patch Changes
+
+- Fix for native token balance validation fails for Gas Station–enabled wallets when either the source or destination chain has zero native token balance
+
 ## 1.3.0
 
 ### Minor Changes

package/README.md

@@ -27,18 +27,14 @@ _Native USDC bridging across 34 chains using Circle's battle-tested protocols._
   - [Supported Chains \& Routes](#supported-chains--routes)
     - [Mainnet Chains](#mainnet-chains)
     - [Testnet Chains](#testnet-chains)
-  - [Usage Examples](#usage-examples)
-    - [Basic Bridge Operation](#basic-bridge-operation)
-    - [Route Validation](#route-validation)
-    - [Bridge Configurations](#bridge-configurations)
   - [Error Handling](#error-handling)
   - [Bridge Process](#bridge-process)
+  - [Forwarder Integration](#forwarder-integration)
+    - [Standard Bridge with Forwarder](#standard-bridge-with-forwarder)
+    - [Forwarder-Only Destination](#forwarder-only-destination)
+    - [Relay Fee Handling](#relay-fee-handling)
   - [Integration with Bridge Kit](#integration-with-bridge-kit)
-  - [API Reference](#api-reference)
-    - [Core Methods](#core-methods)
-    - [Transfer Parameters](#transfer-parameters)
   - [Development](#development)
-  - [Contributing](#contributing)
   - [License](#license)
 
 ## Overview
@@ -137,6 +133,8 @@ const result = await provider.bridge({
 - ✅ **Multi-chain support** - Works across all 34 CCTPv2-supported chains
 - ✅ **Type safety** - Full TypeScript support with detailed error handling
 - ✅ **Bridge speeds** - Support for both FAST and SLOW bridge configurations
+- ✅ **Forwarder integration** - Circle's Orbit relayer handles attestation and mint automatically
+- ✅ **Forwarder-only destinations** - No destination adapter required
 
 ## Supported Chains & Routes
 
@@ -163,7 +161,7 @@ const params = {
 }
 
 try {
-  const result = await kit.bridge(params)
+  const result = await provider.bridge(params)
 
   if (result.state === 'success') {
     console.log('Bridge completed successfully!')
@@ -199,6 +197,92 @@ The CCTPv2 provider handles the complete cross-chain bridging flow:
 
 Each step is tracked and can be monitored through the Provider's event system. Transaction details for each step include explorer URLs for easy verification on block explorers.
 
+> **With Forwarder**: When `useForwarder: true`, the destination mint submission is handled by
+> Circle's Orbit relayer, and relay fees are deducted from the minted amount.
+
+## Forwarder Integration
+
+The CCTPv2 provider supports Circle's Orbit relayer for automated attestation and mint handling.
+When enabled, the relayer automatically fetches the attestation and submits the mint transaction,
+eliminating the need for the user to manage the destination chain transaction.
+
+You can check forwarder route support explicitly:
+
+```typescript
+const canForward = provider.supportsRoute(
+  'Ethereum,
+  'Base,
+  'USDC',
+  true,
+)
+```
+
+### Standard Bridge with Forwarder
+
+Use `useForwarder: true` when you have adapters for both chains but want Circle to handle the mint:
+
+```typescript
+const result = await kit.bridge({
+  from: { adapter: sourceAdapter, chain: 'Ethereum' },
+  to: {
+    adapter: destAdapter,
+    chain: 'Base',
+    useForwarder: true, // Circle handles attestation + mint
+  },
+  amount: '100.50',
+})
+```
+
+### Forwarder-Only Destination
+
+When you don't have access to the destination chain (no wallet/adapter), use forwarder-only mode.
+This is useful for server-side transfers or when users don't have a wallet on the destination chain:
+
+```typescript
+const result = await kit.bridge({
+  from: { adapter: sourceAdapter, chain: 'Ethereum' },
+  to: {
+    recipientAddress: '0x...', // Where to receive USDC
+    chain: 'Base',
+    useForwarder: true, // Required for forwarder-only
+  },
+  amount: '100.50',
+})
+```
+
+**Key differences from standard bridging:**
+
+- No destination adapter required
+- Mint confirmation via IRIS API (not on-chain receipt)
+- Mint step's `data` field will be `undefined`
+
+### Relay Fee Handling
+
+When using the forwarder, a relay fee is automatically included in the `maxFee` estimate:
+
+- The relay fee is fetched from Circle's API based on source/destination chains
+- Fee is deducted from the minted USDC at mint time
+- Net received amount = burn amount - relay fee
+
+The fee estimation accounts for this automatically:
+
+```typescript
+const estimate = await provider.estimate({
+  from: { adapter: sourceAdapter, chain: 'Ethereum' },
+  to: {
+    recipientAddress: '0x...',
+    chain: 'Base',
+    useForwarder: true,
+  },
+  amount: '100.50',
+})
+
+console.log(estimate.fees) // Includes both provider and forwarder fee entries
+```
+
+> If you provide `config.maxFee` manually, ensure it already includes any expected
+> forwarder fee for the selected route and speed.
+
 ## Integration with Bridge Kit
 
 This provider is designed specifically for the [Bridge Kit](https://www.npmjs.com/package/@circle-fin/bridge-kit):