LayerZero Protocol Architecture

LayerZero is an omnichain interoperability protocol that provides a stable, immutable interface for crosschain messaging. By separating interface, verification, and execution into independent layers, LayerZero enables composable crosschain architectures without compromising security.

Architecture: Five Independent Layers

Each layer has one job. They work together but remain independent.

1. Business Logic Interface (OApp)

Omnichain Applications (OApps) are LayerZero’s definition for smart contracts that use LayerZero to send and receive crosschain messages. Building on Module 1’s data messaging concepts, the LayerZero protocol allows applications to define any custom data as bytes and send them as crosschain messages. The OApp standard provides a consistent application interface for invoking the LayerZero protocol with this custom business logic:

// SPDX-License-Identifier: MIT
import {OApp, MessagingFee, Origin} from "@layerzerolabs/oapp-evm/contracts/oapp/OApp.sol";
import {OptionsBuilder} from "@layerzerolabs/oapp-evm/contracts/oapp/libs/OptionsBuilder.sol";

contract MyOmnichainApp is OApp {
    using OptionsBuilder for bytes;

    constructor(address endpoint) OApp(endpoint, msg.sender) {}

    function quoteMessage(uint32 dstEid, bytes memory message, bool payInLzToken)
        external view returns (MessagingFee memory fee) {
        bytes memory options = OptionsBuilder.newOptions()
            .addExecutorLzReceiveOption(200_000, 0);

        // Returns the cost of sending a message in either native gas token or ZRO
        return _quote(dstEid, message, options, payInLzToken);
    }

    function sendMessage(uint32 dstEid, bytes memory message) external payable {
        // Unordered by default; requests destination chain gas units for message delivery
        bytes memory options = OptionsBuilder.newOptions()
            .addExecutorLzReceiveOption(200_000, 0);

        // If you need ordering:
        // options = options.addExecutorOrderedExecutionOption();
        _lzSend(
            dstEid,
            // highlight-next-line
            message,
            combineOptions(dstEid, SEND, options),
            MessagingFee(msg.value, 0),
            payable(msg.sender)
        );
    }

    function _lzReceive(
        Origin calldata origin,
        bytes32 guid,
        // highlight-next-line
        bytes calldata message,
        address /*executor*/,
        bytes calldata /*extraData*/
    ) internal override {
        // your logic
    }
}

The OApp standard acts as a facade that wraps the raw LayerZero protocol interface with developer-friendly methods. Instead of calling endpoint.send() and endpoint.lzReceive() directly, OApps use _lzSend() and _lzReceive() which handle common patterns like fee quoting, message validation, and error handling. Your application code focuses on business logic (encoding/decoding custom data, state transitions, etc.) while the OApp facade manages protocol interaction.

2. Protocol Interface (Endpoint)

The LayerZero Endpoint serves as the single entrypoint and exitpoint for all crosschain messaging on a blockchain. Each chain has one LayerZero Endpoint contract that can send and receive messages between any other LayerZero Endpoint contract on any supported chain. The Endpoint provides the universal, immutable protocol interface:

// Excerpt of ILayerZeroEndpointV2 - core messaging functions

// Core data structures
struct MessagingParams {
    uint32 dstEid;           // Destination endpoint ID
    bytes32 receiver;        // Receiver address (bytes32 for crosschain compatibility)
    bytes message;           // Message containing application-specific business logic
    bytes options;           // Execution options (gas, native drops, etc.)
    bool payInLzToken;       // Payment method (native chain token vs LZ token)
}

struct MessagingReceipt {
    bytes32 guid;            // Globally unique identifier for tracking
    uint64 nonce;            // Message sequence number for ordering
    MessagingFee fee;        // Actual fee charged
}

struct MessagingFee {
    uint256 nativeFee;       // Fee in native gas token
    uint256 lzTokenFee;      // Fee in LZ token (alternative payment)
}

struct Origin {
    uint32 srcEid;           // Source endpoint ID
    bytes32 sender;          // Sender address (bytes32 for crosschain)
    uint64 nonce;            // Message nonce for ordering
}

interface ILayerZeroEndpointV2 {
    // Events for tracking message lifecycle
    event PacketSent(bytes encodedPayload, bytes options, address sendLibrary);
    event PacketVerified(Origin origin, address receiver, bytes32 payloadHash);
    event PacketDelivered(Origin origin, address receiver);

