# CCTPv2 Bridging Provider
[](https://badge.fury.io/js/@circle-fin%2Fprovider-cctp-v2)
[](https://www.typescriptlang.org/)
[](https://opensource.org/licenses/Apache-2.0)
[](https://discord.com/invite/buildoncircle)
**Circle's Cross-Chain Transfer Protocol v2 provider for Bridge Kit**
_Native USDC bridging across 45 chains using Circle's battle-tested protocols._
## Table of Contents
- [CCTPv2 Bridging Provider](#cctpv2-bridging-provider)
- [Table of Contents](#table-of-contents)
- [Overview](#overview)
- [Why CCTPv2 Provider?](#why-cctpv2-provider)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Option 1: With Bridge Kit (Recommended)](#option-1-with-bridge-kit-recommended)
- [Option 2: Direct Provider Usage](#option-2-direct-provider-usage)
- [Features](#features)
- [Supported Chains \& Routes](#supported-chains--routes)
- [Mainnet Chains](#mainnet-chains)
- [Testnet Chains](#testnet-chains)
- [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)
- [Development](#development)
- [License](#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 41+ supported blockchain networks.
While primarily designed to power the [Bridge Kit](https://www.npmjs.com/package/@circle-fin/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
- **⚡ 41 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
```bash
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](https://www.npmjs.com/package/@circle-fin/bridge-kit). You can import this provider if you need to do a custom CCTP integration.
## Quick Start
### Option 1: With Bridge Kit (Recommended)
```typescript
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
```typescript
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 45 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 **968 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**
### 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**
## Error Handling
The provider implements thoughtful error handling for different scenarios:
```typescript
// 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:
```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):
```typescript
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.
```bash
# 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](https://help.circle.com/s/submit-ticket) for details.
---
**Ready for cross-chain bridging?**
[Join Discord](https://discord.com/invite/buildoncircle) •
[Visit our Help-Desk](https://help.circle.com/s/submit-ticket)
_Built with ❤️ by Circle_