CCTPv2 Bridging Provider

Table of Contents

• CCTPv2 Bridging Provider
  • Table of Contents
  • Overview
    • Why CCTPv2 Provider?
  • Installation
  • Quick Start
    • Option 1: With Bridge Kit (Recommended)
    • Option 2: Direct Provider Usage
  • Features
  • Supported Chains & Routes
    • Mainnet Chains
    • Testnet Chains
  • Error Handling
  • Bridge Process
  • Forwarder Integration
    • Standard Bridge with Forwarder
    • Forwarder-Only Destination
    • Relay Fee Handling
  • Integration with Bridge Kit
  • Development
  • License

Overview

The CCTPv2 Bridging Provider is a strongly-typed implementation of Circle's Cross-Chain Transfer Protocol (CCTP) version 2 that enables native USDC bridging between 49 supported blockchain networks.

While primarily designed to power the Bridge Kit, this provider can also be used directly in applications that need fine-grained control over the CCTP transfer process or want to integrate CCTP without the full App Kits framework.

Why CCTPv2 Provider?

• 🔒 Circle's official protocol: Uses Circle's native CCTP infrastructure for maximum security
• ⚡ 51 chain support: Enables bridging across all CCTPv2-supported networks
• 🎯 Native USDC: Bridges actual USDC tokens, not wrapped or synthetic versions
• 🔧 Type-safe operations: Built with TypeScript strict mode and comprehensive validation
• 🛠️ Direct integration: Use standalone or with custom orchestration logic

Installation

npm install @circle-fin/provider-cctp-v2
# or
yarn add @circle-fin/provider-cctp-v2

Note: This provider is included by default with the Bridge Kit. You can import this provider if you need to do a custom CCTP integration.

Quick Start

Option 1: With Bridge Kit (Recommended)

import { BridgeKit } from '@circle-fin/bridge-kit'

// Provider included by default
const kit = new BridgeKit()

const result = await kit.bridge({
  from: { adapter: sourceAdapter, chain: 'Ethereum' },
  to: { adapter: destAdapter, chain: 'Base' },
  amount: '100.50',
})

Option 2: Direct Provider Usage

import { CCTPV2BridgingProvider } from '@circle-fin/provider-cctp-v2'
import { ViemAdapter } from '@circle-fin/adapter-viem-v2'
import { createPublicClient, createWalletClient, http } from 'viem'
import { mainnet, base } from 'viem/chains'
import { privateKeyToAccount } from 'viem/accounts'

const account = privateKeyToAccount(process.env.PRIVATE_KEY)
const provider = new CCTPV2BridgingProvider()

// Create adapters
const sourceAdapter = new ViemAdapter({
  publicClient: createPublicClient({ chain: mainnet, transport: http() }),
  walletClient: createWalletClient({
    account,
    chain: mainnet,
    transport: http(),
  }),
})

const destAdapter = new ViemAdapter({
  publicClient: createPublicClient({ chain: base, transport: http() }),
  walletClient: createWalletClient({ account, chain: base, transport: http() }),
})

// Check route support
const isSupported = provider.supportsRoute('Ethereum', 'Base', 'USDC')

// Get bridge estimate
const estimate = await provider.estimate({
  from: { adapter: sourceAdapter, chain: 'Ethereum' },
  to: { adapter: destAdapter, chain: 'Base' },
  amount: '100.50',
  config: { transferSpeed: 'FAST' },
})

// Execute bridge operation with custom logic
const result = await provider.bridge({
  from: { adapter: sourceAdapter, chain: 'Ethereum' },
  to: { adapter: destAdapter, chain: 'Base' },
  amount: '100.50',
  config: { transferSpeed: 'FAST' },
})

Features

• ✅ 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 52 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

The provider supports 1300 total bridge routes across these chains:

Mainnet Chains

Arbitrum, Arc, Avalanche, Base, Codex, Cronos, Edge, Ethereum, HyperEVM, Injective, Ink, Linea, Monad, Morph, OP Mainnet, Pharos, Plasma, Plume, Polygon PoS, Sei, Solana, Sonic, Unichain, World Chain, XDC, X Layer

Testnet Chains

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, Plasma Testnet, Plume Testnet, Polygon PoS Amoy, Sei Testnet, Solana Devnet, Sonic Testnet, Unichain Sepolia, World Chain Sepolia, XDC Apothem, X Layer Testnet

Error Handling

The provider implements thoughtful error handling for different scenarios:

// Using the same kit and adapters from the examples above
const params = {
  from: { adapter: sourceAdapter, chain: 'Ethereum' },
  to: { adapter: destAdapter, chain: 'Base' },
  amount: '100.50',
}

try {
  const result = await provider.bridge(params)

  if (result.state === 'success') {
    console.log('Bridge completed successfully!')

    // Display explorer URLs for each step
    result.steps.forEach((step) => {
      if (step.explorerUrl) {
        console.log(`${step.name}: ${step.explorerUrl}`)
      }
    })
  } else {
    // Handle partial completion
    const successfulSteps = result.steps.filter((s) => s.state === 'success')
    const failedStep = result.steps.find((s) => s.state === 'error')

    console.log('Successful steps:', successfulSteps)
    console.log('Failed at:', failedStep)
  }
} catch (error) {
  // Handle validation or configuration errors
  console.error('Bridge failed:', error.message)
}

Bridge Process

The CCTPv2 provider handles the complete cross-chain bridging flow:

1. Approval - Approve USDC spending (if needed)
2. Burn - Burn USDC on source chain via depositForBurn
3. Attestation - Fetch Circle's attestation for the burn
4. Mint - Mint USDC on destination chain using attestation

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:

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:

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:

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:

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. For Solana destinations, the forwarder fee also covers creating the recipient's USDC token account.

Integration with Bridge Kit

This provider is designed specifically for the Bridge Kit:

import { BridgeKit } from '@circle-fin/bridge-kit'
import { ViemAdapter } from '@circle-fin/adapter-viem-v2'
import { createPublicClient, createWalletClient, http } from 'viem'
import { mainnet, base } from 'viem/chains'
import { privateKeyToAccount } from 'viem/accounts'

const account = privateKeyToAccount(process.env.PRIVATE_KEY)

// Provider is included by default
const kit = new BridgeKit()

const sourceAdapter = new ViemAdapter({
  publicClient: createPublicClient({ chain: mainnet, transport: http() }),
  walletClient: createWalletClient({
    account,
    chain: mainnet,
    transport: http(),
  }),
})

const destAdapter = new ViemAdapter({
  publicClient: createPublicClient({ chain: base, transport: http() }),
  walletClient: createWalletClient({ account, chain: base, transport: http() }),
})

// 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('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
const result = await kit.bridge({
  from: { adapter: sourceAdapter, chain: 'Ethereum' },
  to: { adapter: destAdapter, chain: 'Base' },
  amount: '25.0',
})

Development

This package is part of the App Kits monorepo.

# Build
nx build @circle-fin/provider-cctp-v2

# Test
nx test @circle-fin/provider-cctp-v2

License

This project is licensed under the Apache 2.0 License. Contact support for details.