@layerzerolabs/lz-evm-protocol-v2 2.0.2

package/contracts/MessageLibManager.sol

@@ -0,0 +1,326 @@
+// SPDX-License-Identifier: LZBL-1.2
+
+pragma solidity ^0.8.22;
+
+import { IERC165 } from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
+import { Ownable } from "@openzeppelin/contracts/access/Ownable.sol";
+
+import { IMessageLib, MessageLibType } from "./interfaces/IMessageLib.sol";
+import { IMessageLibManager, SetConfigParam } from "./interfaces/IMessageLibManager.sol";
+import { Errors } from "./libs/Errors.sol";
+import { BlockedMessageLib } from "./messagelib/BlockedMessageLib.sol";
+
+abstract contract MessageLibManager is Ownable, IMessageLibManager {
+    address private constant DEFAULT_LIB = address(0);
+
+    // the library that reverts both on send and quote
+    // must be configured on construction and be immutable
+    address public immutable blockedLibrary;
+
+    // only registered libraries all valid libraries
+    // the blockedLibrary will be registered on construction
+    address[] internal registeredLibraries;
+    mapping(address lib => bool) public isRegisteredLibrary;
+
+    // both sendLibrary and receiveLibrary config can be lazily resolved
+    mapping(address sender => mapping(uint32 dstEid => address lib)) internal sendLibrary;
+    mapping(address receiver => mapping(uint32 srcEid => address lib)) internal receiveLibrary;
+    mapping(address receiver => mapping(uint32 srcEid => Timeout)) public receiveLibraryTimeout;
+
+    mapping(uint32 dstEid => address lib) public defaultSendLibrary;
+    mapping(uint32 srcEid => address lib) public defaultReceiveLibrary;
+    mapping(uint32 srcEid => Timeout) public defaultReceiveLibraryTimeout;
+
+    constructor() {
+        blockedLibrary = address(new BlockedMessageLib());
+        registerLibrary(blockedLibrary);
+    }
+
+    modifier onlyRegistered(address _lib) {
+        if (!isRegisteredLibrary[_lib]) revert Errors.OnlyRegisteredLib();
+        _;
+    }
+
+    modifier isSendLib(address _lib) {
+        if (_lib != DEFAULT_LIB) {
+            if (IMessageLib(_lib).messageLibType() == MessageLibType.Receive) revert Errors.OnlySendLib();
+        }
+        _;
+    }
+
+    modifier isReceiveLib(address _lib) {
+        if (_lib != DEFAULT_LIB) {
+            if (IMessageLib(_lib).messageLibType() == MessageLibType.Send) revert Errors.OnlyReceiveLib();
+        }
+        _;
+    }
+
+    modifier onlyRegisteredOrDefault(address _lib) {
+        if (!isRegisteredLibrary[_lib] && _lib != DEFAULT_LIB) revert Errors.OnlyRegisteredOrDefaultLib();
+        _;
+    }
+
+    /// @dev check if the library supported the eid.
+    modifier onlySupportedEid(address _lib, uint32 _eid) {
+        /// @dev doesnt need to check for default lib, because when they are initially added they get passed through this modifier
+        if (_lib != DEFAULT_LIB) {
+            if (!IMessageLib(_lib).isSupportedEid(_eid)) revert Errors.UnsupportedEid();
+        }
+        _;
+    }
+
+    function getRegisteredLibraries() external view returns (address[] memory) {
+        return registeredLibraries;
+    }
+
+    /// @notice The Send Library is the Oapp specified library that will be used to send the message to the destination
+    /// endpoint. If the Oapp does not specify a Send Library, the default Send Library will be used.
+    /// @dev If the Oapp does not have a selected Send Library, this function will resolve to the default library
+    /// configured by LayerZero
+    /// @return lib address of the Send Library
+    /// @param _sender The address of the Oapp that is sending the message
+    /// @param _dstEid The destination endpoint id
+    function getSendLibrary(address _sender, uint32 _dstEid) public view returns (address lib) {
+        lib = sendLibrary[_sender][_dstEid];
+        if (lib == DEFAULT_LIB) {
+            lib = defaultSendLibrary[_dstEid];
+            if (lib == address(0x0)) revert Errors.DefaultSendLibUnavailable();
+        }
+    }
+
+    function isDefaultSendLibrary(address _sender, uint32 _dstEid) public view returns (bool) {
+        return sendLibrary[_sender][_dstEid] == DEFAULT_LIB;
+    }
+
+    /// @dev the receiveLibrary can be lazily resolved that if not set it will point to the default configured by LayerZero
+    function getReceiveLibrary(address _receiver, uint32 _srcEid) public view returns (address lib, bool isDefault) {
+        lib = receiveLibrary[_receiver][_srcEid];
+        if (lib == DEFAULT_LIB) {
+            lib = defaultReceiveLibrary[_srcEid];
+            if (lib == address(0x0)) revert Errors.DefaultReceiveLibUnavailable();
+            isDefault = true;
+        }
+    }
+
+    /// @dev called when the endpoint checks if the msgLib attempting to verify the msg is the configured msgLib of the Oapp
+    /// @dev this check provides the ability for Oapp to lock in a trusted msgLib
+    /// @dev it will fist check if the msgLib is the currently configured one. then check if the msgLib is the one in grace period of msgLib versioning upgrade
+    function isValidReceiveLibrary(
+        address _receiver,
+        uint32 _srcEid,
+        address _actualReceiveLib
+    ) public view returns (bool) {
+        // early return true if the _actualReceiveLib is the currently configured one
+        (address expectedReceiveLib, bool isDefault) = getReceiveLibrary(_receiver, _srcEid);
+        if (_actualReceiveLib == expectedReceiveLib) {
+            return true;
+        }
+
+        // check the timeout condition otherwise
+        // if the Oapp is using defaultReceiveLibrary, use the default Timeout config
+        // otherwise, use the Timeout configured by the Oapp
+        Timeout memory timeout = isDefault
+            ? defaultReceiveLibraryTimeout[_srcEid]
+            : receiveLibraryTimeout[_receiver][_srcEid];
+
+        // requires the _actualReceiveLib to be the same as the one in grace period and the grace period has not expired
+        // block.number is uint256 so timeout.expiry must > 0, which implies a non-ZERO value
+        if (timeout.lib == _actualReceiveLib && timeout.expiry > block.number) {
+            // timeout lib set and has not expired
+            return true;
+        }
+
+        // returns false by default
+        return false;
+    }
+
+    //------- Owner interfaces
+    /// @dev all libraries have to implement the erc165 interface to prevent wrong configurations
+    /// @dev only owner
+    function registerLibrary(address _lib) public onlyOwner {
+        // must have the right interface
+        if (!IERC165(_lib).supportsInterface(type(IMessageLib).interfaceId)) revert Errors.UnsupportedInterface();
+        // must have not been registered
+        if (isRegisteredLibrary[_lib]) revert Errors.AlreadyRegistered();
+
+        // insert into both the map and the list
+        isRegisteredLibrary[_lib] = true;
+        registeredLibraries.push(_lib);
+
+        emit LibraryRegistered(_lib);
+    }
+
+    /// @dev owner setting the defaultSendLibrary
+    /// @dev can set to the blockedLibrary, which is a registered library
+    /// @dev the msgLib must enable the support before they can be registered to the endpoint as the default
+    /// @dev only owner
+    function setDefaultSendLibrary(
+        uint32 _eid,
+        address _newLib
+    ) external onlyOwner onlyRegistered(_newLib) isSendLib(_newLib) onlySupportedEid(_newLib, _eid) {
+        address oldLib = defaultSendLibrary[_eid];
+        // must provide a different value
+        if (oldLib == _newLib) revert Errors.SameValue();
+        defaultSendLibrary[_eid] = _newLib;
+        emit DefaultSendLibrarySet(_eid, _newLib);
+    }
+
+    /// @dev owner setting the defaultSendLibrary
+    /// @dev must be a registered library (including blockLibrary) with the eid support enabled
+    /// @dev in version migration, it can add a grace period to the old library. if the grace period is 0, it will delete the timeout configuration.
+    /// @dev only owner
+    function setDefaultReceiveLibrary(
+        uint32 _eid,
+        address _newLib,
+        uint256 _gracePeriod
+    ) external onlyOwner onlyRegistered(_newLib) isReceiveLib(_newLib) onlySupportedEid(_newLib, _eid) {
+        address oldLib = defaultReceiveLibrary[_eid];
+        // must provide a different value
+        if (oldLib == _newLib) revert Errors.SameValue();
+
+        defaultReceiveLibrary[_eid] = _newLib;
+        emit DefaultReceiveLibrarySet(_eid, oldLib, _newLib);
+
+        if (_gracePeriod > 0) {
+            // override the current default timeout to the [old_lib + new expiry]
+            Timeout storage timeout = defaultReceiveLibraryTimeout[_eid];
+            timeout.lib = oldLib;
+            timeout.expiry = block.number + _gracePeriod;
+            emit DefaultReceiveLibraryTimeoutSet(_eid, oldLib, timeout.expiry);
+        } else {
+            // otherwise, remove the old configuration.
+            delete defaultReceiveLibraryTimeout[_eid];
+            emit DefaultReceiveLibraryTimeoutSet(_eid, oldLib, 0);
+        }
+    }
+
+    /// @dev owner setting the defaultSendLibrary
+    /// @dev must be a registered library (including blockLibrary) with the eid support enabled
+    /// @dev can used to (1) extend the current configuration (2) force remove the current configuration (3) change to a new configuration
+    /// @param _expiry the block number when lib expires
+    function setDefaultReceiveLibraryTimeout(
+        uint32 _eid,
+        address _lib,
+        uint256 _expiry
+    ) external onlyRegistered(_lib) isReceiveLib(_lib) onlySupportedEid(_lib, _eid) onlyOwner {
+        if (_expiry == 0) {
+            // force remove the current configuration
+            delete defaultReceiveLibraryTimeout[_eid];
+        } else {
+            // override it with new configuration
+            if (_expiry <= block.number) revert Errors.InvalidExpiry();
+            Timeout storage timeout = defaultReceiveLibraryTimeout[_eid];
+            timeout.lib = _lib;
+            timeout.expiry = _expiry;
+        }
+        emit DefaultReceiveLibraryTimeoutSet(_eid, _lib, _expiry);
+    }
+
+    /// @dev returns true only if both the default send/receive libraries are set
+    function isSupportedEid(uint32 _eid) external view returns (bool) {
+        return defaultSendLibrary[_eid] != address(0) && defaultReceiveLibrary[_eid] != address(0);
+    }
+
+    //------- OApp interfaces
+    /// @dev Oapp setting the sendLibrary
+    /// @dev must be a registered library (including blockLibrary) with the eid support enabled
+    /// @dev authenticated by the Oapp
+    function setSendLibrary(
+        address _oapp,
+        uint32 _eid,
+        address _newLib
+    ) external onlyRegisteredOrDefault(_newLib) isSendLib(_newLib) onlySupportedEid(_newLib, _eid) {
+        _assertAuthorized(_oapp);
+
+        address oldLib = sendLibrary[_oapp][_eid];
+        // must provide a different value
+        if (oldLib == _newLib) revert Errors.SameValue();
+        sendLibrary[_oapp][_eid] = _newLib;
+        emit SendLibrarySet(_oapp, _eid, _newLib);
+    }
+
+    /// @dev Oapp setting the receiveLibrary
+    /// @dev must be a registered library (including blockLibrary) with the eid support enabled
+    /// @dev in version migration, it can add a grace period to the old library. if the grace period is 0, it will delete the timeout configuration.
+    /// @dev authenticated by the Oapp
+    /// @param _gracePeriod the number of blocks from now until oldLib expires
+    function setReceiveLibrary(
+        address _oapp,
+        uint32 _eid,
+        address _newLib,
+        uint256 _gracePeriod
+    ) external onlyRegisteredOrDefault(_newLib) isReceiveLib(_newLib) onlySupportedEid(_newLib, _eid) {
+        _assertAuthorized(_oapp);
+
+        address oldLib = receiveLibrary[_oapp][_eid];
+        // must provide new values
+        if (oldLib == _newLib) revert Errors.SameValue();
+        receiveLibrary[_oapp][_eid] = _newLib;
+        emit ReceiveLibrarySet(_oapp, _eid, oldLib, _newLib);
+
+        if (_gracePeriod > 0) {
+            // to simplify the logic, we only allow to set timeout if neither the new lib nor old lib is DEFAULT_LIB, which would should read the default timeout configurations
+            // (1) if the Oapp wants to fall back to the DEFAULT, then set the newLib to DEFAULT with grace period == 0
+            // (2) if the Oapp wants to change to a non DEFAULT from DEFAULT, then set the newLib to 'non-default' with _gracePeriod == 0, then use setReceiveLibraryTimeout() interface
+            if (oldLib == DEFAULT_LIB || _newLib == DEFAULT_LIB) revert Errors.OnlyNonDefaultLib();
+
+            // write to storage
+            Timeout memory timeout = Timeout({ lib: oldLib, expiry: block.number + _gracePeriod });
+            receiveLibraryTimeout[_oapp][_eid] = timeout;
+            emit ReceiveLibraryTimeoutSet(_oapp, _eid, oldLib, timeout.expiry);
+        } else {
+            delete receiveLibraryTimeout[_oapp][_eid];
+            emit ReceiveLibraryTimeoutSet(_oapp, _eid, oldLib, 0);
+        }
+    }
+
+    /// @dev Oapp setting the defaultSendLibrary
+    /// @dev must be a registered library (including blockLibrary) with the eid support enabled
+    /// @dev can used to (1) extend the current configuration (2)  force remove the current configuration (3) change to a new configuration
+    /// @param _expiry the block number when lib expires
+    function setReceiveLibraryTimeout(
+        address _oapp,
+        uint32 _eid,
+        address _lib,
+        uint256 _expiry
+    ) external onlyRegistered(_lib) isReceiveLib(_lib) onlySupportedEid(_lib, _eid) {
+        _assertAuthorized(_oapp);
+
+        (, bool isDefault) = getReceiveLibrary(_oapp, _eid);
+        // if current library is DEFAULT, Oapp cant set the timeout
+        if (isDefault) revert Errors.OnlyNonDefaultLib();
+
+        if (_expiry == 0) {
+            // force remove the current configuration
+            delete receiveLibraryTimeout[_oapp][_eid];
+        } else {
+            // override it with new configuration
+            if (_expiry <= block.number) revert Errors.InvalidExpiry();
+            Timeout storage timeout = receiveLibraryTimeout[_oapp][_eid];
+            timeout.lib = _lib;
+            timeout.expiry = _expiry;
+        }
+        emit ReceiveLibraryTimeoutSet(_oapp, _eid, _lib, _expiry);
+    }
+
+    //------- library config setter/getter. all pass-through functions to the msgLib
+
+    /// @dev authenticated by the _oapp
+    function setConfig(address _oapp, address _lib, SetConfigParam[] calldata _params) external onlyRegistered(_lib) {
+        _assertAuthorized(_oapp);
+
+        IMessageLib(_lib).setConfig(_oapp, _params);
+    }
+
+    /// @dev a view function to query the current configuration of the OApp
+    function getConfig(
+        address _oapp,
+        address _lib,
+        uint32 _eid,
+        uint32 _configType
+    ) external view onlyRegistered(_lib) returns (bytes memory config) {
+        return IMessageLib(_lib).getConfig(_eid, _oapp, _configType);
+    }
+
+    function _assertAuthorized(address _oapp) internal virtual;
+}