    // Quote fees before sending
    function quote(MessagingParams calldata _params, address _sender) external view returns (MessagingFee memory);

    // Core send primitive - emits message and returns receipt
    function send(
        MessagingParams calldata _params,
        address _refundAddress
    ) external payable returns (MessagingReceipt memory);

    // Mark message as verified
    function verify(Origin calldata _origin, address _receiver, bytes32 _payloadHash) external;

    // Check if message can be verified
    function verifiable(Origin calldata _origin, address _receiver) external view returns (bool);

    // Check if message passes the target receiver's checks
    function initializable(Origin calldata _origin, address _receiver) external view returns (bool);

    // Core receive primitive - delivers message to destination contract
    function lzReceive(
        Origin calldata _origin,
        address _receiver,
        bytes32 _guid,
        bytes calldata _message,
        bytes calldata _extraData
    ) external payable;

    // ... additional configuration and management functions
}

Because every LayerZero Endpoint is immutable and permissionless to interact with, anyone can use a LayerZero Endpoint for crosschain messaging without requiring authorization, integration approval, or dependency on external bridge operators. This creates a fully independent transport layer that, as we’ll expand on in later sections, serves as the ideal crosschain messaging interface for nearly all crosschain applications. The immutable nature ensures that the interface will never change, providing permanent compatibility for applications built on LayerZero. The permissionless design means no gatekeepers can restrict access or censor transactions, creating a truly open crosschain infrastructure. Key Properties:

Universal: Same interface on every supported chain
Immutable: Cannot be upgraded or changed
Permissionless: Anyone can call (with proper fees)
Chain-agnostic: Works across EVM, Solana, Aptos, etc. (see non-EVM sections for specific sister implementations)

Channels: OApp-to-OApp Communication

A channel in LayerZero is uniquely defined by four components:

Sender OApp: The contract initiating the message
Source Endpoint: The LayerZero endpoint on the source chain
Destination Endpoint: The LayerZero endpoint on the destination chain
Receiver OApp: The contract receiving the message

Each unique combination creates an independent channel with its own configuration:

Note: Channel 3 shows the pull messaging pattern where data is queried directly from target contracts without involving the destination chain’s LayerZero endpoint. We’ll expand on this lzRead functionality in future modules.

Channel Identification

In practice, each channel can be identified from a source chain using only the destination Endpoint ID (EID) and receiver contract address. The source EID is already known (stored in the local Endpoint) and the caller is the OApp making the request, simplifying pathway management:

// Standard EIDs for endpoint-to-endpoint channels
uint32 constant ETHEREUM_EID = 30101;    // Ethereum mainnet endpoint
uint32 constant ARBITRUM_EID = 30110;    // Arbitrum mainnet endpoint
uint32 constant POLYGON_EID = 30109;     // Polygon mainnet endpoint

// Channel identification from source chain:
// - Source EID: Known (local endpoint)
// - Sender OApp: Known (msg.sender)
// - Destination EID: Provided as argument
// - Receiver OApp: Provided as argument

// Example: From Ethereum, only need (30110, PeerOApp) to identify Ethereum → Arbitrum channel

Custom Channel IDs: For lzRead pull-messaging, the sender and receiver are the same OApp (request/response pattern). Since we need to distinguish read requests from standard push messages to the same contract, we use arbitrary channel IDs:

// Custom channel ID for lzRead workflows
uint32 constant CUSTOM_READ_CHANNEL = 4294967295;  // Arbitrary identifier

// lzRead pattern:
// - Sender OApp: The contract requesting data (e.g., on Ethereum)
// - Receiver OApp: Same contract receiving the response (same Ethereum contract)
// - Custom EID: Distinguishes this as a read request, not a push message
// - Target: The contract being queried (e.g., on Arbitrum)

Channel-Specific Nonce Tracking

Each channel maintains its own independent nonce sequence, enabling parallel messaging without ordering conflicts: Benefits of Per-Channel Nonces:

Parallel messaging: No ordering dependencies between different channels
Independent scaling: High-traffic channels don’t block low-traffic channels
Replay protection: Each channel has its own sequence for security
Channel isolation: Message ordering only matters within the same communication pathway

Message Packet Generation Per Channel

When applications send messages, the Endpoint wraps the raw message data in a standardized packet container with channel-specific metadata. Based on the EndpointV2 implementation:

