@layerzerolabs/protocol-v2-oapp-evm-contracts 1.2.95

package/contracts/oapp/libs/OAppOptionsType3.sol

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.20;
+
+import { Ownable } from "@openzeppelin/contracts/access/Ownable.sol";
+import { IOAppOptionsType3, EnforcedOptionParam } from "../interfaces/IOAppOptionsType3.sol";
+
+/**
+ * @title OAppOptionsType3
+ * @dev Abstract contract implementing the IOAppOptionsType3 interface with type 3 options.
+ */
+abstract contract OAppOptionsType3 is IOAppOptionsType3, Ownable {
+    uint16 internal constant OPTION_TYPE_3 = 3;
+
+    // @dev The "msgType" should be defined in the child contract.
+    mapping(uint32 eid => mapping(uint16 msgType => bytes enforcedOption)) public enforcedOptions;
+
+    /**
+     * @dev Sets the enforced options for specific endpoint and message type combinations.
+     * @param _enforcedOptions An array of EnforcedOptionParam structures specifying enforced options.
+     *
+     * @dev Only the owner/admin of the OApp can call this function.
+     * @dev Provides a way for the OApp to enforce things like paying for PreCrime, AND/OR minimum dst lzReceive gas amounts etc.
+     * @dev These enforced options can vary as the potential options/execution on the remote may differ as per the msgType.
+     * eg. Amount of lzReceive() gas necessary to deliver a lzCompose() message adds overhead you dont want to pay
+     * if you are only making a standard LayerZero message ie. lzReceive() WITHOUT sendCompose().
+     */
+    function setEnforcedOptions(EnforcedOptionParam[] calldata _enforcedOptions) public virtual onlyOwner {
+        _setEnforcedOptions(_enforcedOptions);
+    }
+
+    /**
+     * @dev Sets the enforced options for specific endpoint and message type combinations.
+     * @param _enforcedOptions An array of EnforcedOptionParam structures specifying enforced options.
+     *
+     * @dev Provides a way for the OApp to enforce things like paying for PreCrime, AND/OR minimum dst lzReceive gas amounts etc.
+     * @dev These enforced options can vary as the potential options/execution on the remote may differ as per the msgType.
+     * eg. Amount of lzReceive() gas necessary to deliver a lzCompose() message adds overhead you dont want to pay
+     * if you are only making a standard LayerZero message ie. lzReceive() WITHOUT sendCompose().
+     */
+    function _setEnforcedOptions(EnforcedOptionParam[] memory _enforcedOptions) internal virtual {
+        for (uint256 i = 0; i < _enforcedOptions.length; i++) {
+            // @dev Enforced options are only available for optionType 3, as type 1 and 2 dont support combining.
+            _assertOptionsType3(_enforcedOptions[i].options);
+            enforcedOptions[_enforcedOptions[i].eid][_enforcedOptions[i].msgType] = _enforcedOptions[i].options;
+        }
+
+        emit EnforcedOptionSet(_enforcedOptions);
+    }
+
+    /**
+     * @notice Combines options for a given endpoint and message type.
+     * @param _eid The endpoint ID.
+     * @param _msgType The OAPP message type.
+     * @param _extraOptions Additional options passed by the caller.
+     * @return options The combination of caller specified options AND enforced options.
+     *
+     * @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 This presence of duplicated options is handled off-chain in the verifier/executor.
+     */
+    function combineOptions(
+        uint32 _eid,
+        uint16 _msgType,
+        bytes calldata _extraOptions
+    ) public view virtual returns (bytes memory) {
+        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, must be type 3 as its 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 The 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);
+    }
+}

package/contracts/oapp/libs/OptionsBuilder.sol

