Skip to main content

​
General

LayerZero is an omnichain messaging protocol — a permissionless, open framework designed to securely move information between blockchains. It empowers any application to bring its own security, execution, and crosschain interaction, providing a predictable and adaptable foundation for decentralized applications living on multiple networks.For details on how it works, see the Protocol Overview.
The devtools repository contains contract examples across all supported VMs. It acts as the central hub for the LayerZero developer experience, including application contract standards, CLI examples, packages, scripting tools, and more.
The delivery time of a LayerZero message can be broken down into a series of processing stages. Every message goes through the following high-level steps:
  • Source Block Confirmations: The message waits for the source chain to finalize a specified number of block confirmations. To view the default configuration for a given pathway, refer to the default configs checker.
  • DVN/Verification: Each Decentralized Verifier Network (DVN) submits one transaction to verify the message.
  • Committer/Commit Verification: One additional transaction is required to commit the verified message.
  • Executor/Message Execution: A final transaction is submitted to execute the message on the destination chain.
Estimated Total Delivery Time You can estimate the total message delivery time with the following formula:Total Time ≈ (sourceBlockTime × number of block confirmations) + (destinationBlockTime × (2 blocks + number of DVNs))Note: This formula offers a rough estimate for a message that does not implement lzCompose. It assumes that each transaction is included in the next block without delay and does not factor in network latency, or other real-world conditions that may affect transaction processing time.
Chain ID is an EVM-specific concept for the native identifier assigned by a blockchain network itself (for example, 1 for Ethereum Mainnet, 42161 for Arbitrum Mainnet). It’s used by node clients, wallets, and RPCs to identify the network.Endpoint ID (EID) is LayerZero’s internal identifier used by the protocol to route messages between chains. Every LayerZero Endpoint contract has a unique EID. EIDs are VM-agnostic and do not map 1:1 to chain IDs.Key points:
  • EIDs are what you use in LayerZero configs, CLI commands, and contract calls
  • Chain IDs are for EVM chains and used for RPCs/wallets; EIDs are for LayerZero messaging
  • For EIDs, Mainnets typically use the 30xxx range; testnets use the 40xxx range
Where to find EIDs: see the list of deployed contracts and Endpoint IDs in Deployed Contracts
Delegate manages LayerZero protocol configurations via the LayerZero Endpoint contract.Owner manages an OApp’s peers, ownership(transfer & revoke) and who the delegate is. Owner is defined on the OApp contract itself using OpenZeppelin’s Ownable.⚠️ Important Configuration Note for Using DevtoolsThe owner and delegate addresses should typically be the same. Assigning different accounts to these roles may result in an LZ_Unauthorized() error.This is because the delegate can call most wire functions (like setPeer()), but only the owner can call setEnforcedOptions(). If the accounts differ and you attempt to call setEnforcedOptions() through the delegate, the call will fail.Unless there’s a specific need to separate permissions, it’s recommended to use the same address for both owner and delegate to avoid unintended access issues.
While it is possible to integrate existing tokens deployed across multiple chains with the OFT standard, this requires additional setup.Specifically, MintBurnOFTAdapter — a variant of OFTAdapter.sol enables OFT functionality by calling the mint and burn methods of the innerToken on each chain.However, for this integration to work:
  • Each innerToken contract must expose externally callable mint and burn functions.
  • The innerToken must grant the MintBurnOFTAdapter the necessary permissions (MINTER_ROLE and BURNER_ROLE) to invoke these functions.
The sharedDecimals is the “lowest common denominator” of decimal precision across all chains in the OFT system. It limits how many decimal places can be reliably represented when moving tokens cross‑chain.By default, sharedDecimals is set to 6, which is sufficient for most use cases across different VMs. However, OApps can override this default if the OApp’s total token supply exceeds (2⁶⁴–1) / 10⁶.⚠️ CAUTION:If you override the vanilla sharedDecimals amount or have an existing token supply exceeding 18,446,744,073,709.551615 tokens, extra caution should be applied to ensure amountSD and amountLD do not overflow.See more explanations here.
msgType 1 and msgType 2 are used to distinguish between two types of messages when setting enforcedOptions. Use the OptionsBuilder to add the message execution options for each msgType.msgType 1 = SENDThis msgType is a basic token transfer or message send. It does not include a composed message.Options you can use:
  • lzReceive Option to specify the gas values the Executor uses when calling lzReceive on the destination chain.
  • lzNativeDrop Option to specify how much native gas to drop to any address on the destination chain.
msgType 2 = SEND_AND_CALLThis msgType includes additional composed message(s), allowing for one or more extra calls to be sent along with the message.Options you can use:
  • lzReceive Option to specify the gas values the Executor uses when calling lzReceive on the destination chain.
  • lzCompose Option to allocate gas and value for Composed Messages on the destination chain.