// Endpoint constructs packet with unique identifiers per channel
Packet memory packet = Packet({
    nonce: latestNonce,                    // Sequential message number per channel
    srcEid: eid,                          // Source endpoint ID (this chain)
    sender: _sender,                      // Sender contract address (the OApp)
    dstEid: _params.dstEid,              // Destination endpoint ID
    receiver: _params.receiver,           // Receiver contract address
    guid: GUID.generate(latestNonce, eid, _sender, _params.dstEid, _params.receiver), // Globally unique ID
    message: _params.message              // Raw application data (bytes)
});

Key Properties:

Nonce: Sequential per channel for ordering and replay protection - each channel maintains its own nonce sequence
GUID: Globally unique identifier generated from channel components + nonce
Channel identification: (sender, srcEid, dstEid, receiver) uniquely identifies the communication pathway
Message isolation: Raw application data separated from protocol metadata

Managing Channel Configuration

The Endpoint provides the interface for managing channel configurations via modular Message Libraries:

struct SetConfigParam {
    uint32 eid;          // Target endpoint ID
    uint32 configType;   // Configuration type identifier
    bytes config;        // Encoded configuration data
}

interface IMessageLibManager {
    // Library selection per pathway
    function setSendLibrary(address _oapp, uint32 _eid, address _newLib) external;
    function setReceiveLibrary(address _oapp, uint32 _eid, address _newLib, uint256 _gracePeriod) external;

    // Library configuration per pathway
    function setConfig(address _oapp, address _lib, SetConfigParam[] calldata _params) external;
    function getConfig(address _oapp, address _lib, uint32 _eid, uint32 _configType)
        external view returns (bytes memory config);
}

Each OApp can configure libraries to define the messaging behavior for its specific channels. These libraries determine how messages are verified, executed, and delivered for that OApp’s communication needs.

3. Configurable Protocol Libraries (Message Libraries)

Message Libraries are onchain rulesets that handle how messages are sent off-chain and arrive onchain between Endpoints. They define the complete workflow: message processing, verification requirements, and delivery coordination while maintaining the universal Endpoint interface.

// Excerpt of IMessageLib, ISendLib - core library functions
interface IMessageLib {
    // Configure verification and execution rules per pathway
    function setConfig(address _oapp, SetConfigParam[] calldata _config) external;

    // Send path: Transform endpoint calls into off-chain instructions
    function send(
        Packet calldata _packet,
        bytes calldata _options
    ) external returns (MessagingFee memory, bytes memory);

    // Receive path: Verifier networks call this to mark messages verified
    function verify(
        Origin calldata _origin,
        address _receiver,
        bytes32 _payloadHash
    ) external;

    // Check compatibility and versioning
    function version() external view returns (uint64 major, uint8 minor, uint8 endpointVersion);
}

struct Packet {
    uint64 nonce;            // Message sequence number
    uint32 srcEid;           // Source endpoint ID
    address sender;          // Sender contract address
    uint32 dstEid;           // Destination endpoint ID
    bytes32 receiver;        // Receiver address (bytes32 for crosschain)
    bytes32 guid;            // Globally unique identifier
    bytes message;           // Message business logic
}

Message Library Types & Workflows

Message Libraries can define different workflows and have specialized roles, such as Sending, Receiving, or Reading crosschain state:

Push Messaging Workflow (Send/Receive ULN)

Pull Messaging Workflow (Request/Response lzRead)

Different libraries enable OApps to handle different channel types with distinct behaviour, security, and delivery characteristics. Each channel represents a unique communication pathway between specific OApps with configurable message processing rules. LayerZero Labs may deploy new libraries with different workflows, features, or versions to enable developers to opt into new changes per channel.

Channel-Specific Library Configuration

Each channel gets unique settings through a two-step process from the Endpoint:

Library Selection: Use setSendLibrary/setReceiveLibrary to assign specific libraries per channel
Library Configuration: Use setConfig to customize each library’s settings per channel

This creates truly independent channel configurations - the same library type (e.g., SendUln302) can have completely different verification, finality, and execution settings for different channels. Each unique combination creates an independent channel setting with its own library configuration:

What Can Be Configured Per Channel

Message Libraries enable three main types of configuration for each channel:

Finality: How many block confirmations are required before verification begins
Verification: Which verifier networks must verify messages and in what combinations
Execution: Which execution services deliver messages and with what parameters

X-of-Y-of-N Verification Coordination

LayerZero libraries today use an X-of-Y-of-N configuration pattern for verification, where:

