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

# System Architecture

> Deep dive into CCTP contract hierarchy, relationships, and design patterns

## Contract Hierarchy

CCTP's architecture is built on a modular contract design with clear separation of concerns:

```mermaid theme={null}
graph TB
    subgraph "User Interface Layer"
        TM[TokenMessenger]
    end
    
    subgraph "Messaging Layer"
        MT[MessageTransmitter]
    end
    
    subgraph "Token Layer"
        TMinter[TokenMinter]
        USDC[USDC Token]
    end
    
    subgraph "Role Contracts"
        O[Ownable2Step]
        P[Pausable]
        R[Rescuable]
        A[Attestable]
        TC[TokenController]
    end
    
    subgraph "Infrastructure"
        Proxy[AdminUpgradableProxy]
        Init[Initializable]
    end
    
    TM -->|deposits/withdraws| TMinter
    TM -->|sends/receives| MT
    TMinter -->|burns/mints| USDC
    MT -.->|inherits| P
    MT -.->|inherits| R
    MT -.->|inherits| A
    TM -.->|inherits| R
    TMinter -.->|inherits| TC
    TMinter -.->|inherits| P
    TMinter -.->|inherits| R
    P -.->|inherits| O
    R -.->|inherits| O
    A -.->|inherits| O
    TC -.->|inherits| O
    Proxy -->|delegates to| TM
    Proxy -->|delegates to| MT
    Proxy -->|delegates to| TMinter
```

## Core Contracts

### TokenMessenger

**Inheritance**: `Rescuable`

**Purpose**: Entry point for users initiating cross-chain USDC transfers

**Key Relationships**:

* Calls `ITokenMinter` to burn tokens on source chain and mint on destination
* Calls `IMessageTransmitter` to send cross-chain messages
* Implements `IMessageHandler` to receive and process incoming messages
* Maintains mapping of remote TokenMessenger contracts by domain

**State Variables**:

```solidity theme={null}
// Immutable reference to local MessageTransmitter
IMessageTransmitter public immutable localMessageTransmitter;

// Message body format version
uint32 public immutable messageBodyVersion;

// Local TokenMinter for burn/mint operations
ITokenMinter public localMinter;

// Remote TokenMessenger addresses by domain
mapping(uint32 => bytes32) public remoteTokenMessengers;
```

### MessageTransmitter

**Inheritance**: `Pausable, Rescuable, Attestable`

**Purpose**: Handles cross-chain message sending, receiving, and attestation verification

**Key Relationships**:

* Invokes `IMessageHandler.handleReceiveMessage()` on recipient contracts
* Inherits attester management from `Attestable`
* Enforces pause controls for emergency situations

**State Variables**:

```solidity theme={null}
// Domain identifier for this chain
uint32 public immutable localDomain;

// Message format version
uint32 public immutable version;

// Maximum message size in bytes
uint256 public maxMessageBodySize;

// Incrementing nonce for outgoing messages
uint64 public nextAvailableNonce;

// Nonce replay prevention: hash(sourceDomain, nonce) => used flag
mapping(bytes32 => uint256) public usedNonces;
```

### TokenMinter

**Inheritance**: `TokenController, Pausable, Rescuable`

**Purpose**: Manages token minting and burning operations with burn limits

**Key Relationships**:

* Only callable by authorized `localTokenMessenger`
* Interacts with `IMintBurnToken` interface for actual mint/burn
* Inherits token pair management from `TokenController`

**State Variables**:

```solidity theme={null}
// Authorized TokenMessenger that can call mint/burn
address public localTokenMessenger;

// Inherited from TokenController:
// - burnLimitsPerMessage: per-token burn limits
// - remoteTokensToLocalTokens: token address mappings
```

## Role-Based Access Control

CCTP implements granular access control through specialized role contracts:

### Ownable2Step

**Purpose**: Two-step ownership transfer to prevent accidental loss of control

**Key Features**:

* Owner must propose new owner
* New owner must accept to complete transfer
* Prevents typos in address entry from permanently losing access

**Functions**:

```solidity theme={null}
function transferOwnership(address newOwner) external onlyOwner
function acceptOwnership() external
```

### Pausable

**Purpose**: Emergency stop mechanism for security incidents

