Integration Checklist

​

Quick Checklist

​

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.

​

Recommended (Best Practices)

• 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

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

​

Pathway Model & Mental Map

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.

​

Critical Pathway Checks

​

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

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.

• Required DVNs (default-required-dvns) — call setConfig on the send and receive libraries with an explicit, ascending-sorted requiredDVNs array and a matching requiredDVNCount. See Set Security and Executor Configurations on Every Pathway.
• Optional DVNs / threshold (default-optional-dvns) — set optionalDVNs and optionalDVNThreshold in the same setConfig call to lock your X-of-Y-of-N posture; leaving them at 0 / [] inherits the default.
• Libraries (default-libraries) — call setSendLibrary / setReceiveLibrary with the intended ULN version so a protocol upgrade cannot move you onto a new library without your consent. See Set Libraries on Every Pathway.
• Confirmations (default-confirmations) — set confirmations in the ULN setConfig to your production floor on both sides; the default can change without notice. See Confirmation depth.

​

1. OApp Implementation

​

Use the Latest Version of LayerZero Packages

​

Avoid Hardcoding LayerZero Endpoint IDs

​

Set Peers on Every Pathway

// 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)));

// 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;
}

​

Peer Address Validation

• Call setPeer(eid, bytes32(uint256(uint160(remoteAddress)))) with the actual deployed remote OApp address.
• For non-EVM remotes (Solana program IDs, Aptos object addresses), use the encoding documented in the per-VM configuration page.
• Re-validate peers after every redeploy of the remote contract — a stale peer points at a contract that no longer exists.

• Leave a placeholder peer like 0x…dead, 0x…01, or all-f in production. Messages sent to a sentinel will be permanently undeliverable.
• Pad an EVM address into the upper bytes (bytes32(uint256(uint160(addr)) << 96)) — this corrupts the encoding and the receiver will fail peer verification.

Validate it yourself

PEER=$(cast call "$OAPP_A" "peers(uint32)(bytes32)" "$EID_B" --rpc-url "$RPC_A")
echo "Raw peer (bytes32): $PEER"

# 1. For an EVM remote, the upper 12 bytes must be zero
if echo "$PEER" | grep -qE '^0x0{24}[0-9a-fA-F]{40}$'; then
  echo "OK: lower-20-bytes peer ($(echo $PEER | sed 's/^0x0\{24\}/0x/'))"
else
  echo "FAIL: peer has non-zero upper bytes — corrupted/wrong-VM encoding"
fi

# 2. Sentinel-address check
ADDR_LOW=$(echo "$PEER" | sed 's/^0x0\{24\}/0x/' | tr 'A-F' 'a-f')
case "$ADDR_LOW" in
  0x0000000000000000000000000000000000000000) echo "FAIL: peer is the zero address — pathway is unpeered (never set, or explicitly cleared with setPeer(eid, bytes32(0)))" ;;
  0x0000000000000000000000000000000000000001) echo "FAIL: sentinel 0x…01" ;;
  0xffffffffffffffffffffffffffffffffffffffff) echo "FAIL: sentinel all-ones" ;;
  0xdeaddeaddeaddeaddeaddeaddeaddeaddeaddead) echo "FAIL: sentinel dead pattern" ;;
esac

​

Verify Peer Reciprocity

• After deploying or updating a remote, call setPeer on both sides in the same operational batch.
• Treat peer reciprocity as a pre-flight check in CI for every pathway in your mesh.
• Use the LayerZero CLI’s lz oapp wire (or equivalent) which sets reciprocal peers atomically.

• Update only one side of a peer change and rely on “we’ll do the other side later.” A single-sided update is a known cause of stuck channels.
• Set the same remote address on both sides if the OApps were deployed at different addresses — peers are per-(local-OApp, remote-EID), not per-chain.

Validate it yourself

LOCAL_PEER=$(cast call "$OAPP_A" "peers(uint32)(bytes32)" "$EID_B" --rpc-url "$RPC_A")
REMOTE_PEER=$(cast call "$OAPP_B" "peers(uint32)(bytes32)" "$EID_A" --rpc-url "$RPC_B")

# Expected: lower 20 bytes of LOCAL_PEER == OAPP_B, and lower 20 bytes of REMOTE_PEER == OAPP_A.
EXPECTED_LOCAL=$(cast --to-uint256 "$OAPP_B")
EXPECTED_REMOTE=$(cast --to-uint256 "$OAPP_A")

[ "$LOCAL_PEER" = "$EXPECTED_LOCAL" ] && echo "A→B peer reciprocal ✓" || echo "A→B peer FAIL: got $LOCAL_PEER want $EXPECTED_LOCAL"
[ "$REMOTE_PEER" = "$EXPECTED_REMOTE" ] && echo "B→A peer reciprocal ✓" || echo "B→A peer FAIL: got $REMOTE_PEER want $EXPECTED_REMOTE"

​

One OApp per Chain

• Maintain a single canonical deployment artifact per (OApp, chain) pair.
• When migrating to a new contract address, drain and decommission the old deployment before announcing the new address — do not let both run in parallel as peers of the mesh.
• Enumerate every OApp address on each chain from your own deployment manifest and confirm exactly one entry per chain (except for the documented adapter exception).

• Run two production OApp deployments on the same chain and expect peers across the mesh to converge — they cannot.
• Treat a forgotten test deployment as harmless if it still has peers set; it can intercept messages from chains that point at its address.

