Transfer Tokens with Data

In this tutorial, you will use Chainlink CCIP to transfer tokens and arbitrary data between smart contracts on different blockchains. First, you will pay for the CCIP fees on the source blockchain using LINK. Then, you will use the same contract to pay CCIP fees in native gas tokens. For example, you would use ETH on Ethereum or AVAX on Avalanche.

Before you begin

  1. You should understand how to write, compile, deploy, and fund a smart contract. If you need to brush up on the basics, read this tutorial, which will guide you through using the Solidity programming language, interacting with the MetaMask wallet and working within the Remix Development Environment.
  2. Your account must have some AVAX and LINK tokens on Avalanche Fuji and ETH tokens on Ethereum Sepolia. Learn how to Acquire testnet LINK.
  3. Check the CCIP Directory to confirm that the tokens you will transfer are supported for your lane. In this example, you will transfer tokens from Avalanche Fuji to Ethereum Sepolia so check the list of supported tokens here.
  4. Learn how to acquire CCIP test tokens. Following this guide, you should have CCIP-BnM tokens, and CCIP-BnM should appear in the list of your tokens in MetaMask.
  5. Learn how to fund your contract. This guide shows how to fund your contract in LINK, but you can use the same guide for funding your contract with any ERC20 tokens as long as they appear in the list of tokens in MetaMask.
  6. Follow the previous tutorial: Transfer tokens.

Tutorial

In this tutorial, you will send a string text and CCIP-BnM tokens between smart contracts on Avalanche Fuji and Ethereum Sepolia using CCIP. First, you will pay CCIP fees in LINK, then you will pay CCIP fees in native gas.

undefined
Open in Remix What is Remix?

Deploy your contracts

To use this contract:

  1. Open the contract in Remix.

  2. Compile your contract.

  3. Deploy, fund your sender contract on Avalanche Fuji and enable sending messages to Ethereum Sepolia:

    1. Open MetaMask and select the network Avalanche Fuji.
    2. In Remix IDE, click on Deploy & Run Transactions and select Injected Provider - MetaMask from the environment list. Remix will then interact with your MetaMask wallet to communicate with Avalanche Fuji.
    3. Fill in your blockchain's router and LINK contract addresses. The router address can be found on the CCIP Directory and the LINK contract address on the LINK token contracts page. For Avalanche Fuji:
      • The router address is 0xF694E193200268f9a4868e4Aa017A0118C9a8177,
      • The LINK contract address is 0x0b9d5D9136855f6FEc3c0993feE6E9CE8a297846.
    4. Click the transact button. After you confirm the transaction, the contract address appears on the Deployed Contracts list. Note your contract address.
    5. Open MetaMask and fund your contract with CCIP-BnM tokens. You can transfer 0.002 CCIP-BnM to your contract.
    6. Enable your contract to send CCIP messages to Ethereum Sepolia:
      1. In Remix IDE, under Deploy & Run Transactions, open the list of functions of your smart contract deployed on Avalanche Fuji.
      2. Call the allowlistDestinationChain, setting the destination chain selector to 16015286601757825753 and setting allowed to true. Each chain selector is found on the CCIP Directory.

  4. Deploy your receiver contract on Ethereum Sepolia and enable receiving messages from your sender contract:

    1. Open MetaMask and select the network Ethereum Sepolia.
    2. In Remix IDE, under Deploy & Run Transactions, make sure the environment is still Injected Provider - MetaMask.
    3. Fill in your blockchain's router and LINK contract addresses. The router address can be found on the CCIP Directory and the LINK contract address on the LINK token contracts page. For Ethereum Sepolia, the router address is 0x0BF3dE8c5D3e8A2B34D2BEeB17ABfCeBaf363A59 and the LINK contract address is 0x779877A7B0D9E8603169DdbD7836e478b4624789.
    4. Click the transact button. After you confirm the transaction, the contract address appears on the Deployed Contracts list. Note your contract address.
    5. Enable your contract to receive CCIP messages from Avalanche Fuji:
      1. In Remix IDE, under Deploy & Run Transactions, open the list of functions of your smart contract deployed on Ethereum Sepolia.
      2. Call the allowlistSourceChain with 14767482510784806043 as the source chain selector, and true as allowed. Each chain selector is found on the CCIP Directory.
    6. Enable your contract to receive CCIP messages from the contract that you deployed on Avalanche Fuji:
      1. In Remix IDE, under Deploy & Run Transactions, open the list of functions of your smart contract deployed on Ethereum Sepolia.
      2. Call the allowlistSender with the contract address of the contract that you deployed on Avalanche Fuji, and true as allowed.

At this point, you have one sender contract on Avalanche Fuji and one receiver contract on Ethereum Sepolia. As security measures, you enabled the sender contract to send CCIP messages to Ethereum Sepolia and the receiver contract to receive CCIP messages from the sender on Avalanche Fuji.

Note: Another security measure enforces that only the router can call the _ccipReceive function. Read the explanation section for more details.

