Omnichain Composers

Crosschain composability has long been a goal for developers building advanced, interconnected decentralized applications. LayerZero V2 introduces horizontal composability — a concept that empowers developers to spread out crosschain calls into multiple, discrete steps.

Prerequisites

Before diving into LayerZero V2 Horizontal Composability, it’s essential to have a foundational understanding of the following concepts:

Solidity Interfaces: Knowledge of defining and implementing interfaces in Solidity.
Solidity Interface Composability: Grasping how interfaces facilitate composability between contracts.

Having familiarity with these topics will enable a smoother comprehension of the concepts discussed.

Workflow

LayerZero V2 supports both Vertical and Horizontal Composability within crosschain calls.

What is Vertical Composability?

Vertical Composability is the traditional model of composability in blockchain applications, where multiple function calls from different contracts are stacked within a single transaction.

// Example of vertical composability with atomicity
function _lzReceive(
    Origin calldata /*_origin*/,
    bytes32 /*_guid*/,
    bytes calldata /*_message*/,
    address /*_executor*/,
    bytes calldata /*_extraData*/
) internal override {
    contractA.functionA();
    contractB.functionB();
    contractC.functionC();
    // If any of the above calls fail, the entire transaction reverts
}

All function calls in the stack execute atomically. This means that either all operations succeed, or the entire transaction reverts if any single operation fails.

Vertical composability can present potential Atomicity Issues in crosschain interactions:

If an operation on one contract fails, it can produce unintended reversions or inconsistencies across the entire stack. This limits the ability to have instant finality guarantees when receiving crosschain messages.

In crosschain contracts, you should minimize the impact of potential message failure by performing only one action per message.

What is Horizontal Composability?

Horizontal Composability is an implementation in LayerZero V2 to address the limitations of vertical composability in crosschain interactions. Unlike vertical composability, which relies on a single, linear stack of function calls, horizontal composability allows for multiple, sequential calls across different chains within a single overarching operation. This facilitates the orchestration of complex, multi-step interactions across multiple chains without being constrained by the depth or complexity of a single call stack.

How Horizontal Composability Works

LayerZero’s horizontal composability leverages composed messages that are treated as separate, containerized message packets. These packets are processed independently, allowing for more flexible and controlled interactions across chains. Workflow Overview:

Sending Application Logic: The sender application uses the OApp._lzSend() function to dispatch a crosschain message.
Receiving Application Logic: A destination application receives the message from EndpointV2.lzReceive(), does some state change, and then calls EndpointV2.sendCompose() to send a new message to the target composer.
Crucially, either the sender or receiver should construct an additional message directed at a composer, which will handle subsequent operations in a new method, EndpointV2.lzCompose().This dual-message approach ensures that both the immediate and follow-up actions are clearly defined and routed appropriately.
Composer Application Logic: A composer application receives the composed message in lzCompose() and does a state change to follow up on the first state changes created in lzReceive().

This workflow creates a way for delivering some critical state change information in separate steps, reducing the complexity of the call stack and enabling non-critical reverts on the destination chain.

Horizontally Composing Supported Contracts

Implementing horizontal composability involves crafting composed messages to expand on existing crosschain contract workflows. By default, both the OFT and ONFT standards support horizontally composed calls out of the box. This allows OFT or ONFT token holders to send tokens crosschain to a trusted composer contract on the destination, and trigger some action on behalf of the token holders (e.g., token swaps, token staking, etc). For more advanced implementations, you can design complex OApp contracts that have other crosschain composer implications.

Installation

To create a composer contract, you can install the OApp package to an existing project:

npm install @layerzerolabs/oapp-evm

yarn add @layerzerolabs/oapp-evm

pnpm add @layerzerolabs/oapp-evm

forge install layerzero-labs/devtools --no-commit

forge install layerzero-labs/LayerZero-v2 --no-commit

forge install OpenZeppelin/openzeppelin-contracts --no-commit

git submodule add https://github.com/GNSPS/solidity-bytes-utils.git lib/solidity-bytes-utils

Then add to your foundry.toml under [profile.default]:

