@layerzerolabs/oapp-upgradeable-evm-contracts 0.2.74

package/contracts/oapp/OAppReceiverUpgradeable.sol

@@ -0,0 +1,135 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+import { IOAppReceiver, Origin } from "@layerzerolabs/oapp-evm-contracts/contracts/interfaces/IOAppReceiver.sol";
+import { OAppCoreBaseUpgradeable } from "./OAppCoreBaseUpgradeable.sol";
+
+/**
+ * @title OAppReceiverUpgradeable
+ * @author LayerZero Labs
+ * @custom:version 1.0.0
+ * @notice Abstract contract implementing the ILayerZeroReceiver interface and extending OAppCoreBase for OApp receivers.
+ */
+abstract contract OAppReceiverUpgradeable is IOAppReceiver, OAppCoreBaseUpgradeable {
+    // Custom error message for when the caller is not the registered endpoint/
+    error OnlyEndpoint(address addr);
+
+    // @dev The version of the OAppReceiver implementation.
+    // @dev Version is bumped when changes are made to this contract.
+    uint64 internal constant RECEIVER_VERSION = 2;
+
+    /**
+     * @notice Initializes the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __OAppReceiver_init() internal onlyInitializing {}
+
+    /**
+     * @notice Unchained initialization function for the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __OAppReceiver_init_unchained() internal onlyInitializing {}
+
+    /**
+     * @notice Retrieves the OApp version information.
+     * @return senderVersion The version of the OAppSender.sol contract.
+     * @return receiverVersion The version of the OAppReceiver.sol contract.
+     *
+     * @dev Providing 0 as the default for OAppSender version. Indicates that the OAppSender is not implemented.
+     * ie. this is a RECEIVE only OApp.
+     * @dev If the OApp uses both OAppSender and OAppReceiver, then this needs to be override returning the correct versions.
+     */
+    function oAppVersion() public view virtual returns (uint64 senderVersion, uint64 receiverVersion) {
+        return (0, RECEIVER_VERSION);
+    }
+
+    /**
+     * @notice Indicates whether an address is an approved composeMsg sender to the Endpoint.
+     * @dev _origin The origin information containing the source endpoint and sender address.
+     *  - srcEid: The source chain endpoint ID.
+     *  - sender: The sender address on the src chain.
+     *  - nonce: The nonce of the message.
+     * @dev _message The lzReceive payload.
+     * @param _sender The sender address.
+     * @return isSender Is a valid sender.
+     *
+     * @dev Applications can optionally choose to implement separate composeMsg senders that are NOT the bridging layer.
+     * @dev The default sender IS the OAppReceiver implementer.
+     */
+    function isComposeMsgSender(
+        Origin calldata /*_origin*/,
+        bytes calldata /*_message*/,
+        address _sender
+    ) public view virtual returns (bool isSender) {
+        return _sender == address(this);
+    }
+
+    /**
+     * @notice Checks if the path initialization is allowed based on the provided origin.
+     * @param origin The origin information containing the source endpoint and sender address.
+     * @return isAllowed Whether the path has been initialized.
+     *
+     * @dev This indicates to the endpoint that the OApp has enabled msgs for this particular path to be received.
+     * @dev This defaults to assuming if a peer has been set, its initialized.
+     * Can be overridden by the OApp if there is other logic to determine this.
+     */
+    function allowInitializePath(Origin calldata origin) public view virtual returns (bool isAllowed) {
+        return peers(origin.srcEid) == origin.sender;
+    }
+
+    /**
+     * @notice Retrieves the next nonce for a given source endpoint and sender address.
+     * @dev _srcEid The source endpoint ID.
+     * @dev _sender The sender address.
+     * @return nonce The next nonce.
+     *
+     * @dev The path nonce starts from 1. If 0 is returned it means that there is NO nonce ordered enforcement.
+     * @dev Is required by the off-chain executor to determine the OApp expects msg execution is ordered.
+     * @dev This is also enforced by the OApp.
+     * @dev By default this is NOT enabled. ie. nextNonce is hardcoded to return 0.
+     */
+    function nextNonce(uint32, /*_srcEid*/ bytes32 /*_sender*/) public view virtual returns (uint64 nonce) {
+        return 0;
+    }
+
+    /**
+     * @dev Entry point for receiving messages or packets from the endpoint.
+     * @param _origin The origin information containing the source endpoint and sender address.
+     *  - srcEid: The source chain endpoint ID.
+     *  - sender: The sender address on the src chain.
+     *  - nonce: The nonce of the message.
+     * @param _guid The unique identifier for the received LayerZero message.
+     * @param _message The payload of the received message.
+     * @param _executor The address of the executor for the received message.
+     * @param _extraData Additional arbitrary data provided by the corresponding executor.
+     *
+     * @dev Entry point for receiving msg/packet from the LayerZero endpoint.
+     */
+    function lzReceive(
+        Origin calldata _origin,
+        bytes32 _guid,
+        bytes calldata _message,
+        address _executor,
+        bytes calldata _extraData
+    ) public payable virtual {
+        // Ensures that only the endpoint can attempt to lzReceive() messages to this OApp.
+        if (address(endpoint) != msg.sender) revert OnlyEndpoint(msg.sender);
+
+        // Ensure that the sender matches the expected peer for the source endpoint.
+        if (_getPeerOrRevert(_origin.srcEid) != _origin.sender) revert OnlyPeer(_origin.srcEid, _origin.sender);
+
+        // Call the internal OApp implementation of lzReceive.
+        _lzReceive(_origin, _guid, _message, _executor, _extraData);
+    }
+
+    /**
+     * @dev Internal function to implement lzReceive logic without needing to copy the basic parameter validation.
+     */
+    function _lzReceive(
+        Origin calldata _origin,
+        bytes32 _guid,
+        bytes calldata _message,
+        address _executor,
+        bytes calldata _extraData
+    ) internal virtual;
+}

