LayerZero V2 OApp Quickstart
The OApp standard lets your contract send and receive arbitrary messages across chains. With OApp, you can update on-chain state on one network and trigger custom business logic on another.
OApp.sol
implements the core interface for calling LayerZero's Endpoint V2 on EVM chains. It also provides hookable _lzSend
and _lzReceive
methods so you can inject your own business logic:
If your use case only involves cross-chain token transfers, consider inheriting the OFT Standard instead of OApp.
Installation
To start using LayerZero contracts in a new project, use the LayerZero CLI tool, create-lz-oapp. The CLI tool is an npx package that allows developers to create any omnichain application in <4 minutes! Get started by running the following from your command line:
npx create-lz-oapp@latest --example oapp
This will create an example repository containing both the Hardhat and Foundry frameworks, LayerZero development utilities, as well as the OApp contract package pre-installed.
To use LayerZero contracts in an existing project, you can install the OApp package directly:
- npm
- yarn
- pnpm
- forge
npm install @layerzerolabs/oapp-evm
yarn add @layerzerolabs/oapp-evm
pnpm add @layerzerolabs/oapp-evm
forge init
forge install https://github.com/LayerZero-Labs/devtools
forge install https://github.com/LayerZero-Labs/layerzero-v2
forge install OpenZeppelin/openzeppelin-contracts@v5.1.0
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',
'@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/',
]
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",
}
Custom OApp Contract
To build your own cross-chain application, inherit from OApp.sol
and implement two key pieces:
- Send business logic: how you encode and dispatch a custom
_message
on the source - Receive business logic: how you decode and apply an incoming
_message
on the destination
Below is a complete example skeleton structure showing:
- A constructor wiring in the local Endpoint and owner
- A
sendString(...)
function that updates state, encodes a string, and calls_lzSend(...)
- An override of
_lzReceive(...)
that decodes the string and applies business logic - (Optional) a
quoteSendString(...)
function to query the fee details needed to callsendString(...)
// 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 Last string received from any remote chain
string public lastMessage;
/// @notice Msg type for sending a string, for use in OAppOptionsType3 as an enforced option
uint16 public constant SEND = 1;
/// @notice Initialize with Endpoint V2 and owner address
/// @param _endpoint The local chain's LayerZero Endpoint V2 address
/// @param _owner The address permitted to configure this OApp
constructor(address _endpoint, address _owner) OApp(_endpoint, _owner) Ownable(_owner) {}
// ────────────────────────────────────────────────────── ────────────────────────
// 0. (Optional) Quote business logic
//
// Example: Get a quote from the Endpoint for a cost estimate of sending a message.
// Replace this to mirror your own send business logic.
// ──────────────────────────────────────────────────────────────────────────────
/**
* @notice Quotes the gas needed to pay for the full omnichain transaction in native gas or ZRO token.
* @param _dstEid Destination chain's endpoint ID.
* @param _string The string to send.
* @param _options Message execution options (e.g., for sending gas to destination).
* @param _payInLzToken Whether to return fee in ZRO token.
* @return fee A `MessagingFee` struct containing the calculated gas fee in either the native token or ZRO token.
*/
function quoteSendString(
uint32 _dstEid,
string calldata _string,
bytes calldata _options,
bool _payInLzToken
) public view returns (MessagingFee memory fee) {
bytes memory _message = abi.encode(_string);
// combineOptions (from OAppOptionsType3) merges enforced options set by the contract owner
// with any additional execution options provided by the caller
fee = _quote(_dstEid, _message, combineOptions(_dstEid, SEND, _options), _payInLzToken);
}
// ──────────────────────────────────────────────────────────────────────────────
// 1. Send business logic
//
// Example: send a simple string to a remote chain. Replace this with your
// own state-update logic, then encode whatever data your application needs.
// ──────────────────────────────────────────────────────────────────────────────
/// @notice Send a string to a remote OApp on another chain
/// @param _dstEid Destination Endpoint ID (uint32)
/// @param _string The string to send
/// @param _options Execution options for gas on the destination (bytes)
function sendString(uint32 _dstEid, string calldata _string, bytes calldata _options) external payable {
// 1. (Optional) Update any local state here.
// e.g., record that a message was "sent":
// sentCount += 1;
// 2. Encode any data structures you wish to send into bytes
// You can use abi.encode, abi.encodePacked, or directly splice bytes
// if you know the format of your data structures
bytes memory _message = abi.encode(_string);
// 3. Call OAppSender._lzSend to package and dispatch the cross-chain message
// - _dstEid: remote chain's Endpoint ID
// - _message: ABI-encoded string
// - _options: combined execution options (enforced + caller-provided)
// - MessagingFee(msg.value, 0): pay all gas as native token; no ZRO
// - payable(msg.sender): refund excess gas to caller
//
// combineOptions (from OAppOptionsType3) merges enforced options set by the contract owner
// with any additional execution options provided by the caller
_lzSend(
_dstEid,
_message,
combineOptions(_dstEid, SEND, _options),
MessagingFee(msg.value, 0),
payable(msg.sender)
);
}
// ──────────────────────────────────────────────────────────────────────────────
// 2. Receive business logic
//
// Override _lzReceive to decode the incoming bytes and apply your logic.
// The base OAppReceiver.lzReceive ensures:
// • Only the LayerZero Endpoint can call this method
// • The sender is a registered peer (peers[srcEid] == origin.sender)
// ──────────────────────────────────────────────────────────────────────────────
/// @notice Invoked by OAppReceiver when EndpointV2.lzReceive is called
/// @dev _origin Metadata (source chain, sender address, nonce)
/// @dev _guid Global unique ID for tracking this message
/// @param _message ABI-encoded bytes (the string we sent earlier)
/// @dev _executor Executor address that delivered the message
/// @dev _extraData Additional data from the Executor (unused here)
function _lzReceive(
Origin calldata /*_origin*/,
bytes32 /*_guid*/,
bytes calldata _message,
address /*_executor*/,
bytes calldata /*_extraData*/
) internal override {
// 1. Decode the incoming bytes into a string
// You can use abi.decode, abi.decodePacked, or directly splice bytes
// if you know the format of your data structures
string memory _string = abi.decode(_message, (string));
// 2. Apply your custom logic. In this example, store it in `lastMessage`.
lastMessage = _string;
// 3. (Optional) Trigger further on-chain actions.
// e.g., emit an event, mint tokens, call another contract, etc.
// emit MessageReceived(_origin.srcEid, _string);
}
}
Constructor
- Pass the Endpoint V2 address and owner address into the base contracts.
OApp(_endpoint, _owner)
binds your contract to the local LayerZero Endpoint V2 and registers the owner as the delegate, making it the only address that can change configurations (such as libraries, DVNs, and Executors.Ownable(_owner)
makes_owner
the only address that can change configurations (such as peers, enforced options, and delegate).
- After deployment, the owner can call:
setConfig(...)
to adjust library or DVN parameterssetSendLibrary(...)
andsetReceiveLibrary(...)
to override default librariessetPeer(...)
to whitelist remote OApp addressessetDelegate(...)
to assign a different delegate address
A full overview of how to use these adminstrative functions can be found below under Deployment & Wiring.
sendString(...)
-
Update local state (optional)
- Before sending, you might update a counter, lock tokens, or perform any on-chain action specific to your app.
-
Encode the message
- Use
abi.encode(_message)
,abi.encodePacked(_message)
, or manual byte shifting/offsets to turn the string into abytes
array. LayerZero packets carry rawbytes
, so you must encode any data type into bytes first.
- Use
-
Call
_lzSend(...)
_dstEid
is the destination chain's Endpoint ID. LayerZero uses numeric IDs (e.g.,30101
for Ethereum,30168
for Solana)._message
is the ABI-encoded string (bytes memory
)._options
is abytes
array specifying gas or executor instructions for the destination. For example, anExecutorLzReceiveOption
tells the destination how much gas to allocate to your receive call.MessagingFee(msg.value, 0)
pays fees in native gas. If you wanted to pay in ZRO tokens, set the second field instead.payable(msg.sender)
specifies the refund address for any unused gas. This can be any address (EOA or contract), but if it's a contract, the contract must have a fallback function to receive the refund.
_lzReceive(...)
-
Endpoint verification
- Only the LayerZero Endpoint V2 contract can invoke this function. The base
OAppReceiver
enforces that. - The call succeeds only if
_origin.sender == peers[_origin.srcEid]
. In other words, the sender's address must match the registered peer for that source chain.
- Only the LayerZero Endpoint V2 contract can invoke this function. The base
-
Decode the incoming bytes
- Use
abi.decode(_message, (string))
to extract the original string. If you sent a different data type (e.g., a struct), decode with the matching types. - Alternatively, you can use
abi.decodePacked()
for packed encoding, or manually splice bytes from specific offsets if you know the exact format of your data structures.
- Use
-
Apply your business logic
- In this example, we store the decoded string in
lastMessage
. - You could instead:
- Emit an event (e.g.,
emit MessageReceived(_origin.srcEid, decoded)
) - Mint or unlock tokens based on the message
- Call another contract to trigger a downstream workflow
- Emit an event (e.g.,
- In this example, we store the decoded string in
Always include all five parameters (_origin
, _guid
, _message
, _executor
, _extraData
) in your override. Even if you only use _message
, matching the function signature ensures the Endpoint can call your method correctly.
(Optional) quoteSendString(...)
You can optionally call the internal OAppSender._quote(...)
method in a public function to provide accurate estimation for the gas cost of calling MyOApp.sendString(...)
.
The internal _quote
method queries the send library selected by the OApp and asks the workers (DVNs and Executor) for fee details for the given encoded message:
-
Fee estimation before sending
- Before calling
sendString(...)
, you need to know how much native gas (or ZRO tokens) to send with your transaction. ThequoteSendString(...)
function provides this cost estimate.
- Before calling
-
Mirrors send logic
- The quote function uses the same message encoding (
abi.encode(_string)
) and option handling (combineOptions(_dstEid, SEND, _options)
) as the actual send function, ensuring accurate fee estimates.
- The quote function uses the same message encoding (
-
Enforced options integration
- By inheriting
OAppOptionsType3
and usingcombineOptions(...)
, the quote function automatically includes any enforced options that the contract owner has configured for theSEND
message type, plus any additional options provided by the caller.
- By inheriting
-
Flexible payment options
-
The
_payInLzToken
parameter lets you choose whether to pay fees in the native gas token of the source chain or in ZRO tokens.Example usage:
// Get fee estimate first
MessagingFee memory fee = myOApp.quoteSendString(
dstEid,
"Hello World",
"0x", // no additional options
false // pay in native gas
);
// Then send with the estimated fee
myOApp.sendString{value: fee.nativeFee}(
dstEid,
"Hello World",
"0x"
); -
This section shows you exactly:
- Where to update or check local state before sending
- How to encode and send your application data over LayerZero
- Where to decode incoming data and execute your custom logic
Replace the string
examples with whatever data structures and state changes your application requires.
Deployment and Wiring
After you finish writing and testing your MyOApp
contract, follow these steps to deploy it on each network and wire up the messaging stack.
We strongly recommend using the LayerZero CLI tool to manage your configurations. Our config generator simplifies access to all available deployments across networks and is the preferred method for cross-chain messaging. See the CLI Guide for examples and how to use it in your project.
1. Deploy Your OApp Contract
Deploy MyOApp
on each chain using either the LayerZero CLI (recommended) or manual deployment scripts.
- LayerZero CLI
- Manual Foundry
After running pnpm compile
at the root level of your example repo, you can deploy your contracts.
Network Configuration
Before using the CLI, you'll need to configure your networks in hardhat.config.ts
with LayerZero Endpoint IDs and declare an RPC URL in your .env
or directly in the config file:
// hardhat.config.ts
import { EndpointId } from '@layerzerolabs/lz-definitions'
// ... rest of hardhat config omitted for brevity
networks: {
'optimism-sepolia-testnet': {
eid: EndpointId.OPTSEP_V2_TESTNET,
url: process.env.RPC_URL_OP_SEPOLIA || 'https://optimism-sepolia.gateway.tenderly.co',
accounts,
},
'avalanche-fuji-testnet': {
eid: EndpointId.AVALANCHE_V2_TESTNET,
url: process.env.RPC_URL_FUJI || 'https://avalanche-fuji.drpc.org',
accounts,
},
'arbitrum-sepolia-testnet': {
eid: EndpointId.ARBSEP_V2_TESTNET,
url: process.env.RPC_URL_ARB_SEPOLIA || 'https://arbitrum-sepolia.gateway.tenderly.co',
accounts,
},
}
The key addition to a standard hardhat.config.ts
is the inclusion of LayerZero Endpoint IDs (eid
) for each network. Check the Deployments section for all available endpoint IDs.
The LayerZero CLI provides automated deployment with built-in endpoint detection based on your hardhat.config.ts
networks object:
# Deploy using interactive prompts
npx hardhat lz:deploy
The CLI will prompt you to:
- Select chains to deploy to:
? Which networks would you like to deploy? ›
◉ fuji
◉ amoy
◉ sepolia
- Choose deploy script tags:
? Which deploy script tags would you like to use? › MyOApp
- Confirm deployment:
✔ Do you want to continue? … yes
Network: amoy
Deployer: 0x0000000000000000000000000000000000000000
Network: sepolia
Deployer: 0x0000000000000000000000000000000000000000
Deployed contract: MyOApp, network: amoy, address: 0x0000000000000000000000000000000000000000
Deployed contract: MyOApp, network: sepolia, address: 0x0000000000000000000000000000000000000000
The CLI automatically:
- Detects the correct LayerZero Endpoint V2 address for each chain
- Deploys your OApp contract with proper constructor arguments
- Generates deployment artifacts in
./deployments/
folder - Creates network-specific deployment files (e.g.,
deployments/sepolia/MyOApp.json
)
For manual deployment using Foundry, create a deployment script that handles endpoint addresses:
// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.22;
import "forge-std/Script.sol";
import { MyOApp } from "../contracts/MyOApp.sol";
contract DeployOApp is Script {
function run() external {
// Replace these env vars with your own values
address endpoint = vm.envAddress("ENDPOINT_ADDRESS");
address owner = vm.envAddress("OWNER_ADDRESS");
vm.startBroadcast(vm.envUint("PRIVATE_KEY"));
MyOApp oapp = new MyOApp(endpoint, owner);
vm.stopBroadcast();
console.log("MyOApp deployed to:", address(oapp));
}
}
Run the deployment script:
# Deploy to testnet
forge script script/DeployOApp.s.sol --rpc-url $RPC_URL --broadcast --verify
# Deploy to multiple chains
forge script script/DeployOApp.s.sol --rpc-url $ETHEREUM_RPC --broadcast --verify
forge script script/DeployOApp.s.sol --rpc-url $POLYGON_RPC --broadcast --verify
You'll need to set the correct LayerZero Endpoint V2 addresses for each chain in your environment variables. Check the Deployments section for endpoint addresses.
2. Wire Messaging Libraries and Configurations
Once your contracts are on-chain, you must set up send/receive libraries and DVN/Executor settings so cross-chain messages flow correctly.
- LayerZero CLI
- Manual Foundry
The LayerZero CLI automatically handles all wiring via a single configuration file and command:
Configuration File
In your project root, you can find a layerzero.config.ts
file:
import {EndpointId} from '@layerzerolabs/lz-definitions';
import {ExecutorOptionType} from '@layerzerolabs/lz-v2-utilities';
import {TwoWayConfig, generateConnectionsConfig} from '@layerzerolabs/metadata-tools';
import {OAppEnforcedOption, OmniPointHardhat} from '@layerzerolabs/toolbox-hardhat';
// This contract object defines the OApp deployment on Optimism Sepolia testnet
// The config references the contract deployment from your ./deployments folder
const optimismContract: OmniPointHardhat = {
eid: EndpointId.OPTSEP_V2_TESTNET,
contractName: 'MyOApp',
};
const avalancheContract: OmniPointHardhat = {
eid: EndpointId.AVALANCHE_V2_TESTNET,
contractName: 'MyOApp',
};
const arbitrumContract: OmniPointHardhat = {
eid: EndpointId.ARBSEP_V2_TESTNET,
contractName: 'MyOApp',
};
// For this example's simplicity, we will use the same enforced options values for sending to all chains
// For production, you should ensure `gas` is set to the correct value through profiling the gas usage of calling OApp._lzReceive(...) on the destination chain
// To learn more, read https://docs.layerzero.network/v2/concepts/applications/oapp-standard#execution-options-and-enforced-settings
const EVM_ENFORCED_OPTIONS: OAppEnforcedOption[] = [
{
msgType: 1,
optionType: ExecutorOptionType.LZ_RECEIVE,
gas: 80000,
value: 0,
},
];
// To connect all the above chains to each other, we need the following pathways:
// Optimism <-> Avalanche
// Optimism <-> Arbitrum
// Avalanche <-> Arbitrum
// With the config generator, pathways declared are automatically bidirectional
// i.e. if you declare A,B there's no need to declare B,A
const pathways: TwoWayConfig[] = [
[
optimismContract, // Chain A contract
avalancheContract, // Chain B contract
[['LayerZero Labs'], []], // [ requiredDVN[], [ optionalDVN[], threshold ] ]
[1, 1], // [A to B confirmations, B to A confirmations]
[EVM_ENFORCED_OPTIONS, EVM_ENFORCED_OPTIONS], // Chain B enforcedOptions, Chain A enforcedOptions
],
[
optimismContract, // Chain A contract
arbitrumContract, // Chain C contract
[['LayerZero Labs'], []], // [ requiredDVN[], [ optionalDVN[], threshold ] ]
[1, 1], // [A to B confirmations, B to A confirmations]
[EVM_ENFORCED_OPTIONS, EVM_ENFORCED_OPTIONS], // Chain C enforcedOptions, Chain A enforcedOptions
],
[
avalancheContract, // Chain B contract
arbitrumContract, // Chain C contract
[['LayerZero Labs'], []], // [ requiredDVN[], [ optionalDVN[], threshold ] ]
[1, 1], // [A to B confirmations, B to A confirmations]
[EVM_ENFORCED_OPTIONS, EVM_ENFORCED_OPTIONS], // Chain C enforcedOptions, Chain B enforcedOptions
],
];
export default async function () {
// Generate the connections config based on the pathways
const connections = await generateConnectionsConfig(pathways);
return {
contracts: [
{contract: optimismContract},
{contract: avalancheContract},
{contract: arbitrumContract},
],
connections,
};
}
Make sure your contract object's contractName
matches the named deployment file for the network under ./deployments/
.
Wire Everything
Run a single command to configure all pathways:
npx hardhat lz:oapp:wire --oapp-config layerzero.config.ts
This automatically handles:
- Fetching the necessary contract addresses for each network from metadata
- Setting send and receive libraries
- Configuring DVNs and Executors
- Setting up peers between contracts
- Applying enforced options
- All bidirectional pathways in your config
For manual configuration using Foundry scripts, follow these steps:
Environment Setup
Here's a comprehensive .env.example
file showing all the environment variables needed for the different configuration scripts:
# Common variables used across scripts
ENDPOINT_ADDRESS=0x... # LayerZero Endpoint V2 address
OAPP_ADDRESS=0x... # Your OApp contract address
SIGNER=0x... # Address with permissions to configure/send
# Library Configuration (SetLibraries.s.sol)
SEND_LIB_ADDRESS=0x... # SendUln302 address
RECEIVE_LIB_ADDRESS=0x... # ReceiveUln302 address
DST_EID=30101 # Destination chain EID
SRC_EID=30110 # Source chain EID
GRACE_PERIOD=0 # Grace period for library switch (0 for immediate)
# Send Config (SetSendConfig.s.sol)
SOURCE_ENDPOINT_ADDRESS=0x... # Chain A Endpoint address
SENDER_OAPP_ADDRESS=0x... # OApp on Chain A
REMOTE_EID=30101 # Endpoint ID for Chain B
# Peer Configuration (SetPeers.s.sol)
CHAIN1_EID=30101 # First chain EID
CHAIN1_PEER=0x... # OApp address on first chain
CHAIN2_EID=30110 # Second chain EID
CHAIN2_PEER=0x... # OApp address on second chain
CHAIN3_EID=30111 # Third chain EID
CHAIN3_PEER=0x... # OApp address on third chain
# Message Sending (SendMessage.s.sol)
MESSAGE="Hello World" # Message to send cross-chain
2.1 Set Send and Receive Libraries
- Choose your libraries (addresses of deployed MessageLib contracts). For standard cross-chain messaging, you should use
SendUln302.sol
forsetSendLibrary(...)
andReceiveUln302.sol
forsetReceiveLibrary(...)
. You can find the deployments for these contracts under the Deployments section. - Call
setSendLibrary(oappAddress, dstEid, sendLibAddress)
on the Endpoint. - Call
setReceiveLibrary(oappAddress, srcEid, receiveLibAddress, gracePeriod)
on the Endpoint.
// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.22;
import "forge-std/Script.sol";
import { ILayerZeroEndpointV2 } from "@layerzerolabs/lz-evm-protocol-v2/contracts/interfaces/ILayerZeroEndpointV2.sol";
/// @title LayerZero Library Configuration Script
/// @notice Sets up send and receive libraries for OApp messaging
contract SetLibraries is Script {
function run() external {
// Load environment variables
address endpoint = vm.envAddress("ENDPOINT_ADDRESS"); // LayerZero Endpoint address
address oapp = vm.envAddress("OAPP_ADDRESS"); // Your OApp contract address
address signer = vm.envAddress("SIGNER"); // Address with permissions to configure
// Library addresses
address sendLib = vm.envAddress("SEND_LIB_ADDRESS"); // SendUln302 address
address receiveLib = vm.envAddress("RECEIVE_LIB_ADDRESS"); // ReceiveUln302 address
// Chain configurations
uint32 dstEid = uint32(vm.envUint("DST_EID")); // Destination chain EID
uint32 srcEid = uint32(vm.envUint("SRC_EID")); // Source chain EID
uint32 gracePeriod = uint32(vm.envUint("GRACE_PERIOD")); // Grace period for library switch
vm.startBroadcast(signer);
// Set send library for outbound messages
ILayerZeroEndpointV2(endpoint).setSendLibrary(
oapp, // OApp address
dstEid, // Destination chain EID
sendLib // SendUln302 address
);
// Set receive library for inbound messages
ILayerZeroEndpointV2(endpoint).setReceiveLibrary(
oapp, // OApp address
srcEid, // Source chain EID
receiveLib, // ReceiveUln302 address
gracePeriod // Grace period for library switch
);
vm.stopBroadcast();
}
}
You would need to set up your .env
file with the appropriate values:
ENDPOINT_ADDRESS=0x...
OAPP_ADDRESS=0x...
SIGNER=0x...
SEND_LIB_ADDRESS=0x... # SendUln302 address
RECEIVE_LIB_ADDRESS=0x... # ReceiveUln302 address
DST_EID=30101
SRC_EID=30110
GRACE_PERIOD=0 # Set to 0 for immediate switch, or block number for gradual migration
2.2 Set Send Config and Receive Config
If you need non-default DVN or Executor settings (block confirmations, required DVNs, max message size, etc.), call setConfig(...)
next. To see defaults, use getConfig(...)
.
Send Config (A → B):
The send config is set on the source chain (Chain A) and applies to messages being sent from Chain A to Chain B. This config determines the DVN and Executor settings for outbound messages leaving Chain A and destined for Chain B. You must call setConfig
on the Endpoint contract on Chain A, specifying the remote Endpoint ID for Chain B and the appropriate SendLib address for the A → B pathway.
// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.22;
import "forge-std/Script.sol";
import { ILayerZeroEndpointV2, SetConfigParam } from "@layerzerolabs/lz-evm-protocol-v2/contracts/interfaces/ILayerZeroEndpointV2.sol";
import { UlnConfig } from "@layerzerolabs/lz-evm-messagelib-v2/contracts/uln/UlnBase.sol";
import { ExecutorConfig } from "@layerzerolabs/lz-evm-messagelib-v2/contracts/SendLibBase.sol";
/// @title LayerZero Send Configuration Script (A → B)
/// @notice Defines and applies ULN (DVN) + Executor configs for cross‑chain messages sent from Chain A to Chain B via LayerZero Endpoint V2.
contract SetSendConfig is Script {
uint32 constant EXECUTOR_CONFIG_TYPE = 1;
uint32 constant ULN_CONFIG_TYPE = 2;
/// @notice Broadcasts transactions to set both Send ULN and Executor configurations for messages sent from Chain A to Chain B
function run() external {
address endpoint = vm.envAddress("SOURCE_ENDPOINT_ADDRESS"); // Chain A Endpoint
address oapp = vm.envAddress("SENDER_OAPP_ADDRESS"); // OApp on Chain A
uint32 eid = uint32(vm.envUint("REMOTE_EID")); // Endpoint ID for Chain B
address sendLib = vm.envAddress("SEND_LIB_ADDRESS"); // SendLib for A → B
address signer = vm.envAddress("SIGNER");
/// @notice ULNConfig defines security parameters (DVNs + confirmation threshold) for A → B
/// @notice Send config requests these settings to be applied to the DVNs and Executor for messages sent from A to B
/// @dev 0 values will be interpretted as defaults, so to apply NIL settings, use:
/// @dev uint8 internal constant NIL_DVN_COUNT = type(uint8).max;
/// @dev uint64 internal constant NIL_CONFIRMATIONS = type(uint64).max;
UlnConfig memory uln = UlnConfig({
confirmations: 15, // minimum block confirmations required on A before sending to B
requiredDVNCount: 2, // number of DVNs required
optionalDVNCount: type(uint8).max, // optional DVNs count, uint8
optionalDVNThreshold: 0, // optional DVN threshold
requiredDVNs: [address(0x1111...), address(0x2222...)], // sorted list of required DVN addresses
optionalDVNs: [] // sorted list of optional DVNs
});
/// @notice ExecutorConfig sets message size limit + fee‑paying executor for A → B
ExecutorConfig memory exec = ExecutorConfig({
maxMessageSize: 10000, // max bytes per cross-chain message
executor: address(0x3333...) // address that pays destination execution fees on B
});
bytes memory encodedUln = abi.encode(uln);
bytes memory encodedExec = abi.encode(exec);
SetConfigParam[] memory params = new SetConfigParam[](2);
params[0] = SetConfigParam(eid, EXECUTOR_CONFIG_TYPE, encodedExec);
params[1] = SetConfigParam(eid, ULN_CONFIG_TYPE, encodedUln);
vm.startBroadcast(signer);
ILayerZeroEndpointV2(endpoint).setConfig(oapp, sendLib, params); // Set config for messages sent from A to B
vm.stopBroadcast();
}
}
Receive Config (B ← A):
The receive config is set on the destination chain (Chain B) and applies to messages being received on Chain B from Chain A. This config determines the DVN settings for inbound messages arriving from Chain A. You must call setConfig
on the Endpoint contract on Chain B, specifying the remote Endpoint ID for Chain A and the appropriate ReceiveLib address for the B ← A pathway.
// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.22;
import "forge-std/Script.sol";
import { ILayerZeroEndpointV2, SetConfigParam } from "@layerzerolabs/lz-evm-protocol-v2/contracts/interfaces/ILayerZeroEndpointV2.sol";
import { UlnConfig } from "@layerzerolabs/lz-evm-messagelib-v2/contracts/uln/UlnBase.sol";
/// @title LayerZero Receive Configuration Script (B ← A)
/// @notice Defines and applies ULN (DVN) config for inbound message verification on Chain B for messages received from Chain A via LayerZero Endpoint V2.
contract SetReceiveConfig is Script {
uint32 constant RECEIVE_CONFIG_TYPE = 2;
function run() external {
address endpoint = vm.envAddress("ENDPOINT_ADDRESS"); // Chain B Endpoint
address oapp = vm.envAddress("OAPP_ADDRESS"); // OApp on Chain B
uint32 eid = uint32(vm.envUint("REMOTE_EID")); // Endpoint ID for Chain A
address receiveLib= vm.envAddress("RECEIVE_LIB_ADDRESS"); // ReceiveLib for B ← A
address signer = vm.envAddress("SIGNER");
/// @notice UlnConfig controls verification threshold for incoming messages from A to B
/// @notice Receive config enforces these settings have been applied to the DVNs for messages received from A
/// @dev 0 values will be interpretted as defaults, so to apply NIL settings, use:
/// @dev uint8 internal constant NIL_DVN_COUNT = type(uint8).max;
/// @dev uint64 internal constant NIL_CONFIRMATIONS = type(uint64).max;
UlnConfig memory uln = UlnConfig({
confirmations: 15, // min block confirmations from source (A)
requiredDVNCount: 2, // required DVNs for message acceptance
optionalDVNCount: type(uint8).max, // optional DVNs count
optionalDVNThreshold: 0, // optional DVN threshold
requiredDVNs: [address(0x1111...), address(0x2222...)], // sorted required DVNs
optionalDVNs: [] // no optional DVNs
});
bytes memory encodedUln = abi.encode(uln);
SetConfigParam[] memory params = new SetConfigParam[](1);
params[0] = SetConfigParam(eid, RECEIVE_CONFIG_TYPE, encodedUln);
vm.startBroadcast(signer);
ILayerZeroEndpointV2(endpoint).setConfig(oapp, receiveLib, params); // Set config for messages received on B from A
vm.stopBroadcast();
}
}
2.3 Set Peers
Once you've finished your OApp Configuration you can open the messaging channel and connect your OApp deployments by calling setPeer
.
A peer is required to be set for each EID (or network). Ideally an OApp (or OFT) will have multiple peers set where one and only one peer exists for one EID.
The function takes 2 arguments: _eid
, the destination endpoint ID for the chain our other OApp contract lives on, and _peer
, the destination OApp contract address in bytes32
format.
// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.22;
import "forge-std/Script.sol";
import { MyOApp } from "../contracts/MyOApp.sol";
/// @title LayerZero OApp Peer Configuration Script
/// @notice Sets up peer connections between OApp deployments on different chains
contract SetPeers is Script {
function run() external {
// Load environment variables
address oapp = vm.envAddress("OAPP_ADDRESS"); // Your OApp contract address
address signer = vm.envAddress("SIGNER"); // Address with owner permissions
// Example: Set peers for different chains
// Format: (chain EID, peer address in bytes32)
(uint32 eid1, bytes32 peer1) = (uint32(vm.envUint("CHAIN1_EID")), bytes32(uint256(uint160(vm.envAddress("CHAIN1_PEER")))));
(uint32 eid2, bytes32 peer2) = (uint32(vm.envUint("CHAIN2_EID")), bytes32(uint256(uint160(vm.envAddress("CHAIN2_PEER")))));
(uint32 eid3, bytes32 peer3) = (uint32(vm.envUint("CHAIN3_EID")), bytes32(uint256(uint160(vm.envAddress("CHAIN3_PEER")))));
vm.startBroadcast(signer);
// Set peers for each chain
MyOApp(oapp).setPeer(eid1, peer1);
MyOApp(oapp).setPeer(eid2, peer2);
MyOApp(oapp).setPeer(eid3, peer3);
vm.stopBroadcast();
}
}
This function opens your OApp to start receiving messages from the messaging channel, meaning you should configure any application settings you intend on changing prior to calling setPeer
.
OApps need setPeer
to be called correctly on both contracts to send messages. The peer address uses bytes32
for handling non-EVM destination chains.
If the peer has been set to an incorrect destination address, your messages will not be delivered and handled properly. If not resolved, users can potentially pay gas on source without any corresponding action on destination. You can confirm the peer address is the expected destination OApp address by viewing the peers
mapping directly.
2.4 Set Enforced Options
Enforced options allow the OApp owner to set mandatory execution parameters that will be applied to all messages of a specific type sent to a destination chain. These options are automatically combined with any caller-provided options when using OAppOptionsType3
.
Why use enforced options?
- Ensure sufficient gas is always allocated for message execution on the destination
- Enforce payment for additional services like PreCrime verification
- Set consistent execution parameters across all users of your OApp
- Prevent failed deliveries due to insufficient gas
// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.22;
import "forge-std/Script.sol";
import { MyOApp } from "../contracts/MyOApp.sol";
import { EnforcedOptionParam } from "@layerzerolabs/oapp-evm/contracts/oapp/libs/OAppOptionsType3.sol";
import { OptionsBuilder } from "@layerzerolabs/oapp-evm/contracts/oapp/libs/OptionsBuilder.sol";
/// @title LayerZero OApp Enforced Options Configuration Script
/// @notice Sets enforced execution options for specific message types and destinations
contract SetEnforcedOptions is Script {
using OptionsBuilder for bytes;
function run() external {
// Load environment variables
address oapp = vm.envAddress("OAPP_ADDRESS"); // Your OApp contract address
address signer = vm.envAddress("SIGNER"); // Address with owner permissions
// Destination chain configurations
uint32 dstEid1 = uint32(vm.envUint("DST_EID_1")); // First destination EID
uint32 dstEid2 = uint32(vm.envUint("DST_EID_2")); // Second destination EID
// Message type (should match your contract's constant)
uint16 SEND = 1; // Message type for sendString function
// Build options using OptionsBuilder
bytes memory options1 = OptionsBuilder.newOptions().addExecutorLzReceiveOption(80000, 0);
bytes memory options2 = OptionsBuilder.newOptions().addExecutorLzReceiveOption(100000, 0);
// Create enforced options array
EnforcedOptionParam[] memory enforcedOptions = new EnforcedOptionParam[](2);
// Set enforced options for first destination
enforcedOptions[0] = EnforcedOptionParam({
eid: dstEid1,
msgType: SEND,
options: options1
});
// Set enforced options for second destination
enforcedOptions[1] = EnforcedOptionParam({
eid: dstEid2,
msgType: SEND,
options: options2
});
vm.startBroadcast(signer);
// Set enforced options on the OApp
MyOApp(oapp).setEnforcedOptions(enforcedOptions);
vm.stopBroadcast();
console.log("Enforced options set successfully!");
console.log("Destination 1 EID:", dstEid1, "Gas:", 80000);
console.log("Destination 2 EID:", dstEid2, "Gas:", 100000);
}
}
Environment variables needed:
OAPP_ADDRESS=0x... # Your deployed MyOApp address
SIGNER=0x... # Address with owner permissions
DST_EID_1=30101 # First destination endpoint ID
DST_EID_2=30110 # Second destination endpoint ID
Run the script:
forge script script/SetEnforcedOptions.s.sol --rpc-url $RPC_URL --broadcast
Once set, these enforced options will be automatically applied when using combineOptions()
in your send functions, ensuring consistent execution parameters across all messages.
Usage
Once deployed and wired, you can begin sending cross-chain messages.
Calling send
- LayerZero CLI
- Manual Foundry
The LayerZero CLI provides a convenient task for sending messages that automatically handles fee estimation and transaction execution.
Using the Send Task
The CLI includes a built-in lz:oapp:send
task that:
- Quotes the gas cost using your OApp's
quoteSendString()
function - Sends the message with the correct fee
- Waits for confirmation and provides tracking links
Basic usage:
npx hardhat lz:oapp:send --dst-eid 30101 --string "Hello ethereum" --network arbitrum-sepolia-testnet
Parameters:
--dst-eid
: Destination endpoint ID (required)--string
: Message to send (required)--network
: Source network name from your hardhat config (required)--options
: Execution options in hex format (optional, defaults to0x
)
Example output:
Initiating string send from arbitrum-sepolia-testnet to ethereum-sepolia-testnet
String to send: "Hello ethereum"
Destination EID: 30101
Using signer: 0x1234567890123456789012345678901234567890
MyOApp contract found at: 0xabcdefabcdefabcdefabcdefabcdefabcdefabcd
Execution options: 0x
Quoting gas cost for the send transaction...
Native fee: 0.001234567890123456 ETH
LZ token fee: 0 LZ
Sending the string transaction...
Transaction hash: 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
Waiting for transaction confirmation...
Gas used: 123456
Block number: 1234567
✅ SENT_VIA_OAPP: Successfully sent "Hello ethereum" from arbitrum-sepolia-testnet to ethereum-sepolia-testnet
✅ TX_HASH: Block explorer link for source chain arbitrum-sepolia-testnet: https://sepolia.arbiscan.io/tx/0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
✅ EXPLORER_LINK: LayerZero Scan link for tracking cross-chain delivery: https://testnet.layerzeroscan.com/tx/0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
The task automatically:
- Finds your deployed
MyOApp
contract - Quotes the exact gas fee needed
- Sends the transaction with proper gas estimation
- Provides block explorer and LayerZero Scan links for tracking
For manual message sending using Foundry, create a script that handles fee estimation and message transmission:
// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.22;
import "forge-std/Script.sol";
import { MyOApp } from "../contracts/MyOApp.sol";
import { MessagingFee } from "@layerzerolabs/oapp-evm/contracts/oapp/OApp.sol";
/// @title LayerZero OApp Message Sending Script
/// @notice Demonstrates how to send messages between OApp deployments
contract SendMessage is Script {
function run() external {
// Load environment variables
address oapp = vm.envAddress("OAPP_ADDRESS"); // Your OApp contract address
address signer = vm.envAddress("SIGNER"); // Address with permissions to send
// Destination chain configuration
uint32 dstEid = uint32(vm.envUint("DST_EID")); // Destination chain EID
// Message to send
string memory message = vm.envString("MESSAGE"); // Your cross-chain message
bytes memory options = vm.envBytes("OPTIONS"); // Execution options (or use "0x" for default)
// Get the MyOApp contract instance
MyOApp myOApp = MyOApp(oapp);
// 1. Quote the gas cost first
MessagingFee memory fee = myOApp.quoteSendString(
dstEid,
message,
options,
false // Pay in native gas, not ZRO tokens
);
console.log("Estimated native fee:", fee.nativeFee);
console.log("Estimated LZ token fee:", fee.lzTokenFee);
// 2. Send the message with the quoted fee
vm.startBroadcast(signer);
myOApp.sendString{value: fee.nativeFee}(
dstEid,
message,
options
);
vm.stopBroadcast();
console.log("Message sent successfully!");
}
}
Environment variables needed:
OAPP_ADDRESS=0x... # Your deployed MyOApp address
SIGNER=0x... # Private key or address with permissions
DST_EID=30101 # Destination endpoint ID
MESSAGE="Hello World" # Message to send
OPTIONS=0x # Execution options (0x for default)
Run the script:
forge script script/SendMessage.s.sol --rpc-url $RPC_URL --broadcast
Extensions
The OApp Standard can be extended with various messaging patterns to support complex cross-chain applications. Each pattern functions as a distinct omnichain building block, capable of being used independently or in combination.
ABA (Ping-Pong) Pattern
The ABA pattern enables nested messaging where a message sent from Chain A to Chain B triggers another message back to Chain A (A
→ B
→ A
). This is useful for cross-chain authentication, data feeds, or conditional contract execution.
Implementation
The key is to nest an _lzSend
call within your _lzReceive
function:
function _lzReceive(
Origin calldata _origin,
bytes32 /*_guid*/,
bytes calldata _message,
address /*_executor*/,
bytes calldata /*_extraData*/
) internal override {
// Decode the incoming message
(string memory data, uint16 msgType, bytes memory returnOptions) = abi.decode(_message, (string, uint16, bytes));
// Process the message
lastMessage = data;
if (msgType == SEND_ABA) {
// Send response back to origin chain
_lzSend(
_origin.srcEid,
abi.encode("Response from Chain B", SEND),
returnOptions,
MessagingFee(msg.value, 0),
payable(address(this))
);
}
}
ABA Pattern Gas Planning: When implementing the ABA pattern, consider these important factors:
-
Encode return options in your message: Include the
_options
parameter for the B→A transaction within your A→B message encoding, as shown in the example above withreturnOptions
. -
Calculate total gas costs upfront: The source OApp (A) needs to know the full transaction cost for the entire A→B→A flow. You should:
- Quote the cost of the B→A transaction beforehand
- Include this cost in your
lzReceiveOption
gas allocation for the A→B transaction - Ensure sufficient
msg.value
is forwarded to cover both legs of the journey
-
Example gas calculation:
// Quote B→A cost first
MessagingFee memory returnFee = quoteBtoA(returnOptions);
// Include return fee in A→B options
bytes memory abaOptions = OptionsBuilder.newOptions()
.addExecutorLzReceiveOption(baseGas + returnGas, returnFee.nativeFee);
This ensures your ABA transaction has sufficient gas to complete the full round trip.
Batch Send
Batch Send allows a single transaction to initiate multiple _lzSend
calls to various destination chains, reducing operational overhead for multi-chain operations.
Implementation
/// @notice Estimates total LayerZero fees for sending the same message to multiple chains.
/// @param _dstEids Array of destination chain endpoint IDs.
/// @param _string The message string to send.
/// @param _options Extra options (gas, adapter params, etc.).
/// @return totalFee Aggregated native and ZRO fees across all destinations.
function quoteBatchSend(
uint32[] memory _dstEids,
string memory _string,
bytes calldata _options,
bool _payInLzToken
) public view returns (MessagingFee memory totalFee) {
bytes memory _message = abi.encode(_string);
uint256 len = _dstEids.length;
uint256 nativeSum = 0;
uint256 zroSum = 0;
for (uint256 i = 0; i < len; i++) {
uint32 dst = _dstEids[i];
bytes memory opts = combineOptions(dst, SEND, _options);
MessagingFee memory fee = _quote(dst, _message, opts, _payInLzToken);
nativeSum += fee.nativeFee;
zroSum += fee.zroFee;
}
return MessagingFee(nativeSum, zroSum);
}
function batchSend(
uint32[] memory _dstEids,
string memory _string,
bytes calldata _options
) external payable {
bytes memory _message = abi.encode(_string);
uint256 len = _dstEids.length;
// 1) Compute each fee exactly once
MessagingFee[] memory fees = new MessagingFee[](len);
uint256 totalNativeFee = 0;
for (uint256 i = 0; i < len; i++) {
bytes memory opts = combineOptions(_dstEids[i], SEND, _options);
// only one _quote call per destination
fees[i] = _quote(_dstEids[i], _message, opts, /*payInZRO=*/ false);
totalNativeFee += fees[i].nativeFee;
}
// 2) Check up‐front that the caller supplied enough
require(msg.value >= totalNativeFee, "Insufficient fee");
// 3) Now do all the sends, reusing the fees we already fetched
for (uint256 i = 0; i < len; i++) {
bytes memory opts = combineOptions(_dstEids[i], SEND, _options);
_lzSend(
_dstEids[i],
_message,
opts,
fees[i],
payable(msg.sender)
);
}
}
Call Composer
Composed messaging enables horizontal composability where a message triggers external contract calls on the destination chain through lzCompose
. Unlike vertical composability (multiple calls in a single transaction), horizontal composability processes operations as separate, containerized message packets.
Benefits of Horizontal Composability
- Fault Isolation: If a composed call fails, it doesn't revert the main token transfer or message
- Gas Efficiency: Each step can have independent gas limits and execution options
- Flexible Workflows: Complex multi-step operations can be broken into manageable pieces
Sending Side
function sendStringToComposer(
uint32 _dstEid,
string memory _string,
address _composer,
bytes calldata _extraOptions
) external payable {
// Include both lzReceive and lzCompose options in enforcedOptions or extraOptions
bytes memory composedOptions = OptionsBuilder.newOptions()
.addExecutorLzReceiveOption(65000, 0) // For the main receive
.addExecutorLzComposeOption(0, 50000, 0); // For the compose call
bytes memory _message = abi.encode(_string, _composer);
_lzSend(
_dstEid,
_message,
composedOptions,
MessagingFee(msg.value, 0),
payable(msg.sender)
);
}
Receiving Side
function _lzReceive(
Origin calldata _origin,
bytes32 _guid,
bytes calldata _message,
address /*_executor*/,
bytes calldata /*_extraData*/
) internal override {
(string memory _string, address composer) = abi.decode(_message, (string, address));
// Store the message and perform primary logic
lastMessage = _string;
// Send composed message to external contract as separate message packet
endpoint.sendCompose(composer, _guid, 0, _message);
}
Composer Contract
import { IOAppComposer } from "@layerzerolabs/oapp-evm/contracts/oapp/interfaces/IOAppComposer.sol";
contract Composer is IOAppComposer {
address public immutable endpoint;
address public immutable trustedOApp;
constructor(address _endpoint, address _trustedOApp) {
endpoint = _endpoint;
trustedOApp = _trustedOApp;
}
function lzCompose(
address _oApp,
bytes32 /*_guid*/,
bytes calldata _message,
address /*_executor*/,
bytes calldata /*_extraData*/
) external payable override {
// Security checks
require(msg.sender == endpoint, "!endpoint");
require(_oApp == trustedOApp, "!oApp");
// Decode the message payload
(string memory _string, ) = abi.decode(_message, (string, address));
// Execute custom business logic
performCustomAction(_string);
}
function performCustomAction(string memory message) internal {
// Your custom logic here (swap, stake, mint, etc.)
}
}
Execution Options for Composed Messages: You must provide gas for both the main lzReceive
call and the lzCompose
call:
bytes memory options = OptionsBuilder.newOptions()
.addExecutorLzReceiveOption(baseGas, 0) // Main message processing
.addExecutorLzComposeOption(0, composeGas, value); // Composed call (index 0)
The _index
parameter allows multiple composed calls with different gas allocations.
Message Ordering
LayerZero supports both unordered (default) and ordered delivery patterns.
Ordered Delivery Implementation
contract OrderedOApp is OApp {
mapping(uint32 eid => mapping(bytes32 sender => uint64 nonce)) private receivedNonce;
function nextNonce(uint32 _srcEid, bytes32 _sender) public view override returns (uint64) {
return receivedNonce[_srcEid][_sender] + 1;
}
function _acceptNonce(uint32 _srcEid, bytes32 _sender, uint64 _nonce) internal override {
receivedNonce[_srcEid][_sender] += 1;
require(_nonce == receivedNonce[_srcEid][_sender], "Invalid nonce");
}
// Must include ExecutorOrderedExecutionOption in your send options
function sendOrdered(uint32 _dstEid, string memory _message) external payable {
bytes memory options = OptionsBuilder.newOptions()
.addExecutorLzReceiveOption(200000, 0)
.addExecutorOrderedExecutionOption(); // Required for ordered execution
_lzSend(_dstEid, abi.encode(_message), options, MessagingFee(msg.value, 0), payable(msg.sender));
}
}
Rate Limiting
Control message frequency to prevent spam and ensure controlled cross-chain interactions:
contract RateLimitedOApp is OApp, RateLimiter {
constructor(
address _endpoint,
address _owner,
RateLimitConfig[] memory _rateLimitConfigs
) OApp(_endpoint, _owner) {
_setRateLimits(_rateLimitConfigs);
}
function sendWithRateLimit(
uint32 _dstEid,
string memory _message,
bytes calldata _options
) external payable {
// Check rate limit before sending
_outflow(_dstEid, 1); // 1 message
_lzSend(
_dstEid,
abi.encode(_message),
_options,
MessagingFee(msg.value, 0),
payable(msg.sender)
);
}
}
Further Reading
For detailed implementations and advanced patterns, see:
- Message Execution Options - Options configuration
- OApp Technical Reference - Deep dive into OApp mechanics
- Integration Checklist - Security considerations and best practices
Tracing and Troubleshooting
You can follow your testnet and mainnet transaction statuses using LayerZero Scan.
Refer to Debugging Messages for any unexpected complications when sending a message.
You can also ask for help or follow development in the Discord.