Interchain Token Service Executable

You can use the Axelar Interchain Token Service (ITS) to create a new Interchain Token or integrate an existing ERC-20 token to ITS to give your token bridging functionality. ITS also allows you to send custom messages when making a cross-chain transfer for an ITS token, enabling you to execute specific logic on the destination chain.

If you want your token transfers to trigger custom logic on the destination chain, the destination contract must implement the InterchainTokenExecutable interface.

Once your token has been deployed and integrated with ITS, you can use the executable functionality to send messages along with your cross-chain token transfer.

Send Token + Message from Source Chain

To send a token transfer with a custom message, use the interchainTransfer() function from the Interchain Token Service contract. You should provide the tokenId, destinationChain, destinationAddress, amount, and metadata as parameters.

/**
 * @notice Initiates an interchain transfer of tokens through the token service.
 * @param tokenId The token ID.
 * @param destinationChain The destination chain.
 * @param destinationAddress The destination address (bytes format).
 * @param amount The amount of tokens to transfer.
 * @param metadata Metadata for the interchain transfer. To execute a contract on the destination,
 *      format as bytes.concat(bytes4(0), yourCustomPayload).
 */
function interchainTransfer(
    bytes32 tokenId,
    string calldata destinationChain,
    bytes calldata destinationAddress,
    uint256 amount,
    bytes calldata metadata
) external payable {}

🚨

  • The destinationAddress should be an address encoded as bytes. Use the toBytes() method to accomplish this on-chain.
  • To execute code on the destination chain, the metadata parameter should be formatted as: bytes.concat(bytes4(0), yourCustomPayload). The leading bytes4(0) signals this is an executable transfer.

When the tokens arrive on the destination chain, if the destination address implements the InterchainTokenExecutable interface, the system will:

  1. Transfer the tokens to your contract.
  2. Call the _executeWithInterchainToken() function on your contract.

Your contract needs to implement the _executeWithInterchainToken() function that contains your custom logic:

/**
 * @notice Internal function containing the logic to be executed with interchain token transfer.
 * derived contracts must implement @dev Logic.
 * @param commandId The unique message id.
 * @param sourceChain The source chain of the token transfer.
 * @param sourceAddress The source address of the token transfer.
 * @param data The custom data payload you included in the metadata.
 * @param tokenId The token ID.
 * @param token The token address.
 * @param amount The amount of tokens being transferred.
 */
function _executeWithInterchainToken(
    bytes32 commandId,
    string calldata sourceChain,
    bytes calldata sourceAddress,
    bytes calldata data,
    bytes32 tokenId,
    address token,
    uint256 amount
) internal virtual;

The transferred amount is accessible in the amount parameter, and any additional data you included is available in the data parameter.

Here’s a simple example of a contract that implements the InterchainTokenExecutable interface:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;


import "@axelar-network/interchain-token-service/contracts/executable/InterchainTokenExecutable.sol";


contract MyDestinationContract is InterchainTokenExecutable {
    // Event to log received transfers
    event TokensReceived(
        string sourceChain,
        bytes sourceAddress,
        uint256 amount,
        bytes data
 );


    /**
 * @notice Handle incoming token transfers with custom logic
 */
    function _executeWithInterchainToken(
        bytes32 commandId,
        string calldata sourceChain,
        bytes calldata sourceAddress,
        bytes calldata data,
        bytes32 tokenId,
        address token,
        uint256 amount
 ) internal override {
        // Access the transferred amount directly from the amount parameter


        // Decode any custom data you sent
        // Example: (uint256 value) = abi.decode(data, (uint256));


        // Your custom logic here


        // Emit an event for logging
 emit TokensReceived(sourceChain, sourceAddress, amount, data);
 }
}

To find more examples of how to utilize the Interchain Token Service and test the Interchain Token Service Executable, please refer to the axelar-examples repository on GitHub.

Edit on GitHub