X: Required verifier networks that MUST always verify (non-fungible)
Y: Total verifications needed (required + threshold of optional)
N: Total pool of available verifier networks

Example: 2-of-4-of-6 configuration

2 specific networks must always verify (X = required)
4 total verifications needed (Y = required + optional threshold)
6 networks available in the pool (N = total options)
Any 2 of the remaining 4 optional networks can provide the additional verifications

Each “verifier network” is an independent verification system that implements one of the verification approaches from Module 1 (ZK proofs, committee consensus, light clients, etc.). This creates a quorum of quorums - each network must reach its own internal verification criteria before contributing to the overall X-of-Y-of-N requirement.

Example: 2-of-2-of-2 Verifier Networks

This simple 2-of-2-of-2 configuration shows two required verifier networks with no optional networks.

1-of-2-of-3 Verifier Networks

This 1-of-2-of-3 configuration shows 1 required verifier network (solid border) and 2 optional verifier networks (dashed borders). Only 1 of the 2 optional networks needs to verify, providing flexibility while maintaining the required verification.

Configuration Per Channel

Message Libraries enable each channel to specify different X-of-Y-of-N configurations based on security requirements:
Each channel’s Message Library enforces these X-of-Y-of-N requirements onchain, ensuring that the specified verification pattern is met before message execution.

Configuration Structures

Message Libraries define specific configuration structures for the three configurable aspects:

Note: The configuration structures reference “DVNs” (Decentralized Verifier Networks) and “Executors”. You don’t need to understand their implementation details yet - just know that DVNs help determine which verifier networks to select, and Executors handle message delivery. Both will be explained in detail in Module 4: Verification & Execution Services.

Push Messaging Configuration (ULN)

struct UlnConfig {
    uint64 confirmations;        // Block confirmations required for finality
    uint8 requiredDVNCount;      // Number of required DVNs (0 = DEFAULT, NIL_DVN_COUNT = NONE)
    uint8 optionalDVNCount;      // Number of optional DVNs available
    uint8 optionalDVNThreshold;  // How many optional DVNs needed: (0, optionalDVNCount]
    address[] requiredDVNs;      // Required DVN addresses (sorted, no duplicates)
    address[] optionalDVNs;      // Optional DVN addresses (sorted, no duplicates)
}

struct ExecutorConfig {
    uint32 maxMessageSize;       // Maximum message size in bytes
    address executor;            // Executor contract address
}

Pull Messaging Configuration (lzRead)

struct ReadLibConfig {
    address executor;            // Executor for read operations
    uint8 requiredDVNCount;      // Number of required DVNs
    uint8 optionalDVNCount;      // Number of optional DVNs available
    uint8 optionalDVNThreshold;  // How many optional DVNs needed
    address[] requiredDVNs;      // Required DVN addresses (sorted, no duplicates)
    address[] optionalDVNs;      // Optional DVN addresses (sorted, no duplicates)
}

Key Insight: Message Libraries are the onchain glue that makes verifier networks and delivery services pluggable while maintaining security guarantees. Different libraries can implement completely different messaging paradigms and verification requirements.

Crosschain Services (Workers)

Message Libraries coordinate two types of off-chain worker services that handle verification and execution:

4. DVNs (Decentralized Verifier Networks)

DVNs are LayerZero’s official term for the “verifier networks” discussed in previous sections. Each DVN is an independent verification service that implements one of the verification approaches from Module 1 (ZK proofs, committee consensus, light clients, middlechains, etc.). Key Properties:

Independent operation: Each DVN runs its own verification logic
Configurable per pathway: Different DVN sets per channel
X-of-Y-of-N coordination: Multiple DVNs work together via Message Library rules
Verification diversity: Different DVNs use different trust models and verification methods

5. Executors

Executors are permissionless services that deliver verified messages to destination chains. Anyone can run an executor, making message delivery competitive and censorship-resistant. Key Properties:

Permissionless: Anyone can operate an executor
Competitive: Multiple executors compete on speed and cost
Optional: Applications can opt out and execute manually
Separation from verification: Executors deliver, DVNs verify

Worker Service Architecture

// Message Libraries coordinate both worker types:
// 1. DVNs verify messages according to X-of-Y-of-N rules
// 2. Executors deliver verified messages to destination contracts

// SPDX-License-Identifier: MIT

pragma solidity >=0.8.0;

