CCIP v1.5.1 Client Library API Reference

npm install @chainlink/contracts-ccip@1.5.1-beta.0

yarn add @chainlink/contracts-ccip@1.5.1-beta.0

If you use Foundry, install the package:

forge install smartcontractkit/ccip@5e7b2096586bc32c6e975fc13f4c411eb687f833

CCIP senders and receivers use the CCIP Client library to build CCIP messages.

import { Client } from "@chainlink/contracts-ccip/src/v0.8/ccip/libraries/Client.sol";

Types and Constants

Use this solidity struct to specify the token address and amount.

struct EVMTokenAmount {
  address token;
  uint256 amount;
}

Name	Type	Description
token	address	token address on the local chain.
amount	uint256	Amount of tokens.

CCIP receivers use this solidity struct to parse the received CCIP message.

struct Any2EVMMessage {
  bytes32 messageId;
  uint64 sourceChainSelector;
  bytes sender;
  bytes data;
  EVMTokenAmount[] destTokenAmounts;
}

Name	Type	Description
messageId	bytes32	CCIP messageId, generated on the source chain.
sourceChainSelector	uint64	Source chain selector.
sender	bytes	Sender address. `abi.decode(sender, (address))` if the source chain is an EVM chain.
data	bytes	Payload sent within the CCIP message.
destTokenAmounts	EVMTokenAmount[]	Tokens and their amounts in their destination chain representation.

CCIP senders use this solidity struct to build a CCIP message.

struct EVM2AnyMessage {
  bytes receiver;
  bytes data;
  EVMTokenAmount[] tokenAmounts;
  address feeToken;
  bytes extraArgs;
}

Name	Type	Description
receiver	bytes	abi.encode(receiver address) for destination EVM chains.
data	bytes	Data payload.
tokenAmounts	EVMTokenAmount[]	Token transfers.
feeToken	address	Address of feeToken. address(0) means you will send msg.value.
extraArgs	bytes	Populate this with _argsToBytes(EVMExtraArgsV2).

bytes4 public constant EVM_EXTRA_ARGS_V1_TAG = 0x97a657c9;

struct EVMExtraArgsV1 {
  uint256 gasLimit;
}

bytes4 public constant EVM_EXTRA_ARGS_V2_TAG = 0x181dcf10;

struct EVMExtraArgsV2 {
  uint256 gasLimit;
  bool allowOutOfOrderExecution;
}

Name	Type	Description
gasLimit	uint256	specifies the maximum amount of gas CCIP can consume to execute `ccipReceive()` on the contract located on the destination blockchain. Read Setting gasLimit for more details.
allowOutOfOrderExecution	bool	if true, it indicates that the message can be executed in any order relative to other messages from the same sender. This value's default varies by chain. On some chains, a particular value is enforced, meaning if the expected value is not set, the message request will revert.

function _argsToBytes(struct Client.EVMExtraArgsV1 extraArgs) internal pure returns (bytes bts)

It is used to convert the arguments to bytes.

Name	Type	Description
extraArgs	Client.EVMExtraArgsV1	Extra arguments.

Name	Type	Description
bts	bytes	Encoded extra arguments in bytes.

function _argsToBytes(struct Client.EVMExtraArgsV2 extraArgs) internal pure returns (bytes bts)

It is used to convert the arguments to bytes.

Name	Type	Description
extraArgs	Client.EVMExtraArgsV2	Extra arguments.

Name	Type	Description
bts	bytes	Encoded extra arguments in bytes.