**Key Features**:

* Separate `pauser` role from `owner`
* `whenNotPaused` modifier blocks critical functions
* Quick response capability without ownership transfer

**Functions**:

```solidity theme={null}
function pause() external onlyPauser
function unpause() external onlyPauser  
function updatePauser(address newPauser) external onlyOwner
```

**Usage**: Applied to:

* `TokenMessenger.depositForBurn()`
* `MessageTransmitter.sendMessage()` and `receiveMessage()`
* `TokenMinter.mint()` and `burn()`

### Rescuable

**Purpose**: Recover accidentally sent ERC20 tokens

**Key Features**:

* Separate `rescuer` role from `owner`
* Can rescue any ERC20 token sent to contract
* Uses OpenZeppelin's `SafeERC20` for safe transfers

**Functions**:

```solidity theme={null}
function rescueERC20(
    IERC20 tokenContract,
    address to,
    uint256 amount
) external onlyRescuer

function updateRescuer(address newRescuer) external onlyOwner
```

### Attestable

**Purpose**: Manage authorized attesters and signature verification

**Key Features**:

* Maintains set of enabled attester addresses
* Configurable signature threshold (m-of-n multisig)
* Separate `attesterManager` role
* ECDSA signature recovery and validation

**Functions**:

```solidity theme={null}
function enableAttester(address attester) external onlyAttesterManager
function disableAttester(address attester) external onlyAttesterManager
function setSignatureThreshold(uint256 newThreshold) external onlyAttesterManager
function updateAttesterManager(address newManager) external onlyOwner
```

**State Variables**:

```solidity theme={null}
// Threshold for valid attestation (m in m/n multisig)
uint256 public signatureThreshold;

// Set of enabled attester addresses (n in m/n multisig)
EnumerableSet.AddressSet private enabledAttesters;

// Address that can manage attesters
address private _attesterManager;
```

See [Attestation](/concepts/attestation) for detailed signature verification logic.

### TokenController

**Purpose**: Manage token pair mappings and burn limits

**Key Features**:

* Links remote tokens to local tokens by domain
* Enforces per-message burn limits
* Separate `tokenController` role

**Functions**:

```solidity theme={null}
function linkTokenPair(
    address localToken,
    uint32 remoteDomain,
    bytes32 remoteToken
) external onlyTokenController

function setMaxBurnAmountPerMessage(
    address localToken,
    uint256 burnLimitPerMessage  
) external onlyTokenController
```

## Proxy Pattern for Upgradeability

All three core contracts (TokenMessenger, MessageTransmitter, TokenMinter) are deployed behind `AdminUpgradableProxy` contracts:

### AdminUpgradableProxy

**Purpose**: Upgradeable proxy with admin-only upgrade functions

**Key Features**:

* Based on EIP-1967 transparent proxy pattern
* Admin calls don't forward to implementation (prevents function selector clashes)
* Non-admin calls always forward to implementation
* Uses assembly for gas-efficient storage slot access

**Architecture**:

```
┌─────────────────────────────────────┐
│         User / Contract             │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│     AdminUpgradableProxy            │
│  ┌──────────────────────────────┐   │
│  │ Admin Storage Slot           │   │
│  │ Implementation Storage Slot  │   │
│  └──────────────────────────────┘   │
│                                     │
│  if (msg.sender == admin) {         │
│    execute admin functions          │
│  } else {                           │
│    delegatecall to implementation   │
│  }                                  │
└──────────────┬──────────────────────┘
               │ delegatecall
               ▼
┌─────────────────────────────────────┐
│   Implementation Contract           │
│   (TokenMessenger/MessageTransmitter│
│    /TokenMinter)                    │
│  ┌──────────────────────────────┐   │
│  │ Business Logic               │   │
│  │ State Variables              │   │
│  └──────────────────────────────┘   │
└─────────────────────────────────────┘
```

**Admin Functions**:

```solidity theme={null}
// View current admin address
function admin() external view returns (address)

// View current implementation address  
function implementation() external view returns (address)

// Change proxy admin
function changeAdmin(address newAdmin) external ifAdmin

// Upgrade implementation
function upgradeTo(address newImplementation) external ifAdmin

// Upgrade and initialize in one transaction
function upgradeToAndCall(
    address newImplementation,
    bytes calldata data
) external payable ifAdmin
```