@@ -0,0 +1,218 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.20;
+
+import { BytesLib } from "solidity-bytes-utils/contracts/BytesLib.sol";
+import { SafeCast } from "@openzeppelin/contracts/utils/math/SafeCast.sol";
+
+import { ExecutorOptions } from "@layerzerolabs/lz-evm-messagelib-v2/contracts/libs/ExecutorOptions.sol";
+import { DVNOptions } from "@layerzerolabs/lz-evm-messagelib-v2/contracts/uln/libs/DVNOptions.sol";
+
+/**
+ * @title OptionsBuilder
+ * @dev Library for building and encoding various message options.
+ */
+library OptionsBuilder {
+    using SafeCast for uint256;
+    using BytesLib for bytes;
+
+    // Constants for options types
+    uint16 internal constant TYPE_1 = 1; // legacy options type 1
+    uint16 internal constant TYPE_2 = 2; // legacy options type 2
+    uint16 internal constant TYPE_3 = 3;
+
+    // Custom error message
+    error InvalidSize(uint256 max, uint256 actual);
+    error InvalidOptionType(uint16 optionType);
+
+    // Modifier to ensure only options of type 3 are used
+    modifier onlyType3(bytes memory _options) {
+        if (_options.toUint16(0) != TYPE_3) revert InvalidOptionType(_options.toUint16(0));
+        _;
+    }
+
+    /**
+     * @dev Creates a new options container with type 3.
+     * @return options The newly created options container.
+     */
+    function newOptions() internal pure returns (bytes memory) {
+        return abi.encodePacked(TYPE_3);
+    }
+
+    /**
+     * @dev Adds an executor LZ receive option to the existing options.
+     * @param _options The existing options container.
+     * @param _gas The gasLimit used on the lzReceive() function in the OApp.
+     * @param _value The msg.value passed to the lzReceive() function in the OApp.
+     * @return options The updated options container.
+     *
+     * @dev When multiples of this option are added, they are summed by the executor
+     * eg. if (_gas: 200k, and _value: 1 ether) AND (_gas: 100k, _value: 0.5 ether) are sent in an option to the LayerZeroEndpoint,
+     * that becomes (300k, 1.5 ether) when the message is executed on the remote lzReceive() function.
+     */
+    function addExecutorLzReceiveOption(
+        bytes memory _options,
+        uint128 _gas,
+        uint128 _value
+    ) internal pure onlyType3(_options) returns (bytes memory) {
+        bytes memory option = ExecutorOptions.encodeLzReceiveOption(_gas, _value);
+        return addExecutorOption(_options, ExecutorOptions.OPTION_TYPE_LZRECEIVE, option);
+    }
+
+    /**
+     * @dev Adds an executor LZ read option to the existing options.
+     * @param _options The existing options container.
+     * @param _gas The gas limit used for the lzReceive() function in the ReadOApp.
+     * @param _calldataSize The size of the payload for lzReceive() function in the ReadOApp.
+     * @param _value The msg.value passed to the lzReceive() function in the ReadOApp.
+     * @return options The updated options container.
+     */
+    function addExecutorLzReadOption(
+        bytes memory _options,
+        uint128 _gas,
+        uint32 _calldataSize,
+        uint128 _value
+    ) internal pure onlyType3(_options) returns (bytes memory) {
+        bytes memory option = ExecutorOptions.encodeLzReadOption(_gas, _calldataSize, _value);
+        return addExecutorOption(_options, ExecutorOptions.OPTION_TYPE_LZREAD, option);
+    }
+
+    /**
+     * @dev Adds an executor native drop option to the existing options.
+     * @param _options The existing options container.
+     * @param _amount The amount for the native value that is airdropped to the 'receiver'.
+     * @param _receiver The receiver address for the native drop option.
+     * @return options The updated options container.
+     *
+     * @dev When multiples of this option are added, they are summed by the executor on the remote chain.
+     */
+    function addExecutorNativeDropOption(
+        bytes memory _options,
+        uint128 _amount,
+        bytes32 _receiver
+    ) internal pure onlyType3(_options) returns (bytes memory) {
+        bytes memory option = ExecutorOptions.encodeNativeDropOption(_amount, _receiver);
+        return addExecutorOption(_options, ExecutorOptions.OPTION_TYPE_NATIVE_DROP, option);
+    }
+
+    /**
+     * @dev Adds an executor LZ compose option to the existing options.
+     * @param _options The existing options container.
+     * @param _index The index for the lzCompose() function call.
+     * @param _gas The gasLimit for the lzCompose() function call.
+     * @param _value The msg.value for the lzCompose() function call.
+     * @return options The updated options container.
+     *
+     * @dev When multiples of this option are added, they are summed PER index by the executor on the remote chain.
+     * @dev If the OApp sends N lzCompose calls on the remote, you must provide N incremented indexes starting with 0.
+     * ie. When your remote OApp composes (N = 3) messages, you must set this option for index 0,1,2
+     */
+    function addExecutorLzComposeOption(
+        bytes memory _options,
+        uint16 _index,
+        uint128 _gas,
+        uint128 _value
+    ) internal pure onlyType3(_options) returns (bytes memory) {
+        bytes memory option = ExecutorOptions.encodeLzComposeOption(_index, _gas, _value);
+        return addExecutorOption(_options, ExecutorOptions.OPTION_TYPE_LZCOMPOSE, option);
+    }
+
+    /**
+     * @dev Adds an executor ordered execution option to the existing options.
+     * @param _options The existing options container.
+     * @return options The updated options container.
+     */
+    function addExecutorOrderedExecutionOption(
+        bytes memory _options
+    ) internal pure onlyType3(_options) returns (bytes memory) {
+        return addExecutorOption(_options, ExecutorOptions.OPTION_TYPE_ORDERED_EXECUTION, bytes(""));
+    }
+
+    /**
+     * @dev Adds a DVN pre-crime option to the existing options.
+     * @param _options The existing options container.
+     * @param _dvnIdx The DVN index for the pre-crime option.
+     * @return options The updated options container.
+     */
+    function addDVNPreCrimeOption(
+        bytes memory _options,
+        uint8 _dvnIdx
+    ) internal pure onlyType3(_options) returns (bytes memory) {
+        return addDVNOption(_options, _dvnIdx, DVNOptions.OPTION_TYPE_PRECRIME, bytes(""));
+    }
+
+    /**
+     * @dev Adds an executor option to the existing options.
+     * @param _options The existing options container.
+     * @param _optionType The type of the executor option.
+     * @param _option The encoded data for the executor option.
+     * @return options The updated options container.
+     */
+    function addExecutorOption(
+        bytes memory _options,
+        uint8 _optionType,
+        bytes memory _option
+    ) internal pure onlyType3(_options) returns (bytes memory) {
+        return
+            abi.encodePacked(
+                _options,
+                ExecutorOptions.WORKER_ID,
+                _option.length.toUint16() + 1, // +1 for optionType
+                _optionType,
+                _option
+            );
+    }
+
+    /**
+     * @dev Adds a DVN option to the existing options.
+     * @param _options The existing options container.
+     * @param _dvnIdx The DVN index for the DVN option.
+     * @param _optionType The type of the DVN option.
+     * @param _option The encoded data for the DVN option.
+     * @return options The updated options container.
+     */
+    function addDVNOption(
+        bytes memory _options,
+        uint8 _dvnIdx,
+        uint8 _optionType,
+        bytes memory _option
+    ) internal pure onlyType3(_options) returns (bytes memory) {
+        return
+            abi.encodePacked(
+                _options,
+                DVNOptions.WORKER_ID,
+                _option.length.toUint16() + 2, // +2 for optionType and dvnIdx
+                _dvnIdx,
+                _optionType,
+                _option
+            );
+    }
+
+    /**
+     * @dev Encodes legacy options of type 1.
+     * @param _executionGas The gasLimit value passed to lzReceive().
+     * @return legacyOptions The encoded legacy options.
+     */
+    function encodeLegacyOptionsType1(uint256 _executionGas) internal pure returns (bytes memory) {
+        if (_executionGas > type(uint128).max) revert InvalidSize(type(uint128).max, _executionGas);
+        return abi.encodePacked(TYPE_1, _executionGas);
+    }
+
+    /**
+     * @dev Encodes legacy options of type 2.
+     * @param _executionGas The gasLimit value passed to lzReceive().
+     * @param _nativeForDst The amount of native air dropped to the receiver.
+     * @param _receiver The _nativeForDst receiver address.
+     * @return legacyOptions The encoded legacy options of type 2.
+     */
+    function encodeLegacyOptionsType2(
+        uint256 _executionGas,
+        uint256 _nativeForDst,
+        bytes memory _receiver // @dev Use bytes instead of bytes32 in legacy type 2 for _receiver.
+    ) internal pure returns (bytes memory) {
+        if (_executionGas > type(uint128).max) revert InvalidSize(type(uint128).max, _executionGas);
+        if (_nativeForDst > type(uint128).max) revert InvalidSize(type(uint128).max, _nativeForDst);
+        if (_receiver.length > 32) revert InvalidSize(32, _receiver.length);
+        return abi.encodePacked(TYPE_2, _executionGas, _nativeForDst, _receiver);
+    }
+}

