CCIP Architecture

High-level architecture

Below is a diagram displaying the basic architecture of CCIP. Routers are smart contracts that provide a simple and consistent interface for users. Users can interact with routers to:

• Call smart contract functions on a different blockchain.
• Transfer tokens to a smart contract or Externally Owned Account (EOA) on a different blockchain.
• Send arbitrary messages and tokens within the same transaction. Use this functionality to transfer tokens and instructions on what to do with those tokens to a smart contract on a different blockchain.

CCIP terminology

CCIP enables a sender on a source blockchain to send a message to a receiver on a destination blockchain.

Detailed architecture

The figure below outlines the different components involved in a cross-chain transaction:

• Cross-Chain dApps are user-specific. A smart contract, a smart account, or an EOA (Externally Owned Account) interacts with the CCIP Router to send arbitrary data and/or transfer tokens cross-chain.

• The contracts in dark blue are the CCIP interface (Router). To use CCIP, users need only to understand how to interact with the router; they don't need to understand the whole CCIP architecture. Note: The CCIP interface is static and remains consistent over time to provide reliability and stability to the users.

• The contracts in light blue are internal to the CCIP protocol and subject to change.

• The contracts highlighted in orange have been integrated into the CCIP protocol to enable the Cross-Chain Token (CCT) standard.

  
  

Onchain components

Router

The Router is the primary contract CCIP users interface with. This contract is responsible for initiating cross-chain interactions. One router contract exists per blockchain. When transferring tokens, callers have to approve tokens for the router contract. The router contract routes the instruction to the destination-specific OnRamp.

When a message is received on the destination chain, the router is the contract that “delivers” tokens to the user's account or the message to the receiver's smart contract.

Commit Store

The Committing DON interacts with the CommitStore contract on the destination blockchain to store the Merkle root of the finalized messages on the source blockchain. This Merkle root must be blessed by the Risk Management Network before the Executing DON can execute them on the destination blockchain. The CommitStore ensures the message is blessed by the Risk Management Network and only one CommitStore exists per lane.

OnRamp

One OnRamp contract exists per lane. This contract performs the following tasks:

• Checks destination blockchain-specific validity, such as validating account address syntax.

• Verifies message size limits and gas limits.

• Keeps track of sequence numbers to preserve the order of messages for the receiver

• Manages billing.

• Interacts with the TokenAdminRegistry to retrieve the token pool linked to a token if the message includes a token transfer.

• Interacts with the TokenPool to lock or burn a specified amount of tokens if the message includes a token transfer.

• Emits an event monitored by the committing DON.

OffRamp

One OffRamp contract exists per lane. This contract performs the following tasks:

• Ensures the message is authentic by verifying the proof provided by the Executing DON against a committed and blessed Merkle root.
• Ensures transactions are executed only once.
• Interacts with the TokenAdminRegistry to retrieve the token pool linked to a token if the message includes a token transfer.
• If the CCIP transaction includes token transfers, the OffRamp contract calls the TokenPool to unlock or mint the correct assets for the receiver.
• After validation, the OffRamp contract transmits any received message to the Router contract.

TokenAdminRegistry and RegistryModuleOwnerCustom

The registry contracts manage the registration of tokens within the Cross-Chains Tokens (CCT) standard. For more information, read the CCT standard concepts.

Token pools

Each token is associated with its own token pool, an abstraction layer over ERC-20 tokens designed to facilitate token-related operations for OnRamping and OffRamping. Token pools provide rate limiting, a security feature enabling token developers to set a maximum rate at which their token can be transferred per lane. Token pools are configured to lock or burn tokens on the source blockchain and unlock or mint tokens on the destination blockchain. This setup results in four primary mechanisms:

• Burn and Mint: Tokens are burned on the source blockchain, and an equivalent amount of tokens are minted on the destination blockchain.
• Lock and Mint: Tokens are locked on their issuing blockchain, and fully collateralized "wrapped" tokens are minted on the destination blockchain. These wrapped tokens can be transferred across non-issuing blockchains using the Burn and Mint mechanism.
• Burn and Unlock: Tokens are burned on the source blockchain, and an equivalent amount of tokens are released on the destination blockchain. This mechanism is the inverse of the Lock and Mint mechanism. It applies when you send tokens to their issuing source blockchain.
• Lock and Unlock: Tokens are locked on the source blockchain, and an equivalent amount of tokens are released on the destination blockchain.

Currently, token pools are administered in two ways:

• Self-Administered Token Pools: These are managed directly by projects, allowing them to self-manage their tokens. Projects configure their token pools autonomously. This is currently only possible on blockchains where the Cross-Chain Token standard is available.

