Message Options

In the LayerZero protocol, message options are a way for applications to describe how they want their messages to be handled by off-chain infrastructure. These options are passed along with every message sent through LayerZero and are formatted as serialized bytes; a universal language that both the protocol and workers (like DVNs and Executors) can understand.

Each option acts like an instruction or a setting for a specific worker. For example, you might request that a certain amount of gas / compute units are allocated to execute your message on the destination chain, or that some native tokens be delivered along with the message.

Options are how applications communicate verification and execution preferences to the off-chain workers that carry out cross-chain messages.

How Does LayerZero Route Options?

When an application sends a message through LayerZero, it includes a field called options. This field is a compact, structured byte array that can contain multiple worker-specific instructions. LayerZero doesn’t interpret these options directly; instead, it forwards them to the appropriate service providers (called workers) that know how to read and act on the instructions.

The workers typically fall into two categories:

• Decentralized Verifier Networks (DVNs): These provide verification to ensure the message is valid and has not been tampered with.

• Executors: These are responsible for delivering and executing the message on the destination chain.

The LayerZero messaging library understands how to break apart the options and route them to the correct workers. Since applications can configure message libraries, this design is modular, as new types of workers and options can be added over time without changing the core protocol.

Enforcing Options

Some applications may require strict guarantees on how their messages are handled. Without this enforcement, users could accidentally (or maliciously) send messages that fail to execute, leading to a poor user experience or even stuck tokens.

To prevent this, applications can enforce options. Enforcement means the application itself verifies and guarantees that a specific set of options is always present and correctly formatted before the message is allowed to be sent.

Enforced options helps by:

• Preventing underfunded executions that would otherwise fail on the destination chain.

• Protecting users who omit critical options for a specific application use case.

• Providing a consistent baseline experience regardless of the sender’s intent.

This concept is especially important in applications like token bridges, composable smart contracts, or stateful protocols where execution must be predictable and reliable.

info

Enforcing options means your application checks that users provide the correct options when calling the Endpoint's send() method. However, this does NOT guarantee that the specified instructions (e.g., gas limits or native drops) will be executed as intended by the worker or respected by permissionless callers on the destination chain.

If your application requires strict guarantees, such as an exact gas amount or mandatory native gas drops, you must also validate those conditions on-chain at the destination, or use a worker you trust. See the Integration Checklist for guidance on how to enforce execution requirements inside your _lzReceive() or lzCompose() logic.

Extra Options

While enforced options protect the base behavior of an application, users often have additional use cases that require more flexibility.

To support this, LayerZero applications can also allow users to supply extra options. These are user-defined additions to the enforced baseline, offering more granular control over the message’s behavior on the destination chain.

Why would a user want to add extra options?

Take the example of an Omnichain Token (OFT) that supports Omnichain Composability; allowing the token to trigger additional logic after being received. This logic might involve calling another contract, performing swaps, or interacting with a dApp on the destination chain.

In this case, the user might want to pay for:

• A required amount of gas to ensure lzReceive() succeeds (enforced by the app).

• Extra gas to support additional post-processing via lzCompose() (added by the user).

By adding these extra options, users pay to extend the functionality without modifying the underlying application logic.

Another example: Token + Native Gas Drop

Suppose a user is bridging USDT0 (an OFT) to a new chain and wants to start interacting with dApps right away. Normally, they'd receive the token, but they wouldn’t have any native gas on the destination chain to pay for further transactions.

With extra options, the user can:

• Ensure lzReceive() executes successfully to receive the USDT0.

• Add a native token drop option, funding their wallet with native gas on arrival.

From the user's perspective, they complete a single cross-chain action and arrive on the new chain with both:

• The token they sent (USDT0)

• Enough native gas to immediately start interacting

This separation of concerns makes the system both secure by default and flexible by design; a core benefit of LayerZero's modular architecture.

Why Do Options Matter?

When sending a cross-chain message, the source chain has no direct knowledge of the destination chain’s state: things like how much gas is needed, what the native currency is, or how the contract should be called.

Options solve this by letting the sender provide detailed instructions about how the message should be processed once it arrives.

Some common examples include:

• Execution Gas: Telling the Executor how much gas or native token the destination contract will need during lzReceive().

• Composer Gas: Adding gas or native tokens for the composer contract when calling calling lzCompose().

• Native Token Drops: Sending native tokens (like ETH or APT) separately from the message.

These instructions are interpreted by the off-chain workers, so that the message is handled as expected.

Key Takeaways

• options are serialized instructions that help off-chain workers understand how to process a message.

• Each type of worker (DVN, Executor, etc.) looks for specific options relevant to their task.

• Applications can enforce options to require correct behavior on source.

• Users can extend options for extra functionality on destination.

• The LayerZero protocol’s modular design means it can support new worker types without breaking existing behavior.