/// @dev should be implemented by the ReceiveUln302 contract and future ReceiveUln contracts on EndpointV2
interface IReceiveUlnE2 {
    /// @notice for each dvn to verify the payload
    /// @dev this function signature 0x0223536e
    function verify(bytes calldata _packetHeader, bytes32 _payloadHash, uint64 _confirmations) external;

    /// @notice verify the payload at endpoint, will check if all DVNs verified
    function commitVerification(bytes calldata _packetHeader, bytes32 _payloadHash) external;
}

interface ILayerZeroEndpointV2 {
    function lzReceive(
        Origin calldata _origin,
        address _receiver,
        bytes32 _guid,
        bytes calldata _message,
        bytes calldata _extraData
    ) external payable;
}

Coordination: Message Libraries define the rules, DVNs verify according to X-of-Y-of-N configurations, and Executors deliver once verification requirements are met. This separation enables independent scaling and competitive markets for both verification and execution services. For detailed implementation, configuration examples, and provider information, see Module 4: Verification & Execution Services.

Exit Criteria

Before proceeding to Module 4, you should be able to:

Describe the four layers (application, endpoint, libraries, workers)
Explain what DVNs do and how to configure them
Show how to set different verification per route

Concepts

Crosschain Development

Applications

Protocol

Message Libraries

Workers

Technical Reference

Troubleshooting

LayerZero Protocol Architecture

Architecture: Five Independent Layers

1. Business Logic Interface (OApp)

2. Protocol Interface (Endpoint)

Channels: OApp-to-OApp Communication

Channel Identification

Channel-Specific Nonce Tracking

Message Packet Generation Per Channel

Managing Channel Configuration

3. Configurable Protocol Libraries (Message Libraries)

Message Library Types & Workflows

Push Messaging Workflow (Send/Receive ULN)

Pull Messaging Workflow (Request/Response lzRead)

Channel-Specific Library Configuration

What Can Be Configured Per Channel

X-of-Y-of-N Verification Coordination

Example: 2-of-2-of-2 Verifier Networks

1-of-2-of-3 Verifier Networks

Configuration Per Channel

Configuration Structures

Push Messaging Configuration (ULN)

Pull Messaging Configuration (lzRead)

Crosschain Services (Workers)

4. DVNs (Decentralized Verifier Networks)

5. Executors

Worker Service Architecture

Exit Criteria

See Also

​Architecture: Five Independent Layers

​1. Business Logic Interface (OApp)

​2. Protocol Interface (Endpoint)

​Channels: OApp-to-OApp Communication

​Channel Identification

​Channel-Specific Nonce Tracking

​Message Packet Generation Per Channel

​Managing Channel Configuration

​3. Configurable Protocol Libraries (Message Libraries)

​Message Library Types & Workflows

​Push Messaging Workflow (Send/Receive ULN)

​Pull Messaging Workflow (Request/Response lzRead)

​Channel-Specific Library Configuration

​What Can Be Configured Per Channel

​X-of-Y-of-N Verification Coordination

​Example: 2-of-2-of-2 Verifier Networks

​1-of-2-of-3 Verifier Networks

​Configuration Per Channel

​Configuration Structures

​Push Messaging Configuration (ULN)

​Pull Messaging Configuration (lzRead)

​Crosschain Services (Workers)

​4. DVNs (Decentralized Verifier Networks)

​5. Executors

​Worker Service Architecture

​Exit Criteria

​See Also

Architecture: Five Independent Layers

1. Business Logic Interface (OApp)

2. Protocol Interface (Endpoint)

Channels: OApp-to-OApp Communication

Channel Identification

Channel-Specific Nonce Tracking

Message Packet Generation Per Channel

Managing Channel Configuration

3. Configurable Protocol Libraries (Message Libraries)

Message Library Types & Workflows

Push Messaging Workflow (Send/Receive ULN)

Pull Messaging Workflow (Request/Response lzRead)

Channel-Specific Library Configuration

What Can Be Configured Per Channel

X-of-Y-of-N Verification Coordination

Example: 2-of-2-of-2 Verifier Networks

1-of-2-of-3 Verifier Networks

Configuration Per Channel

Configuration Structures

Push Messaging Configuration (ULN)

Pull Messaging Configuration (lzRead)

Crosschain Services (Workers)

4. DVNs (Decentralized Verifier Networks)

5. Executors

Worker Service Architecture

Exit Criteria

See Also