Encoding and Decoding Messages

How to encode and decode the bytes payload of an ICM message with abi.encode and abi.decode, including how to route multiple actions with a double encoding.

An ICM message carries a single bytes value. Your contracts decide what is inside it. The sender encodes the data with abi.encode, and the receiver decodes it with abi.decode. Both are part of Solidity, so you do not need to import anything.

Note

Learn more

The Interchain Messaging course covers bytes, encoding and decoding step by step.

Encode and Decode Values

The sender encodes any number of values into one bytes value and passes it as the message field of TeleporterMessageInput.

string memory someString = "test";
uint256 someNumber = 42;

bytes memory message = abi.encode(someString, someNumber);

The receiver decodes the message parameter of receiveTeleporterMessage. It must use the same types, in the same order.

(string memory someString, uint256 someNumber) = abi.decode(message, (string, uint256));

If the types or the order differ between sender and receiver, the decode reverts or returns wrong values.

Route Multiple Actions with a Double Encoding

A receiver often handles more than one kind of message, and each kind has different parameters. The common pattern is to encode twice:

  1. Inner encoding: the parameters of the action, encoded into bytes.
  2. Outer encoding: an enum that identifies the action, together with the inner bytes.

The receiver decodes the outer layer first to learn the action. The action then tells it which types to use to decode the inner layer.

Send

enum Action {
    SetGreeting,
    SetNumber
}

function sendSetGreeting(string memory greeting) external {
    // 1. Inner encoding: the parameters of this action
    bytes memory params = abi.encode(greeting);

    // 2. Outer encoding: the action and its encoded parameters
    bytes memory message = abi.encode(Action.SetGreeting, params);

    // Pass `message` as the `message` field of TeleporterMessageInput
}

function sendSetNumber(uint256 number, address account) external {
    bytes memory params = abi.encode(number, account);
    bytes memory message = abi.encode(Action.SetNumber, params);
}

Receive

function receiveTeleporterMessage(
    bytes32 sourceBlockchainID,
    address originSenderAddress,
    bytes calldata message
) external {
    // Only the Teleporter messenger can deliver a message.
    require(msg.sender == address(teleporterMessenger), "Unauthorized.");

    // 1. Outer decoding: which action is it, and what are its raw parameters?
    (Action action, bytes memory params) = abi.decode(message, (Action, bytes));

    // 2. Inner decoding: the action decides which types to use
    if (action == Action.SetGreeting) {
        string memory greeting = abi.decode(params, (string));
        _setGreeting(greeting);
    } else if (action == Action.SetNumber) {
        (uint256 number, address account) = abi.decode(params, (uint256, address));
        _setNumber(number, account);
    }
}

Keep the enum and the parameter types in a shared file that both the sending and the receiving contract import, so they cannot drift apart.

Example: Interchain Token Transfer

The Interchain Token Transfer contracts use this pattern. The action is the enum TransferrerMessageType, and the two layers are wrapped in a struct. These definitions are in ITokenTransferrer.sol:

enum TransferrerMessageType {
    REGISTER_REMOTE,
    SINGLE_HOP_SEND,
    SINGLE_HOP_CALL,
    MULTI_HOP_SEND,
    MULTI_HOP_CALL
}

struct TransferrerMessage {
    TransferrerMessageType messageType;
    bytes payload;
}

struct SingleHopSendMessage {
    address recipient;
    uint256 amount;
}

When a TokenRemote sends tokens back to its TokenHome, it encodes the inner payload and wraps it:

TransferrerMessage memory message = TransferrerMessage({
    messageType: TransferrerMessageType.SINGLE_HOP_SEND,
    payload: abi.encode(SingleHopSendMessage({recipient: input.recipient, amount: amount}))
});
// The Teleporter message field is abi.encode(message)

TokenHome decodes the outer struct, reads messageType, and decodes payload with the matching struct:

TransferrerMessage memory transferrerMessage = abi.decode(message, (TransferrerMessage));

if (transferrerMessage.messageType == TransferrerMessageType.SINGLE_HOP_SEND) {
    SingleHopSendMessage memory payload =
        abi.decode(transferrerMessage.payload, (SingleHopSendMessage));
    // ... release the tokens to payload.recipient
}

Each action has its own struct for the parameters (RegisterRemoteMessage, SingleHopSendMessage, MultiHopCallMessage and so on), and all of them travel in the same Teleporter message field.

Is this guide helpful?