Stellar CCTP

Official implementation of Circle's Cross-Chain Transfer Protocol (CCTP) smart contracts for Stellar.

Overview

Cross-Chain Transfer Protocol (CCTP) is a permissionless on-chain utility that facilitates the transfer of USDC between blockchain networks. This repository contains the official Stellar implementation of CCTP smart contracts, enabling secure and efficient cross-chain USDC transfers between Stellar and other supported blockchains.

Key Features

• Native Cross-Chain Transfers: Burn USDC on the source chain and mint native USDC on the destination chain
• Permissionless: Anyone can transfer USDC cross-chain using CCTP
• Attestation-Based Security: Leverages Circle's attestation service for secure message verification
• Composable: Integrate cross-chain USDC transfers directly into your smart contracts
• Soroban Implementation: Built using Soroban, Stellar's native smart contract platform

Architecture

CCTP on Stellar consists of three main contracts:

1. Message Transmitter V2

• Handles cross-chain message transmission and verification
• Manages attestation validation and message replay prevention
• Ensures message authenticity through signature verification
• Controls attester management and signature thresholds

2. Token Messenger Minter V2

• Manages USDC burning on source chains and minting on destination chains
• Controls token pairs between local and remote domains
• Enforces burn limits and transfer controls
• Handles fee collection and decimal conversion between chains
• Manages remote token messenger mappings

3. CCTP Forwarder

• Provides hook-based message forwarding for composable integrations
• Enables post-mint token forwarding to specified recipients
• Validates CCTP messages and burn message versions

Getting Started

Prerequisites

• Rust - The project uses the Rust version specified in rust-toolchain.toml
• Stellar CLI (optional, for deployment)
• Node.js (for running scripts)

The Rust toolchain, including rustfmt and clippy, will be automatically installed based on the rust-toolchain.toml file when you run cargo commands.

Installation

1. Clone the repository with submodules

   git clone --recurse-submodules <repository-url>
   cd stellar-cctp

   If you already cloned without submodules:

   git submodule update --init --recursive

2. Set up pre-commit hooks (recommended)

   git config core.hooksPath .githooks

Usage

Building Contracts

# Build all contracts
cargo build --target wasm32v1-none --release

Testing

# Run all unit tests
cargo test --all-features --workspace

Code Quality

# Format code
cargo fmt

# Run linter
cargo clippy --all-targets --all-features -- --deny warnings

Test Coverage

This project uses cargo-llvm-cov for measuring test coverage:

# Install coverage tool
cargo install cargo-llvm-cov

# Run coverage
cargo cov

# Generate HTML report
cargo cov-html

Project Structure

stellar-cctp/
├── contracts/
│   ├── message-transmitter/        # Message transmission and attestation (v1)
│   ├── message-transmitter-v2/     # Message transmission and attestation (v2)
│   ├── token-messenger-minter/     # Token burning and minting (v1)
│   ├── token-messenger-minter-v2/  # Token burning and minting (v2)
│   └── cctp-forwarder/             # Hook-based message forwarding
├── packages/
│   ├── cctp-interfaces/            # Contract interfaces (MessageHandler, Receiver, Relayer)
│   ├── cctp-roles/                 # CCTP-specific roles (Attestable, TokenController, etc.)
│   ├── cctp-utils/                 # Message parsing and construction utilities
│   └── test-contracts/             # Mock contracts for testing
└── scripts/                        # Deployment and admin scripts
    ├── clients/                    # Generated TypeScript bindings
    └── stablecoin-xlm/             # Git submodule
        └── soroban/
            ├── contracts/
            │   └── fiat-token-admin/   # Fiat token admin contract
            └── packages/
                ├── common-roles/       # Shared role implementations
                ├── stablecoin-roles/   # Stablecoin-specific roles
                └── ...                 # Other shared packages

Submodules

This project uses the stablecoin-xlm repository as a git submodule to share the fiat-token-admin contract and related packages.

Updating Submodules

# Update to latest commit
git submodule update --remote stablecoin-xlm

Troubleshooting

Submodule Issues

Problem: Commands from the scripts folder fail to execute and exit with an error.

Solution:

git submodule update --init --recursive

Problem: Submodule directory exists but is empty

Solution:

git submodule sync
git submodule update --init --recursive

Build Issues

Problem: cargo build fails with package version conflicts

Solution:

cargo clean
rm Cargo.lock
cargo build --target wasm32v1-none --release

Security

Security is our top priority. If you discover a security vulnerability, please follow our Security Policy

Resources

• CCTP Documentation
• Circle Developer Hub
• Stellar Documentation
• Soroban Documentation

License

This project is licensed under the Apache License, Version 2.0 - see the LICENSE file for details.