You will transfer 0.001 CCIP-BnM and a text. The CCIP fees for using CCIP will be paid in LINK. Read this explanation for a detailed description of the code example.

  1. Open MetaMask and connect to Avalanche Fuji. Fund your contract with LINK tokens. You can transfer 70 LINK to your contract. In this example, LINK is used to pay the CCIP fees.

    Note: This transaction fee is significantly higher than normal due to gas spikes on Sepolia. To run this example, you can get additional testnet LINK from faucets.chain.link or use a supported testnet other than Sepolia.

  2. Send a string data with tokens from Avalanche Fuji:

    1. Open MetaMask and select the network Avalanche Fuji.

    2. In Remix IDE, under Deploy & Run Transactions, open the list of functions of your smart contract deployed on Avalanche Fuji.

    3. Fill in the arguments of the sendMessagePayLINK function:


      ArgumentValue and Description
      _destinationChainSelector16015286601757825753
      CCIP Chain identifier of the destination blockchain (Ethereum Sepolia in this example). You can find each chain selector on the CCIP Directory.
      _receiverYour receiver contract address on Ethereum Sepolia.
      The destination contract address.
      _textHello World!
      Any string
      _token0xD21341536c5cF5EB1bcb58f6723cE26e8D8E90e4
      The CCIP-BnM contract address at the source chain (Avalanche Fuji in this example). You can find all the addresses for each supported blockchain on the CCIP Directory.
      _amount1000000000000000
      The token amount (0.001 CCIP-BnM).

    4. Click on transact and confirm the transaction on MetaMask.

    5. After the transaction is successful, record the transaction hash. Here is an example of a transaction on Avalanche Fuji.

  3. Open the CCIP explorer and search your cross-chain transaction using the transaction hash.


  4. The CCIP transaction is completed once the status is marked as "Success". In this example, the CCIP message ID is 0x99a15381125e740c43a60f03c6b011ae05a3541998ca482fb5a4814417627df8.


  5. Check the receiver contract on the destination chain:

    1. Open MetaMask and select the network Ethereum Sepolia.

    2. In Remix IDE, under Deploy & Run Transactions, open the list of functions of your smart contract deployed on Ethereum Sepolia.

    3. Call the getLastReceivedMessageDetails function.


    4. Notice the received messageId is 0x99a15381125e740c43a60f03c6b011ae05a3541998ca482fb5a4814417627df8, the received text is Hello World!, the token address is 0xFd57b4ddBf88a4e07fF4e34C487b99af2Fe82a05 (CCIP-BnM token address on Ethereum Sepolia) and the token amount is 1000000000000000 (0.001 CCIP-BnM).

Note: These example contracts are designed to work bi-directionally. As an exercise, you can use them to transfer tokens with data from Avalanche Fuji to Ethereum Sepolia and from Ethereum Sepolia back to Avalanche Fuji.

Transfer and Receive tokens and data and pay in native

You will transfer 0.001 CCIP-BnM and a text. The CCIP fees for using CCIP will be paid in Avalanche's native AVAX. Read this explanation for a detailed description of the code example.

  1. Open MetaMask and connect to Avalanche Fuji. Fund your contract with AVAX tokens. You can transfer 0.2 AVAX to your contract. The native gas tokens are used to pay the CCIP fees.

  2. Send a string data with tokens from Avalanche Fuji:

    1. Open MetaMask and select the network Avalanche Fuji.

    2. In Remix IDE, under Deploy & Run Transactions, open the list of functions of your smart contract deployed on Avalanche Fuji.

    3. Fill in the arguments of the sendMessagePayNative function:


      ArgumentValue and Description
      _destinationChainSelector16015286601757825753
      CCIP Chain identifier of the destination blockchain (Ethereum Sepolia in this example). You can find each chain selector on the CCIP Directory.
      _receiverYour receiver contract address at Ethereum Sepolia.
      The destination contract address.
      _textHello World!
      Any string
      _token0xD21341536c5cF5EB1bcb58f6723cE26e8D8E90e4
      The CCIP-BnM contract address at the source chain (Avalanche Fuji in this example). You can find all the addresses for each supported blockchain on the CCIP Directory.
      _amount1000000000000000
      The token amount (0.001 CCIP-BnM).

    4. Click on transact and confirm the transaction on MetaMask.

    5. Once the transaction is successful, note the transaction hash. Here is an example of a transaction on Avalanche Fuji.

  3. Open the CCIP explorer and search your cross-chain transaction using the transaction hash.


  4. The CCIP transaction is completed once the status is marked as "Success". In this example, the CCIP message ID is 0x32bf96ac8b01fe3f04ffa548a3403b3105b4ed479eff407ff763b7539a1d43bd. Note that CCIP fees are denominated in LINK. Even if CCIP fees are paid using native gas tokens, node operators will be paid in LINK.


  5. Check the receiver contract on the destination chain:

    1. Open MetaMask and select the network Ethereum Sepolia.

    2. In Remix IDE, under Deploy & Run Transactions, open the list of functions of your smart contract deployed on Ethereum Sepolia.

    3. Call the getLastReceivedMessageDetails function.


    4. Notice the received messageId is 0x32bf96ac8b01fe3f04ffa548a3403b3105b4ed479eff407ff763b7539a1d43bd, the received text is Hello World!, the token address is 0xFd57b4ddBf88a4e07fF4e34C487b99af2Fe82a05 (CCIP-BnM token address on Ethereum Sepolia) and the token amount is 1000000000000000 (0.001 CCIP-BnM).

