Crate cctp_rs

Expand description

§cctp-rs

A production-ready Rust SDK for Circle’s Cross-Chain Transfer Protocol (CCTP).

This library provides a safe, ergonomic interface for bridging USDC across multiple blockchain networks using Circle’s CCTP infrastructure.

§Choosing an API

Task	Type
Bridge USDC (recommended)	`CctpV2Bridge`
Bridge USDC on a v1-only legacy chain	`Cctp`
Self-relay safely against permissionless relayers	`CctpV2Bridge::mint_if_needed`
Wait for any relayer (cheapest happy path)	`CctpV2Bridge::wait_for_receive`
Inspect a v2 message as serializable JSON	`ParsedV2MessageSummary`
Look up chain config without a provider	`CctpV1` / `CctpV2` traits
Drive contracts directly	`TokenMessengerV2Contract` etc.

For longer-form guidance and the full list of footguns see AGENTS.md in the repository.

§Quick Start (V2, recommended)

use cctp_rs::{CctpV2Bridge, CctpError, PollingConfig};
use alloy_chains::NamedChain;
use alloy_primitives::FixedBytes;

// V2 bridge with fast transfer support
let eth_provider = ProviderBuilder::new().connect("http://localhost:8545").await?;
let linea_provider = ProviderBuilder::new().connect("http://localhost:8546").await?;

let bridge = CctpV2Bridge::builder()
    .source_chain(NamedChain::Mainnet)
    .destination_chain(NamedChain::Linea)
    .source_provider(eth_provider)
    .destination_provider(linea_provider)
    .recipient("0x742d35Cc6634C0532925a3b844Bc9e7595f8fA0d".parse()?)
    .fast_transfer(true)  // Enable sub-30 second settlement
    .build();

// V2 uses transaction hash directly and returns both message and attestation
let burn_tx_hash = FixedBytes::from([0u8; 32]);
let (message, attestation) = bridge.get_attestation(
    burn_tx_hash,
    PollingConfig::fast_transfer(),  // Optimized for fast transfers
).await?;

§Quick Start (V1, legacy v1-only chains)

use cctp_rs::{Cctp, CctpError, PollingConfig};
use alloy_chains::NamedChain;
use alloy_primitives::FixedBytes;

// Set up providers and create bridge
let eth_provider = ProviderBuilder::new().connect("http://localhost:8545").await?;
let arb_provider = ProviderBuilder::new().connect("http://localhost:8546").await?;

let bridge = Cctp::builder()
    .source_chain(NamedChain::Mainnet)
    .destination_chain(NamedChain::Arbitrum)
    .source_provider(eth_provider)
    .destination_provider(arb_provider)
    .recipient("0x742d35Cc6634C0532925a3b844Bc9e7595f8fA0d".parse()?)
    .build();

// Get message from burn transaction, then fetch attestation
let burn_tx_hash = FixedBytes::from([0u8; 32]);
let (message, message_hash) = bridge.get_message_sent_event(burn_tx_hash).await?;
let attestation = bridge.get_attestation(message_hash, PollingConfig::default()).await?;

§Direct Contract Access

For advanced use cases, you can use the contract wrappers directly:

use cctp_rs::{TokenMessengerV2Contract, MessageTransmitterV2Contract};
use alloy_primitives::address;
use alloy_provider::ProviderBuilder;

let provider = ProviderBuilder::new().connect("http://localhost:8545").await?;
let contract_address = address!("9f3B8679c73C2Fef8b59B4f3444d4e156fb70AA5");

// Create contract wrapper
let token_messenger = TokenMessengerV2Contract::new(contract_address, provider);

§Features

Type-safe contract interactions using Alloy
Multi-chain support for mainnet and testnet networks
Comprehensive error handling with detailed error types
Builder pattern for intuitive API usage
Agent-friendly protocol inspection with serializable v2 message parsing
Extensive test coverage ensuring reliability

§Public API

AttestationResponse and AttestationStatus - Circle’s Iris API attestation types
Cctp and CctpV2Bridge - Core CCTP bridge implementations for v1 and v2
CctpV1 and CctpV2 - Traits for chain-specific configurations
PollingConfig - Configuration for attestation polling behavior
ParsedV2Message and ParsedV2MessageSummary - Parse canonical v2 messages into serializable structs
ParseMessageError - Error type for canonical v2 message parsing
InvalidDomainId and InvalidFinalityThreshold - Errors returned by TryFrom<u32> for DomainId / FinalityThreshold
CctpError and Result - Error types for error handling
Contract wrappers for direct contract interaction:
- v1: TokenMessengerContract, MessageTransmitterContract
- v2: TokenMessengerV2Contract, MessageTransmitterV2Contract
sol!-generated modules for decoding raw event logs against the canonical ABI:
- v1: TokenMessenger, MessageTransmitter
- v2: TokenMessengerV2, MessageTransmitterV2