package/contracts/oapp/OAppSenderUpgradeable.sol

@@ -0,0 +1,141 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+import {
+    MessagingParams,
+    MessagingFee,
+    MessagingReceipt
+} from "@layerzerolabs/lz-evm-protocol-v2/contracts/interfaces/ILayerZeroEndpointV2.sol";
+import { SafeERC20, IERC20 } from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+import { OAppCoreBaseUpgradeable } from "./OAppCoreBaseUpgradeable.sol";
+
+/**
+ * @title OAppSenderUpgradeable
+ * @author LayerZero Labs
+ * @custom:version 1.0.0
+ * @notice Abstract contract implementing the OAppSender functionality for sending messages to a LayerZero endpoint.
+ */
+abstract contract OAppSenderUpgradeable is OAppCoreBaseUpgradeable {
+    using SafeERC20 for IERC20;
+
+    // Custom error messages
+    error NotEnoughNative(uint256 msgValue);
+    error LzTokenUnavailable();
+
+    // @dev The version of the OAppSender implementation.
+    // @dev Version is bumped when changes are made to this contract.
+    uint64 internal constant SENDER_VERSION = 1;
+
+    /**
+     * @notice Initializes the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __OAppSender_init() internal onlyInitializing {}
+
+    /**
+     * @notice Unchained initialization function for the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __OAppSender_init_unchained() internal onlyInitializing {}
+
+    /**
+     * @notice Retrieves the OApp version information.
+     * @return senderVersion The version of the OAppSender.sol contract.
+     * @return receiverVersion The version of the OAppReceiver.sol contract.
+     *
+     * @dev Providing 0 as the default for OAppReceiver version. Indicates that the OAppReceiver is not implemented.
+     * ie. this is a SEND only OApp.
+     * @dev If the OApp uses both OAppSender and OAppReceiver, then this needs to be override returning the correct versions
+     */
+    function oAppVersion() public view virtual returns (uint64 senderVersion, uint64 receiverVersion) {
+        return (SENDER_VERSION, 0);
+    }
+
+    /**
+     * @dev Internal function to interact with the LayerZero EndpointV2.quote() for fee calculation.
+     * @param _dstEid The destination endpoint ID.
+     * @param _message The message payload.
+     * @param _options Additional options for the message.
+     * @param _payInLzToken Flag indicating whether to pay the fee in LZ tokens.
+     * @return fee The calculated MessagingFee for the message.
+     *      - nativeFee: The native fee for the message.
+     *      - lzTokenFee: The LZ token fee for the message.
+     */
+    function _quote(
+        uint32 _dstEid,
+        bytes memory _message,
+        bytes memory _options,
+        bool _payInLzToken
+    ) internal view virtual returns (MessagingFee memory fee) {
+        return
+            endpoint.quote(
+                MessagingParams(_dstEid, _getPeerOrRevert(_dstEid), _message, _options, _payInLzToken),
+                address(this)
+            );
+    }
+
+    /**
+     * @dev Internal function to interact with the LayerZero EndpointV2.send() for sending a message.
+     * @param _dstEid The destination endpoint ID.
+     * @param _message The message payload.
+     * @param _options Additional options for the message.
+     * @param _fee The calculated LayerZero fee for the message.
+     *      - nativeFee: The native fee.
+     *      - lzTokenFee: The lzToken fee.
+     * @param _refundAddress The address to receive any excess fee values sent to the endpoint.
+     * @return receipt The receipt for the sent message.
+     *      - guid: The unique identifier for the sent message.
+     *      - nonce: The nonce of the sent message.
+     *      - fee: The LayerZero fee incurred for the message.
+     */
+    function _lzSend(
+        uint32 _dstEid,
+        bytes memory _message,
+        bytes memory _options,
+        MessagingFee memory _fee,
+        address _refundAddress
+    ) internal virtual returns (MessagingReceipt memory receipt) {
+        // @dev Push corresponding fees to the endpoint, any excess is sent back to the _refundAddress from the endpoint.
+        uint256 messageValue = _payNative(_fee.nativeFee);
+        if (_fee.lzTokenFee > 0) _payLzToken(_fee.lzTokenFee);
+
+        return
+            // solhint-disable-next-line check-send-result
+            endpoint.send{ value: messageValue }(
+                MessagingParams(_dstEid, _getPeerOrRevert(_dstEid), _message, _options, _fee.lzTokenFee > 0),
+                _refundAddress
+            );
+    }
+
+    /**
+     * @dev Internal function to pay the native fee associated with the message.
+     * @param _nativeFee The native fee to be paid.
+     * @return nativeFee The amount of native currency paid.
+     *
+     * @dev If the OApp needs to initiate MULTIPLE LayerZero messages in a single transaction,
+     * this will need to be overridden because msg.value would contain multiple lzFees.
+     * @dev Should be overridden in the event the LayerZero endpoint requires a different native currency.
+     * @dev Some EVMs use an ERC20 as a method for paying transactions/gasFees.
+     * @dev The endpoint is EITHER/OR, ie. it will NOT support both types of native payment at a time.
+     */
+    function _payNative(uint256 _nativeFee) internal virtual returns (uint256 nativeFee) {
+        if (msg.value != _nativeFee) revert NotEnoughNative(msg.value);
+        return _nativeFee;
+    }
+
+    /**
+     * @dev Internal function to pay the LZ token fee associated with the message.
+     * @param _lzTokenFee The LZ token fee to be paid.
+     *
+     * @dev If the caller is trying to pay in the specified lzToken, then the lzTokenFee is passed to the endpoint.
+     * @dev Any excess sent, is passed back to the specified _refundAddress in the _lzSend().
+     */
+    function _payLzToken(uint256 _lzTokenFee) internal virtual {
+        // @dev Cannot cache the token because it is not immutable in the endpoint.
+        address lzToken = endpoint.lzToken();
+        if (lzToken == address(0)) revert LzTokenUnavailable();
+
+        // Pay LZ token fee by sending tokens to the endpoint.
+        IERC20(lzToken).safeTransferFrom(msg.sender, address(endpoint), _lzTokenFee);
+    }
+}