package/contracts/MessagingChannel.sol

@@ -0,0 +1,161 @@
+// SPDX-License-Identifier: LZBL-1.2
+
+pragma solidity ^0.8.22;
+
+import { IMessagingChannel } from "./interfaces/IMessagingChannel.sol";
+import { Errors } from "./libs/Errors.sol";
+import { GUID } from "./libs/GUID.sol";
+
+abstract contract MessagingChannel is IMessagingChannel {
+    bytes32 public constant EMPTY_PAYLOAD_HASH = bytes32(0);
+    bytes32 public constant NIL_PAYLOAD_HASH = bytes32(type(uint256).max);
+
+    // The universally unique id (UUID) of this deployed Endpoint
+    uint32 public immutable eid;
+
+    mapping(address receiver => mapping(uint32 srcEid => mapping(bytes32 sender => uint64 nonce)))
+        public lazyInboundNonce;
+    mapping(address receiver => mapping(uint32 srcEid => mapping(bytes32 sender => mapping(uint64 inboundNonce => bytes32 payloadHash))))
+        public inboundPayloadHash;
+    mapping(address sender => mapping(uint32 dstEid => mapping(bytes32 receiver => uint64 nonce))) public outboundNonce;
+
+    /// @param _eid is the universally unique id (UUID) of this deployed Endpoint
+    constructor(uint32 _eid) {
+        eid = _eid;
+    }
+
+    /// @dev increase and return the next outbound nonce
+    function _outbound(address _sender, uint32 _dstEid, bytes32 _receiver) internal returns (uint64 nonce) {
+        unchecked {
+            nonce = ++outboundNonce[_sender][_dstEid][_receiver];
+        }
+    }
+
+    /// @dev inbound won't update the nonce eagerly to allow unordered verification
+    /// @dev instead, it will update the nonce lazily when the message is received
+    /// @dev messages can only be cleared in order to preserve censorship-resistance
+    function _inbound(
+        address _receiver,
+        uint32 _srcEid,
+        bytes32 _sender,
+        uint64 _nonce,
+        bytes32 _payloadHash
+    ) internal {
+        if (_payloadHash == EMPTY_PAYLOAD_HASH) revert Errors.InvalidPayloadHash();
+        inboundPayloadHash[_receiver][_srcEid][_sender][_nonce] = _payloadHash;
+    }
+
+    /// @dev returns the max index of the longest gapless sequence of verified msg nonces.
+    /// @dev the uninitialized value is 0. the first nonce is always 1
+    /// @dev it starts from the lazyInboundNonce (last checkpoint) and iteratively check if the next nonce has been verified
+    /// @dev this function can OOG if too many backlogs, but it can be trivially fixed by just clearing some prior messages
+    /// @dev NOTE: Oapp explicitly skipped nonces count as "verified" for these purposes
+    /// @dev eg. [1,2,3,4,6,7] => 4, [1,2,6,8,10] => 2, [1,3,4,5,6] => 1
+    function inboundNonce(address _receiver, uint32 _srcEid, bytes32 _sender) public view returns (uint64) {
+        uint64 nonceCursor = lazyInboundNonce[_receiver][_srcEid][_sender];
+
+        // find the effective inbound currentNonce
+        unchecked {
+            while (_hasPayloadHash(_receiver, _srcEid, _sender, nonceCursor + 1)) {
+                ++nonceCursor;
+            }
+        }
+        return nonceCursor;
+    }
+
+    /// @dev checks if the storage slot is not initialized. Assumes computationally infeasible that payload can hash to 0
+    function _hasPayloadHash(
+        address _receiver,
+        uint32 _srcEid,
+        bytes32 _sender,
+        uint64 _nonce
+    ) internal view returns (bool) {
+        return inboundPayloadHash[_receiver][_srcEid][_sender][_nonce] != EMPTY_PAYLOAD_HASH;
+    }
+
+    /// @dev the caller must provide _nonce to prevent skipping the unintended nonce
+    /// @dev it could happen in some race conditions, e.g. to skip nonce 3, but nonce 3 was consumed first
+    /// @dev usage: skipping the next nonce to prevent message verification, e.g. skip a message when Precrime throws alerts
+    /// @dev if the Oapp wants to skip a verified message, it should call the clear() function instead
+    /// @dev after skipping, the lazyInboundNonce is set to the provided nonce, which makes the inboundNonce also the provided nonce
+    /// @dev ie. allows the Oapp to increment the lazyInboundNonce without having had that corresponding msg be verified
+    function skip(address _oapp, uint32 _srcEid, bytes32 _sender, uint64 _nonce) external {
+        _assertAuthorized(_oapp);
+
+        if (_nonce != inboundNonce(_oapp, _srcEid, _sender) + 1) revert Errors.InvalidNonce(_nonce);
+        lazyInboundNonce[_oapp][_srcEid][_sender] = _nonce;
+        emit InboundNonceSkipped(_srcEid, _sender, _oapp, _nonce);
+    }
+
+    /// @dev Marks a packet as verified, but disallows execution until it is re-verified.
+    /// @dev Reverts if the provided _payloadHash does not match the currently verified payload hash.
+    /// @dev A non-verified nonce can be nilified by passing EMPTY_PAYLOAD_HASH for _payloadHash.
+    /// @dev Assumes the computational intractability of finding a payload that hashes to bytes32.max.
+    /// @dev Authenticated by the caller
+    function nilify(address _oapp, uint32 _srcEid, bytes32 _sender, uint64 _nonce, bytes32 _payloadHash) external {
+        _assertAuthorized(_oapp);
+
+        bytes32 curPayloadHash = inboundPayloadHash[_oapp][_srcEid][_sender][_nonce];
+        if (curPayloadHash != _payloadHash) revert Errors.PayloadHashNotFound(curPayloadHash, _payloadHash);
+        if (_nonce <= lazyInboundNonce[_oapp][_srcEid][_sender] && curPayloadHash == EMPTY_PAYLOAD_HASH)
+            revert Errors.InvalidNonce(_nonce);
+        // set it to nil
+        inboundPayloadHash[_oapp][_srcEid][_sender][_nonce] = NIL_PAYLOAD_HASH;
+        emit PacketNilified(_srcEid, _sender, _oapp, _nonce, _payloadHash);
+    }
+
+    /// @dev Marks a nonce as unexecutable and un-verifiable. The nonce can never be re-verified or executed.
+    /// @dev Reverts if the provided _payloadHash does not match the currently verified payload hash.
+    /// @dev Only packets with nonces less than or equal to the lazy inbound nonce can be burned.
+    /// @dev Reverts if the nonce has already been executed.
+    /// @dev Authenticated by the caller
+    function burn(address _oapp, uint32 _srcEid, bytes32 _sender, uint64 _nonce, bytes32 _payloadHash) external {
+        _assertAuthorized(_oapp);
+
+        bytes32 curPayloadHash = inboundPayloadHash[_oapp][_srcEid][_sender][_nonce];
+        if (curPayloadHash != _payloadHash) revert Errors.PayloadHashNotFound(curPayloadHash, _payloadHash);
+        if (curPayloadHash == EMPTY_PAYLOAD_HASH || _nonce > lazyInboundNonce[_oapp][_srcEid][_sender])
+            revert Errors.InvalidNonce(_nonce);
+        delete inboundPayloadHash[_oapp][_srcEid][_sender][_nonce];
+        emit PacketBurnt(_srcEid, _sender, _oapp, _nonce, _payloadHash);
+    }
+
+    /// @dev calling this function will clear the stored message and increment the lazyInboundNonce to the provided nonce
+    /// @dev if a lot of messages are queued, the messages can be cleared with a smaller step size to prevent OOG
+    /// @dev NOTE: this function does not change inboundNonce, it only changes the lazyInboundNonce up to the provided nonce
+    function _clearPayload(
+        address _receiver,
+        uint32 _srcEid,
+        bytes32 _sender,
+        uint64 _nonce,
+        bytes memory _payload
+    ) internal returns (bytes32 actualHash) {
+        uint64 currentNonce = lazyInboundNonce[_receiver][_srcEid][_sender];
+        if (_nonce > currentNonce) {
+            unchecked {
+                // try to lazily update the inboundNonce till the _nonce
+                for (uint64 i = currentNonce + 1; i <= _nonce; ++i) {
+                    if (!_hasPayloadHash(_receiver, _srcEid, _sender, i)) revert Errors.InvalidNonce(i);
+                }
+                lazyInboundNonce[_receiver][_srcEid][_sender] = _nonce;
+            }
+        }
+
+        // check the hash of the payload to verify the executor has given the proper payload that has been verified
+        actualHash = keccak256(_payload);
+        bytes32 expectedHash = inboundPayloadHash[_receiver][_srcEid][_sender][_nonce];
+        if (expectedHash != actualHash) revert Errors.PayloadHashNotFound(expectedHash, actualHash);
+
+        // remove it from the storage
+        delete inboundPayloadHash[_receiver][_srcEid][_sender][_nonce];
+    }
+
+    /// @dev returns the GUID for the next message given the path
+    /// @dev the Oapp might want to include the GUID into the message in some cases
+    function nextGuid(address _sender, uint32 _dstEid, bytes32 _receiver) external view returns (bytes32) {
+        uint64 nextNonce = outboundNonce[_sender][_dstEid][_receiver] + 1;
+        return GUID.generate(nextNonce, eid, _sender, _dstEid, _receiver);
+    }
+
+    function _assertAuthorized(address _oapp) internal virtual;
+}

