Message, Packet, and Payload

Because cross-chain messaging enables a wide range of operations, such as transferring assets, relaying data, or executing external calls, the LayerZero protocol standardizes how information is passed from one chain to another. This standardization is achieved by breaking down the process into three interconnected components:

Message (Application)

The message is the raw, original content or instruction as defined by the application in bytes. It represents the core data that the sender intends to deliver to the recipient via the LayerZero Endpoint:

// packages/layerzero-v2/evm/protocol/contracts/interfaces/ILayerZeroEndpointV2.sol
struct MessagingParams {
    uint32 dstEid;
    bytes32 receiver;
    bytes message;
    bytes options;
    bool payInLzToken;
}

Packet (Endpoint)

The Packet is the protocol-level container that wraps the application’s message along with additional metadata necessary for secure and reliable cross-chain communication. The standard Packet structure is defined as follows in the LayerZero Endpoint:

// packages/layerzero-v2/evm/protocol/contracts/interfaces/ISendLib.sol
struct Packet {
    uint64 nonce;     // The nonce of the message in the pathway, ensuring proper ordering and preventing replay attacks.
    uint32 srcEid;    // The source endpoint ID.
    address sender;   // The sender address.
    uint32 dstEid;    // The destination endpoint ID.
    bytes32 receiver; // The receiving address.
    bytes32 guid;     // A globally unique identifier for tracking the message.
    bytes message;    // The application’s original message.
}

This structure ensures that each message is uniquely identifiable and carries the necessary information (like routing, ordering, and traceability data) for the underlying protocols to process it accurately.

Payload (Message Libraries)

The payload is the encoded representation of the key components of the Packet that the messaging libraries operate on. In many library implementations (for example, in the Ultra Light Node), the payload is created by serializing specific elements of the Packet (typically the GUID followed by the actual application message) into a compact binary format:

// packages/layerzero-v2/evm/protocol/contracts/messagelib/libs/PacketV1Codec.sol
function encodePayload(Packet memory _packet) internal pure returns (bytes memory) {
  return abi.encodePacked(_packet.guid, _packet.message);
}

When combined with the encoded packet header (which contains routing and metadata information such as the nonce, endpoint IDs, and addresses), the payload forms the final encodedPacket that is transmitted between chains.

// packages/layerzero-v2/evm/protocol/contracts/messagelib/libs/PacketV1Codec.sol
function encodePacketHeader(Packet memory _packet) internal pure returns (bytes memory) {
  return
    abi.encodePacked(
      PACKET_VERSION,
      _packet.nonce,
      _packet.srcEid,
      _packet.sender.toBytes32(),
      _packet.dstEid,
      _packet.receiver
  );
}

// packages/layerzero-v2/evm/messagelib/contracts/uln/SendUlnBase.sol
encodedPacket = abi.encodePacked(packetHeader, payload);

Packet Structure and Its Benefits

Standardizing the Packet structure brings several advantages:

• Ordering and Routing:
  Fields like nonce, srcEid, dstEid, and receiver ensure that messages are delivered in the correct order to the proper destination, while also mitigating replay attacks.

• Traceability:
  The inclusion of a unique guid along with source and destination identifiers allows each message to be tracked across chains, providing a robust audit trail that enhances debugging and system trust.

• Payload Integrity:
  The message field carries the actual application data, and when the Packet is processed by a messaging library, its contents are split into two parts:

  1. Packet Header: Contains essential routing and identification metadata.

  2. Payload: Comprises the encoded version of the GUID and the application’s message.

  This separation allows for efficient processing by downstream components while ensuring that the integrity of the message is maintained throughout transit.

Summary

• Message:
  The raw application data or instruction that needs to be communicated.

• Packet:
  The complete protocol container that encapsulates the message along with metadata (nonce, endpoint IDs, sender, receiver, and a global identifier) required for secure and orderly cross-chain communication.

• Payload:
  The encoded portion (typically a serialization of the GUID and message) that is generated by the messaging library and used for efficient data transmission and processing.

This layered approach ensures that messages are both adaptable to various blockchain environments and robust in terms of security and traceability.