Skip to main content
Version: Endpoint V2

Integration Checklist

The checklist below is designed to help prepare a project that integrates LayerZero V2 OApps for an external audit or Mainnet deployment. Use it as a pre‑production gate for your omnichain application.

Quick Checklist​

Use this high‑level checklist first, then refer to the detailed sections below.

Critical (Must Complete)​

  • Peers set on all pathways (bidirectional)
    A↔B and B↔A peers configured and verified on every chain.
  • DVN configuration set on all pathways
    Required and optional DVNs explicitly configured per pathway.
  • Executor configuration set on all pathways
    Max message size, executor address, and related parameters configured.
  • Enforced options configured for gas/value
    enforcedOptions set so users pay enough gas for destination execution.
  • Mock and test functions removed
    No leftover debug or example functions in production deployments.
  • Ownership and delegate addresses verified
    OApp owner, delegate, and upgrade admins set to the correct addresses.
  • Using latest LayerZero packages
    Contracts imported from the latest published packages, not copied source.
  • Libraries explicitly set (no reliance on defaults)
    Send/receive libraries set per pathway instead of using protocol defaults.
  • Message safety checks implemented
    One action per message or robust handling for bundled actions.
  • msg.value checks in lzReceive/lzCompose
    Encoded and validated to prevent underfunded execution or unexpected state.

0. Introduction​

LayerZero applications operate over directional pathways between chains. Each direction (A→B and B→A) is configured and verified separately, and both must be correct for reliable omnichain behavior.

At a high level:

  • On the source chain (Chain A), OApp(A) calls EndpointV2(A) to construct and dispatch a packet.
  • On the destination chain (Chain B), EndpointV2(B) verifies the packet, inserts it into the channel, and calls OApp(B).lzReceive.

Throughout this checklist, treat each A→B and B→A pathway as a separate unit of review. Configuration, peers, DVNs, and executors must be validated in both directions.

Pathway Model & Mental Map​

A LayerZero application operates over directional pathways:

Path A → B:

  1. Source Chain (Chain A): OApp(A) calls EndpointV2(A) → constructs & dispatches packet.
  2. Destination Chain (Chain B): EndpointV2(B) verifies, inserts packet into channel, and calls OApp(B).lzReceive.

Important: A → B configuration must be checked separately from B → A. Pathways are directional.

Critical Pathway Checks​

Use EndpointV2 and OApp methods as documented.

On Chain A (Source) — EndpointV2(A)​

  1. Send Library in Use

    getSendLibrary(oApp, dstEid) → confirms which send library is active.

  2. Executor & DVN Configuration (Send‑Side)

    getConfig(oApp, sendLib, dstEid, configType)

    1. configType = 1: Executor config (max message size, executor address).
    2. configType = 2: ULN/DVN config (confirmations, required/optional DVNs).

  3. Delegate Check

    delegates(oApp) → verifies the delegate authorized to configure endpoint settings.

On Chain B (Destination) — EndpointV2(B)​

  1. Receive Library in Use

    getReceiveLibrary(oApp, srcEid) → confirms which receive library is expected.

  2. DVN Configuration (Receive‑Side)

    getConfig(oApp, recvLib, srcEid, 2) → ULN config (confirmations + DVN sets).

  3. Initialization Gate

    initializable(origin, receiver) → Endpoint check if path can be initialized. Falls back to OApp’s allowInitializePath if no lazyNonce is present.

  4. Optional Diagnostic Checks

    verifiable(origin, receiver) or inboundPayloadHash(...) for debugging message states.

On OApp Contracts (Both Chains)​

  1. Peer Mapping

    peers(eid) → verifies that each OApp is correctly mapped to its counterpart on the remote chain.

  2. Initialization Override

    allowInitializePath(origin) → ensures the OAppReceiver provides a default implementation. If using ILayerZeroReceiver directly, you must implement this method to control initialization permissions.

Defaults in LayerZero Protocol​

LayerZero maintains default configurations at the Endpoint level. These serve as fallbacks if an OApp has not explicitly called setSendLibrary, setReceiveLibrary, or setConfig.

  1. A default configuration may:

    1. Be a working config (with active DVNs + Executor).
    2. Be a dead config (e.g., DVNs not listening → hard revert on send).
    3. Be misconfigured (Executor not set or not connected, even if pathway appears live).

  2. Review Implication:

    1. Do not assume defaults are safe for production.
    2. Always check explicitly: getSendLibrary, getReceiveLibrary, and getConfig. If these resolve to defaults, confirm whether the defaults are valid for the intended pathway.
    3. Unintentional fallbacks to defaults are a common cause of blocked or failing pathways.

