CCIP v2.0.0 OnRamp API Reference

OnRamp is the source-chain execution engine for CCIP messages.

It is responsible for:

• validating outbound messages
• computing and collecting fees
• coordinating token locking or burning via pools
• generating message payloads for cross-chain delivery

All outbound message processing flows through this contract.

Applications do not call this contract directly.

Usage Boundary

You do not call this contract directly.

• The Router calls this contract to submit outbound messages.
• OnRamp validates messages, processes tokens, and emits data for delivery.
• The owner configures destination chains, fee parameters, and execution behavior.
• You are responsible for ensuring correct destination chain and token configuration.
• Fee calculation depends on FeeQuoter (pricing) and Executor (execution policy).

Contract

onRamp/OnRamp.sol

Import

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

Inheritance

• IEVM2AnyOnRampClient
• ITypeAndVersion
• Ownable2StepMsgSender

Constructor

constructor(StaticConfig memory staticConfig, DynamicConfig memory dynamicConfig)

Execution Flow

1. The Router calls forwardFromRouter.
2. Message parameters are validated.
3. Fees are computed and collected.
4. Tokens are processed via configured pools.
5. Verifier data is generated.
6. Message data is emitted for delivery to the destination chain.

External API

getExpectedNextMessageNumber

function getExpectedNextMessageNumber(uint64 destChainSelector) external view returns (uint64)

Returns the next expected message sequence number for a destination chain.

forwardFromRouter

function forwardFromRouter(
  uint64 destChainSelector,
  Client.EVM2AnyMessage calldata message,
  uint256 feeTokenAmount,
  address originalSender
) external returns (bytes32 messageId)

Processes an outbound message submitted by the Router and prepares it for cross-chain delivery.

• Must only be called by the Router.
• Computes fees, processes tokens, and emits message data.

Returns:

getStaticConfig

function getStaticConfig() public view returns (StaticConfig memory)

Returns static configuration.

getDynamicConfig

function getDynamicConfig() external view returns (DynamicConfig memory dynamicConfig)

Returns dynamic configuration.

setDynamicConfig

function setDynamicConfig(DynamicConfig memory dynamicConfig) external onlyOwner

Updates dynamic configuration.

applyDestChainConfigUpdates

function applyDestChainConfigUpdates(
  DestChainConfigArgs[] calldata destChainConfigArgs
) external onlyOwner

Updates destination chain configuration.

getDestChainConfig

function getDestChainConfig(uint64 destChainSelector)
  external
  view
  returns (DestChainConfig memory destChainConfig)

Returns configuration for a destination chain.

getAllDestChainConfigs

function getAllDestChainConfigs()
  external
  view
  returns (uint64[] memory, DestChainConfig[] memory)

Returns all configured destination chains.

getPoolBySourceToken

function getPoolBySourceToken(
  uint64 destChainSelector,
  IERC20 sourceToken
) public view returns (IPoolV1)

Returns the token pool used for handling a source token.

getSupportedTokens

function getSupportedTokens(uint64 destChainSelector) external pure returns (address[] memory)

Returns supported tokens (legacy behavior; consult TokenAdminRegistry for canonical data).

getFee

function getFee(
  uint64 destChainSelector,
  Client.EVM2AnyMessage calldata message
) external view returns (uint256 feeTokenAmount)

Returns the fee required to send a message through the OnRamp.

withdrawFeeTokens

function withdrawFeeTokens(address[] calldata feeTokens) external

Withdraws accumulated fees.

Events

• event ConfigSet(StaticConfig staticConfig, DynamicConfig dynamicConfig)
• event DestChainConfigSet(uint64 indexed destChainSelector, uint64 messageNumber, DestChainConfigArgs config)
• event CCIPMessageSent(uint64 indexed destChainSelector, address indexed sender, bytes32 indexed messageId, address feeToken, uint256 tokenAmountBeforeTokenPoolFees, bytes encodedMessage, Receipt[] receipts, bytes[] verifierBlobs)

