Skip to content
Developers
General Message Passing
Send Messages with Tokens

Call a contract on chain B from chain A and attach some tokens

To call chain B from chain A and send some tokens 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 AxelarExecutable defined in AxelarExecutable.sol (opens in a new tab).
  • 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.

As per the snippet below:

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

AxelarExecutable 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(
    string memory sourceChain,
    string memory sourceAddress,
    bytes calldata payload,
    string memory tokenSymbol,
    uint256 amount
) internal virtual {}

Example

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(
    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.

Example of payload encoding in JavaScript (using ethers.js):

const { ethers } = require("ethers");
 
// encoding a string
const payload = ethers.utils.defaultAbiCoder.encode(
  ["string"],
  ["Hello from contract A"]
);

Example of payload decoding in Solidity:

function _execute(
    string memory sourceChain,
    string memory sourceAddress,
    bytes calldata payload
) internal override {
    // decoding a string
    string memory _message = abi.decode(payload, (string));
}