1. OApp Implementation​

Use the Latest Version of LayerZero Packages​

Always use the latest version of LayerZero packages. Avoid copying contracts directly from LayerZero repositories. You can find the latest packages on each contract's home page.

Avoid Hardcoding LayerZero Endpoint IDs​

Use admin-restricted setters to configure endpoint IDs instead of hardcoding them.

Set Peers on Every Pathway​

To ensure successful one-way messages between chains, it's essential to establish peer configurations on both the source and destination chains. Both chains' OApps perform peer verification before executing the message on the destination chain, ensuring secure and reliable cross-chain communication.

// The real endpoint ids will vary per chain, and can be found under "Supported Chains"
uint32 aEid = 1;
uint32 bEid = 2;

MyOApp aOApp;
MyOApp bOApp;

// Call on both sides per pathway
aOApp.setPeer(bEid, addressToBytes32(address(bOApp)));
bOApp.setPeer(aEid, addressToBytes32(address(aOApp)));

If using a custom OApp implementation that is not a child contract of the LayerZero OApp Standard, implement the receive side check for initializing the OApp's pathway. The Receive Library will call allowInitializePath when a message is received, and if true, it will initialize the pathway for message passing.

// LayerZero V2 OAppReceiver.sol (implements ILayerZeroReceiver.sol)

/**
 * @notice Checks if the path initialization is allowed based on the provided origin.
 * @param origin The origin information containing the source endpoint and sender address.
 * @return Whether the path has been initialized.
 *
 * @dev This indicates to the endpoint that the OApp has enabled msgs for this particular path to be received.
 * @dev This defaults to assuming if a peer has been set, its initialized.
 * Can be overridden by the OApp if there is other logic to determine this.
 */
function allowInitializePath(Origin calldata origin) public view virtual returns (bool) {
    return peers[origin.srcEid] == origin.sender;
}

Set Libraries on Every Pathway​

It is recommended that OApps explicitly set the intended libraries.

EndpointV2.setSendLibrary(aOApp, bEid, newLib)
EndpointV2.setReceiveLibrary(aOApp, bEid, newLib, gracePeriod)
EndpointV2.setReceiveLibraryTimeout(aOApp, bEid, lib, gracePeriod)
caution

If libraries are not set, the OApp will fallback to the default libraries set by LayerZero Labs.

/// @notice The Send Library is the Oapp specified library that will be used to send the message to the destination
/// endpoint. If the Oapp does not specify a Send Library, the default Send Library will be used.
/// @dev If the Oapp does not have a selected Send Library, this function will resolve to the default library
/// configured by LayerZero
/// @return lib address of the Send Library
/// @param _sender The address of the Oapp that is sending the message
/// @param _dstEid The destination endpoint id
function getSendLibrary(address _sender, uint32 _dstEid) public view returns (address lib) {
    lib = sendLibrary[_sender][_dstEid];
    if (lib == DEFAULT_LIB) {
        lib = defaultSendLibrary[_dstEid];
        if (lib == address(0x0)) revert Errors.LZ_DefaultSendLibUnavailable();
    }
}

Set Security and Executor Configurations on Every Pathway​

You must configure Decentralized Validator Networks (DVNs) manually on all chain pathways for your OApp. LayerZero maintains a neutral stance and does not presuppose any security assumptions on behalf of deployed OApps. This approach requires you to define and implement security considerations that align with your application’s requirements.

EndpointV2.setConfig(aOApp, sendLibrary, sendConfig)
EndpointV2.setConfig(aOApp, receiveLibrary, receiveConfig)

Follow the Protocol Configuration documentation to configure DVNs for each chain pathway.

caution

If no configuration is set, the OApp will fallback to the default settings set by LayerZero Labs.

