> ## 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.

# Version 2 Overview

> Introduction to EVM CCTP Contracts V2 architecture and improvements

## What's New in V2

Version 2 of the EVM CCTP Contracts introduces significant enhancements to the Cross-Chain Transfer Protocol while maintaining backward compatibility in the core message transmission architecture. V2 focuses on fee mechanisms, security features, and execution flexibility.

### Key Improvements Over V1

<CardGroup cols={2}>
  <Card title="Fee Mechanism" icon="dollar-sign">
    Support for destination domain fees with configurable minimum fees and fee recipients
  </Card>

  <Card title="Finality Thresholds" icon="gauge-high">
    Messages can specify minimum finality requirements (500, 1000, or 2000) for flexible security/speed tradeoffs
  </Card>

  <Card title="Hook Execution" icon="webhook">
    Optional `hookData` parameter enables custom logic execution on the destination domain
  </Card>

  <Card title="Denylist Support" icon="ban">
    Protocol-level denylist functionality to prevent malicious actors from using the system
  </Card>
</CardGroup>

## Architectural Changes

### Contract Structure

V2 introduces a modular architecture with base contracts:

```
TokenMessengerV2
└── BaseTokenMessenger
    ├── Rescuable
    ├── Denylistable
    └── Initializable

TokenMinterV2
└── TokenMinter (V1)
    └── ... (existing hierarchy)

MessageTransmitterV2
└── BaseMessageTransmitter
    └── ... (existing hierarchy)
```

### Proxy Pattern

V2 contracts use the proxy pattern for upgradeability:

* **Implementation Contracts**: Contain all business logic
* **Proxy Contracts**: Deployed via CREATE2 for deterministic addresses across chains
* **Create2Factory**: Deploys all proxies to ensure consistent addresses

**Reference**: `src/v2/Create2Factory.sol`

### New Message Format

V2 introduces an enhanced burn message format that includes:

* **maxFee**: Maximum fee willing to pay on destination domain
* **hookData**: Optional data for hook execution
* **expirationBlock**: Message expiration (optional)

The message body version remains separate from V1 to distinguish message formats.

**Reference**: `src/messages/v2/BurnMessageV2.sol`

## Fee Mechanism

### How Fees Work

1. **Source Domain**: User specifies `maxFee` in `depositForBurn()`
2. **Minimum Fee Validation**: Contract validates `maxFee >= minFeeAmount`
3. **Destination Domain**: Actual fee is determined by relayer/broadcaster
4. **Fee Collection**: Fees are minted to the `feeRecipient` address
5. **Recipient Amount**: User receives `amount - fee`

### Fee Calculation

```solidity theme={null}
minFeeAmount = (amount * minFee) / MIN_FEE_MULTIPLIER
```

Where:

* `MIN_FEE_MULTIPLIER = 10,000,000` (enables 1/1000 basis point precision)
* `minFee` is configurable by the `minFeeController`

**Example**: If `minFee = 5000` (0.05%):

```
Amount: 1,000,000 (1 USDC)
minFeeAmount = (1,000,000 * 5000) / 10,000,000 = 500 (0.0005 USDC)
```

**Reference**: `src/v2/BaseTokenMessenger.sol:314-319`

## Finality Thresholds

V2 introduces three levels of finality:

<AccordionGroup>
  <Accordion title="Finalized (2000)" icon="shield-check">
    **Maximum Security**: Messages attested at finalized threshold provide the highest security guarantees. No fees are charged for finalized messages.

    * Use for high-value transfers
    * Longer attestation wait time
    * Zero fee requirement
  </Accordion>

  <Accordion title="Confirmed (1000)" icon="shield">
    **Balanced**: Confirmed finality provides good security with moderate wait times.

    * Suitable for most transfers
    * Moderate attestation time
    * Fees apply
  </Accordion>

  <Accordion title="Minimum (500)" icon="gauge-simple">
    **Fast Execution**: TokenMessenger accepts minimum finality of 500 for fastest execution.

    * Use for low-value or time-sensitive transfers
    * Fastest attestation time
    * Fees apply
    * Lower security guarantees
  </Accordion>