• CCIP-Managed Token Pools: Some token pools that existed before the Cross-Chain Token standard are managed by CCIP and will continue to exist alongside the self-administered ones. Eventually, all token pools will be fully administered by their respective projects.

The mechanism for handling tokens varies depending on the characteristics of each token. Below are several examples to illustrate this:

• LINK Token is minted on a single blockchain (Ethereum mainnet) and has a fixed total supply. Consequently, CCIP cannot natively mint it on another blockchain. For LINK, the token pool is configured to lock tokens on Ethereum mainnet (the issuing blockchain) and mint them on the destination blockchain. Conversely, when transferring from a non-issuing blockchain to Ethereum mainnet, the LINK token pool is set to burn the tokens on the source (non-issuing) blockchain and unlock them on Ethereum Mainnet (issuing). For example, transferring 10 LINK from Ethereum mainnet to Base mainnet involves the LINK token pool locking 10 LINK on Ethereum mainnet and minting 10 LINK on Base mainnet. Conversely, transferring 10 LINK from Base mainnet to Ethereum mainnet involves the LINK token pool burning 10 LINK on Base mainnet and unlocking 10 LINK on Ethereum mainnet.
• Wrapped native Assets (e.g., WETH) use a Lock and Unlock mechanism. For instance, when transferring 10 WETH from Ethereum mainnet to Optimism mainnet, the WETH token pool will lock 10 WETH on Ethereum mainnet and unlock 10 WETH on Optimism mainnet. Conversely, transferring from Optimism mainnet back to Ethereum mainnet involves the WETH token pool locking 10 WETH on Optimism mainnet and unlocking 10 WETH on the Ethereum mainnet.
• Stablecoins (e.g., USDC) can be minted natively on multiple blockchains. Their respective token pools employ a Burn and Mint mechanism, burning the token on the source blockchain and then minting it natively on the destination blockchain.
• Tokens with a Proof Of Reserve (PoR) with a PoR feed on a specific blockchain present a challenge for the Burn and Mint mechanism when applied across other blockchains due to conflicts with the PoR feed. For such tokens, the Lock and Mint approach is preferred.

Risk Management Network contract

The Risk Management contract maintains the list of Risk Management node addresses that are allowed to bless or curse. The contract also holds the quorum logic for blessing a committed Merkle Root and cursing CCIP on a destination blockchain. Read the Risk Management Network Concepts section to learn more.

Offchain components

Committing DON

The Committing DON has several jobs where each job monitors cross-chain transactions between a given source blockchain and destination blockchain:

• Each job monitors events from a given OnRamp contract on the source blockchain.
• The job waits for finality, which depends on the source blockchain.
• The job bundles transactions and creates a Merkle root. This Merkle root is signed by a quorum of oracles nodes part of the Committing DON.
• Finally, the job writes the Merkle root to the CommitStore contract on the given destination blockchain.

Executing DON

Like the Committing DON, the Executing DON has several jobs where each executes cross-chain transactions between a source blockchain and a destination blockchain:

• Each job monitors events from a given OnRamp contract on the source blockchain.
• The job checks whether the transaction is part of the relayed Merkle root in the CommitStore contract.
• The job waits for the Risk Management Network to bless the message.
• Finally, the job creates a valid Merkle proof, which is verified by the OffRamp contract against the Merkle root in the CommitStore contract. After these check pass, the job calls the OffRamp contract to complete the CCIP transactions on the destination blockchain.

Separating commitment and execution permits the Risk Management Network to have enough time to check the commitment of messages before executing them. The delay between commitment and execution also permits additional checks such as abnormal reorg depth, potential simulation, and slashing.

Saving a commitment is compact and has a fixed gas cost, whereas executing user callbacks can be highly gas intensive. Separating commitment and execution permits execution by end users in various cases, such as retrying failed executions.

Risk Management Network

The Risk Management Network is a set of independent nodes that monitor the Merkle roots committed by the Committing DON into the Commit Store.

Each node compares the committed Merkle roots with the transactions received by the OnRamp contract. After the verification succeeds, it calls the Risk Management contract to "bless"  the committed Merkle root. When there are enough blessing votes, the root becomes available for execution. In case of anomalies, each Risk Management node calls the Risk Management contract to "curse"  the system. If the cursed quorum is reached, the Risk Management contract is paused to prevent any CCIP transaction from being executed.

Read the Risk Management Network Concepts section to learn more.

CCIP rate limits