See more information for composed message options.Please follow the best practice to determine the gas cost for lzRecieve and lzCompose option. Overestimating wastes funds; underestimating may cause message execution to fail.
If you are using Sepolia as the destination chain, transaction costs can spike due to high and volatile gas prices on Sepolia. To avoid high fees during testing, it is recommended to use alternative testnets as the destination chain.LayerZero’s transaction pricing model is designed to fairly distribute costs across the various components that enable secure, reliable crosschain messaging. Understanding this model helps developers and users make informed decisions about gas allocation and fee optimization.Learn more: Transaction Pricing Model
Yes. An OApp’s delegate can call the skip() method on the endpoint to stop delivery. The skip function should be used only in instances where either message verification fails or must be stopped, not message execution. LayerZero provides separate handling for retrying or removing messages that have successfully been verified, but fail to execute.Learn more: Skip Message Guide
LZ Dead DVN Represents a Dead Decentralized Verifier Network (DVN). These contracts are placeholders used when the default LayerZero config is inactive and will require the OApp owner to manually configure the contract’s config to use the pathway.LayerZero allows anyone to permissionlessly run DVNs, but default providers (e.g. Google Cloud, Polyhedra) may not cover every chain immediately. If a pathway lacks default DVN support, OApps must explicitly configure supported DVNs on both the source and destination chains.
To add a new network to your existing OFT deployment, you’ll need to update your project configuration and deploy the OFT to the new chain:
  1. Add the new network to your hardhat.config.ts with the correct LayerZero Endpoint ID and RPC URL
  2. Deploy the OFT on the new network
  3. Update your layerzero.config.ts to include the new contract and connections
  4. Wire peers to apply configuration (If the current OFT deployment involves a non-EVM chain, follow the specific instructions for that VM)
For detailed step-by-step instructions, see Adding Networks.

​
Error & Troubleshooting

This error indicates that your OApp configuration is missing the required DVN and/or Executor settings.On Mainnet, default DVNs are not guaranteed to be available for every pathway. OApps must explicitly configure supported DVNs on both the source and destination chains.DVN Addresses can be found here.To simplify setup, use simple config generator , which provides CLI commands for setting DVNs. Be sure to also consult the VM-specific configuration sections to complete your configurations properly.
Failures in _quote() often stem from:
  • Incomplete Network Pathway: Not all pathways are fully wired, especially on testnets. Contact LayerZero if you require support for a specific pathway.
  • Missing enforcedOptions or extraOptions: At least one must be set for a successful quote.
  • LZ Dead DVN: If your configuration includes LZ Dead DVN for a particular pathway, the quote will fail. OApps must configure DVNs explicitly on Mainnet.
This status typically indicates that the destination OApp is either missing trusted peer settings or the pathway has not been properly initialized.Common causes:
  • Incorrect peer configuration: Ensure that setPeer() is correctly called on both the source and destination chains during deployment. Double-check that the address format and EID (endpoint ID) are accurate.
  • Pathway not initialized correctly: Confirm that allowInitializePath() is properly implemented in your OApp contract. Learn more: Integration Checklist
On Solana, if you have a custom writing implementation, ensure that endpoint.initOAppNonce was called with the correct parameters.
A “Blocked” message usually points to configuration issues:
  • NotInitializable: Ensure peers are set correctly on both ends or pathway is initialized correctly as explained above.
  • DVN mismatch: All DVN providers must be the same on source and destination.
  • Block confirmations mismatch: Outbound confirmations must be ≥ inbound confirmations.
Step 1: Identify which DVN contract is reverting and capture the exact error.Step 2: Verify that the correct DVN type is configured for your message workflow.
  • Read-compatible DVNs (lzRead) must only be used for lzRead (pull / request-response) workflows.
  • Using a Read-compatible DVN for push messaging will cause the error DVN_EidNotSupported.
If an incorrect DVN type is configured, update the DVN configuration to resolve the error.Step 3: If the configuration appears correct, contact the LayerZero support team to confirm that the DVN is properly configured for the affected pathway.
To avoid out-of-gas errors when executing lzReceive() on the destination:
  • Use enforcedOptions (set at the OApp/OFT contract level) to define a default gas value for all sends.
  • Use extraOptions (specified in the send function call) for transaction-specific overrides.
Both values must sum to at least the gas required by lzReceive() on the destination. It is also common to simply use enforcedOptions and set extraOptions to 0x.If the destination message fails due to insufficient gas, you can retry it manually:

​
Ecosystem

You can explore the current list of projects on the Ecosystem page. This list is not exhaustive—projects can submit a request to be listed.
Submit your application via the Ecosystem Listing Form if your dApp uses LayerZero for omnichain messaging.
LayerZero does not have a traditional grant program. However, the LayerZero Foundation runs lzCatalyst, a program connecting top builders with leading VCs in the space.More info: lzCatalyst Program