Messaging Properties
Messages are sent from the User Application (UA) at source
srcUA to the UA at the destination dstUA. Once the message is received by dstUA, the message is considered delivered (transitioning from INFLIGHT to either SUCCESS or STORED)Message State | Cases |
|---|---|
INFLIGHT | After a message is sent |
SUCCESS | A1: dstUA success OK()
A2: dstUA fails with caught error/exception |
STORED | B1: dstUA fails with uncaught error/exception |
// message handling at destination chain
try ILayerZeroReceiver(_dstAddress).lzReceive{gas: _gasLimit}(_srcChainId, _srcAddress, _nonce, _payload) {
// message state becomes SUCCESS
} catch {
// message state becomes STORED
emit PayloadStored(_srcChainId, _srcAddress, _dstAddress, _payload);
}
Case A2:
dstUA is expected to store the message in their contract to be retried (LayerZero will not store any successfully delivered messages). dstUA is expected to monitor and retry STORED messages on behalf of its users. Case B1:
dstUA is expected to gracefully handle all errors/exceptions when receiving a message, and any uncaught errors/exceptions (including out-of-gas) will cause the message to transition into STORED. A STORED message will block the delivery of any future message from srcUA to all dstUA on the same destination chain and can be retried until the message becomes SUCCESS. dstUA should implement a handler to transition the stored message from STORED to SUCCESS. If a bug in dstUA contract results in an unrecoverable error/exception, LayerZero provides a last-resort interface to force resume message delivery, only by the dstUA contract. LayerZero provides ordered delivery of messages from a given sender to a destination chain, i.e.
srcUA-> dstChain. In other words, the message order nonce is shared by all `dstUA` on the same dstChain. That's why a STORED message blocks the message pathway from srcUA to all dstUA on the same destination chain. If it isn't necessary to preserve the sequential nonce property for a particular dstUA the sender must add the nonce into the payload and handle it end-to-end within the UA. UA can implement a non-blocking pattern in their contract code. LayerZero allows UAs to add arbitrary transaction params in the send() function, providing a high level of flexibility and opening up opportunities for a diverse set of 3rd party plugins This is implemented as an unreserved byte array parameter to the send() function, with UAs allowed to write any additional data necessary into that parameter. We recommend that UAs leave some degree of configurability for the extra parameters to allow for feature extensions.
LayerZero Endpoint has a non-reentrancy guard for both the send() and receive(), respectively. In other words, both send() and receive() can not call themselves on the same chain. UAs should not rely on LayerZero to perform the non-reentrancy check. However, UAs can query the endpoint to see if the endpoint isSendingPayload() or isReceivingPayload() for finer-grained reentrancy control.
UA can call send() in the receive() calls on the same chain. Example applications for calling send() in the receive() include (Example: Ping Pong ):
- the UA at the source chain wants a message receipt (Chain A -> Chain B -> Chain A)
- the UA at the destination reroutes the message .(Chain A -> Chain B -> Chain C)
function lzReceive(uint16 _srcChainId, bytes memory _fromAddress, uint64, /*_nonce*/ bytes memory _payload) external override {
...
// message chaining
endpoint.send{value: messageFee}(
...
);
}
However, the fee for sending messages on another chain is not observable on-chain. UAs would need to create some fee estimate heuristics. Optionally, user apps can store the chained message and then resend them with another transaction.
UA can send multiple messages in one transaction at the source chain. The endpoint non-reentrancy will not block this pattern.
function sendFirstMessage(
uint gasAmountForDst, uint16[] calldata chainIds, bytes[] calldata dstAddresses) external payable {
...
for(uint i = 0; i < chainIds.length; i++){
endpoint.send{value: fee}(chainIds[i], dstAddresses[i], messageString, msg.sender, address(0x0), _relayerParams);
}
}
LayerZero endpoint only supports messaging unicasting (from one address to another address). It is very simple to implement a multicasting address in lzReceive().
function lzReceive(uint16 _srcChainId, bytes memory _fromAddress, uint64 _nonce, bytes memory _payload) external override {
...
// extract the multicast messages.
(address[] addresses, bytes[] payloads) = extractMultiCast(_payload);
for(uint i = 0; i < addresses.length; i++){
// call downstream
// address.receive(_srcChainId, _nonce, payloads[i]);
}
}
Last modified 4mo ago