Note: These example contracts are designed to work bi-directionally. As an exercise, you can use them to transfer tokens with data from Avalanche Fuji to Ethereum Sepolia and from Ethereum Sepolia back to Avalanche Fuji.

Explanation

The smart contract featured in this tutorial is designed to interact with CCIP to transfer and receive tokens and data. The contract code contains supporting comments clarifying the functions, events, and underlying logic. Here we will further explain initializing the contract and sending data with tokens.

Initializing the contract

When deploying the contract, we define the router address and LINK contract address of the blockchain we deploy the contract on. Defining the router address is useful for the following:

  • Sender part:

    • Calls the router's getFee function to estimate the CCIP fees.
    • Calls the router's ccipSend function to send CCIP messages.

  • Receiver part:

    • The contract inherits from CCIPReceiver, which serves as a base contract for receiver contracts. This contract requires that child contracts implement the _ccipReceive function. _ccipReceive is called by the ccipReceive function, which ensures that only the router can deliver CCIP messages to the receiver contract.

The sendMessagePayLINK function undertakes six primary operations:

  1. Call the _buildCCIPMessage private function to construct a CCIP-compatible message using the EVM2AnyMessage struct:

    • The _receiver address is encoded in bytes to accommodate non-EVM destination blockchains with distinct address formats. The encoding is achieved through abi.encode.

    • The data is encoded from a string to bytes using abi.encode.

    • The tokenAmounts is an array, with each element comprising an EVMTokenAmount struct containing the token address and amount. The array contains one element where the _token (token address) and _amount (token amount) are passed by the user when calling the sendMessagePayLINK function.

    • The extraArgs specifies the gasLimit for relaying the message to the recipient contract on the destination blockchain. In this example, the gasLimit is set to `200000.

    • The _feeTokenAddress designates the token address used for CCIP fees. Here, address(linkToken) signifies payment in LINK.

  2. Computes the fees by invoking the router's getFee function.

  3. Ensures your contract balance in LINK is enough to cover the fees.

  4. Grants the router contract permission to deduct the fees from the contract's LINK balance.

  5. Grants the router contract permission to deduct the amount from the contract's CCIP-BnM balance.

  6. Dispatches the CCIP message to the destination chain by executing the router's ccipSend function.

Note: As a security measure, the sendMessagePayLINK function is protected by the onlyAllowlistedDestinationChain, ensuring the contract owner has allowlisted a destination chain.

Transferring tokens and data and pay in native

The sendMessagePayNative function undertakes five primary operations:

  1. Call the _buildCCIPMessage private function to construct a CCIP-compatible message using the EVM2AnyMessage struct:

    • The _receiver address is encoded in bytes to accommodate non-EVM destination blockchains with distinct address formats. The encoding is achieved through abi.encode.

    • The data is encoded from a string to bytes using abi.encode.

    • The tokenAmounts is an array, with each element comprising an EVMTokenAmount struct containing the token address and amount. The array contains one element where the _token (token address) and _amount (token amount) are passed by the user when calling the sendMessagePayNative function.

    • The extraArgs specifies the gasLimit for relaying the message to the recipient contract on the destination blockchain. In this example, the gasLimit is set to `200000.

    • The _feeTokenAddress designates the token address used for CCIP fees. Here, address(0) signifies payment in native gas tokens (ETH).

  2. Computes the fees by invoking the router's getFee function.

  3. Ensures your contract balance in native gas is enough to cover the fees.

  4. Grants the router contract permission to deduct the amount from the contract's CCIP-BnM balance.

  5. Dispatches the CCIP message to the destination chain by executing the router's ccipSend function. Note: msg.value is set because you pay in native gas.

Note: As a security measure, the sendMessagePayNative function is protected by the onlyAllowlistedDestinationChain, ensuring the contract owner has allowlisted a destination chain.

Receiving messages

On the destination blockchain, the router invokes the _ccipReceive function which expects a Any2EVMMessage struct that contains:

  • The CCIP messageId.
  • The sourceChainSelector.
  • The sender address in bytes format. Given that the sender is known to be a contract deployed on an EVM-compatible blockchain, the address is decoded from bytes to an Ethereum address using the ABI specifications.
  • The tokenAmounts is an array containing received tokens and their respective amounts. Given that only one token transfer is expected, the first element of the array is extracted.
  • The data, which is also in bytes format. Given a string is expected, the data is decoded from bytes to a string using the ABI specifications.

Note: Three important security measures are applied:

  • _ccipReceive is called by the ccipReceive function, which ensures that only the router can deliver CCIP messages to the receiver contract. See the onlyRouter modifier for more information.
  • The modifier onlyAllowlisted ensures that only a call from an allowlisted source chain and sender is accepted.

What's next

Get the latest Chainlink content straight to your inbox.