EVM Cross-Chain Gateway Token Transfers

To call chain B from chain A and send some tokens supported by the gateway along the way, the user needs to call callContractWithToken on the gateway of chain A, specifying:

  • The destination chain, which must be an EVM chain from Chain names.
  • The destination contract address, which must inherit from AxelarExecutableWithToken defined in AxelarExecutableWithToken.sol.
  • The payload bytes to pass to the destination contract.
  • The symbol of the token to transfer, which must be a supported asset (Mainnet | Testnet).
  • The amount of the token to transfer.

Gateway tokens, as the name implies, are tokens supported at the Axelar core gateway layer. You can find the list of tokens supported here.

🚨

NOTE: The security of your contracts, and the tokens passed between them, is limited to the security of the chains they integrate with. Since blockchains can have different security practices, we recommend doing due diligence on all chains your contract will be deployed to.

As per the snippet below:

function callContractWithToken(
    string memory destinationChain,
    string memory contractAddress,
    bytes memory payload,
    string memory symbol,
    uint256 amount
) external;

The AxelarExecutableWithToken has an executeWithToken function that will be triggered by the Axelar network on the destination chain after the callContractWithToken function has been executed on the source chain. This will validate the contract call and then invoke your _executeWithToken method, where you should write any custom logic.

The destination contract will be authorized to transfer the ERC-20 identified by the tokenSymbol.

function _executeWithToken(
    bytes32 commandId,
    string memory sourceChain,
    string memory sourceAddress,
    bytes calldata payload,
    string memory tokenSymbol,
    uint256 amount
) internal virtual {}

Suppose our destination contract wants to forward the token it received to a recipient provided in the payload. It could be done this way.

function _executeWithToken(
    bytes32 commandId,
    string memory sourceChain,
    string memory sourceAddress,
    bytes calldata payload,
    string memory tokenSymbol,
    uint256 amount
) internal virtual {
    // decode recipient
    address recipient = abi.decode(payload, (address));
    // get ERC-20 address from gateway
    address tokenAddress = gateway.tokenAddresses(tokenSymbol);


    // transfer received tokens to the recipient
    IERC20(tokenAddress).transfer(recipient, amount);
}

ℹ️

Ensure the payload is encoded bytes!

The payload passed to callContract (and ultimately to the _execute and _executeWithToken) has type bytes. Use the ABI encoder/decoder convert your data to bytes.

const { ethers } = require("ethers");


// encoding a string
const payload = ethers.utils.defaultAbiCoder.encode(
  ["string"],
  ["Hello from contract A"],
);
function _execute(
    bytes32 commandId,
    string memory sourceChain,
    string memory sourceAddress,
    bytes calldata payload
) internal override {
    // decoding a string
    string memory _message = abi.decode(payload, (string));
}

Learn More: Explore our tutorial on building a decentralized application (dApp) for cross-chain airdrops using Solidity, Next.js, and Axelar’s General Message Passing with callContractWithToken. This tutorial will guide you through the process of distributing tokens across multiple chains: How to Build a Cross-Chain Airdrop DApp With Solidity, Next.js, and Axelar.

Edit on GitHub