@circle-fin/provider-cctp-v2 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -0,0 +1,100 @@
+# @circle-fin/provider-cctp-v2
+
+## 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.

package/README.md

@@ -232,8 +232,10 @@ const destAdapter = new ViemAdapter({
 // Monitor transfer events
 kit.on('*', (event) => console.log('Event:', event)) // subscribe to all events
 kit.on('approve', (event) => console.log('Approval:', event.values.txHash))
-kit.on('depositForBurn', (event) => console.log('Burn:', event.values.txHash))
-kit.on('attestation', (event) => console.log('Burn:', event.attestation))
+kit.on('burn', (event) => console.log('Burn:', event.values.txHash))
+kit.on('fetchAttestation', (event) =>
+  console.log('Attestation:', event.values.data),
+)
 kit.on('mint', (event) => console.log('Mint:', event.values.txHash))
 
 // Execute transfer