Skip to main content
The V2 protocol now splits the verification and contract logic execution of messages into two separate, distinct phases: Verified: the destination chain has received verification from all configured DVNs and the message nonce has been committed to the Endpoint’s messaging channel. Delivered: the message has been successfully executed by the Executor. Because verification and execution are separate, LayerZero can provide specific error handling for each message state. General debugging steps can be found here.

​
Message Execution

When your message is successfully delivered to the destination chain, the protocol attempts to execute the message with the execution parameters defined by the sender. Message execution can result in two possible states:
  • Success: If the execution is successful, an event (PacketReceived) is emitted.
  • Failure: If the execution fails, the contract reverses the clearing of the payload (re-inserts the payload) and emits an event (LzReceiveAlert) to signal the failure.
    • Out of Gas: The message fails because the transaction that contains the message doesn’t provide enough gas for execution. The Message Execution Options applied to a message can be viewed on LayerZero Scan. There are several ways to determine the optimal gas values for these options. See Determining Gas Costs for more details.
    • Logic Error: There’s an error in either the contract code or the message parameters passed that prevents the message from being executed correctly.

​
Retry Message

Because LayerZero separates the verification of a message from its execution, if a message fails to execute due to either of the reasons above, the message can be retried without having to resend it from the origin chain. This is possible because the message has already been confirmed by the DVNs as a valid message packet, meaning execution can be retried at anytime, by anyone. Here’s how an OApp contract owner or user can retry a message:
  • Using LayerZero Scan: For users that want a simple frontend interface to interact with, LayerZero Scan provides both message failure detection and in-browser message retrying.
  • Calling lzReceive Directly: If message execution fails, any user can retry the call on the Endpoint’s lzReceive function via the block explorer or any popular library for interacting with the blockchain like ethers, viem, etc.

​
lzReceive() - Receive Messages

Note: In the event of an lzCompose failure, the resolution process is similar. Any user can simply retry the call by invoking the Endpoint’s lzCompose function.

​
lzCompose() - Execute Compose Messages

​
Skipping Nonce

Occasionally, an OApp delegate may want to cancel the verification of an in-flight message. This might be due to a variety of reasons, such as:
  • Race Conditions: conditions where multiple transactions are being processed in parallel, and some might become invalid or redundant before they are processed.
  • Error Handling: In scenarios where a message cannot be delivered (for example, due to being invalid or because prerequisites are not met), the skip function provides a way to bypass it and continue with subsequent messages.
By allowing the OApp to skip the problematic message, the OApp can maintain efficiency and avoid getting stuck by a single bottleneck.
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.
It is crucial to use this function with caution because once a payload is skipped, it cannot be recovered.

An OApp’s delegate can call the skip method via the Endpoint to stop message delivery:

​
skip()

Example for calling skip
  1. Set up Dependencies and Define the ABI
// using ethers v5
const {ethers} = require('ethers');
const skipFunctionABI = [
  'function skip(address _oapp,uint32 _srcEid, bytes32 _sender, uint64 _nonce)',
];
  1. Configure the Contract Instance
// Example Endpoint Address
const ENDPOINT_CONTRACT_ADDRESS = '0xb6319cC6c8c27A8F5dAF0dD3DF91EA35C4720dd7';

const provider = new ethers.providers.JsonRpcProvider(YOUR_RPC_URL);
const signer = new ethers.Wallet(YOUR_PRIVATE_KEY, provider);
const endpointContract = new ethers.Contract(ENDPOINT_CONTRACT_ADDRESS, skipFunctionABI, signer);
  1. Prepare Function Parameters
// Example Oapp Address
const oAppAddress = '0x123123123678afecb367f032d93F642f64180aa3';

// Parameters for the skip function
const srcEid = 50121; // srcEid example

// padding an example address to bytes32
const sender = ethers.zeroPadValue(`0x5FbDB2315678afecb367f032d93F642f64180aa3`, 32);
const nonce = 3; // uint64 nonce example

const tx = await endpointContract.skip(oAppAddress, srcEid, sender, nonce);
  1. Send the Transaction
const tx = await endpointContract.skip(oAppAddress, srcEid, sender, nonce);
await tx.wait();

​
Clearing Message

As a last resort, an OApp contract owner may want to force eject a message packet, either due to an unrecoverable error or to prevent a malicious packet from being executed:
  • When logic errors exist and the message can’t be retried successfully.
  • When a malicious message needs to be avoided.
Using the clear Function: This function exists on the Endpoint and allows an OApp contract delegate to burn the message payload so it can never be retried again.
It is crucial to use this function with caution because once a payload is cleared, it cannot be recovered.

​
clear() - Clear Stored Message

Example for calling clear
  1. Set up Dependencies and Define the ABI
// using ethers v5
const {ethers} = require('ethers');
const clearFunctionABI = [
  {
    inputs: [
      {
        components: [
          {internalType: 'uint32', name: 'srcEid', type: 'uint32'},
          {internalType: 'bytes32', name: 'sender', type: 'bytes32'},
          {internalType: 'uint64', name: 'nonce', type: 'uint64'},
        ],
        internalType: 'struct Origin',
        name: '_origin',
        type: 'tuple',
      },
      {internalType: 'bytes32', name: '_guid', type: 'bytes32'},
      {internalType: 'bytes', name: '_message', type: 'bytes'},
    ],
    name: 'clear',
    outputs: [],
    stateMutability: 'nonpayable',
    type: 'function',
  },
];
  1. Configure the Contract Instance
// Example Endpoint Address
const ENDPOINT_CONTRACT_ADDRESS = '0xb6319cC6c8c27A8F5dAF0dD3DF91EA35C4720dd7';

const provider = new ethers.providers.JsonRpcProvider(YOUR_RPC_URL);
const signer = new ethers.Wallet(YOUR_PRIVATE_KEY, provider);
const endpointContract = new ethers.Contract(ENDPOINT_CONTRACT_ADDRESS, clearFunctionABI, signer);
  1. Prepare Function Parameters
// Example Oapp Address
const oAppAddress = '0x123123123678afecb367f032d93F642f64180aa3';

// Parameters for the skip function
const origin = {
  srcEid: 10111, // example source chain endpoint Id
  sender: ethers.zeroPadValue(`0x5FbDB2315678afecb367f032d93F642f64180aa3`, 32), // bytes32 representation of an address
  nonce: 3, // example nonce
};

const _guid = '0x0af522cbed56c0e67988a3eab0e83fc576d501659ffe7743ffa4a0a76b40419d'; // example _guid
const _message =
  '0x0000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000064849484948490000000000000000000000000000000000000000000000000000'; //example _message
  1. Send the Transaction
const tx = await endpointContract.clear(oAppAddress, origin, _guid, _message);
await tx.wait();

​
Nilify and Burn

These two functions exist in the Endpoint contract and are used in very specific cases to avoid malicious acts by DVNs. These two functions are infrequently utilized and serve as precautionary design measures.
nilify and burn are called similarly to clear and skip, refer to those examples if needed.

​
nilify() - Mark Message as Nil

The nilify function is designed to transform a non-executed payload hash into NIL value (0xFFFFFF…). This transformation enables the resubmission of these NIL packets via the MessageLib back into the endpoint, providing a recovery mechanism from disruptions caused by malicious DVNs.

​
burn() - Permanently Block Message

The burn function operates similarly to the clear function with two key distinctions:
  1. The OApp is not required to be aware of the original payload
  2. The nonce designated for burning must be less than the lazyInboundNonce
This function exists to avoid malicious DVNs from hiding the original payload to avoid the message from being cleared.