@circle-fin/provider-cctp-v2 1.8.5 → 1.9.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @circle-fin/provider-cctp-v2
 
+## 1.9.0
+
+### Minor Changes
+
+- Add support for bridging USDC to and from Cronos (mainnet and testnet) via CCTP v2.
+- Add a `headers` config option to forward custom HTTP headers with CCTP
+  attestation API requests.
+
+  `CCTPV2Config`, `BridgeKitConfig`, and the AppKit context now accept an optional
+  `headers` map. The headers are sent with every Circle attestation (Iris) API
+  request the CCTP v2 provider makes — attestation fetch, re-attestation, and
+  relayer mint status polling — and are merged on top of the SDK defaults (such
+  as `Content-Type`) rather than replacing them.
+
+### Patch Changes
+
+- Fix transactions failing with an out-of-gas error on chains that enforce the
+  EIP-7623 calldata gas floor (e.g. Cronos). Bridge transactions on affected
+  chains now use a safe minimum gas limit automatically — no configuration
+  change needed.
+- Fix a missing runtime dependency (`pino`) that could cause `Could not find package`
+  errors under strict module resolvers (Deno, Supabase Edge Runtime, pnpm).
+
 ## 1.8.5
 
 ### Patch Changes
@@ -109,6 +132,7 @@
   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
@@ -123,6 +147,7 @@
     capability checks.
 
   Compatibility:
+
   - Existing non-forwarded bridge flows remain unchanged.
   - If you set `config.maxFee` manually, include any expected forwarding fee.
 
@@ -144,6 +169,7 @@
 ### Minor Changes
 
 - Add attestation expiry detection utilities for CCTP v2 fast transfers:
+
   - `isAttestationExpired(attestation, currentBlockNumber)` - Check if an attestation has expired based on the destination chain's current block/slot
   - `getBlocksUntilExpiry(attestation, currentBlockNumber)` - Get the number of blocks remaining until expiry (returns `null` for attestations that never expire)
   - `isMintFailureRelatedToAttestation(error)` - Detect if a mint failure was caused by attestation expiry to know when to call `reAttest()`
@@ -171,6 +197,7 @@
 ### Patch Changes
 
 - Improved how the retry function handles bridge transfers stuck in a pending state:
+
   - The retry function now properly waits for pending transactions to complete before continuing with the next steps, instead of failing or skipping them
   - Validates that required data (like transaction hashes) is present before attempting to continue, throwing clear errors immediately instead of failing silently
   - Error messages now clearly indicate when "user action is required" for non-actionable states
@@ -180,6 +207,7 @@
 - Validation errors now use standardized error codes for consistent error handling. All validation failures return the same `KitError` structure as other SDK errors.
 
   **Migration:** If you're catching validation errors, update your error handling:
+
   - Check `error.code === 1098` instead of `instanceof ValidationError`
   - Access details via `error.cause?.trace?.validationErrors` instead of `error.errors`
 
@@ -197,6 +225,7 @@
 - Fixed bug where tokens could be burned when bridging to unsupported chains, and improved error messages to clearly show which chains are supported.
 
   **What's Fixed:**
+
   - **Prevents fund loss**: Bridge operations now fail immediately if your adapter doesn't support the source or destination chain, **before** any tokens are approved or burned. Previously, tokens could be burned on the source chain before discovering the destination chain was unsupported, requiring manual recovery.
   - **Better error messages**: When you attempt to use an unsupported chain, the error now clearly lists all chains your adapter supports, making it easy to pick an alternative:
     ```
@@ -208,6 +237,7 @@
 - Improved error handling with more informative and consistent error messages.
 
   Errors now include:
+
   - Specific error codes for programmatic handling
   - Error type categorization (BALANCE, ONCHAIN, RPC, NETWORK)
   - Recoverability information (FATAL vs RETRYABLE)
@@ -231,6 +261,7 @@
 - Fixes a bug where custom recipient addresses were not respected in cross-chain USDC transfers. Previously, when using `recipientAddress` to specify a different destination address than the signer (common in custody solutions or when bridging to third-party addresses), the provider would incorrectly use the signer's address as the mint recipient, causing transfers to fail or mint to the wrong address.
 
   With this fix, the provider now correctly uses `recipientAddress` when provided, while still using the signer's address for transaction authorization. This enables:
+
   - **Third-party transfers**: Bridge USDC to any address without requiring them to sign
   - **Custody integrations**: Separate signing authority from fund destination
   - **Developer-controlled flows**: API-based signers can bridge to user-specified recipients
@@ -251,6 +282,7 @@
 - Update Sonic Testnet chain definition to canonical network. The `SonicTestnet` chain definition now points to the official Sonic Testnet (chainId: 14601) instead of the deprecated Sonic Blaze Testnet (chainId: 57054). The RPC endpoint has been updated to `https://rpc.testnet.soniclabs.com`, the display name simplified to "Sonic Testnet", and the USDC contract address updated to the new deployment.
 
   **Breaking Changes:**
