LayerZero V2 Integration Checklist
The checklist below is designed to help prepare a project that integrates LayerZero V2 for an external audit or Mainnet deployment.
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.
Token Bridging Guidelines
For new tokens, inherit from OFT or ONFT.
For existing tokens, use OFTAdapter or ONFTAdapter.
For non-EVM tokens, select the correct VM from the navbar and see the equivalent sections.
There can only be one 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.
Avoid Hardcoding LayerZero Endpoint IDs
Use admin-restricted setters to configure endpoint IDs instead of hardcoding them.
Call setPeer on every OApp Deployment
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 Security and Executor Configurations
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.setSendLibrary(aOApp, bEid, newLib)
EndpointV2.setReceiveLibrary(aOApp, bEid, newLib, gracePeriod)
EndpointV2.setReceiveLibraryTimeout(aOApp, bEid, lib, gracePeriod)
EndpointV2.setConfig(aOApp, sendLibrary, sendConfig)
EndpointV2.setConfig(aOApp, receiveLibrary, receiveConfig)
EndpointV2.setDelegate(delegate)
Follow the Protocol Configuration documentation to configure DVNs for each chain pathway.
If no configuration is set, the OApp will fallback to the default settings 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();
}
}
Implement Enforced Options
Implement and set enforcedOptions to ensure users pay a predetermined amount of gas for delivery on the destination transaction. This setup guarantees that messages sent from a source have sufficient gas to be executed on the destination chain.
Test the gas required for execution on the destination chain to prevent failures due to insufficient gas.
// 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);
Avoid Redundant require Statements
Do not add require statements that repeat checks in parent contracts, such as those in OAppReceiver.lzReceive.
/**
* @dev Entry point for receiving messages or packets from the endpoint.
* @param _origin The origin information containing the source endpoint and sender address.
* - srcEid: The source chain endpoint ID.
* - sender: The sender address on the src chain.
* - nonce: The nonce of the message.
* @param _guid The unique identifier for the received LayerZero message.
* @param _message The payload of the received message.
* @param _executor The address of the executor for the received message.
* @param _extraData Additional arbitrary data provided by the corresponding executor.
*
* @dev Entry point for receiving msg/packet from the LayerZero endpoint.
*/
function lzReceive(
Origin calldata _origin,
bytes32 _guid,
bytes calldata _message,
address _executor,
bytes calldata _extraData
) public payable virtual {
// Ensures that only the endpoint can attempt to lzReceive() messages to this OApp.
if (address(endpoint) != msg.sender) revert OnlyEndpoint(msg.sender);
// Ensure that the sender matches the expected peer for the source endpoint.
if (_getPeerOrRevert(_origin.srcEid) != _origin.sender) revert OnlyPeer(_origin.srcEid, _origin.sender);
// Call the internal OApp implementation of lzReceive.
_lzReceive(_origin, _guid, _message, _executor, _extraData);
}
Add require Statements in lzCompose
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.
Implement Instant Finality Guarantee (IFG)
Design your OApp with IFG to ensure that transactions accepted at the source will be accepted at the destination, minimizing state damage in case of message failure.
Perform One Action Per Message
Minimize the impact of potential message failure by performing only one action per message.
Message Encoding
Use type-safe bytes codec for message encoding. Use custom codecs only if necessary and if your app requires deep optimization. For example, see the OFTMsgCodec.sol:
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
library OFTMsgCodec {
// Offset constants for encoding and decoding OFT messages
uint8 private constant SEND_TO_OFFSET = 32;
uint8 private constant SEND_AMOUNT_SD_OFFSET = 40;
/**
* @dev Encodes an OFT LayerZero message.
* @param _sendTo The recipient address.
* @param _amountShared The amount in shared decimals.
* @param _composeMsg The composed message.
* @return _msg The encoded message.
* @return hasCompose A boolean indicating whether the message has a composed payload.
*/
function encode(
bytes32 _sendTo,
uint64 _amountShared,
bytes memory _composeMsg
) internal view returns (bytes memory _msg, bool hasCompose) {
hasCompose = _composeMsg.length > 0;
// @dev Remote chains will want to know the composed function caller ie. msg.sender on the src.
_msg = hasCompose
? abi.encodePacked(_sendTo, _amountShared, addressToBytes32(msg.sender), _composeMsg)
: abi.encodePacked(_sendTo, _amountShared);
}
/**
* @dev Checks if the OFT message is composed.
* @param _msg The OFT message.
* @return A boolean indicating whether the message is composed.
*/
function isComposed(bytes calldata _msg) internal pure returns (bool) {
return _msg.length > SEND_AMOUNT_SD_OFFSET;
}
/**
* @dev Retrieves the recipient address from the OFT message.
* @param _msg The OFT message.
* @return The recipient address.
*/
function sendTo(bytes calldata _msg) internal pure returns (bytes32) {
return bytes32(_msg[:SEND_TO_OFFSET]);
}
/**
* @dev Retrieves the amount in shared decimals from the OFT message.
* @param _msg The OFT message.
* @return The amount in shared decimals.
*/
function amountSD(bytes calldata _msg) internal pure returns (uint64) {
return uint64(bytes8(_msg[SEND_TO_OFFSET:SEND_AMOUNT_SD_OFFSET]));
}
/**
* @dev Retrieves the composed message from the OFT message.
* @param _msg The OFT message.
* @return The composed message.
*/
function composeMsg(bytes calldata _msg) internal pure returns (bytes memory) {
return _msg[SEND_AMOUNT_SD_OFFSET:];
}
/**
* @dev Converts an address to bytes32.
* @param _addr The address to convert.
* @return The bytes32 representation of the address.
*/
function addressToBytes32(address _addr) internal pure returns (bytes32) {
return bytes32(uint256(uint160(_addr)));
}
/**
* @dev Converts bytes32 to an address.
* @param _b The bytes32 value to convert.
* @return The address representation of bytes32.
*/
function bytes32ToAddress(bytes32 _b) internal pure returns (address) {
return address(uint160(uint256(_b)));
}
}