// @dev get the executor config and if not set, return the default config
function getExecutorConfig(address _oapp, uint32 _remoteEid) public view returns (ExecutorConfig memory rtnConfig) {
    ExecutorConfig storage defaultConfig = executorConfigs[DEFAULT_CONFIG][_remoteEid];
    ExecutorConfig storage customConfig = executorConfigs[_oapp][_remoteEid];

    uint32 maxMessageSize = customConfig.maxMessageSize;
    rtnConfig.maxMessageSize = maxMessageSize != 0 ? maxMessageSize : defaultConfig.maxMessageSize;

    address executor = customConfig.executor;
    rtnConfig.executor = executor != address(0x0) ? executor : defaultConfig.executor;
}

Additional considerations:

Do:

  • Use more than one DVN for each production pathway instead of relying on a single DVN.
  • Keep DVN configurations consistent on both sides of every pathway (send and receive).
  • Ensure DVN and Executor contracts implement the expected interfaces for your deployment.
  • Verify DVN and Executor addresses against V2 Contracts and DVN Providers.

Don’t:

  • Configure only one DVN for a pathway and treat it as production‑ready.
  • Assume that mismatched DVN configurations are safe just because messages appear to be delivering (for example, when the receive‑side configuration is less strict than the send‑side).

Set Delegate on Every OApp​

It is recommended that OApps review and explicitly set the delegate for each deployment.

EndpointV2.setDelegate(delegate)

Check Initialization Logic is Valid on Every OApp​

Ensure that EndpointV2 can initialize the OApp on every chain.

function _initializable(
    Origin calldata _origin,
    address _receiver,
    uint64 _lazyInboundNonce
) internal view returns (bool) {
    return
        _lazyInboundNonce > 0 || // allowInitializePath already checked
        ILayerZeroReceiver(_receiver).allowInitializePath(_origin);
}

function initializable(Origin calldata _origin, address _receiver) external view returns (bool) {
    return _initializable(_origin, _receiver, lazyInboundNonce[_receiver][_origin.srcEid][_origin.sender]);
}

2. Custom Business Logic via LayerZero Interfaces​

Check Message Safety​

Do:

  • Design messages so that a single, clearly scoped action happens per cross‑chain message wherever possible.
  • If you bundle multiple actions, ensure they cannot fail mid‑sequence and leave partial state.
  • Consider Instant Finality Guarantee (IFG) for use cases with strict state‑safety requirements.

Don’t:

  • Pack unrelated or high‑risk state changes into a single message without robust failure handling.
  • Assume that all downstream calls will succeed just because the message is verified.

Check Mock and Test Functions Are Removed​

When example contracts are used as boilerplates, ensure that both any mock or test function existing or added is removed in the production deployments.

Check Enforced Gas and Value​

Do:

  • Profile destination gas and value requirements for each message type on each pathway.
  • Use enforcedOptions so senders pay enough gas/value for reliable execution at the destination.
  • Refer to transaction pricing guidance when setting limits.

Don’t:

  • Rely on “best guess” gas limits or leave options unset for production pathways.
  • Assume that executors will always provide the same msg.value you requested if you don’t verify it in your code.
// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.22;

import { OApp, Origin, MessagingFee } from "@layerzerolabs/oapp-evm/contracts/oapp/OApp.sol";
import { OAppOptionsType3 } from "@layerzerolabs/oapp-evm/contracts/oapp/libs/OAppOptionsType3.sol";
import { Ownable } from "@openzeppelin/contracts/access/Ownable.sol";

contract MyOApp is OApp, OAppOptionsType3 {

    /// @notice Message types that are used to identify the various OApp operations.
    /// @dev These values are used in things like combineOptions() in OAppOptionsType3.
    uint16 public constant SEND = 1;

    constructor(address _endpoint, address _owner) OApp(_endpoint, _owner) Ownable(_owner) {}
    // ... contract continues
}
EnforcedOptionParam[] memory aEnforcedOptions = new EnforcedOptionParam[](1);
// Send gas for lzReceive (A -> B).
aEnforcedOptions[0] = EnforcedOptionParam({eid: bEid, msgType: SEND, options: OptionsBuilder.newOptions().addExecutorLzReceiveOption(50000, 0)}); // gas limit, msg.value
aOApp.setEnforcedOptions(aEnforcedOptions);

See more on Solana OFT Message Execution Options.

EVM-Specific​

Check _lzReceive Security​

  1. If using OAppReceiver (inherited by OApp and OFT), msg.sender != endpoint and _origin.srcEid != expectedOApp checks are already enforced in OAppReceiver.lzReceive (endpoint-only access, peer validation).
  2. If implementing directly from ILayerZeroReceiver, you must implement these checks and initialization safeguards.