[profile.default]
src = "src"
out = "out"
libs = ["lib"]

remappings = [
    '@layerzerolabs/oapp-evm/=lib/devtools/packages/oapp-evm/',
    '@layerzerolabs/lz-evm-protocol-v2/=lib/layerzero-v2/packages/layerzero-v2/evm/protocol',
    '@layerzerolabs/lz-evm-messagelib-v2/=lib/layerzero-v2/packages/layerzero-v2/evm/messagelib',
    '@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/',
    'solidity-bytes-utils/=lib/solidity-bytes-utils/',
]

# See more config options https://github.com/foundry-rs/foundry/blob/master/crates/config/README.md#all-options

LayerZero contracts work with both OpenZeppelin V5 and V4 contracts. Specify your desired version in your project’s package.json:

"resolutions": {
    "@openzeppelin/contracts": "^5.0.1",
}

Usage

To implement a composer contract, simply inherit the IOAppComposer.sol interface from the oapp-evm package:

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

import { IOAppComposer } from "@layerzerolabs/oapp-evm/contracts/oapp/interfaces/IOAppComposer.sol";

/**
 * @title Composer
 * @notice Demonstrates the minimum `IOAppComposer` interface necessary to receive composed messages via LayerZero.
 * @dev Implements the `lzCompose` function to process incoming composed messages.
 */
contract Composer is IOAppComposer {

    /**
     * @notice Address of the LayerZero Endpoint.
     */
    address public immutable endpoint;

    /**
     * @notice Address of the OApp that is sending the composed message.
     */
    address public immutable oApp;

    /**
     * @notice Constructs the contract and initializes state variables.
     * @dev Stores the LayerZero Endpoint and OApp addresses.
     *
     * @param _endpoint The address of the LayerZero Endpoint.
     * @param _oApp The address of the OApp that is sending composed messages.
     */
    constructor(address _endpoint, address _oApp) {
        endpoint = _endpoint;
        oApp = _oApp;
    }

    /**
     * @notice Handles incoming composed messages from LayerZero.
     * @dev Ensures the message comes from the correct OApp and is sent through the authorized endpoint.
     *
     * @param _oApp The address of the OApp that is sending the composed message.
     */
    function lzCompose(
        address _oApp,
        bytes32 /* _guid */,
        bytes calldata /* _message */,
        address /* _executor */,
        bytes calldata /* _extraData */
    ) external payable override {
        // Ensure the composed message comes from the correct OApp.
        require(_oApp == oApp, "ComposedReceiver: Invalid OApp");
        require(msg.sender == endpoint, "ComposedReceiver: Unauthorized sender");
        // ... execute logic for handling composed messages
    }
}

Composed Message Execution Options

Longer composer messages, which contain more bytes encoded instructions, increase the cost of calling EndpointV2.lzReceive(). Typically, the reason for the gas increase can be found in the additional length being added to your crosschain message, as well as the cost of invoking EndpointV2.sendCompose() inside your OApp._lzReceive() function. Ensure that when calling OFT.send() and ONFT.send() or your own custom OApp, that you correctly estimate the cost of calling endpoint.sendCompose() and add the additional LzReceiveOption gas limit to your SendParam.extraOptions or OApp specific options argument:

// addExecutorLzReceiveOption(uint128 _gas, uint128 _value)
Options.newOptions().addExecutorLzReceiveOption(50000, 0);

Besides the increase cost of EndpointV2.lzReceive(), you should also take into account the cost of your actual composer.lzCompose(). Similar to lzReceive(), you can specify the gas limit and msg.value the Executor should use when calling the composer contract:

// addExecutorLzComposeOption(uint16 _index, uint128 _gas, uint128 _value)
Options.newOptions().addExecutorLzReceiveOption(50000, 0).addExecutorLzComposeOption(0, 30000, 0);

_index: Identifies the specific composed call within a batch of composed messages. This allows for distinct execution settings for each call.
_gas: Specifies the gas limit allocated for the composed call’s execution on the destination chain. Gas requirements may vary across chains due to different opcode costs and gas mechanisms.
_value: Determines the amount of native currency (e.g., ETH) to be sent alongside the composed call, facilitating payable functions or covering additional costs.