package/contracts/oapp/libs/ReadCmdCodecV1.sol

@@ -0,0 +1,231 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.20;
+
+import { SafeCast } from "@openzeppelin/contracts/utils/math/SafeCast.sol";
+
+struct EVMCallRequestV1 {
+    uint16 appRequestLabel; // Label identifying the application or type of request (can be use in lzCompute)
+    uint32 targetEid; // Target endpoint ID (representing a target blockchain)
+    bool isBlockNum; // True if the request = block number, false if timestamp
+    uint64 blockNumOrTimestamp; // Block number or timestamp to use in the request
+    uint16 confirmations; // Number of block confirmations on top of the requested block number or timestamp before the view function can be called
+    address to; // Address of the target contract on the target chain
+    bytes callData; // Calldata for the contract call
+}
+
+struct EVMCallComputeV1 {
+    uint8 computeSetting; // Compute setting (0 = map only, 1 = reduce only, 2 = map reduce)
+    uint32 targetEid; // Target endpoint ID (representing a target blockchain)
+    bool isBlockNum; // True if the request = block number, false if timestamp
+    uint64 blockNumOrTimestamp; // Block number or timestamp to use in the request
+    uint16 confirmations; // Number of block confirmations on top of the requested block number or timestamp before the view function can be called
+    address to; // Address of the target contract on the target chain
+}
+
+library ReadCmdCodecV1 {
+    using SafeCast for uint256;
+
+    uint16 internal constant CMD_VERSION = 1;
+
+    uint8 internal constant REQUEST_VERSION = 1;
+    uint16 internal constant RESOLVER_TYPE_SINGLE_VIEW_EVM_CALL = 1;
+
+    uint8 internal constant COMPUTE_VERSION = 1;
+    uint16 internal constant COMPUTE_TYPE_SINGLE_VIEW_EVM_CALL = 1;
+
+    error InvalidVersion();
+    error InvalidType();
+
+    function decode(
+        bytes calldata _cmd
+    )
+        internal
+        pure
+        returns (uint16 appCmdLabel, EVMCallRequestV1[] memory evmCallRequests, EVMCallComputeV1 memory compute)
+    {
+        uint256 offset = 0;
+        uint16 cmdVersion = uint16(bytes2(_cmd[offset:offset + 2]));
+        offset += 2;
+        if (cmdVersion != CMD_VERSION) revert InvalidVersion();
+
+        appCmdLabel = uint16(bytes2(_cmd[offset:offset + 2]));
+        offset += 2;
+
+        (evmCallRequests, offset) = decodeRequestsV1(_cmd, offset);
+
+        // decode the compute if it exists
+        if (offset < _cmd.length) {
+            (compute, ) = decodeEVMCallComputeV1(_cmd, offset);
+        }
+    }
+
+    function decodeRequestsV1(
+        bytes calldata _cmd,
+        uint256 _offset
+    ) internal pure returns (EVMCallRequestV1[] memory evmCallRequests, uint256 newOffset) {
+        newOffset = _offset;
+        uint16 requestCount = uint16(bytes2(_cmd[newOffset:newOffset + 2]));
+        newOffset += 2;
+
+        evmCallRequests = new EVMCallRequestV1[](requestCount);
+        for (uint16 i = 0; i < requestCount; i++) {
+            uint8 requestVersion = uint8(_cmd[newOffset]);
+            newOffset += 1;
+            if (requestVersion != REQUEST_VERSION) revert InvalidVersion();
+
+            uint16 appRequestLabel = uint16(bytes2(_cmd[newOffset:newOffset + 2]));
+            newOffset += 2;
+
+            uint16 resolverType = uint16(bytes2(_cmd[newOffset:newOffset + 2]));
+            newOffset += 2;
+
+            if (resolverType == RESOLVER_TYPE_SINGLE_VIEW_EVM_CALL) {
+                (EVMCallRequestV1 memory request, uint256 nextOffset) = decodeEVMCallRequestV1(
+                    _cmd,
+                    newOffset,
+                    appRequestLabel
+                );
+                newOffset = nextOffset;
+                evmCallRequests[i] = request;
+            } else {
+                revert InvalidType();
+            }
+        }
+    }
+
+    function decodeEVMCallRequestV1(
+        bytes calldata _cmd,
+        uint256 _offset,
+        uint16 _appRequestLabel
+    ) internal pure returns (EVMCallRequestV1 memory request, uint256 newOffset) {
+        newOffset = _offset;
+        request.appRequestLabel = _appRequestLabel;
+
+        uint16 requestSize = uint16(bytes2(_cmd[newOffset:newOffset + 2]));
+        newOffset += 2;
+        request.targetEid = uint32(bytes4(_cmd[newOffset:newOffset + 4]));
+        newOffset += 4;
+        request.isBlockNum = uint8(_cmd[newOffset]) == 1;
+        newOffset += 1;
+        request.blockNumOrTimestamp = uint64(bytes8(_cmd[newOffset:newOffset + 8]));
+        newOffset += 8;
+        request.confirmations = uint16(bytes2(_cmd[newOffset:newOffset + 2]));
+        newOffset += 2;
+        request.to = address(bytes20(_cmd[newOffset:newOffset + 20]));
+        newOffset += 20;
+        uint16 callDataSize = requestSize - 35;
+        request.callData = _cmd[newOffset:newOffset + callDataSize];
+        newOffset += callDataSize;
+    }
+
+    function decodeEVMCallComputeV1(
+        bytes calldata _cmd,
+        uint256 _offset
+    ) internal pure returns (EVMCallComputeV1 memory compute, uint256 newOffset) {
+        newOffset = _offset;
+        uint8 computeVersion = uint8(_cmd[newOffset]);
+        newOffset += 1;
+        if (computeVersion != COMPUTE_VERSION) revert InvalidVersion();
+        uint16 computeType = uint16(bytes2(_cmd[newOffset:newOffset + 2]));
+        newOffset += 2;
+        if (computeType != COMPUTE_TYPE_SINGLE_VIEW_EVM_CALL) revert InvalidType();
+
+        compute.computeSetting = uint8(_cmd[newOffset]);
+        newOffset += 1;
+        compute.targetEid = uint32(bytes4(_cmd[newOffset:newOffset + 4]));
+        newOffset += 4;
+        compute.isBlockNum = uint8(_cmd[newOffset]) == 1;
+        newOffset += 1;
+        compute.blockNumOrTimestamp = uint64(bytes8(_cmd[newOffset:newOffset + 8]));
+        newOffset += 8;
+        compute.confirmations = uint16(bytes2(_cmd[newOffset:newOffset + 2]));
+        newOffset += 2;
+        compute.to = address(bytes20(_cmd[newOffset:newOffset + 20]));
+        newOffset += 20;
+    }
+
+    function decodeCmdAppLabel(bytes calldata _cmd) internal pure returns (uint16) {
+        uint256 offset = 0;
+        uint16 cmdVersion = uint16(bytes2(_cmd[offset:offset + 2]));
+        offset += 2;
+        if (cmdVersion != CMD_VERSION) revert InvalidVersion();
+
+        return uint16(bytes2(_cmd[offset:offset + 2]));
+    }
+
+    function decodeRequestV1AppRequestLabel(bytes calldata _request) internal pure returns (uint16) {
+        uint256 offset = 0;
+        uint8 requestVersion = uint8(_request[offset]);
+        offset += 1;
+        if (requestVersion != REQUEST_VERSION) revert InvalidVersion();
+
+        return uint16(bytes2(_request[offset:offset + 2]));
+    }
+
+    function encode(
+        uint16 _appCmdLabel,
+        EVMCallRequestV1[] memory _evmCallRequests,
+        EVMCallComputeV1 memory _evmCallCompute
+    ) internal pure returns (bytes memory) {
+        bytes memory cmd = encode(_appCmdLabel, _evmCallRequests);
+        if (_evmCallCompute.targetEid != 0) {
+            // if eid is 0, it means no compute
+            cmd = appendEVMCallComputeV1(cmd, _evmCallCompute);
+        }
+        return cmd;
+    }
+
+    function encode(
+        uint16 _appCmdLabel,
+        EVMCallRequestV1[] memory _evmCallRequests
+    ) internal pure returns (bytes memory) {
+        bytes memory cmd = abi.encodePacked(CMD_VERSION, _appCmdLabel, _evmCallRequests.length.toUint16());
+        for (uint256 i = 0; i < _evmCallRequests.length; i++) {
+            cmd = appendEVMCallRequestV1(cmd, _evmCallRequests[i]);
+        }
+        return cmd;
+    }
+
+    // todo: optimize this with Buffer
+    function appendEVMCallRequestV1(
+        bytes memory _cmd,
+        EVMCallRequestV1 memory _request
+    ) internal pure returns (bytes memory) {
+        bytes memory newCmd = abi.encodePacked(
+            _cmd,
+            REQUEST_VERSION,
+            _request.appRequestLabel,
+            RESOLVER_TYPE_SINGLE_VIEW_EVM_CALL,
+            (_request.callData.length + 35).toUint16(),
+            _request.targetEid
+        );
+        return
+            abi.encodePacked(
+                newCmd,
+                _request.isBlockNum,
+                _request.blockNumOrTimestamp,
+                _request.confirmations,
+                _request.to,
+                _request.callData
+            );
+    }
+
+    function appendEVMCallComputeV1(
+        bytes memory _cmd,
+        EVMCallComputeV1 memory _compute
+    ) internal pure returns (bytes memory) {
+        return
+            abi.encodePacked(
+                _cmd,
+                COMPUTE_VERSION,
+                COMPUTE_TYPE_SINGLE_VIEW_EVM_CALL,
+                _compute.computeSetting,
+                _compute.targetEid,
+                _compute.isBlockNum,
+                _compute.blockNumOrTimestamp,
+                _compute.confirmations,
+                _compute.to
+            );
+    }
+}