No deployment found for {contractName} on {chainDisplayName}
}
}
;
};
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](../../../concepts/modular-security/security-stack-dvns) and the message nonce has been committed to the [Endpoint](../../../concepts/protocol/layerzero-endpoint)'s messaging channel.
**`Delivered`**: the message has been successfully executed by the [Executor](../../../concepts/permissionless-execution/executors).
Because verification and execution are separate, LayerZero can provide specific error handling for each message state.
General debugging steps can be found [here](../../../concepts/troubleshooting/debugging-messages).
## 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](../../../tools/sdks/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](../../../tools/sdks/options#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](https://docs.ethers.org/v5/), [viem](https://viem.sh/docs/getting-started.html), 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](../oapp/overview#setting-delegates) 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**
```js wrap theme={null}
// using ethers v5
const {ethers} = require('ethers');
const skipFunctionABI = [
'function skip(address _oapp,uint32 _srcEid, bytes32 _sender, uint64 _nonce)',
];
```
2. **Configure the Contract Instance**
```js wrap theme={null}
// 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);
```
3. **Prepare Function Parameters**
```js wrap theme={null}
// 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);
```
4. **Send the Transaction**
```js wrap theme={null}
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**
```js wrap theme={null}
// 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',
},
];
```
2. **Configure the Contract Instance**
```js wrap theme={null}
// 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);
```
3. **Prepare Function Parameters**
```js wrap theme={null}
// 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
```
4. **Send the Transaction**
```js wrap theme={null}
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.