Review the existing documentation on Message Execution Options to learn more.

If not enough gas limit or msg.value is provided, the EndpointV2.lzReceive() will not execute, and will need to be manually retried either via the LayerZero Scan explorer, or manual contract call.

Composing an OFT / ONFT

Both the OFT and ONFT support sending a composed message along with the crosschain token transfers.

// IOFT.sol

/**
 * @dev Struct representing token parameters for the OFT send() operation.
 */
struct SendParam {
    uint32 dstEid; // Destination endpoint ID.
    // highlight-next-line
    bytes32 to; // Composer address.
    uint256 amountLD; // Amount to send in local decimals.
    uint256 minAmountLD; // Minimum amount to send in local decimals.
    // highlight-next-line
    bytes extraOptions; // Compose options supplied by the caller to be used in the LayerZero message.
    // highlight-next-line
    bytes composeMsg; // The composed message for the send() operation.
    bytes oftCmd; // The OFT command to be executed, unused in default OFT implementations.
}

// IONFT.sol

/**
 * @dev Struct representing token parameters for the ONFT send() operation.
 */
struct SendParam {
    uint32 dstEid; // Destination LayerZero EndpointV2 ID.
    // highlight-next-line
    bytes32 to; // Composer address.
    uint256 tokenId; // The ERC721 tokenId for the send() operation.
    // highlight-next-line
    bytes extraOptions; // Compose options supplied by the caller to be used in the LayerZero message.
    // highlight-next-line
    bytes composeMsg; // The composed message for the send() operation.
    bytes onftCmd; // The ONFT command to be executed, unused in default ONFT implementations.
}

When calling send(), specify the composer as the to address, encode a composeMsg based on the composer’s specification, and add a ComposeExecutionOption gas limit and/or msg.value depending on the composer’s needs. When creating the composeMsg, the OFT / ONFT will already encode specific parameters along with your message for use in the composer. Below is how the OFTCore and ONFT721Core contracts encode the composeMsg and send it to the composer:

// OFTCore.sol

/**
 * @dev The `OFTMsgCodec` provides a helper function to extract the `composeMsg` from
 *      the overall message. This ensures that the `composeMsg` is properly formed and can
 *      be processed by the composer.
 *
 * @notice The `composeMsg` includes both:
 *         - The `msg.sender` on the source chain (as bytes32).
 *         - The actual `composeMsg` intended for the composer.
 *
 * @notice The final encoded message structure is:
 *         abi.encodePacked(_sendTo, _amountShared, addressToBytes32(msg.sender), _composeMsg);
 */
using OFTMsgCodec for bytes;

/**
 * @dev When sending a message, the `composeMsg` is encoded alongside standard parameters.
 */
(message, hasCompose) = OFTMsgCodec.encode(_sendParam.to, _toSD(_amountLD), _sendParam.composeMsg());

/**
 * @dev If the message is composed (i.e., it contains a `composeMsg`),
 *      we extract it and send it to the composer.
 */
if (_message.isComposed()) {
    /**
     * @dev The `composeMsg` sent to the composer includes:
     *      - `_origin.nonce` (to track the originating transaction).
     *      - `_origin.srcEid` (the source chain endpoint ID).
     *      - The actual `composeMsg` extracted from `_message`.
     */
    bytes memory composeMsg = ONFTComposeMsgCodec.encode(_origin.nonce, _origin.srcEid, _message.composeMsg());

    /**
     * @dev Sends the composed message to the specified `toAddress` (the composer).
     *
     * @notice The `composeIndex` is always `0` because batching is not implemented.
     *         - If batching is added, the index will need to be properly tracked.
     */
    endpoint.sendCompose(toAddress, _guid, 0 /* the index of composed message */, composeMsg);
}

Below is how the ONFT721Core contract encodes the composeMsg and sends it to the composer:

// ONFT721Core.sol

