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 enables a sender on a source blockchain to send a message to a receiver on a destination blockchain.
|Sender||A smart contract or an EOA.|
|Source Blockchain||The blockchain the sender interacts with CCIP from.|
|Message||Arbitrary data and/or tokens.|
|Receiver||A smart contract or an EOA. Note: An EOA cannot receive arbitrary data. It can only receive tokens.|
|Destination Blockchain||The blockchain the receiver resides on.|
The figure below outlines the different components involved in a cross-chain transaction:
- Cross-Chain dApps are user-specific. A smart contract 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 Router is the primary contract CCIP users interface with. This contract is responsible for initiating cross-chain interactions. One router contract exists per chain. 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.
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.
One OnRamp contract per lane exists. This contract performs the following tasks:
- Checks destination-blockchain-specific validity such as validating account address syntax
- Verifies the message size limit and gas limits
- Keeps track of sequence numbers to preserve the sequence of messages for the receiver
- Manages billing
- Interacts with the TokenPool if the message includes a token transfer.
- Emits an event monitored by the committing DON
One OffRamp contract per lane exists. 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
- Makes sure transactions are executed only once
- After validation, the OffRamp contract transmits any received message to the Router contract. If the CCIP transaction includes token transfers, the OffRamp contract calls the TokenPool to transfer the correct assets to the receiver.
Each token has its own token pool, an abstraction layer over ERC-20 tokens that facilitates OnRamp and OffRamp token-related operations. Token pools are configurable to
burn at the source blockchain and
mint at the destination blockchain. The mechanism for handling tokens depends on the characteristics of the token in question. Here are a few examples:
- Blockchain-native gas tokens, such as ETH, MATIC, and AVAX, can only be minted on their native chains. These tokens cannot be burned on the source and minted at the destination to transfer these tokens between chains. Instead, the linked token pool uses a "Lock and Mint" approach that locks the token at its source and then mints a wrapped or synthetic asset on the destination blockchain. This synthetic asset represents the locked asset and is essential for redeeming the locked asset.
- A token like LINK is minted on a single chain (Ethereum mainnet) with a fixed total supply. CCIP cannot natively mint it on another chain. In this case, the "Lock and Mint" approach is required.
- Some tokens can be minted on multiple chains. Examples of such tokens include stablecoins like USDC, TUSD, USDT, and FRAX. The linked token pools use a "Burn and Mint" method to burn the token at its source and then mint it natively on the destination blockchain. Wrapped assets such as WBTC or WETH are other examples that use the "Burn and Mint" approach.
- A token with a Proof Of Reserve (PoR) feed on a specific chain poses a challenge for the "Burn and Mint" method when applied to other chains because it conflicts with the PoR feed. For these tokens, "Lock and Mint" is the preferred approach.
Token pools provide rate limiting, which is a security feature enabling token issuers to set a maximum rate at which their token can be transferred.
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.
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.
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.
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.
The CCIP billing model uses the
feeToken specified in the message to pay a single fee on the source chain. CCIP uses a gas-locked fee payment mechanism, referred to as Smart Execution, to help ensure the reliable execution of cross-chain transactions regardless of destination chain gas spikes. For developers, this means you can simply pay on the source chain and CCIP will take care of execution on the destination chain.
On each source chain, CCIP maintains a cache of destination gas prices, denominated in each
feeToken. To prevent staleness, these prices are routinely updated by either piggybacking user messages or timeouts. CCIP supports fee payments in LINK and in alternative assets, which currently includes blockchain-native gas tokens and their ERC20 wrapped versions. The payment model for CCIP is designed to significantly reduce friction for users and quickly scale CCIP to more blockchains by supporting fee payments that originate across a multitude of chains over time.
Users should note that CCIP fees include both gas cost overhead and a flat/basis points premium as follows:
- Destination gas overhead: This is the average overhead incurred on the destination chain by CCIP to process the message and/or token transfer.
- Flat network premium for messages: this fee is a static amount that users pay when sending cross-chain messages.
- Basis point based premium for tokens: This is a percentage-based fee that users pay for cross-chain token transfers. It is calculated using the following expression:
tokenAmount x price x bps ratio.
priceis initially denominated in USD and translated into the
Current CCIP premium fees are in line with industry standards within the cross-chain ecosystem, but these values are subject to change. The premium portion of fees paid in alternative assets will have a surcharge of 10% when compared to LINK payments. To understand service limits, read the CCIP Service Limits page.
Aside from billing, overhead costs, and fees, remember to carefully estimate the
gasLimit that you set for your destination contract so CCIP can have enough gas to execute
ccipReceive(), if applicable. Any unspent gas from this user-set limit is not refunded.
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 chain 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 chain 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 chain 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
permissionlessExecutionThresholdSeconds parameter represents the waiting time before manual execution is enabled. If the DON fails to execute within the duration of
permissionlessExecutionThresholdSeconds due to extreme network conditions, you can manually execute the message through the CCIP Explorer.
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 Supported Networks 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.
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 snxUSD token pool on the Mainnet Ethereum → Optimism lane is 100,000 snxUSD. The refill rate is 167 snxUSD per second. If 100,000 snxUSD is transferred on that lane, the entire capacity is consumed. After that, if a user wants to send 1670 snxUSD, they must wait at least 10 seconds as the capacity refills. The maximum throughput for this token on the lane is 100,000 snxUSD every 10 minutes.
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.