**Storage Layout**:

* Uses EIP-1967 standard storage slots to avoid collisions
* Admin slot: `keccak256("eip1967.proxy.admin") - 1`
* Implementation slot: `keccak256("eip1967.proxy.implementation") - 1`

### Upgrade Process

1. Deploy new implementation contract
2. Admin calls `proxy.upgradeTo(newImplementation)`
3. Proxy updates implementation storage slot
4. All subsequent calls route to new implementation
5. Existing storage and state preserved

<Warning>
  **Upgrade Safety**: Storage layout must be compatible between implementation versions. Adding new variables is safe; reordering or removing variables can corrupt state.
</Warning>

## Message Format

CCTP uses a fixed-format message structure defined in `Message.sol`:

| Field             | Bytes   | Type    | Index |
| ----------------- | ------- | ------- | ----- |
| version           | 4       | uint32  | 0     |
| sourceDomain      | 4       | uint32  | 4     |
| destinationDomain | 4       | uint32  | 8     |
| nonce             | 8       | uint64  | 12    |
| sender            | 32      | bytes32 | 20    |
| recipient         | 32      | bytes32 | 52    |
| destinationCaller | 32      | bytes32 | 84    |
| messageBody       | dynamic | bytes   | 116   |

**Design Rationale**:

* Fixed-size fields prevent hash collisions
* `destinationCaller` enables permissioned receiving
* Dynamic `messageBody` supports custom burn message formats

## Cross-Domain Communication

CCTP enables token transfers between domains through coordinated contract interactions:

```mermaid theme={null}
sequenceDiagram
    participant User
    participant TokenMessenger_A as TokenMessenger<br/>(Domain A)
    participant MessageTransmitter_A as MessageTransmitter<br/>(Domain A)
    participant TokenMinter_A as TokenMinter<br/>(Domain A)
    participant Attestation as Attestation Service<br/>(Off-chain)
    participant MessageTransmitter_B as MessageTransmitter<br/>(Domain B)
    participant TokenMessenger_B as TokenMessenger<br/>(Domain B)
    participant TokenMinter_B as TokenMinter<br/>(Domain B)
    
    User->>TokenMessenger_A: depositForBurn(amount, domainB, recipient)
    TokenMessenger_A->>TokenMinter_A: burn(token, amount)
    TokenMinter_A->>TokenMinter_A: USDC.burn(amount)
    TokenMessenger_A->>MessageTransmitter_A: sendMessage(domainB, message)
    MessageTransmitter_A->>MessageTransmitter_A: emit MessageSent(message)
    
    Attestation->>MessageTransmitter_A: Listen for MessageSent
    Attestation->>Attestation: Validate & Sign messageHash
    
    User->>Attestation: GET /attestations/{messageHash}
    Attestation->>User: Return attestation signature
    
    User->>MessageTransmitter_B: receiveMessage(message, attestation)
    MessageTransmitter_B->>MessageTransmitter_B: Verify attestation signatures
    MessageTransmitter_B->>TokenMessenger_B: handleReceiveMessage(domainA, sender, body)
    TokenMessenger_B->>TokenMinter_B: mint(domainA, token, recipient, amount)
    TokenMinter_B->>TokenMinter_B: USDC.mint(recipient, amount)
```

## Security Architecture

Multiple layers ensure system security:

1. **Access Control**: Role-based permissions limit critical operations
2. **Attestation**: Multi-signature validation prevents unauthorized mints
3. **Nonce Tracking**: Replay attack prevention per (domain, nonce) pair
4. **Burn Limits**: Per-message caps limit damage from compromised keys
5. **Pause Controls**: Emergency stop for security incidents
6. **Upgradeability**: Fix vulnerabilities without redeployment
7. **Domain Validation**: Ensure messages route to correct chains

## Next Steps

<CardGroup cols={2}>
  <Card title="Message Flow" icon="arrow-right-arrow-left" href="/concepts/message-flow">
    Follow a transfer through the complete lifecycle
  </Card>

  <Card title="Attestation" icon="signature" href="/concepts/attestation">
    Deep dive into signature verification
  </Card>
</CardGroup>