/**
 * @dev The `ONFT721MsgCodec` provides a helper function to extract the `composeMsg` from
 *      the overall message. This ensures that the `composeMsg` is properly formed and can
 *      be processed by the composer.
 *
 * @notice The `composeMsg` includes both:
 *         - The `msg.sender` on the source chain (as bytes32).
 *         - The actual `composeMsg` intended for the composer.
 *
 * @notice The final encoded message structure is:
 *         abi.encodePacked(_sendTo, _tokenId, addressToBytes32(msg.sender), _composeMsg)
 */
using ONFT721MsgCodec for bytes;

/**
 * @dev When sending a message, the `composeMsg` is encoded alongside standard parameters.
 */
(message, hasCompose) = ONFT721MsgCodec.encode(_sendParam.to, _sendParam.tokenId, _sendParam.composeMsg());

/**
 * @dev If the message is composed (i.e., it contains a `composeMsg`),
 *      we extract it and send it to the composer.
 */
if (_message.isComposed()) {
    /**
     * @dev The `composeMsg` sent to the composer includes:
     *      - `_origin.nonce` (to track the originating transaction).
     *      - `_origin.srcEid` (the source chain endpoint ID).
     *      - The actual `composeMsg` extracted from `_message`.
     */
    bytes memory composeMsg = ONFTComposeMsgCodec.encode(_origin.nonce, _origin.srcEid, _message.composeMsg());

    /**
     * @dev Sends the composed message to the specified `toAddress` (the composer).
     *
     * @notice The `composeIndex` is always `0` because batching is not implemented.
     *         - If batching is added, the index will need to be properly tracked.
     */
    endpoint.sendCompose(toAddress, _guid, 0 /* the index of composed message */, composeMsg);
}

This means that in your composer application, you can decode the msg.sender for specific checks, along with the other composer encodings.

Message Encoding Reference

Both OFT and ONFT use a two-step message flow when composing. This section documents the message structures using OFT as the primary example.

Source Chain Message

When sending a crosschain transfer with a composeMsg, the token contract encodes the message for transit. For OFT, this uses OFTMsgCodec:

                                 ┌──────────────────────────────────────────────────────────────────────────┐
                                 │                       OFT Message Layout                                 │
                                 ├────────────────────┬───────────────┬─────────────────────────────────────┤
                                 │       sendTo       │   amountSD    │           composeMsg                │
                                 │      32 bytes      │    8 bytes    │ [composeFrom (32)][payload (var)]   │
                                 ├────────────────────┴───────────────┴─────────────────────────────────────┤
                                 │                    32              40                                    │
                                 └──────────────────────────────────────────────────────────────────────────┘

Bytes	Field	Type	Description
0–31	`sendTo`	`bytes32`	Recipient address (composer contract if using compose)
32–39	`amountSD`	`uint64`	Amount in shared decimals (6 decimal precision)
40+	`composeMsg`	`bytes`	Optional: `[composeFrom (msg.sender)][your payload]`

Composed Message (What Your Composer Receives)

After processing the token transfer in _lzReceive(), the destination contract re-encodes the data and calls endpoint.sendCompose(). This is the message your composer receives in lzCompose(). OFT Composed Message (OFTComposeMsgCodec):

                                 ┌─────────────────────────────────────────────────────────────────────────────┐
                                 │                     OFT Composed Message Layout                             │
                                 ├─────────┬─────────┬──────────────────┬──────────────────┬───────────────────┤
                                 │  nonce  │ srcEid  │     amountLD     │   composeFrom    │    composeMsg     │
                                 │ 8 bytes │ 4 bytes │     32 bytes     │     32 bytes     │                   │
                                 ├─────────┴─────────┴──────────────────┴──────────────────┴───────────────────┤
                                 │         8         12                 44                 76                  │
                                 └─────────────────────────────────────────────────────────────────────────────┘

Bytes	Field	Type	Description
0–7	`nonce`	`uint64`	Unique identifier for tracking the originating transaction
8–11	`srcEid`	`uint32`	Source endpoint ID (originating chain)
12–43	`amountLD`	`uint256`	Amount of tokens in local decimals (full precision)
44–75	`composeFrom`	`bytes32`	Address of the original sender on the source chain
76+	`composeMsg`	`bytes`	The arbitrary payload you passed to `send()`

