CCIPLocalSimulatorFork v0.3.1 API Reference
CCIPLocalSimulatorFork
A contract that simulates CCIP (Cross-Chain Interoperability Protocol) message routing in a Foundry test environment, for every CCIP era: pre-1.6 (EVM2EVMOnRamp), 1.6 and CCIP 2.0 (CCV-based lanes, which live testnet lanes run today).
Enums
CCIPEra
enum CCIPEra { UNKNOWN, PRE_V1_DOT_6, V1_DOT_6, V2 }
V2VerificationMode
enum V2VerificationMode { STRICT, HYBRID, SYNTHETIC_ONLY, OFFRAMP_DERIVED }
V2ExecutionMode
enum V2ExecutionMode { AUTO, RESPECT_NO_EXEC, MANUAL_ONLY }
MessageStatus
enum MessageStatus { NOT_FOUND, QUEUED, FAILED, SUCCESS }
Structs
MessageOutcome
struct MessageOutcome {
MessageStatus status;
bytes reason;
}
| Field | Type | Description |
|---|---|---|
| status | MessageStatus | The outcome of the message |
| reason | bytes | For FAILED: the revert data, or an Error(string) explaining why the message was not routed. Empty otherwise. |
Errors
CCIPLocalSimulatorFork__MessageNotRouted
error CCIPLocalSimulatorFork__MessageNotRouted(bytes32 messageId, string reason)
CCIPLocalSimulatorFork__MessageExecutionFailed
error CCIPLocalSimulatorFork__MessageExecutionFailed(bytes32 messageId, bytes reason)
Variables
i_register
Register immutable i_register
LINK_FAUCET
address constant LINK_FAUCET = 0x4281eCF07378Ee595C564a59048801330f3084eE
s_processedMessages
mapping(bytes32 messageId => bool isProcessed) internal s_processedMessages
s_messageOutcomes
mapping(bytes32 messageId => MessageOutcome outcome) internal s_messageOutcomes
s_strictRouting
bool internal s_strictRouting
s_ccipV2Routers
mapping(uint256 chainId => address router) internal s_ccipV2Routers
Functions
constructor
Initializes the contract and sets up logging and persistence.
constructor()
switchChainAndRouteMessage
Routes a cross-chain message on the destination network after switching to the specified fork.
function switchChainAndRouteMessage(uint256 forkId) external
Parameters
| Parameter | Type | Description |
|---|---|---|
| forkId | uint256 | The ID of the destination network fork (returned by createFork() or createSelectFork()) |
switchChainAndRouteMessage (multiple forks)
Override variant of switchChainAndRouteMessage(uint256 forkId) for multiple destination forks.
function switchChainAndRouteMessage(uint256[] memory forkIds) external
Parameters
| Parameter | Type | Description |
|---|---|---|
| forkIds | uint256[] | The IDs of the destination network forks |
getNetworkDetails
Returns the network configuration details for a specified chain ID.
function getNetworkDetails(uint256 chainId) external view returns (Register.NetworkDetails memory)
Parameters
| Parameter | Type | Description |
|---|---|---|
| chainId | uint256 | The blockchain network chain ID (e.g., 11155111 for Ethereum Sepolia) |
Returns
| Parameter | Type | Description |
|---|---|---|
| (unnamed) | NetworkDetails | The network configuration details for the specified chain |
setNetworkDetails
Updates or adds new network configuration details for a specified chain ID.
function setNetworkDetails(uint256 chainId, Register.NetworkDetails memory networkDetails) external
Parameters
| Parameter | Type | Description |
|---|---|---|
| chainId | uint256 | The blockchain network chain ID (e.g., 11155111 for Ethereum Sepolia) |
| networkDetails | NetworkDetails | The network configuration details to be stored |
getCCIPV2RouterAddress
Returns the CCIP 2.0 router for a chain, or address(0) if none is known.
function getCCIPV2RouterAddress(uint256 chainId) external view returns (address)
Parameters
| Parameter | Type | Description |
|---|---|---|
| chainId | uint256 | The blockchain network chain ID |
setCCIPV2RouterAddress
Manually sets the CCIP 2.0 router for a chain.
function setCCIPV2RouterAddress(uint256 chainId, address router) external
Parameters
| Parameter | Type | Description |
|---|---|---|
| chainId | uint256 | The blockchain network chain ID |
| router | address | The CCIP 2.0 router address to set |
getOffRampForLane
Returns the destination OffRamp configured for a source OnRamp on the given fork.
function getOffRampForLane(uint256 forkId, uint64 sourceChainSelector, address sourceOnRamp) external returns (address offRamp)
Parameters
| Parameter | Type | Description |
|---|---|---|
| forkId | uint256 | The ID of the destination network fork |
| sourceChainSelector | uint64 | The chain selector of the source chain |
| sourceOnRamp | address | The address of the OnRamp on the source chain |
Returns
| Parameter | Type | Description |
|---|---|---|
| offRamp | address | The matching OffRamp address, or address(0) when not found |
setLaneDefaultCCVs
Points a destination lane's default CCVs at a CCV address by impersonating the OffRamp owner.
function setLaneDefaultCCVs(uint256 forkId, address offRamp, uint64 sourceChainSelector, address ccv) external
Parameters
| Parameter | Type | Description |
|---|---|---|
| forkId | uint256 | The ID of the destination network fork |
| offRamp | address | The destination OffRamp that holds the lane config |
| sourceChainSelector | uint64 | The chain selector of the source chain |
| ccv | address | The CCV address to set as the lane default |
requestLinkFromFaucet
Requests LINK tokens from the faucet for a specified address.
function requestLinkFromFaucet(address to, uint256 amount) external returns (bool success)
Parameters
| Parameter | Type | Description |
|---|---|---|
| to | address | The address to receive the LINK tokens |
| amount | uint256 | The amount of LINK tokens to transfer |
Returns
| Parameter | Type | Description |
|---|---|---|
| success | bool | Returns true if the token transfer was successful |
setStrictRouting
Enables or disables strict routing (enabled by default).
function setStrictRouting(bool strict) external
Parameters
| Parameter | Type | Description |
|---|---|---|
| strict | bool | Whether to enable (true) or disable (false) strict routing |
getStrictRouting
Returns whether strict routing is enabled.
function getStrictRouting() external view returns (bool strict)
getMessageStatus
Returns the outcome of a captured CCIP message.
function getMessageStatus(bytes32 messageId) external view returns (MessageStatus status, bytes memory reason)
Parameters
| Parameter | Type | Description |
|---|---|---|
| messageId | bytes32 | The CCIP message ID |
Returns
| Parameter | Type | Description |
|---|---|---|
| status | MessageStatus | NOT_FOUND, QUEUED, FAILED or SUCCESS |
| reason | bytes | For FAILED: the revert data of the execution, or an Error(string) explaining why the message was not routed. Empty otherwise. |
setV2VerificationMode
Sets how CCIP 2.0 messages are verified when routed.
function setV2VerificationMode(V2VerificationMode mode) external
Parameters
| Parameter | Type | Description |
|---|---|---|
| mode | V2VerificationMode | The verification mode to set |
getV2VerificationMode
Returns the current CCIP 2.0 verification mode.
function getV2VerificationMode() external view returns (V2VerificationMode mode)
setV2ExecutionMode
Sets how NO_EXECUTION_ADDRESS (manual execution) CCIP 2.0 messages are handled.
function setV2ExecutionMode(V2ExecutionMode mode) external
Parameters
| Parameter | Type | Description |
|---|---|---|
| mode | V2ExecutionMode | The execution mode to set |
getV2ExecutionMode
Returns the current CCIP 2.0 execution mode.
function getV2ExecutionMode() external view returns (V2ExecutionMode mode)
getPendingV2MessageIds
Returns the message IDs of pending CCIP 2.0 NO_EXECUTION_ADDRESS messages on the current route scope.
function getPendingV2MessageIds() external view returns (bytes32[] memory messageIds)
isPendingV2Message
Checks whether a CCIP 2.0 message is pending manual execution.
function isPendingV2Message(bytes32 messageId) external view returns (bool isPending)
executePendingV2Message
Executes a pending CCIP 2.0 NO_EXECUTION_ADDRESS message on the current fork.
function executePendingV2Message(bytes32 messageId) external returns (bool attempted)
Parameters
| Parameter | Type | Description |
|---|---|---|
| messageId | bytes32 | The CCIP message ID to execute |
Returns
| Parameter | Type | Description |
|---|---|---|
| attempted | bool | Whether an execution was attempted on the current fork |