package/contracts/oapp/OAppUpgradeable.sol

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+import { OAppCoreBaseUpgradeable } from "./OAppCoreBaseUpgradeable.sol";
+// @dev Import the 'Origin' so it's exposed to OApp implementers
+// solhint-disable-next-line no-unused-import
+import { OAppReceiverUpgradeable, Origin } from "./OAppReceiverUpgradeable.sol";
+// @dev Import the 'MessagingFee' and 'MessagingReceipt' so it's exposed to OApp implementers
+// solhint-disable-next-line no-unused-import
+import { OAppSenderUpgradeable, MessagingFee, MessagingReceipt } from "./OAppSenderUpgradeable.sol";
+
+/**
+ * @title OAppUpgradeable
+ * @author LayerZero Labs
+ * @custom:version 1.0.0
+ * @notice Abstract contract serving as the base for OApp implementation, combining OAppSender and OAppReceiver functionality.
+ */
+abstract contract OAppUpgradeable is OAppSenderUpgradeable, OAppReceiverUpgradeable {
+    /**
+     * @dev Constructor to initialize the OApp with the provided endpoint.
+     * @param _endpoint The address of the LOCAL LayerZero endpoint.
+     */
+    constructor(address _endpoint) OAppCoreBaseUpgradeable(_endpoint) {}
+
+    /**
+     * @notice Initializes the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __OApp_init() internal onlyInitializing {}
+
+    /**
+     * @notice Unchained initialization function for the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __OApp_init_unchained() internal onlyInitializing {}
+
+    /**
+     * @notice Retrieves the OApp version information.
+     * @return senderVersion The version of the OAppSender.sol implementation.
+     * @return receiverVersion The version of the OAppReceiver.sol implementation.
+     */
+    function oAppVersion()
+        public
+        pure
+        virtual
+        override(OAppSenderUpgradeable, OAppReceiverUpgradeable)
+        returns (uint64 senderVersion, uint64 receiverVersion)
+    {
+        return (SENDER_VERSION, RECEIVER_VERSION);
+    }
+}