package/contracts/MessagingComposer.sol

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: LZBL-1.2
+
+pragma solidity ^0.8.22;
+
+import { IMessagingComposer } from "./interfaces/IMessagingComposer.sol";
+import { ILayerZeroComposer } from "./interfaces/ILayerZeroComposer.sol";
+import { Errors } from "./libs/Errors.sol";
+
+abstract contract MessagingComposer is IMessagingComposer {
+    bytes32 private constant NO_MESSAGE_HASH = bytes32(0);
+    bytes32 private constant RECEIVED_MESSAGE_HASH = bytes32(uint256(1));
+
+    mapping(address from => mapping(address to => mapping(bytes32 guid => mapping(uint16 index => bytes32 messageHash))))
+        public composeQueue;
+
+    /// @dev the Oapp sends the lzCompose message to the endpoint
+    /// @dev the composer MUST assert the sender because anyone can send compose msg with this function
+    /// @dev with the same GUID, the Oapp can send compose to multiple _composer at the same time
+    /// @dev authenticated by the msg.sender
+    /// @param _to the address which will receive the composed message
+    /// @param _guid the message guid
+    /// @param _message the message
+    function sendCompose(address _to, bytes32 _guid, uint16 _index, bytes calldata _message) external {
+        // must have not been sent before
+        if (composeQueue[msg.sender][_to][_guid][_index] != NO_MESSAGE_HASH) revert Errors.ComposeExists();
+        composeQueue[msg.sender][_to][_guid][_index] = keccak256(_message);
+        emit ComposeSent(msg.sender, _to, _guid, _index, _message);
+    }
+
+    /// @dev execute a composed messages from the sender to the composer (receiver)
+    /// @dev the execution provides the execution context (caller, extraData) to the receiver.
+    ///      the receiver can optionally assert the caller and validate the untrusted extraData
+    /// @dev can not re-entrant
+    /// @param _from the address which sends the composed message. in most cases, it is the Oapp's address.
+    /// @param _to the address which receives the composed message
+    /// @param _guid the message guid
+    /// @param _message the message
+    /// @param _extraData the extra data provided by the executor. this data is untrusted and should be validated.
+    function lzCompose(
+        address _from,
+        address _to,
+        bytes32 _guid,
+        uint16 _index,
+        bytes calldata _message,
+        bytes calldata _extraData
+    ) external payable {
+        // assert the validity
+        bytes32 expectedHash = composeQueue[_from][_to][_guid][_index];
+        bytes32 actualHash = keccak256(_message);
+        if (expectedHash != actualHash) revert Errors.ComposeNotFound(expectedHash, actualHash);
+
+        // marks the message as received to prevent reentrancy
+        // cannot just delete the value, otherwise the message can be sent again and could result in some undefined behaviour
+        // even though the sender(composing Oapp) is implicitly fully trusted by the composer.
+        // eg. sender may not even realize it has such a bug
+        composeQueue[_from][_to][_guid][_index] = RECEIVED_MESSAGE_HASH;
+        ILayerZeroComposer(_to).lzCompose{ value: msg.value }(_from, _guid, _message, msg.sender, _extraData);
+        emit ComposeDelivered(_from, _to, _guid, _index);
+    }
+
+    /// @param _from the address which sends the composed message
+    /// @param _to the address which receives the composed message
+    /// @param _guid the message guid
+    /// @param _message the message
+    /// @param _extraData the extra data provided by the executor
+    /// @param _reason the reason why the message is not received
+    function lzComposeAlert(
+        address _from,
+        address _to,
+        bytes32 _guid,
+        uint16 _index,
+        uint256 _gas,
+        uint256 _value,
+        bytes calldata _message,
+        bytes calldata _extraData,
+        bytes calldata _reason
+    ) external {
+        emit LzComposeAlert(_from, _to, msg.sender, _guid, _index, _gas, _value, _message, _extraData, _reason);
+    }
+}