For a cross-contract event index, see Events.

Errors

• error CannotSendZeroTokens()
• error DestinationChainNotSupportedByCCV(address ccvAddress, uint64 destChainSelector)
• error UnsupportedToken(address token)
• error CanOnlySendOneTokenPerMessage()
• error MustBeCalledByRouter()
• error RouterMustSetOriginalSender()
• error InvalidConfig()
• error CursedByRMN(uint64 destChainSelector)
• error GetSupportedTokensFunctionalityRemovedCheckAdminRegistry()
• error InvalidDestChainConfig(uint64 destChainSelector)
• error ReentrancyGuardReentrantCall()
• error DestinationChainNotSupported(uint64 destChainSelector)
• error InvalidDestChainAddress(bytes destChainAddress)
• error FTFNotSupportedOnPoolV1()
• error TokenArgsNotSupportedOnPoolV1()
• error InsufficientFeeTokenAmount()
• error TokenReceiverNotAllowed(uint64 destChainSelector)
• error SourceTokenDataTooLarge(address token, uint256 actualLength, uint32 maxLength)
• error FeeExceedsMaxAllowed(uint256 feeUSDCents, uint32 maxUSDCentsPerMessage)

For a cross-contract error index, see Errors.

Notes

• Message numbers are strictly increasing per destination chain.
• Each messageId is derived deterministically from message parameters and sequence number.
• Only one token transfer is allowed per message.
• The Router must supply the correct original sender.
• Destination chain configuration must be enabled for message submission.
• Token handling is delegated to configured token pools.
• Fees returned by getFee must match parameters used in forwardFromRouter.
• Message parameters must not change between fee quoting and submission.
• Message submission will revert if destination chain, token, or CCV configuration is invalid.
• Message submission will revert if fee payment is insufficient or token pool configuration is invalid.
• Encoded message format must match MessageV1Codec expectations.

Structs

StaticConfig

struct StaticConfig {
  uint64 localChainSelector;
  IRMNRemote rmnRemote;
  uint32 maxUSDCentsPerMessage;
  address tokenAdminRegistry;
}

DynamicConfig

struct DynamicConfig {
  address feeQuoter;
  address feeAggregator;
}

DestChainConfig

struct DestChainConfig {
  IRouter router;
  uint64 messageNumber;
  uint8 addressBytesLength;
  bool tokenReceiverAllowed;
  uint16 messageNetworkFeeUSDCents;
  uint16 tokenNetworkFeeUSDCents;
  uint32 baseExecutionGasCost;
  address defaultExecutor;
  address[] laneMandatedCCVs;
  address[] defaultCCVs;
  address offRamp;
}

DestChainConfigArgs

struct DestChainConfigArgs {
  uint64 destChainSelector;
  IRouter router;
  uint8 addressBytesLength;
  bool tokenReceiverAllowed;
  uint16 messageNetworkFeeUSDCents;
  uint16 tokenNetworkFeeUSDCents;
  uint32 baseExecutionGasCost;
  address[] defaultCCVs;
  address[] laneMandatedCCVs;
  address defaultExecutor;
  address offRamp;
}

Receipt

struct Receipt {
  address issuer;
  uint32 destGasLimit;
  uint32 destBytesOverhead;
  uint256 feeTokenAmount;
  bytes extraArgs;
}

Internal Functions

Internal helpers implement validation, token handling, and message processing logic.

Security model

• Router is the only allowed caller for message submission.
• Owner controls destination chain configuration and fee parameters.
• RMN can block message processing under unsafe conditions.
• Reentrancy protection enforces safe execution.
• Misconfiguration may result in failed message submission or incorrect fee handling.

Related Interfaces & Contracts

• Router
• IEVM2AnyOnRampClient
• IFeeQuoter
• IExecutor
• ITokenAdminRegistry
• Client
• IPoolV1
• IPoolV2