Layerzero
Layerzero Messaging inputs, state changes and observable outputs
Layerzero Messaging converts an OApp's destination endpoint ID, receiver, application payload and execution options into a trackable packet and, after configured verification, a destination call. The protocol assigns a GUID and pathway nonce at send time. Destination verification records the payload hash, while successful execution invokes the receiving OApp. The receiving OApp's intended effect is the final output that confirms completion.
Those outputs belong to different stages, so one transaction hash can't prove the whole journey. Read the route configuration, packet identity, verification record, execution receipt and receiving contract state as connected evidence.
Pathway configuration sets the valid route
A directional pathway connects a sending OApp to a receiving OApp. Its configuration identifies the remote peer, send and receive libraries, Decentralized Verifier Networks (DVNs), confirmation requirement and Executor. The reverse direction is a separate pathway and may use different settings. A working route in one direction therefore doesn't prove that replies can travel back.
The source can form a packet only after the application supplies a destination endpoint ID, receiver, payload and options. On the destination, the receive library must accept the packet's origin and verification evidence. The receiving OApp must also recognize the source sender as its configured peer. Missing peer wiring or incompatible library settings are configuration faults; adding more execution gas won't make that pathway valid.
Five stages connect message inputs to destination state
The normal path has five stages. Match each observed output to its stage before choosing another action. This keeps a delayed verification distinct from an execution failure and prevents a second send from creating a separate packet while the first remains active.
| Stage | Input or state change | Observable result, count or timing |
|---|---|---|
| Form and quote | The OApp supplies the destination EID, receiver, payload, options and fee-payment choice. | The quote reflects those inputs but doesn't promise a delivery time. |
| Send and packetize |
The Endpoint increments the pathway nonce, creates the GUID and emits
PacketSent.
|
Each accepted send returns one GUID and one nonce. |
| Verify | Configured DVNs submit evidence for the packet header and payload hash. | The required count comes from the required DVN list and optional threshold; timing follows the confirmation setting. |
| Commit | The receive library checks the collected evidence and records the payload hash in the destination Endpoint. | Commit can proceed after the configured confirmations and DVN requirements are satisfied. |
| Execute |
An Executor or another caller invokes
lzReceive, which clears the matching payload and calls the receiving OApp.
|
One successful delivery clears that stored payload hash; no universal duration applies. |
Begin with the earliest missing output. If no
PacketSent
evidence exists, the message didn't enter this lifecycle. If the packet was sent but hasn't been committed, execution retries are premature. Once the payload hash is committed, a destination attempt can be judged independently of the source transaction. Acceptance requires the destination call to succeed and the expected application effect to appear.
Packet identity separates content from routing
The application message is only one field in the LayerZero packet. The container also carries a nonce, source and destination endpoint IDs, sender, receiver and GUID. Message libraries encode routing fields into a packet header and pair the GUID with the application bytes as the payload. That structure lets workers refer to the same message without treating its business content as its identity.
An accepted send returns a MessagingReceipt containing one GUID, its pathway nonce and the fee paid. The GUID identifies the individual packet across stages, while the nonce locates it within one directional channel. A payload hash later binds the GUID and message bytes to the verified destination record. Searching only by payload text can confuse repeated instructions that belong to different nonces.
Verification commits a payload hash, not the business result
DVNs attest to the packet header and payload hash after the configured source-chain confirmation condition has been met. Their submissions don't execute the receiving application. The receive library first checks the packet version, destination endpoint and receiver's security configuration, then determines whether the configured verification requirement has been satisfied.
ReceiveUln302 commits a packet only after every required DVN and any configured threshold of optional DVNs have submitted verification.
A successful commit calls the destination Endpoint's verification function, which stores the payload hash in the inbound channel and emits
PacketVerified. That event proves protocol acceptance of the verified payload. It doesn't prove that the receiver decoded the message or changed its own state.
Execution options define the delivery attempt
Execution options tell the Executor what resources and behavior the destination call needs. An
lzReceive
option can specify gas and native value, while an ordered-execution option requests nonce-ordered delivery instead of the default unordered path. The quote must use the same destination EID, receiver, payload, options and fee-payment choice as the send. Too little destination gas can leave a verified packet undelivered, but more gas can't repair invalid receiver logic, a missing peer or incompatible message decoding.
Protocol signals and application state answer different questions
On the source chain, a successful transaction and
PacketSent
show that the Endpoint accepted and exposed an encoded packet. The GUID and nonce connect that event to later activity. Neither signal says that the configured DVNs have finished their work.
On the destination chain,
PacketVerified
shows that the payload hash entered the receiving channel under the applicable verification configuration. A delivery transaction then supplies the GUID and message bytes. The Endpoint hashes them, compares that value with its stored record and clears the matching payload before calling the OApp.
A successful
PacketDelivered
signal proves that the Endpoint's call completed. The receiving application may emit its own event, update storage or trigger another supported action. That application-level effect answers whether the original instruction accomplished its purpose. Protocol delivery and business completion coincide only when the OApp's intended logic also succeeds.
Verified messages can still fail during execution
Verification and execution are separate, so a valid packet may remain incomplete after a destination attempt. Insufficient gas, a receiver revert, incompatible decoding or an unmet application condition can stop
lzReceive. A failed attempt may produce an
LzReceiveAlert
and leave the verified payload available rather than requiring another source send. This separation preserves the accepted message while the execution fault is diagnosed.
Recovery follows the last completed state
Start recovery at the latest confirmed transition. Repeating an earlier action can create a second GUID without advancing the original packet.
If the source transaction reverted, no send was accepted. Correct the source call, refresh its quote if the inputs changed and submit a new transaction.
If
PacketSent
exists but
PacketVerified
doesn't, preserve the original GUID. Check the directional pathway, active libraries, peer relationship, confirmation requirement and configured DVN submissions. A destination execution call has nothing to consume until the payload hash is committed.
If verification completed but execution failed, inspect the destination attempt. An out-of-gas failure calls for enough destination resources on a retry. A receiver revert must be resolved at the application layer first. Because the payload is already verified, any caller with the matching packet data can retry
lzReceive
without recreating the source packet.
A peer mismatch or incompatible receiver can't be solved by repeated delivery calls. Correct the missing compatibility dependency, then retry the existing verified message if its channel state still permits execution. Resending is a different operation because it creates a new packet identity.
Completion ends with the receiving application's effect
The strongest completion record joins the original GUID and pathway nonce to a committed payload hash, a successful destination transaction and the receiving application's intended effect. Each item answers a different question: which packet was sent, which bytes were verified, whether delivery executed and whether the application produced its promised output.
Stop when that final state is observable and consistent with the message's instruction. A monitoring label can summarize progress, but it shouldn't replace the underlying chain records. A source receipt proves dispatch, while the receiving application's observable effect proves completion.
Still wondering about Layerzero Messaging?
Why might a successful source transaction still lack a LayerZero packet?
The transaction may have completed another contract action without reaching a successful Endpoint send. A LayerZero send should produce the expected PacketSent evidence and a packet identity. Without that event, don't infer that DVNs received a job or that destination activity should follow. Inspect the called contract and its logs to find where the source execution stopped before submitting another transaction.
Does payload size alone determine the messaging fee?
No, payload size is only one fee input. The quote also reflects the destination pathway, selected DVNs, confirmation configuration, Executor settings and requested destination gas or value. Changing execution options can therefore change the quote even when the application bytes stay identical. Use a quote built from the same destination EID, receiver, payload, options and payment choice that the send will submit.
Can a later nonce execute before an earlier one?
Yes, the default V2 execution path is unordered, but every preceding nonce on that pathway must first have a verified channel record. The earlier payload doesn't necessarily need to execute before the later one. Adding the ordered-execution option changes that behavior by making delivery observe nonce order. The receiving application may also impose stricter sequencing through its own state and logic.
Is the application payload private while LayerZero delivers it?
No, LayerZero messaging doesn't provide payload confidentiality. The encoded packet is exposed through source-chain activity, and destination execution supplies the message bytes to the Endpoint and receiving OApp. Storing a payload hash in the destination channel protects integrity; it doesn't encrypt the underlying content. Applications shouldn't place secrets in the message unless they apply a separate encryption design with appropriate key management.
- last updated