package/contracts/oapp/alt/OAppAltUpgradeable.sol

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+import { IOAppAlt } from "@layerzerolabs/oapp-evm-contracts/contracts/interfaces/IOAppAlt.sol";
+import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import { SafeERC20 } from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+import { OAppCoreBaseUpgradeable } from "./../OAppCoreBaseUpgradeable.sol";
+
+/**
+ * @title OAppAltUpgradeable
+ * @author LayerZero Labs (@TRileySchwarz, tinom.eth)
+ * @custom:version 1.0.0
+ * @notice OApp extension that pays native fees using an ERC20 token instead of `msg.value`.
+ * @dev For chains where gas/native fees are paid via an ERC20 token (e.g., some L2s using `EndpointV2Alt`).
+ * @dev When using multiple inheritance, inherit from `OAppAltUpgradeable` after OApp or OFT contracts to ensure
+ *      `endpoint` is already set when this constructor runs.
+ * @dev Overrides `OAppCoreBaseUpgradeable` instead of `OAppSenderUpgradeable` to avoid inheritance conflicts.
+ */
+abstract contract OAppAltUpgradeable is IOAppAlt, OAppCoreBaseUpgradeable {
+    using SafeERC20 for IERC20;
+
+    /// @dev ERC20 token used to pay native fees, cached from the endpoint.
+    address internal immutable NATIVE_TOKEN;
+
+    /**
+     * @dev Sets immutable variables.
+     * @dev Reverts if the endpoint has a zero address native token.
+     */
+    constructor() {
+        /// @dev `endpoint` should already be set at this point by `OAppCoreUpgradeable`.
+        NATIVE_TOKEN = endpoint.nativeToken();
+        if (NATIVE_TOKEN == address(0)) revert InvalidNativeToken();
+    }
+
+    /**
+     * @dev Overrides native fee payment to use an ERC20 token instead of `msg.value`, always returns 0.
+     * @dev Implicitly overrides `OAppSenderUpgradeable._payNative` to return 0.
+     * @param _nativeFee Native fee to be paid
+     * @return nativeFee Always 0 since the fee is paid via ERC20 transfer
+     */
+    function _payNative(uint256 _nativeFee) internal virtual returns (uint256 nativeFee) {
+        if (msg.value > 0) revert OnlyAltToken();
+        if (_nativeFee > 0) {
+            IERC20(NATIVE_TOKEN).safeTransferFrom(msg.sender, address(endpoint), _nativeFee);
+        }
+        return 0;
+    }
+}