Validate it yourself

​

Set Libraries on Every Pathway

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

/// @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

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

• EVM
• Solana
• Aptos Move

// @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;
}

• Use more than one DVN for each production pathway instead of relying on a single DVN. Use Production DVN Configuration to pick the right tier for your exposure.
• Include at least one required DVN that is not operated by LayerZero Labs. Most preset configurations that ship a real default include LayerZero Labs as a required DVN, and the rest are placeholder Dead DVNs that you must replace before going live; production deployments should not concentrate trust in a single operator.
• 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.
• Configure an Executor explicitly. The default Executor in every preset configuration is operated by LayerZero Labs; for high-value pathways, evaluate a custom Executor.
• If you currently ship a single-DVN configuration, follow Migrating from a Single-DVN Configuration.

• Configure only one DVN for a pathway and treat it as production‑ready.
• Configure two required DVNs that are both operated by the same entity; this does not provide the operator-diversity that multi-DVN is designed to deliver.
• 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).
• Rely on the default Executor without considering its liveness implications for your application.

​

Set Delegate on Every OApp

EndpointV2.setDelegate(delegate)

​

Check Initialization Logic is Valid on Every OApp

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

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

• 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

​

Check Enforced Gas and Value

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

• 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";
// highlight-next-line
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);

​

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

// 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.
        // highlight-start
        require(_oApp == oApp, "!oApp");
        require(msg.sender == endpoint, "!endpoint");
        // highlight-end

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

​

Enforce msg.value in _lzReceive and lzCompose

// 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.
        /////////////////////////////////////////////////////////////////////////////
        // highlight-next-line
        require(msg.value >= _message.value(), "OmniCounter: insufficient value");

        count++;
    }
}

​

3. LayerZero OFT/ONFT Implementation

​

Check Use-Case Contracts

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

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

​

Check Shared Decimals

​

Check Local Decimals

​

Check Minter and Burner Permissions

​

Check Structured Codecs

• EVM OFT.
• Solana OFT.

​

Solana-Specific

​

Avoid Enforcing Options Value to Initialize Accounts

• 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

• Set owner() to a multisig (e.g., Safe), governance module, or timelock that requires more than one signer.
• Document the signing policy alongside the deployment artifact.
• Re-verify ownership after every chain rollout.

• Leave owner() as a single externally-owned account (EOA). A single key compromise lets the attacker rewrite peers, libraries, and DVN/Executor config on every pathway.
• Treat “we’ll rotate later” as acceptable for mainnet — the rotation window is the exposure window.

​

Validate it yourself

OWNER=$(cast call "$OAPP_A" "owner()(address)" --rpc-url "$RPC_A")
CODE=$(cast code "$OWNER" --rpc-url "$RPC_A")
if [ "$CODE" = "0x" ]; then
  echo "FAIL: owner $OWNER is an EOA — move to a multisig or governance contract"
else
  echo "OK: owner $OWNER is a contract"
fi

​

Check OApp Delegate

• Set the delegate to a multisig or governance contract.
• If the delegate differs from the owner, confirm the split is intentional — a separate delegate can modify DVN, library, and executor configuration without the owner’s signature.
• Treat the delegate as protocol-config root authority; review its signers with the same rigor as the owner’s.

• Leave the delegate as an EOA. The delegate can call setSendLibrary, setReceiveLibrary, and setConfig — a single key compromise can rewrite the entire protocol stack on that chain.
• Assume “no delegate set” is safe; the zero address can be unrecoverable on some pathway configurations.

​

Validate it yourself

DELEGATE=$(cast call "$ENDPOINT_A" "delegates(address)(address)" "$OAPP_A" --rpc-url "$RPC_A")
CODE=$(cast code "$DELEGATE" --rpc-url "$RPC_A")
if [ "$CODE" = "0x" ]; then
  echo "FAIL: delegate $DELEGATE is an EOA — a single key compromise can rewrite DVN/library/executor config"
else
  echo "OK: delegate $DELEGATE is a contract"
fi

​

Owner-Delegate Mismatch

• Default to owner == delegate unless you have a specific reason to split them.
• If you do split, ensure the delegate is held by an entity at least as trusted as the owner — for example, the same multisig members under a faster-rotation policy.
• Document the split rationale next to the deployment artifact so an auditor can see why the two roles diverge.

• Set the delegate to a more permissive group than the owner.
• Leave a split that originated as a deployment expedient (“we used a deployer EOA temporarily”) in place after launch.

Validate it yourself

OWNER=$(cast call "$OAPP_A" "owner()(address)" --rpc-url "$RPC_A")
DELEGATE=$(cast call "$ENDPOINT_A" "delegates(address)(address)" "$OAPP_A" --rpc-url "$RPC_A")
if [ "$OWNER" = "$DELEGATE" ]; then
  echo "OK: owner == delegate ($OWNER)"
else
  echo "MISMATCH: owner=$OWNER delegate=$DELEGATE"
  echo "Confirm this split is intentional — a delegate can modify protocol config without the owner's signature."
fi

​

Check Upgradeable Contracts Admin

​

EVM-Specific

​

Check Upgradeable Contracts Implementation Initialization

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

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.

​

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

• EVM Interactive Contract Playground
• Production Deployment Checklist (Upgradeable OFT Example)