+
   - **Chain ID:** 57054 → 14601
   - **RPC Endpoint:** `https://rpc.blaze.soniclabs.com` → `https://rpc.testnet.soniclabs.com`
   - **USDC Address:** `0xA4879Fed32Ecbef99399e5cbC247E533421C4eC6` → `0x0BA304580ee7c9a980CF72e55f5Ed2E9fd30Bc51`
@@ -266,6 +298,7 @@
   Circle's Cross-Chain Transfer Protocol (CCTP) v2 integration - the primary transport layer for secure, native USDC transfers across supported blockchain networks.
 
   ## 🚀 Core CCTP Features
+
   - **Native USDC Bridging**: Direct integration with Circle's official CCTP v2 protocol
   - **Multi-chain Support**: Seamless transfers between EVM chains and Solana
   - **Attestation Management**: Automatic handling of Circle's attestation service
@@ -273,12 +306,14 @@
   ## ⚡ Transfer Speed Options
 
   **FAST Transfers**
+
   - Optimized for speed with Circle's fast liquidity network
   - Dynamic fee calculation based on transfer amount and network conditions
   - Automatic fee estimation with 10% buffer for fluctuations
   - Typical completion time: ~1 minute
 
   **SLOW Transfers**
+
   - Zero protocol fees for cost-optimized transfers
   - Standard CCTP attestation flow
   - Typical completion time: 10-20 minutes
@@ -302,18 +337,21 @@
   ```
 
   ## 🔄 Advanced Retry Support
+
   - **Step-by-step Recovery**: Resume from burn, attestation, or mint phases
   - **Automatic State Analysis**: Intelligent detection of completion status
   - **Network Resilience**: Handle temporary API and RPC failures
   - **Transaction Resubmission**: Retry failed blockchain transactions
 
   ## 💰 Fee Management
+
   - **Dynamic Fee Calculation**: Real-time fee estimation from Circle's API
   - **Custom Fee Limits**: Set maximum fees to control costs
   - **Protocol Fee Transparency**: Clear breakdown of all fees involved
   - **Multi-chain Fee Support**: Different fee structures per chain pair
 
   ## 🛡️ Security & Reliability
+
   - **No Custom Cryptography**: Uses only Circle's audited smart contracts
   - **Deterministic Operations**: Predictable outcomes and gas estimation
   - **Comprehensive Validation**: Runtime parameter validation and type safety

package/README.md

@@ -9,7 +9,7 @@
 
 **Circle's Cross-Chain Transfer Protocol v2 provider for Bridge Kit**
 
-_Native USDC bridging across 45 chains using Circle's battle-tested protocols._
+_Native USDC bridging across 47 chains using Circle's battle-tested protocols._
 
 </div>
 
@@ -130,7 +130,7 @@ const result = await provider.bridge({
 - ✅ **Native USDC bridging** - Move real USDC between supported networks
 - ✅ **CCTP v2 integration** - Direct integration with Circle's CCTP v2 protocol
 - ✅ **Comprehensive validation** - Route validation and parameter checking
-- ✅ **Multi-chain support** - Works across all 45 CCTPv2-supported chains
+- ✅ **Multi-chain support** - Works across all 47 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
@@ -138,15 +138,15 @@ const result = await provider.bridge({
 
 ## Supported Chains & Routes
 
-The provider supports **968 total bridge routes** across these chains:
+The provider supports **1058 total bridge routes** across these chains:
 
 ### Mainnet Chains
 
-**Arbitrum**, **Avalanche**, **Base**, **Codex**, **Edge**, **Ethereum**, **HyperEVM**, **Injective**, **Ink**, **Linea**, **Monad**, **Morph**, **OP Mainnet**, **Pharos**, **Plume**, **Polygon PoS**, **Sei**, **Solana**, **Sonic**, **Unichain**, **World Chain**, **XDC**
+**Arbitrum**, **Avalanche**, **Base**, **Codex**, **Cronos**, **Edge**, **Ethereum**, **HyperEVM**, **Injective**, **Ink**, **Linea**, **Monad**, **Morph**, **OP Mainnet**, **Pharos**, **Plume**, **Polygon PoS**, **Sei**, **Solana**, **Sonic**, **Unichain**, **World Chain**, **XDC**
 
 ### Testnet Chains
 
-**Arc Testnet**, **Arbitrum Sepolia**, **Avalanche Fuji**, **Base Sepolia**, **Codex Testnet**, **Edge Testnet**, **Ethereum Sepolia**, **HyperEVM Testnet**, **Injective Testnet**, **Ink Testnet**, **Linea Sepolia**, **Monad Testnet**, **Morph Testnet**, **OP Sepolia**, **Pharos Atlantic**, **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**, **Cronos Testnet**, **Edge Testnet**, **Ethereum Sepolia**, **HyperEVM Testnet**, **Injective Testnet**, **Ink Testnet**, **Linea Sepolia**, **Monad Testnet**, **Morph Testnet**, **OP Sepolia**, **Pharos Atlantic**, **Plume Testnet**, **Polygon PoS Amoy**, **Sei Testnet**, **Solana Devnet**, **Sonic Testnet**, **Unichain Sepolia**, **World Chain Sepolia**, **XDC Apothem**
 
 ## Error Handling