package/contracts/oapp/msg-inspection/OAppMsgInspectionBaseUpgradeable.sol

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+import { IOAppMsgInspection } from "@layerzerolabs/oapp-evm-contracts/contracts/interfaces/IOAppMsgInspection.sol";
+import { Initializable } from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
+
+/**
+ * @title OAppMsgInspectionBaseUpgradeable
+ * @author LayerZero Labs (@TRileySchwarz, tinom.eth)
+ * @custom:version 1.0.0
+ * @notice Abstract upgradeable contract that implements message inspection functionality.
+ * @dev No public management functions are exposed by this contract, wrappers should be used with access control.
+ *      Alternatively, refer to `OAppMsgInspectionRBACUpgradeable` for a permissioned implementation.
+ */
+abstract contract OAppMsgInspectionBaseUpgradeable is IOAppMsgInspection, Initializable {
+    /// @custom:storage-location erc7201:layerzerov2.storage.oappmsginspection
+    struct OAppMsgInspectionStorage {
+        address msgInspector;
+    }
+
+    // keccak256(abi.encode(uint256(keccak256("layerzerov2.storage.oappmsginspection")) - 1)) & ~bytes32(uint256(0xff))
+    bytes32 private constant OAPP_MSG_INSPECTION_STORAGE_LOCATION =
+        0x24c2aca717bd6504b7874a40f547315f719b854b33e7ff8940b1b271c2deaf00;
+
+    /**
+     * @notice Internal function to get the message inspection storage.
+     * @return $ Storage pointer
+     */
+    function _getOAppMsgInspectionStorage() internal pure returns (OAppMsgInspectionStorage storage $) {
+        assembly {
+            $.slot := OAPP_MSG_INSPECTION_STORAGE_LOCATION
+        }
+    }
+
+    /**
+     * @notice Initializes the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __OAppMsgInspectionBase_init() internal onlyInitializing {}
+
+    /**
+     * @notice Unchained initialization function for the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __OAppMsgInspectionBase_init_unchained() internal onlyInitializing {}
+
+    /**
+     * @inheritdoc IOAppMsgInspection
+     */
+    function msgInspector() public view virtual returns (address inspector) {
+        OAppMsgInspectionStorage storage $ = _getOAppMsgInspectionStorage();
+        return $.msgInspector;
+    }
+
+    // ============ Internal Functions to Wrap with Access Control ============
+
+    /**
+     * @notice Internal function to set the message inspector address.
+     * @dev To be wrapped with access control.
+     * @param _msgInspector Address of the new message inspector
+     */
+    function _setMsgInspector(address _msgInspector) internal virtual {
+        OAppMsgInspectionStorage storage $ = _getOAppMsgInspectionStorage();
+        $.msgInspector = _msgInspector;
+        emit MsgInspectorSet(_msgInspector);
+    }
+}

package/contracts/oapp/msg-inspection/OAppMsgInspectionRBACUpgradeable.sol

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+import { IOAppMsgInspection } from "@layerzerolabs/oapp-evm-contracts/contracts/interfaces/IOAppMsgInspection.sol";
+import { AccessControl2StepUpgradeable } from "@layerzerolabs/utils-upgradeable-evm-contracts/contracts/access/AccessControl2StepUpgradeable.sol";
+import { OAppMsgInspectionBaseUpgradeable } from "./OAppMsgInspectionBaseUpgradeable.sol";
+
+/**
+ * @title OAppMsgInspectionRBACUpgradeable
+ * @author LayerZero Labs (@TRileySchwarz, tinom.eth)
+ * @custom:version 1.0.0
+ * @notice Abstract upgradeable contract that implements message inspector functionality.
+ * @dev Exposes public management functions through `AccessControl2StepUpgradeable`.
+ */
+abstract contract OAppMsgInspectionRBACUpgradeable is OAppMsgInspectionBaseUpgradeable, AccessControl2StepUpgradeable {
+    /**
+     * @notice Initializes the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __OAppMsgInspectionRBAC_init() internal onlyInitializing {}
+
+    /**
+     * @notice Unchained initialization function for the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __OAppMsgInspectionRBAC_init_unchained() internal onlyInitializing {}
+
+    /**
+     * @inheritdoc IOAppMsgInspection
+     */
+    function setMsgInspector(address _msgInspector) public virtual onlyRole(DEFAULT_ADMIN_ROLE) {
+        _setMsgInspector(_msgInspector);
+    }
+}

package/contracts/oapp/options-type-3/OAppOptionsType3BaseUpgradeable.sol