OFT: amountSD vs amountLD

The OFT converts from shared decimals (amountSD, uint64) to local decimals (amountLD, uint256) before calling your composer. Your composer receives the full precision amount in the destination chain’s native token decimals.

ONFT Composed Message (ONFTComposeMsgCodec): The ONFT uses a simpler structure without an amount field (since NFTs are unique):

Bytes	Field	Type	Description
0–7	`nonce`	`uint64`	Unique identifier for tracking the originating transaction
8–11	`srcEid`	`uint32`	Source endpoint ID (originating chain)
12–43	`composeFrom`	`bytes32`	Address of the original sender on the source chain
44+	`composeMsg`	`bytes`	The arbitrary payload you passed to `send()`

Codec Functions

Import the appropriate codec in your composer contract:

// For OFT composers
import { OFTComposeMsgCodec } from "@layerzerolabs/oft-evm/contracts/libs/OFTComposeMsgCodec.sol";

// For ONFT composers
import { ONFTComposeMsgCodec } from "@layerzerolabs/onft-evm/contracts/libs/ONFTComposeMsgCodec.sol";

OFTComposeMsgCodec Functions:

Function	Returns	Description
`nonce(bytes calldata _msg)`	`uint64`	Extracts the unique transaction identifier
`srcEid(bytes calldata _msg)`	`uint32`	Extracts the source endpoint ID (originating chain)
`amountLD(bytes calldata _msg)`	`uint256`	Extracts the token amount in local decimals
`composeFrom(bytes calldata _msg)`	`bytes32`	Extracts the original sender address on the source chain
`composeMsg(bytes calldata _msg)`	`bytes memory`	Extracts the arbitrary payload passed to `send()`
`addressToBytes32(address _addr)`	`bytes32`	Converts an address to bytes32 (left-padded with zeros)
`bytes32ToAddress(bytes32 _b)`	`address`	Converts bytes32 back to an address

The ONFTComposeMsgCodec provides the same functions except amountLD() (since NFTs don’t have amounts).

The composeFrom field is useful for authorization checks or refunds back to the source chain.

For example, see the following composer example which mocks an ERC20 token swap after receiving from an OFT:

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

import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import { SafeERC20 } from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";

import { IOAppComposer } from "@layerzerolabs/oapp-evm/contracts/oapp/interfaces/IOAppComposer.sol";
import { OFTComposeMsgCodec } from "@layerzerolabs/oft-evm/contracts/libs/OFTComposeMsgCodec.sol";

/**
 * @title SwapMock Contract
 * @notice Mocks an ERC20 token swap in response to receiving an OFT message via LayerZero.
 * @dev This contract interacts with LayerZero's Omnichain Fungible Token (OFT) Standard,
 *      processing incoming OFT messages (`lzCompose`) and executing a token swap action.
 */
