CCIP v2.0.0 Router API Reference

Router is the onchain entry point for sending CCIP messages and token transfers from a source chain.

If you integrate directly with the Router, you construct messages, choose how fees are paid, and initiate cross-chain delivery using getFee and ccipSend.

The Router also routes inbound messages from authorized OffRamp contracts to destination-chain receivers.

Router implements IRouter and IRouterClient.

Applications may call this contract directly, but most integrations rely on the Router through the IRouterClient interface.

Usage Boundary

You use the Router to construct, price, and send CCIP messages.

• Call isChainSupported to confirm the destination chain is available.
• Construct an EVM2AnyMessage with your desired payload, receiver, tokens, and fee token.
• Call getFee to estimate the cost of that message.
• Call ccipSend with sufficient payment to initiate delivery.
• You are responsible for message correctness and fee sufficiency.

Do not call internal routing or admin functions.

• routeMessage is invoked by authorized OffRamp contracts during delivery.
• Configuration functions are restricted to the contract owner.

Contract

Router.sol

Import

import {Router} from "chainlink-ccip/Router.sol";

If you have not installed the package:

npm install @chainlink/contracts-ccip@2.0.0

Inheritance

• IRouter
• IRouterClient
• ITypeAndVersion
• OwnerIsCreator

Constructor

constructor( address wrappedNative, address armProxy )

External API

getFee

function getFee(
  uint64 destinationChainSelector,
  Client.EVM2AnyMessage memory message
) external view returns (uint256 fee)

Returns the fee required to send a message with the specified parameters.

You define the message contents and fee token, and use this value to determine how much to pay when calling ccipSend.

Returns:

ccipSend

function ccipSend(
  uint64 destinationChainSelector,
  Client.EVM2AnyMessage memory message
) external payable whenNotCursed returns (bytes32)

Sends a cross-chain message through the Router.

You provide the message configuration and payment, and the Router forwards the request to the configured OnRamp.

This call commits the message. If the message is invalid or the fee is insufficient, the transaction reverts.

Returns:

isChainSupported

function isChainSupported( uint64 chainSelector ) public view returns (bool)

Checks whether the Router supports a destination chain.

Returns:

getSupportedTokens

function getSupportedTokens( uint64 chainSelector ) external view returns (address[] memory)

Returns the tokens supported for cross-chain transfers to the specified chain.

Returns:

routeMessage

function routeMessage(
  Client.Any2EVMMessage calldata message,
  uint16 gasForCallExactCheck,
  uint256 gasLimit,
  address receiver
) external whenNotCursed returns (bool success, bytes memory retData, uint256 gasUsed)

Routes an inbound message from an authorized OffRamp to a receiver contract.

You do not call this function directly. The protocol calls it during message delivery after validating the OffRamp.

Returns:

getWrappedNative

function getWrappedNative() external view returns (address)

Returns the configured wrapped native token address.

Returns:

setWrappedNative

function setWrappedNative( address wrappedNative ) external onlyOwner

Owner-only function that updates the wrapped native token address used for fee payments.

getArmProxy

function getArmProxy() external view returns (address)

Returns the RMN proxy address used for curse checks.

Returns:

getOnRamp

function getOnRamp( uint64 destChainSelector ) external view returns (address)

Returns the OnRamp configured for a destination chain.

Returns:

getOffRamps

function getOffRamps() external view returns (OffRamp[] memory)

Returns the configured OffRamp contracts.

Returns:

isOffRamp

function isOffRamp( uint64 sourceChainSelector, address offRamp ) public view returns (bool)

Checks whether an address is an authorized OffRamp.

Returns:

applyRampUpdates

function applyRampUpdates(
  OnRamp[] calldata onRampUpdates,
  OffRamp[] calldata offRampRemoves,
  OffRamp[] calldata offRampAdds
) external onlyOwner

Owner-only function that updates OnRamp and OffRamp configuration.

recoverTokens

function recoverTokens( address tokenAddress, address to, uint256 amount ) external onlyOwner

Owner-only function that recovers tokens held by the Router.

Events

• event OnRampSet(uint64 indexed destChainSelector, address onRamp)
• event OffRampAdded(uint64 indexed sourceChainSelector, address offRamp)
• event OffRampRemoved(uint64 indexed sourceChainSelector, address offRamp)
• event MessageExecuted(bytes32 messageId, uint64 sourceChainSelector, address offRamp, bytes32 calldataHash)

For a cross-contract event index, see Events.

Errors

FailedToSendValue

Thrown when native value transfer fails.

error FailedToSendValue();

InvalidRecipientAddress

Thrown when the recipient address is invalid.

error InvalidRecipientAddress(address to);

OffRampMismatch

Thrown when an OffRamp does not match the expected configuration.

error OffRampMismatch(uint64 chainSelector, address offRamp);

BadARMSignal

Thrown when the RMN proxy indicates the system is cursed.

error BadARMSignal();

For a cross-contract error index, see Errors.

Structs

OnRamp

struct OnRamp {
  uint64 destChainSelector;
  address onRamp;
}

OffRamp

struct OffRamp {
  uint64 sourceChainSelector;
  address offRamp;
}

Internal Functions

_mergeChainSelectorAndOffRamp

function _mergeChainSelectorAndOffRamp(
  uint64 sourceChainSelector,
  address offRampAddress
) internal pure returns (uint256)

Encodes (sourceChainSelector, offRampAddress) as:

(uint256(sourceChainSelector) << 160) + uint160(offRampAddress)

Security model

Trust boundaries

1. Owner-controlled configuration

   • Controls OnRamp and OffRamp configuration
   • Controls wrapped native token
   • Can recover tokens

2. OffRamp authorization

   • Only allowlisted OffRamps can call routeMessage

3. RMN curse gating

   • whenNotCursed prevents execution when the system is paused

Execution containment

• Receiver calls are constrained to IAny2EVMMessageReceiver.ccipReceive(message)
• Calls use exact-gas execution with bounded return data

Fee and token validation delegation

• The Router relies on the configured OnRamp to calculate fees
• The Router relies on the configured OnRamp to determine token pool routing

Notes

• The fee returned by getFee is specific to the exact message parameters. If you change the message, you must quote the fee again.

Related Interfaces & Contracts

• IRouterClient
• IAny2EVMMessageReceiver
• Client
• OnRamp
• OffRamp