</AccordionGroup>

**Reference**: `src/v2/FinalityThresholds.sol`

## Hook Execution

V2 enables custom logic on the destination domain through the `hookData` parameter:

```solidity theme={null}
// Deposit with hook
tokenMessenger.depositForBurnWithHook(
    amount,
    destinationDomain,
    recipientAddress,
    address(usdc),
    bytes32(0),
    maxFee,
    minFinalityThreshold,
    customHookData  // Interpreted by recipient contract
);
```

### Hook Use Cases

* **Automated Swaps**: Hook data triggers DEX swap on destination
* **NFT Claims**: Hook data specifies NFT to mint after transfer
* **Conditional Transfers**: Hook data defines conditions for fund release
* **Multi-Step Workflows**: Hook data orchestrates complex operations

<Note>
  Hook data is application-specific and must be interpreted by the recipient contract or relayer on the destination domain.
</Note>

## Denylist Functionality

V2 introduces protocol-level denylist support:

* **Denylister Role**: Authorized address can add/remove denylisted addresses
* **Caller Protection**: Denylisted addresses cannot call `depositForBurn` or `depositForBurnWithHook`
* **Transparent**: Denylist is stored on-chain and publicly verifiable

```solidity theme={null}
// Add to denylist (denylister only)
tokenMessenger.addToDenylist(maliciousAddress);

// Remove from denylist (denylister only)
tokenMessenger.removeFromDenylist(address);
```

**Reference**: `src/roles/v2/Denylistable.sol`

## New Roles in V2

V2 introduces additional administrative roles:

| Role                 | Responsibilities              | V1 Equivalent |
| -------------------- | ----------------------------- | ------------- |
| **feeRecipient**     | Receives collected fees       | N/A (new)     |
| **denylister**       | Manages protocol denylist     | N/A (new)     |
| **minFeeController** | Sets minimum fee requirements | N/A (new)     |
| **owner**            | General administration        | Same          |
| **rescuer**          | Emergency token recovery      | Same          |
| **pauser**           | Emergency pause               | Same          |
| **attesterManager**  | Manages attesters             | Same          |
| **tokenController**  | Manages token pairs           | Same          |

## When to Use V2 vs V1

### Use V2 When:

* ✅ You need fee collection capabilities
* ✅ You want flexible finality requirements
* ✅ You need hook execution for custom logic
* ✅ You require denylist functionality
* ✅ You want deterministic cross-chain addresses (CREATE2)
* ✅ You need upgradeability through proxy pattern

### Use V1 When:

* ✅ You need simple burn-and-mint without fees
* ✅ You don't require hook execution
* ✅ You prefer non-upgradeable contracts
* ✅ You're integrating with existing V1 deployments

## Backward Compatibility

V2 maintains compatibility with V1 in the following ways:

* **Message Format**: V1 and V2 use different message body versions
* **Message Transmitters**: V1 MessageTransmitters cannot process V2 messages
* **Token Minter**: V2 extends V1 TokenMinter with dual-recipient mint capability
* **Separate Deployments**: V1 and V2 can coexist on the same chain

<Warning>
  V1 and V2 are separate protocol deployments. Messages created in V1 cannot be received by V2 contracts and vice versa.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="What's New" icon="star" href="/v2/whats-new">
    Detailed feature breakdown and technical changes
  </Card>

  <Card title="Migration Guide" icon="arrow-right" href="/v2/migration-guide">
    Step-by-step guide for migrating from V1 to V2
  </Card>

  <Card title="Deployment" icon="rocket" href="/v2/deployment">
    Deploy V2 contracts to your network
  </Card>

  <Card title="API Reference" icon="code" href="/api/v2/token-messenger-v2">
    Complete V2 contract API documentation
  </Card>
</CardGroup>