contract SwapMock is IOAppComposer {
    using SafeERC20 for IERC20;

    /// @notice The ERC20 token used for swaps.
    IERC20 public erc20;

    /// @notice Address of the LayerZero Endpoint.
    address public immutable endpoint;

    /// @notice Address of the OApp that is sending the composed message.
    address public immutable oApp;

    /**
     * @notice Emitted when a token swap is executed.
     * @dev This event logs the swap details, including the recipient, token, and amount swapped.
     *
     * @param user The address of the user who receives the swapped tokens.
     * @param tokenOut The address of the ERC20 token being swapped.
     * @param amount The amount of tokens swapped.
     */
    event Swapped(address indexed user, address tokenOut, uint256 amount);

    /**
     * @notice Constructs the `SwapMock` contract.
     * @dev Initializes the contract by setting the ERC20 token, LayerZero endpoint, and OApp address.
     *
     * @param _erc20 The address of the ERC20 token that will be used in swaps.
     * @param _endpoint The LayerZero Endpoint address.
     * @param _oApp The address of the OApp that is sending the composed message.
     */
    constructor(address _erc20, address _endpoint, address _oApp) {
        erc20 = IERC20(_erc20);
        endpoint = _endpoint;
        oApp = _oApp;
    }

    /**
     * @notice Handles incoming composed messages from LayerZero and executes a token swap.
     * @dev Decodes the `composeMsg` from `_message`, extracts relevant parameters, and transfers
     *      tokens to the intended recipient.
     *
     *      The `message` is structured in the sender's contract and includes:
     *      - `_nonce`: A unique identifier for tracking the message.
     *      - `_srcEid`: The source endpoint ID, identifying the originating chain.
     *      - `_amountLD`: The amount of tokens in local decimals being transferred.
     *      - `_composeFrom`: The address of the original sender (encoded as `bytes32`).
     *      - `_composeMsg`: The payload containing the recipient address.
     *
     * @param _oApp The address of the originating OApp.
     * @param _message The encoded message containing the `composeMsg`.
     */
    function lzCompose(
        address _oApp,
        bytes32 /*_guid*/,
        bytes calldata _message,
        address /*_executor*/,
        bytes calldata /*_extraData*/
    ) external payable override {
        require(_oApp == oApp, "SwapMock: Invalid OApp");
        require(msg.sender == endpoint, "SwapMock: Unauthorized sender");

        // Decode the nonce (unique identifier for the transaction)
        uint64 _nonce = OFTComposeMsgCodec.nonce(_message);

        // Decode the source endpoint ID (originating chain)
        uint32 _srcEid = OFTComposeMsgCodec.srcEid(_message);

        // Decode the amount in local decimals being transferred
        uint256 _amountLD = OFTComposeMsgCodec.amountLD(_message);

        // Decode the `composeFrom` address (original sender) from bytes32 to address
        bytes32 _composeFromBytes = OFTComposeMsgCodec.composeFrom(_message);
        address _composeFrom = OFTComposeMsgCodec.bytes32ToAddress(_composeFromBytes);

        // Decode the actual `composeMsg` payload to extract the recipient address
        bytes memory _actualComposeMsg = OFTComposeMsgCodec.composeMsg(_message);
        address _receiver = abi.decode(_actualComposeMsg, (address));

        // Execute the token swap by transferring `_amountLD` to `_receiver`
        erc20.safeTransfer(_receiver, _amountLD);

        // Emit an event for logging the swap details
        emit Swapped(_receiver, address(erc20), _amountLD);
    }
}

Composing an OApp

Source OApp: Sends a crosschain message via _lzSend() to a destination chain.
Destination OApp: Receives the crosschain message via _lzReceive() and initiates composed calls using EndpointV2.sendCompose():

/**
 * @dev Handles incoming LayerZero messages and sends a composed message using `endpoint.sendCompose()`.
 * @notice This function processes received packets and relays them to a composed receiver.
 *
 * @param _guid A globally unique identifier for tracking the packet.
 * @param payload The encoded message payload.
 */
function _lzReceive(
    Origin calldata /*_origin*/,
    bytes32 _guid,
    bytes calldata payload,
    address /*_executor*/,
    bytes calldata /*_extraData*/
) internal override {
    /**
     * @dev Decode the payload based on the expected format from the sender application.
     *      The structure of `payload` depends entirely on how the sender encoded it.
     *      In this case, we assume the sender encoded a string message and a composer address.
     *      If the sender encodes different types or a different order, this decoding must be updated accordingly.
     */
    (string memory _message, address _composedAddress) = abi.decode(payload, (string, address));

    // Store received data in the destination OApp
    data = _message;

    // Send a composed message to the composed receiver using the same GUID
    endpoint.sendCompose(_composedAddress, _guid, 0, payload);
}

Composer: Contracts that implement business logic to handle incoming composed messages via EndpointV2.lzCompose().

​Prerequisites

​Workflow

​What is Vertical Composability?

​What is Horizontal Composability?

​How Horizontal Composability Works

​Horizontally Composing Supported Contracts

​Installation

​Usage

​Composed Message Execution Options

​Composing an OFT / ONFT

​Message Encoding Reference

​Source Chain Message

​Composed Message (What Your Composer Receives)

​OFT: amountSD vs amountLD

​Codec Functions

​Composing an OApp