@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+import { IOAppOptionsType3 } from "@layerzerolabs/oapp-evm-contracts/contracts/interfaces/IOAppOptionsType3.sol";
+import { Initializable } from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
+
+/**
+ * @title OAppOptionsType3BaseUpgradeable
+ * @author LayerZero Labs
+ * @custom:version 1.0.0
+ * @notice Abstract upgradeable contract implementing type 3 OApp options.
+ * @dev No public management functions are exposed by this contract, wrappers should be used with access control.
+ *      Alternatively, refer to `OAppOptionsType3RBACUpgradeable` for a permissioned implementation.
+ */
+abstract contract OAppOptionsType3BaseUpgradeable is IOAppOptionsType3, Initializable {
+    /// @dev Option type 3 prefix (`0x0003`).
+    uint16 internal constant OPTION_TYPE_3 = 3;
+
+    /// @custom:storage-location erc7201:layerzerov2.storage.oappoptionstype3
+    struct OAppOptionsType3Storage {
+        /// @dev `msgType` must be defined in the child contract. E.g., `SEND` or `SEND_AND_CALL`.
+        mapping(uint32 eid => mapping(uint16 msgType => bytes options)) enforcedOptions;
+    }
+
+    // keccak256(abi.encode(uint256(keccak256("layerzerov2.storage.oappoptionstype3")) - 1)) & ~bytes32(uint256(0xff))
+    bytes32 private constant OAPP_OPTIONS_TYPE_3_STORAGE_LOCATION =
+        0x8d2bda5d9f6ffb5796910376005392955773acee5548d0fcdb10e7c264ea0000;
+
+    /**
+     * @notice Internal function to get the OAppOptionsType3 storage.
+     * @return $ Storage pointer
+     */
+    function _getOAppOptionsType3Storage() internal pure returns (OAppOptionsType3Storage storage $) {
+        assembly {
+            $.slot := OAPP_OPTIONS_TYPE_3_STORAGE_LOCATION
+        }
+    }
+
+    /**
+     * @notice Initializes the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __OAppOptionsType3Base_init() internal onlyInitializing {}
+
+    /**
+     * @notice Unchained initialization function for the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __OAppOptionsType3Base_init_unchained() internal onlyInitializing {}
+
+    /**
+     * @inheritdoc IOAppOptionsType3
+     */
+    function enforcedOptions(uint32 _eid, uint16 _msgType) public view returns (bytes memory options) {
+        OAppOptionsType3Storage storage $ = _getOAppOptionsType3Storage();
+        return $.enforcedOptions[_eid][_msgType];
+    }
+
+    /**
+     * @dev If there is an enforced `lzReceive` option `{ gasLimit: 200k, msg.value: 1 ether }` AND a caller supplies a
+     *      `lzReceive` option `{ gasLimit: 100k, msg.value: 0.5 ether }`, the resulting options will be
+     *      `{ gasLimit: 300k, msg.value: 1.5 ether }` when the message is executed on the remote `lzReceive` function.
+     * @dev The presence of duplicated options is handled off-chain in the verifier/executor.
+     * @inheritdoc IOAppOptionsType3
+     */
+    function combineOptions(
+        uint32 _eid,
+        uint16 _msgType,
+        bytes calldata _extraOptions
+    ) public view virtual returns (bytes memory options) {
+        OAppOptionsType3Storage storage $ = _getOAppOptionsType3Storage();
+        bytes memory enforced = $.enforcedOptions[_eid][_msgType];
+
+        // No enforced options, pass whatever the caller supplied, even if it's empty or legacy type 1/2 options.
+        if (enforced.length == 0) return _extraOptions;
+
+        // No caller options, return enforced
+        if (_extraOptions.length == 0) return enforced;
+
+        /// @dev If caller provided `_extraOptions`, they must be type 3 as it's the ONLY type that can be combined.
+        if (_extraOptions.length >= 2) {
+            _assertOptionsType3(_extraOptions);
+            /// @dev Remove the first 2 bytes containing the type from the `_extraOptions` and combine with enforced.
+            return bytes.concat(enforced, _extraOptions[2:]);
+        }
+
+        // No valid set of options was found.
+        revert InvalidOptions(_extraOptions);
+    }
+
+    /**
+     * @dev Internal function to assert that options are of type 3.
+     * @param _options Options to be checked
+     */
+    function _assertOptionsType3(bytes memory _options) internal pure virtual {
+        uint16 optionsType;
+        assembly {
+            optionsType := mload(add(_options, 2))
+        }
+        if (optionsType != OPTION_TYPE_3) revert InvalidOptions(_options);
+    }
+
+    // ============ Internal Functions to Wrap with Access Control ============
+
+    /**
+     * @notice Internal function to set the enforced options for specific endpoint and message type combinations.
+     * @dev To be wrapped with access control.
+     * @dev Provides a way for the OApp to enforce things like paying for minimum destination `lzReceive` gas amounts.
+     * @dev These enforced options can vary as the potential options/execution on the remote may differ as per the
+     *      `msgType`. E.g., the amount of `lzReceive` gas necessary to deliver a `lzCompose` message adds overhead you
+     *      don't want to pay if you are only sending a standard message such as `lzReceive` WITHOUT `sendCompose`.
+     * @param _enforcedOptions Array of `EnforcedOptionParam` structures specifying enforced options
+     */
+    function _setEnforcedOptions(IOAppOptionsType3.EnforcedOptionParam[] memory _enforcedOptions) internal virtual {
+        OAppOptionsType3Storage storage $ = _getOAppOptionsType3Storage();
+        for (uint256 i = 0; i < _enforcedOptions.length; i++) {
+            /// @dev Enforced options are only available for option type 3, as types 1 and 2 don't support combining.
+            if (_enforcedOptions[i].options.length != 0) {
+                _assertOptionsType3(_enforcedOptions[i].options);
+            }
+            $.enforcedOptions[_enforcedOptions[i].eid][_enforcedOptions[i].msgType] = _enforcedOptions[i].options;
+        }
+
+        emit EnforcedOptionSet(_enforcedOptions);
+    }
+}