Check lzCompose Security​

Unlike child contracts with the OAppReceiver.lzReceive method, the ILayerZeroComposer.lzCompose does not have built-in checks.

Add these checks for the source oApp and endpoint before any custom state change logic:

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

import { ILayerZeroComposer } from "@layerzerolabs/lz-evm-protocol-v2/contracts/interfaces/ILayerZeroComposer.sol";

/// @title ComposedReceiver
/// @dev A contract demonstrating the minimum ILayerZeroComposer interface necessary to receive composed messages via LayerZero.
contract ComposedReceiver is ILayerZeroComposer {

    /// @notice Stores the last received message.
    string public data = "Nothing received yet";

    /// @notice Store LayerZero addresses.
    address public immutable endpoint;
    address public immutable oApp;

    /// @notice Constructs the contract.
    /// @dev Initializes the contract.
    /// @param _endpoint LayerZero Endpoint address
    /// @param _oApp The address of the OApp that is sending the composed message.
    constructor(address _endpoint, address _oApp) {
        endpoint = _endpoint;
        oApp = _oApp;
    }

    /// @notice Handles incoming composed messages from LayerZero.
    /// @dev Decodes the message payload and updates the state.
    /// @param _oApp The address of the originating OApp.
    /// @param /*_guid*/ The globally unique identifier of the message.
    /// @param _message The encoded message content.
    function lzCompose(
        address _oApp,
        bytes32 /*_guid*/,
        bytes calldata _message,
        address,
        bytes calldata
    ) external payable override {
        // Perform checks to make sure composed message comes from correct OApp.
        require(_oApp == oApp, "!oApp");
        require(msg.sender == endpoint, "!endpoint");

        // Decode the payload to get the message
        (string memory message, ) = abi.decode(_message, (string, address));
        data = message;
    }
}

Enforce msg.value in _lzReceive and lzCompose​

If you specify in the executor _options a certain msg.value, it is not guaranteed that the message will be executed with these exact parameters because any caller can execute a verified message.

In certain scenarios depending on the encoded message data, this can result in a successful message being delivered, but with a state change different than intended.

Encode the msg.value inside the message on the sending chain, and then decode it in the lzReceive or lzCompose and compare with the actual msg.value.

// LayerZero V2 OmniCounter.sol example

function value(bytes calldata _message) internal pure returns (uint256) {
    return uint256(bytes32(_message[VALUE_OFFSET:]));
}

function _lzReceive(
    Origin calldata _origin,
    bytes32 _guid,
    bytes calldata _message,
    address /*_executor*/,
    bytes calldata /*_extraData*/
) internal override {
    _acceptNonce(_origin.srcEid, _origin.sender, _origin.nonce);
    uint8 messageType = _message.msgType();

    if (messageType == MsgCodec.VANILLA_TYPE) {

        //////////////////////////////// IMPORTANT //////////////////////////////////
        /// if you request for msg.value in the options, you should also encode it
        /// into your message and check the value received at destination (example below).
        /// if not, the executor could potentially provide less msg.value than you requested
        /// leading to unintended behavior. Another option is to assert the executor to be
        /// one that you trust.
        /////////////////////////////////////////////////////////////////////////////
        require(msg.value >= _message.value(), "OmniCounter: insufficient value");

        count++;
    }
}

This requires encoding the msg.value as part of the _message on the source chain, and extracting it from the encoded message.

3. LayerZero OFT/ONFT Implementation​

Check Use-Case Contracts​

Do:

  • Use plain OFT/ONFT implementations (OFT or ONFT) for new omnichain tokens on every chain.
  • For existing tokens with mint and burn capabilities, use a mint‑and‑burn adapter such as MintAndBurnOFTAdapter on existing chains, plus plain OFT/ONFT implementations on new chains.
  • For existing tokens without mint/burn capabilities, use a lockbox adapter such as OFTAdapter or ONFT721Adapter on the original chain, with plain OFT/ONFT on new chains.
  • For native gas tokens (for example, ETH or BNB), use a native lockbox adapter such as NativeOFTAdapter.

Don’t:

  • Mix multiple lockbox adapters for the same OFT deployment (see warning below).
  • Treat adapter choice as interchangeable across chains without considering the underlying token’s capabilities.