For example, to decode a v2 DepositForBurn event log:

use cctp_rs::TokenMessengerV2::DepositForBurn;
use alloy_sol_types::SolEvent;

let _topic = DepositForBurn::SIGNATURE_HASH;
let _decoded = DepositForBurn::decode_log(log)?;

Modules§

MessageTransmitter: Generated by the following Solidity interface…
MessageTransmitterV2: Generated by the following Solidity interface…
TokenMessenger: Generated by the following Solidity interface…
TokenMessengerV2: Generated by the following Solidity interface…
spans: OpenTelemetry span helpers for CCTP operations

Structs§

AttestationResponse: Represents the response from the attestation service
BurnMessageV2: CCTP v2 Burn Message Body
Cctp: CCTP v1 bridge implementation
CctpV2Bridge: CCTP v2 bridge implementation
Erc20Contract: ERC20 contract wrapper for approval operations
InvalidDomainId: Error returned when attempting to convert an invalid u32 to a DomainId
InvalidFinalityThreshold: Error returned when attempting to convert an invalid u32 to a FinalityThreshold
MessageHeader: CCTP v2 Message Header
MessageTransmitterContract: The CCTP v1 Message Transmitter contract wrapper
MessageTransmitterV2Contract: The CCTP v2 Message Transmitter contract wrapper
ParseMessageError: Error returned when parsing a canonical CCTP v2 message fails.
ParsedV2Message: Parsed representation of a canonical CCTP v2 transfer message.
ParsedV2MessageSummary: JSON-friendly summary of a canonical CCTP v2 transfer message.
PollingConfig: Configuration for attestation polling behavior.
ProviderConfig: Configuration for creating production-ready providers.
ProviderConfigBuilder: Builder for ProviderConfig
TokenMessengerContract: The CCTP v1 Token Messenger contract wrapper
TokenMessengerV2Contract: The CCTP v2 Token Messenger contract wrapper
TokenState: Token state containing balance and allowance information.
V2AttestationResponse: Represents the response from the CCTP v2 attestation API
V2Message: Represents a single message in the v2 attestation response

Enums§

AttestationFailureKind: Categorical reasons an attestation poll can fail.
AttestationStatus: Represents the status of the attestation.
CctpError
DomainId: CCTP domain identifier for blockchain networks
FinalityThreshold: Finality threshold for CCTP v2 messages
MintResult: Result of attempting to mint on the destination chain

Constants§

CCTP_V2_MESSAGE_TRANSMITTER_MAINNET: CCTP V2 MessageTransmitter address (Mainnet)
CCTP_V2_MESSAGE_TRANSMITTER_TESTNET: CCTP V2 MessageTransmitter address (Testnet)
CCTP_V2_TOKEN_MESSENGER_MAINNET: CCTP V2 TokenMessenger address (Mainnet)
CCTP_V2_TOKEN_MESSENGER_TESTNET: CCTP V2 TokenMessenger address (Testnet)
DEFAULT_GAS_BUFFER_PERCENT: Default gas buffer percentage (20%)
DEFAULT_RETRY_ATTEMPTS: Default number of retry attempts
DEFAULT_TIMEOUT_SECS: Default request timeout in seconds

Traits§

CctpBridge: Common trait interface for CCTP bridge implementations (v1 and v2)
CctpV1: Trait for chains that support CCTP bridging
CctpV2: CCTP v2 chain configuration trait

Functions§

batch_token_state: Fetch token balance and allowance in parallel and return them as a TokenState.
calculate_gas_price_with_buffer: Helper to calculate gas price with a tip buffer for EIP-1559 transactions.
estimate_gas_with_buffer: Estimate gas for a transaction with an optional safety buffer.

Type Aliases§

AttestationBytes: The bytes of the attestation.
Result

Crate cctp_rs

Crate cctp_rs Copy item path

§cctp-rs

§Choosing an API

§Quick Start (V2, recommended)

§Quick Start (V1, legacy v1-only chains)

§Direct Contract Access

§Features

§Public API

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Crate cctp_rs