# @circle-fin/provider-cctp-v2 ## 1.8.5 ### Patch Changes - Internal dependency updates. No user-facing changes. ## 1.8.4 ### Patch Changes - Fix forwarded-route support to depend only on the destination chain. `supportsRoute(source, destination, 'USDC', true)` previously also required the source chain's `cctp.forwarderSupported.source` to be `true`. Today's Forwarding Service operates on the destination chain, so any CCTP v2 chain can originate a forwarded transfer; the route check now gates only on the destination chain's `cctp.forwarderSupported.destination`, matching the bridge execution path. `cctp.forwarderSupported.source` is now `false` for every chain definition, reflecting that source-side forwarding is not yet available. This corrects metadata that previously implied source-side forwarding was supported. Also surfaced through `@circle-fin/bridge-kit` and `@circle-fin/app-kit`. ## 1.8.3 ### Patch Changes - `bridge` no longer rejects Gas Station-enabled smart-contract accounts (SCAs) with zero native balance on the source or destination chain. EOA wallets without native funds will still fail at simulation with the underlying RPC error. ## 1.8.2 ### Patch Changes - Internal dependency updates. No user-facing changes. ## 1.8.1 ### Patch Changes - Internal dependency updates. No user-facing changes. ## 1.8.0 ### Minor Changes - Add support for bridging USDC to and from Injective (mainnet and testnet) via CCTP v2. Both networks are now available as source and destination options in Bridge Kit. ## 1.7.0 ### Minor Changes - Add support for bridging USDC to and from Pharos (mainnet and testnet) via CCTP v2. - Bridge errors now expose a machine-readable `errorCategory` so apps can distinguish user rejections, wallet capability errors, and offchain vs onchain failures without string-matching. ## 1.6.3 ### Patch Changes - Fix burn step incorrectly reporting state "success" when on-chain transaction reverts ## 1.6.2 ### Patch Changes - Bridge operations that fail due to transient RPC errors during receipt polling now automatically retry with exponential backoff instead of failing permanently - Update HyperEVM mainnet explorer URL to resolve location-restricted access issues - Improved search discoverability ## 1.6.1 ### Patch Changes - Add support for Solana as a forwarder destination ## 1.6.0 ### Minor Changes - Add support for EIP-5792 batched transactions in the bridge flow ### Patch Changes - Enable forwarder destination support for Codex, Plume, and XDC chains on both mainnet and testnet - Update HyperEVM explorer URLs to use the official Hyperliquid explorer ## 1.5.0 ### Minor Changes - Add support for bridging USDC to and from Edge and Morph networks. Both mainnet and testnet chains are now available as source and destination options in Bridge Kit. ## 1.4.1 ### Patch Changes - More accurate gas fee estimates for CCTP v2 bridge operations. ## 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 - Integrate automatic re-attestation into bridge orchestrator retry logic for CCTP v2 fast transfers: - Automatically detect mint failures due to expired attestations and trigger re-attestation flow ## 1.2.0 ### 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()` - Add native balance validation for transaction gas fees before bridge tx. ## 1.1.0 ### Minor Changes - Add `reAttest` method to `CCTPV2BridgingProvider` for handling expired attestations. When a CCTP v2 attestation expires before the mint transaction can be completed, users can now call `reAttest()` to request a fresh attestation using the original burn transaction hash. - **Enhanced bridge estimate response**: `EstimateResult` now includes `token`, `amount`, `source`, `destination` fields to provide complete transfer information alongside cost estimates. ### Patch Changes - Fix fast burn fee calculation to handle decimal basis points from IRIS API The IRIS API returns `minimumFee` as decimal basis points (e.g., `"1.3"` for 1.3 bps), but the code was attempting to convert this directly to `BigInt`, which fails for non-integer values. This caused `"Max fee must be less than amount"` errors during FAST transfers. ## 1.0.5 ### 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 - Validation errors during pending state resolution are no longer silently caught and now surface properly - Fix retry functionality when a custom `recipientAddress` is specified in bridge parameters. Previously, retry operations would fail attestation validation because the `recipientAddress` was not preserved in the bridge result, causing the system to use the adapter address instead of the originally specified recipient. - 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` The legacy `ValidationError` class remains available for backward compatibility. - **Improved retry() behavior for completed bridges** -The `retry()` method now handles completed bridge operations gracefully: Calling `retry()` on an already-completed bridge now returns successfully instead of throwing an error ## 1.0.4 ### Patch Changes - 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: ``` Invalid chain 'Linea Sepolia': Not supported by this adapter. It supports 17 chains: Arbitrum, Base, Ethereum, Polygon, Solana, ... ``` - **Correct error codes**: Chain validation errors now use the correct `INVALID_CHAIN` error code instead of `UNSUPPORTED_ROUTE`, making it easier to handle errors programmatically. - 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) - Clearer error messages with chain context - Original error details preserved for debugging - Fixed an issue where bridging USDC to Solana would fail when specifying a recipient address different from the transaction signing wallet. The adapter now correctly creates the Associated Token Account (ATA) for the specified recipient address and delivers USDC to that address. ## 1.0.3 ### Patch Changes - Improves the Solana CCTP v2 custom burn flow to ensure developer fee payouts never fail due to a missing associated token account (ATA). The instruction builder now checks for the existence of the developer fee recipient's ATA and, if absent, emits an idempotent creation instruction. ## 1.0.2 ### Patch Changes - Fix CommonJS compatibility by correcting file extensions and package exports. This resolves a "ReferenceError: require is not defined" error that occurred when using packages in CommonJS projects with ts-node. - 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 **No changes required** for existing code - the fix is backward compatible. If you don't provide `recipientAddress`, transfers work exactly as before. If you were previously experiencing failures when specifying a custom recipient, this update resolves those issues. - Improves static gas estimate values for contract calls. Updates adapters' `prepare()` method so that transaction simulation is now performed only during `execute()`, not during `estimate()`. Adds an optional fallback parameter to `estimate()` for cases where gas estimation fails. ## 1.0.1 ### Patch Changes - Standardize `maxFee` parameter to accept human-readable values. The `maxFee` parameter in `BridgeConfig` now correctly accepts human-readable token amounts (e.g., `"1"` for 1 USDC, `"0.5"` for 0.5 USDC), matching the behavior of `customFee.value`. This resolves an undocumented inconsistency in the API. If you were previously passing values in smallest units, update to human-readable format: use `"1"` instead of `"1000000"` for 1 USDC. - Add support for Arc Testnet chain definition. Arc is Circle's EVM-compatible Layer-1 blockchain designed for stablecoin finance and asset tokenization, featuring USDC as the native gas token and sub-second finality via the Malachite BFT consensus engine. - Fix bridge event dispatching in retry flow to include complete step metadata. The retry flow was incorrectly dispatching only step.data instead of the full step object, causing retry events to miss critical metadata like txHash, explorerUrl, name, and state. This change also introduces a shared dispatchStepEvent utility to eliminate code duplication between bridge and retry flows. - These changes standardize and clarifiy error handling across bridge steps, make all bridge steps only need 1 blockchain confirmation when waiting for the step transaction, refactor burn transfer speed logic for simplicity, and improve polling configuration for slow attestation fetches. - 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` **Migration:** If you were using `SonicTestnet`, your application will automatically connect to the new network upon upgrading. Any accounts, contracts, or transactions on the old Blaze testnet (chainId: 57054) will need to be recreated on the new testnet. ## 1.0.0 ### Major Changes - # CCTP v2 Provider 1.0.0 Release 🎉 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 ## ⚡ 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 ```typescript // Fast transfer with automatic fee calculation const result = await provider.bridge({ source: { adapter: sourceAdapter, chain: "Ethereum" }, destination: { adapter: destAdapter, chain: "Base" }, amount: "10.0", config: { transferSpeed: "FAST" }, }); // Slow transfer with zero fees const result = await provider.bridge({ source: { adapter: sourceAdapter, chain: "Ethereum" }, destination: { adapter: destAdapter, chain: "Base" }, amount: "10.0", config: { transferSpeed: "SLOW" }, }); ``` ## 🔄 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 - **Production Ready**: Battle-tested protocol with institutional adoption This provider implements Circle's official CCTP v2 specification, ensuring maximum security and compatibility with the broader USDC ecosystem.