Chainlink CCIP token transfers benefit from rate limits for additional security. A rate limit has a maximum capacity and a refill rate, which is the speed at which the maximum capacity is restored after a token transfer has consumed some or all of the available capacity.

You can find the complete list of lanes and their rate limits on the CCIP Directory page.

The rate limits are enforced at both the source and destination blockchains for maximum security. If these rate limits are reached, descriptive errors with detailed information are generated and returned to the sender. This enables CCIP users to gracefully handle these errors within their dApps to preserve the end-user experience. A comprehensive list of errors and their descriptions is available on the errors API reference page.

Token pool rate limit

For each supported token on each individual lane, the token pool rate limit manages the total number of tokens that can be transferred within a given time. This limit is independent of the USD value of the token.

For example, the maximum capacity of the suUSD token pool on the Ethereum mainnet → Base mainnet lane is 200,000 suUSD. The refill rate is 2 suUSD per second. If 200,000 suUSD are transferred on that lane, the entire capacity is consumed. After that, if a user wants to send 20 suUSD, they must wait at least 10 seconds as the capacity refills. The maximum throughput for this token on the lane is 1200 suUSD every 10 minutes.

Aggregate rate limit

Each lane also has an aggregate rate limit that limits the overall USD value that can be transferred on that lane across all supported tokens. To improve security, the aggregate rate limit for any given lane is always lower than the sum of all individual token pool rate limits for that lane.

Consider an example where a lane has a maximum capacity of 100,000 USD, a refill rate of 167 USD per second, and several token transfers with a total value of 60,000 USD have been executed. In that example, the remaining available capacity is 40,000 USD. If a user intends to transfer tokens equating to 50,000 USD, they must wait at least 60 seconds for capacity to refill the additional 10,000 USD that is required. The maximum throughput in USD value on the lane is 100,000 USD every 10 minutes.

CCIP execution latency

Chainlink CCIP has been purposely designed to take a security-first approach to minimize the risk of block reorgs on the source blockchain. The end-to-end transaction time of a CCIP cross-chain transaction largely depends on the time it takes for the transaction on the source blockchain to reach finality. The time to reach finality varies by blockchain. For example, on Ethereum, it takes about 15 minutes for a block to be finalized. When cross-chain transactions are initiated from a blockchain with faster finality, such as Avalanche, which has a time-to-finality of around one second, the end-to-end transaction time is faster.

If the fee paid on the source blockchain is within an acceptable range of the execution cost on the destination chain, the message will be transmitted as soon as possible after it is blessed by the Risk Management Network. If the cost of execution increases between request and execution time, CCIP incrementally increases the gas price to attempt to reach eventual execution, but this might introduce additional latency.

Execution delays in excess of one hour should be rare as a result of Smart Execution. The Smart Execution time window parameter represents the waiting time before manual execution is enabled. If the DON fails to execute within the duration of Smart Execution time window due to extreme network conditions, you can manually execute the message through the CCIP Explorer. Read the manual execution conceptual guide to learn more.

CCIP Upgradability

What can be upgraded

Upgradability in the context of CCIP refers to the ability to upgrade CCIP’s operational scope, feature set, security, or reliability. These updates are applied via changes to the following items:

• Smart Contract Configuration: Configuration can be updated via dedicated functions exposed by the smart contract. Examples are updates to the rate limits for a specific lane, the list of supported tokens, and the OnRamp contract to call for a given destination blockchain.
• Smart Contract Code: Once deployed, smart contract code cannot be modified or upgraded. The only option is to deploy a new version of the contract (e.g., OnRamp, OffRamp, Token Pool) and redirect the calling contract to the newly deployed contract via a configuration change. One exception is the Router contract, which is the primary interface for CCIP users on both the source and destination blockchains. The Router contract remains static and consistent over time to ensure reliability and stability for developers who integrate with it.

Implementation process

All onchain configuration changes and upgrades to CCIP must pass through a Role-based Access Control Timelock (RBACTimelock) smart contract.

Any proposal must either (1) be proposed by a dedicated ManyChainMultiSig (MCMS) contract and then be subjected to a review period enforced by the RBACTimelock, during which a quorum of node operators securing CCIP are able to veto the proposal; or (2) be proposed by a dedicated MCMS contract and be explicitly approved by a quorum of independent signers, including multiple node operators securing CCIP, providing an alternative path during time-sensitive circumstances.

Any onchain update that passes the timelock review period without a veto becomes executable by anyone, which can be done by running a timelock-worker to process executable upgrades.

Documentation and source code relating to the CCIP owner contracts can be read on GitHub. The proposer multisig on Ethereum can be found on Etherscan, where configuration details can also be read.