package/contracts/MessagingContext.sol

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: LZBL-1.2
+
+pragma solidity ^0.8.22;
+
+import { IMessagingContext } from "./interfaces/IMessagingContext.sol";
+import { Errors } from "./libs/Errors.sol";
+
+/// this contract acts as a non-reentrancy guard and a source of messaging context
+/// the context includes the remote eid and the sender address
+/// it separates the send and receive context to allow messaging receipts (send back on receive())
+abstract contract MessagingContext is IMessagingContext {
+    uint256 private constant NOT_ENTERED = 1;
+    uint256 private _sendContext = NOT_ENTERED;
+
+    /// @dev the sendContext is set to 8 bytes 0s + 4 bytes eid + 20 bytes sender
+    modifier sendContext(uint32 _dstEid, address _sender) {
+        if (_sendContext != NOT_ENTERED) revert Errors.SendReentrancy();
+        _sendContext = (uint256(_dstEid) << 160) | uint160(_sender);
+        _;
+        _sendContext = NOT_ENTERED;
+    }
+
+    /// @dev returns true if sending message
+    function isSendingMessage() public view returns (bool) {
+        return _sendContext != NOT_ENTERED;
+    }
+
+    /// @dev returns (eid, sender) if sending message, (0, 0) otherwise
+    function getSendContext() external view returns (uint32, address) {
+        return isSendingMessage() ? _getSendContext(_sendContext) : (0, address(0));
+    }
+
+    function _getSendContext(uint256 _context) internal pure returns (uint32, address) {
+        return (uint32(_context >> 160), address(uint160(_context)));
+    }
+}

package/contracts/interfaces/ILayerZeroComposer.sol

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity >=0.8.0;
+
+/**
+ * @title ILayerZeroComposer
+ */
+interface ILayerZeroComposer {
+    /**
+     * @notice Composes a LayerZero message from an OApp.
+     * @param _from The address initiating the composition, typically the OApp where the lzReceive was called.
+     * @param _guid The unique identifier for the corresponding LayerZero src/dst tx.
+     * @param _message The composed message payload in bytes. NOT necessarily the same payload passed via lzReceive.
+     * @param _executor The address of the executor for the composed message.
+     * @param _extraData Additional arbitrary data in bytes passed by the entity who executes the lzCompose.
+     */
+    function lzCompose(
+        address _from,
+        bytes32 _guid,
+        bytes calldata _message,
+        address _executor,
+        bytes calldata _extraData
+    ) external payable;
+}