package/contracts/oapp/options-type-3/OAppOptionsType3RBACUpgradeable.sol

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+import { IOAppOptionsType3 } from "@layerzerolabs/oapp-evm-contracts/contracts/interfaces/IOAppOptionsType3.sol";
+import { AccessControl2StepUpgradeable } from "@layerzerolabs/utils-upgradeable-evm-contracts/contracts/access/AccessControl2StepUpgradeable.sol";
+import { OAppOptionsType3BaseUpgradeable } from "./OAppOptionsType3BaseUpgradeable.sol";
+
+/**
+ * @title OAppOptionsType3RBACUpgradeable
+ * @author LayerZero Labs
+ * @custom:version 1.0.0
+ * @notice Abstract upgradeable contract implementing the IOAppOptionsType3 interface with RBAC access control.
+ * @dev Exposes public management functions through `AccessControl2StepUpgradeable`.
+ */
+abstract contract OAppOptionsType3RBACUpgradeable is OAppOptionsType3BaseUpgradeable, AccessControl2StepUpgradeable {
+    /**
+     * @notice Initializes the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __OAppOptionsType3RBAC_init() internal onlyInitializing {}
+
+    /**
+     * @notice Unchained initialization function for the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __OAppOptionsType3RBAC_init_unchained() internal onlyInitializing {}
+
+    /**
+     * @inheritdoc IOAppOptionsType3
+     */
+    function setEnforcedOptions(
+        IOAppOptionsType3.EnforcedOptionParam[] calldata _enforcedOptions
+    ) public virtual onlyRole(DEFAULT_ADMIN_ROLE) {
+        _setEnforcedOptions(_enforcedOptions);
+    }
+}

package/foundry.toml

@@ -0,0 +1,20 @@
+[profile.default]
+solc = '0.8.22'
+verbosity = 3
+src = "contracts"
+test = "test"
+out = "artifacts"
+cache_path = "cache"
+libs = ['node_modules', 'node_modules/@layerzerolabs/toolbox-foundry/lib']
+optimizer = true
+optimizer_runs = 200
+
+remappings = [
+    'ds-test/=node_modules/@layerzerolabs/toolbox-foundry/lib/ds-test/',
+    'forge-std/=node_modules/@layerzerolabs/toolbox-foundry/lib/forge-std/',
+    '@openzeppelin/=node_modules/@openzeppelin/',
+    '@layerzerolabs/=node_modules/@layerzerolabs/',
+]
+
+[fuzz]
+runs = 1000