warning

There can only be one lockbox OFT Adapter used in an OFT deployment.

Multiple OFT Adapters break omnichain unified liquidity by effectively creating token pools.

If you create OFT Adapters on multiple chains, you have no way to guarantee finality for token transfers due to the fact that the source chain has no knowledge of the destination pool's supply (or lack of supply). This can create race conditions where if a sent amount exceeds the available supply on the destination chain, those sent tokens will be permanently lost.

Check Shared Decimals​

Shared Decimals must be consistent across all OFT deployments, or amount conversion will vary by orders of magnitude and allow double spending.

Check Local Decimals​

Every chain's OFT token enforces its own local decimals, which ultimately cap how much supply can exist on that chain (for example, Solana balances are stored as u64). You must ensure that the OFT token on all chains can hold the same max supply value. Failing to do so may result in failed cross-chain transactions due to overflow issues.

For detailed guidance, see Deciding the number of local decimals for your Solana OFT for an example of how the local decimals value affects the max supply ceiling.

Check Minter and Burner Permissions​

When using mint-and-burn Adapters such as MintAndBurnOFTAdapter, ensure that the Adapter has the required roles to mint and burn the underlying token through the specified interface.

Check Structured Codecs​

Use type-safe bytes codec for message encoding. Use custom codecs only if necessary and if your app requires deep optimization.

Examples:

Solana-Specific​

Avoid Enforcing Options Value to Initialize Accounts​

caution

OFT sends to Solana to uninitialized token accounts require additional options value to pay for ATA creation. The first transfer of a specific token to a recipient will require value, but any subsequent transaction will not.

Static enforced options value should be avoided to deal with it, as it'd keep overpaying after the first send.

Nonetheless, enforcing options for regular gas consumption and other value requirements is still recommended in Solana.

Examples:

  • First OFT send transaction to a Solana recipient. Note that the value received is non-zero, as it is used to pay for ATA creation of the token recipient.
  • Second OFT send transaction to Solana recipient. Note that the SOL value sent is zero, as ATA is already created for the token recipient.

4. Authority & Ownership Transfers​

Check OApp Ownership​

Ensure the OApp owner is set or transferred to the intended address.

Check Solana reference.

Check OApp Delegate​

Ensure the OApp delegate at the EndpointV2 is set or transferred to the intended address. It must be transferred before transferring ownership, as only the OApp owner can set the delegate.

Check Upgradeable Contracts Admin​

Ensure proxy admin for upgradeable contracts or upgrade authority is set or transferred to the intended addresses.

EVM-Specific​

Check Upgradeable Contracts Implementation Initialization​

Ensure implementation contracts for EVM upgradeable contracts disable initializers in the constructor.

contract MyOFTUpgradeable is OFTUpgradeable {
    constructor(address _lzEndpoint) OFTUpgradeable(_lzEndpoint) {
        _disableInitializers();
    }

    function initialize(string memory _name, string memory _symbol, address _delegate) public initializer {
        __OFT_init(_name, _symbol, _delegate);
        __Ownable_init(_delegate);
    }
}

5. Testing Your Configuration​

After completing the checklist, validate your setup end‑to‑end:

  1. Send a test message A→B
    • Use your OApp’s send function on Chain A.
    • Confirm the message appears and is delivered on a LayerZero explorer (for example, LayerZero Scan).
  2. Verify execution on Chain B
    • Check destination chain logs/events and state changes in OApp(B).
  3. Send a test message B→A
    • Repeat the same steps in the opposite direction to validate bidirectional configuration.
  4. Test failure scenarios
    • Intentionally underfund gas/value (in a test environment) to confirm your error handling and enforcedOptions work as intended.
  5. Repeat for every pathway
    • For each new chain or pathway you add, repeat the full A→B and B→A test sequence.

If any test fails, map the failure back to the relevant section in this checklist (peers, DVNs, executors, options, or ownership) and re‑verify the configuration.

Usage Notes​

  • This checklist is production-focused: it ensures pathway correctness, contract readiness, and monitoring preparedness.

  • It is not a substitute for an audit, but provides:

    • A systematic way to review OApp state.
    • Clear visibility into configuration consistency across chains.
    • Guidance on what Scan or external dashboards should surface automatically.

  • OFT/ONFT checks are categorized separately to avoid conflating with protocol-level messaging.

References​