> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/circlefin/evm-cctp-contracts/llms.txt
> Use this file to discover all available pages before exploring further.
# Changelog
> Version history and release notes for EVM CCTP Contracts
## Version 2 (V2)
V2 represents a major upgrade to the CCTP protocol with significant new features and enhancements.
### Major Features
V2 introduces a flexible fee system for cross-chain transfers:
* Protocol fees configurable via `minFee` parameter
* Fees paid in the same token being transferred
* Separate `feeRecipient` role receives collected fees
* `minFeeController` role for managing fee structure
* Dynamic fee calculation based on transfer amount
* Fee validation during deposit operations
**New functions:**
* `getMinFeeAmount(amount)`: Calculate minimum required fee
* `setMinFee(newMinFee)`: Update minimum fee percentage
* `setFeeRecipient(newFeeRecipient)`: Update fee recipient
Execute custom logic on the destination chain after minting:
* `depositForBurnWithHook()` function with `hookData` parameter
* Enables complex cross-chain workflows
* Hook data passed through message and executed after mint
* Support for DeFi integrations, automatic swaps, and more
* Flexible hook data encoding for custom use cases
**Use cases:**
* Automatic token swaps after receiving USDC
* Depositing into lending protocols
* Multi-step cross-chain operations
* Integration with existing DeFi strategies
Configurable finality levels for different security/speed trade-offs:
* **Finalized** (2000+): Full block finality, highest security
* **Confirmed** (1000-1999): Strong confirmation, balanced approach
* **Unfinalized** (500-999): Faster execution, requires fees
**Message fields:**
* `minFinalityThreshold`: Sender's requested finality level
* `finalityThresholdExecuted`: Actual finality at attestation time
**Benefits:**
* Faster transfers for time-sensitive applications
* Flexibility to choose security vs. speed
* Fee incentives for accepting lower finality
Address denylist functionality for regulatory compliance:
* `Denylistable` contract with denylist management
* Separate `denylister` role for operational flexibility
* Checks both `msg.sender` and `tx.origin`
* Prevents denylisted addresses from initiating transfers
**New functions:**
* `denylist(account)`: Add address to denylist
* `unDenylist(account)`: Remove address from denylist
* `isDenylisted(account)`: Check denylist status
* `updateDenylister(newDenylister)`: Update denylister role
**Events:**
* `Denylisted(address indexed account)`
* `UnDenylisted(address indexed account)`
* `DenylisterChanged(address indexed oldDenylister, address indexed newDenylister)`
Deterministic contract addresses across chains:
* `Create2Factory` for deterministic deployments
* Same contract addresses on all chains
* Simplified integration and configuration
* Predictable address calculation before deployment
**Components:**
* Create2Factory contract with owner controls
* Implementation contracts deployed via CREATE2
* Proxy contracts with deterministic addresses
* Salt-based addressing scheme
**Benefits:**
* Easier multi-chain integration
* Reduced configuration complexity
* Single address for all chains
* Advance address reservation
### Enhanced Message Format
V2 uses an updated message format (version 1) with additional fields:
**New fields:**
* `destinationCaller`: Authorized caller on destination (V1 had separate function)
* `minFinalityThreshold`: Requested finality level
* `finalityThresholdExecuted`: Actual finality at execution
* `maxFee`: Maximum fee sender willing to pay
* `feeExecuted`: Actual fee charged
* `expirationBlock`: Optional message expiration
* `hookData`: Optional data for hook execution
**Message structure:**
```
Field Bytes Type Index
version 4 uint32 0
sourceDomain 4 uint32 4
destinationDomain 4 uint32 8
nonce 32 bytes32 12
sender 32 bytes32 44
recipient 32 bytes32 76
destinationCaller 32 bytes32 108
minFinalityThreshold 4 uint32 140
finalityThresholdExecuted 4 uint32 144
messageBody dynamic bytes 148
```
### Interface Changes
**New/Modified functions:**
* `depositForBurn()`: Added `destinationCaller`, `maxFee`, `minFinalityThreshold` parameters
* `depositForBurnWithHook()`: New function with `hookData` parameter
* `handleReceiveUnfinalizedMessage()`: New handler for unfinalized messages
* `handleReceiveFinalizedMessage()`: Separate handler for finalized messages
* `getMinFeeAmount()`: Calculate minimum fee for an amount
**Removed functions:**
* `depositForBurnWithCaller()`: Unified into `depositForBurn` with `destinationCaller` param
**New/Modified functions:**
* `sendMessage()`: Added `destinationCaller` and `minFinalityThreshold` parameters
* Message format version changed from 0 to 1
**Enhanced validation:**
* Destination caller validation
* Finality threshold checks
* Message version validation
**Fee-aware minting:**
* `mint()`: Now handles fee deduction
* Separate minting for recipient and fee recipient
* Fee validation and calculation
### Deployment Process
V2 introduces a multi-step deployment process:
1. **Deploy Create2Factory**: One-time factory deployment
2. **Deploy Implementation Contracts**: MessageTransmitterV2, TokenMessengerV2, TokenMinterV2
3. **Deploy Proxy Contracts**: Using CREATE2 for deterministic addresses
4. **Setup Remote Resources**: Configure cross-chain connections
5. **Key Rotation** (Mainnet only): Transfer ownership to production keys
See the [V2 deployment documentation](/v2/deployment) for detailed instructions.
### Migration Considerations
V1 and V2 are not directly compatible. Messages created with V1 cannot be received by V2 contracts and vice versa.
**Key differences:**
* Different message versions (0 vs 1)
* Incompatible message formats
* Different function signatures
* Additional parameters required
**Migration strategy:**
* Both versions can coexist on the same chain
* Plan phased migration for existing integrations
* Update client code to support V2 message format
* Test thoroughly on testnets before production migration
***
## Version 1 (V1)
### Initial Release Features
V1 established the foundational CCTP protocol:
* `TokenMessenger`: Manages deposits and minting
* `MessageTransmitter`: Handles cross-chain message passing
* `TokenMinter`: Controls token minting and burning
* Burn tokens on source chain
* Attestation service signing
* Mint tokens on destination chain
Initial message format with essential fields:
```
Field Bytes Type Index
version 4 uint32 0
sourceDomain 4 uint32 4
destinationDomain 4 uint32 8
nonce 32 bytes32 12
sender 32 bytes32 44
recipient 32 bytes32 76
destinationCaller 32 bytes32 108
messageBody dynamic bytes 140
```
Secure administrative role system:
* **Owner**: Full administrative control with two-step transfer
* **Pauser**: Emergency pause/unpause capability
* **Rescuer**: Rescue accidentally sent tokens
* **Attester Manager**: Manage attesters and signature threshold
* **Token Controller**: Manage token minting permissions
Based on OpenZeppelin's Ownable pattern with security enhancements.
Decentralized attestation mechanism:
* Multiple attester nodes operated by Circle
* Threshold signature requirement (e.g., 2-of-3)
* Attester enable/disable functionality
* Configurable signature threshold
* Replay protection via nonce tracking
Emergency stop mechanism:
* Pauser role can pause contract operations
* Protects against attacks or bugs
* Affects all state-changing functions
* View functions remain operational
* Quick resume capability via unpause
Protect user funds:
* Rescuer role can withdraw accidentally sent tokens
* Prevents permanent loss of funds
* Separate from owner role for security
* Cannot rescue USDC (only accidentally sent tokens)
### V1 Functions
**TokenMessenger:**
* `depositForBurn()`: Basic burn and transfer
* `depositForBurnWithCaller()`: Burn with restricted destination caller
* `handleReceiveMessage()`: Process incoming messages and mint
* `addRemoteTokenMessenger()`: Register remote chain
* `removeRemoteTokenMessenger()`: Unregister remote chain
**MessageTransmitter:**
* `sendMessage()`: Send cross-chain message
* `receiveMessage()`: Receive and validate message
* `enableAttester()`: Add new attester
* `disableAttester()`: Remove attester
* `setSignatureThreshold()`: Update signature requirement
**TokenMinter:**
* `mint()`: Mint tokens to recipient
* `burn()`: Burn tokens from address
* `addLocalTokenMessenger()`: Register local messenger
* `setMaxBurnAmountPerMessage()`: Set burn limits
***
## Upgrade Path
For projects looking to upgrade from V1 to V2:
1. **Assess V2 features**: Determine which V2 features benefit your use case
2. **Test on testnets**: Thoroughly test V2 integration on testnets
3. **Update contracts**: Modify integration contracts for V2 message format
4. **Update client code**: Update frontend/backend to use V2 functions
5. **Deploy to mainnet**: Deploy V2 integration after thorough testing
6. **Gradual migration**: Consider supporting both V1 and V2 during transition
Both V1 and V2 contracts can operate simultaneously on the same chain, allowing for gradual migration strategies.
## Additional Resources
Deploy V1 or V2 contracts
Version comparison and feature questions