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

package/contracts/uln/ReceiveUlnBase.sol

@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: LZBL-1.2
+
+pragma solidity ^0.8.20;
+
+import { PacketV1Codec } from "@layerzerolabs/lz-evm-protocol-v2/contracts/messagelib/libs/PacketV1Codec.sol";
+
+import { UlnBase, UlnConfig } from "./UlnBase.sol";
+
+struct Verification {
+    bool submitted;
+    uint64 confirmations;
+}
+
+/// @dev includes the utility functions for checking ULN states and logics
+abstract contract ReceiveUlnBase is UlnBase {
+    using PacketV1Codec for bytes;
+
+    mapping(bytes32 headerHash => mapping(bytes32 payloadHash => mapping(address dvn => Verification)))
+        public hashLookup;
+
+    event PayloadVerified(address dvn, bytes header, uint256 confirmations, bytes32 proofHash);
+
+    error LZ_ULN_InvalidPacketHeader();
+    error LZ_ULN_InvalidPacketVersion();
+    error LZ_ULN_InvalidEid();
+    error LZ_ULN_Verifying();
+
+    // ============================ External ===================================
+    function verifiable(
+        UlnConfig memory _config,
+        bytes32 _headerHash,
+        bytes32 _payloadHash
+    ) external view returns (bool) {
+        return _checkVerifiable(_config, _headerHash, _payloadHash);
+    }
+
+    function assertHeader(bytes calldata _packetHeader, uint32 _localEid) external pure {
+        _assertHeader(_packetHeader, _localEid);
+    }
+
+    // ============================ Internal ===================================
+    /// @dev per DVN signing function
+    function _verify(bytes calldata _packetHeader, bytes32 _payloadHash, uint64 _confirmations) internal {
+        hashLookup[keccak256(_packetHeader)][_payloadHash][msg.sender] = Verification(true, _confirmations);
+        emit PayloadVerified(msg.sender, _packetHeader, _confirmations, _payloadHash);
+    }
+
+    function _verified(
+        address _dvn,
+        bytes32 _headerHash,
+        bytes32 _payloadHash,
+        uint64 _requiredConfirmation
+    ) internal view returns (bool verified) {
+        Verification memory verification = hashLookup[_headerHash][_payloadHash][_dvn];
+        // return true if the dvn has signed enough confirmations
+        verified = verification.submitted && verification.confirmations >= _requiredConfirmation;
+    }
+
+    function _verifyAndReclaimStorage(UlnConfig memory _config, bytes32 _headerHash, bytes32 _payloadHash) internal {
+        if (!_checkVerifiable(_config, _headerHash, _payloadHash)) {
+            revert LZ_ULN_Verifying();
+        }
+
+        // iterate the required DVNs
+        if (_config.requiredDVNCount > 0) {
+            for (uint8 i = 0; i < _config.requiredDVNCount; ++i) {
+                delete hashLookup[_headerHash][_payloadHash][_config.requiredDVNs[i]];
+            }
+        }
+
+        // iterate the optional DVNs
+        if (_config.optionalDVNCount > 0) {
+            for (uint8 i = 0; i < _config.optionalDVNCount; ++i) {
+                delete hashLookup[_headerHash][_payloadHash][_config.optionalDVNs[i]];
+            }
+        }
+    }
+
+    function _assertHeader(bytes calldata _packetHeader, uint32 _localEid) internal pure {
+        // assert packet header is of right size 81
+        if (_packetHeader.length != 81) revert LZ_ULN_InvalidPacketHeader();
+        // assert packet header version is the same as ULN
+        if (_packetHeader.version() != PacketV1Codec.PACKET_VERSION) revert LZ_ULN_InvalidPacketVersion();
+        // assert the packet is for this endpoint
+        if (_packetHeader.dstEid() != _localEid) revert LZ_ULN_InvalidEid();
+    }
+
+    /// @dev for verifiable view function
+    /// @dev checks if this verification is ready to be committed to the endpoint
+    function _checkVerifiable(
+        UlnConfig memory _config,
+        bytes32 _headerHash,
+        bytes32 _payloadHash
+    ) internal view returns (bool) {
+        // iterate the required DVNs
+        if (_config.requiredDVNCount > 0) {
+            for (uint8 i = 0; i < _config.requiredDVNCount; ++i) {
+                if (!_verified(_config.requiredDVNs[i], _headerHash, _payloadHash, _config.confirmations)) {
+                    // return if any of the required DVNs haven't signed
+                    return false;
+                }
+            }
+            if (_config.optionalDVNCount == 0) {
+                // returns early if all required DVNs have signed and there are no optional DVNs
+                return true;
+            }
+        }
+
+        // then it must require optional validations
+        uint8 threshold = _config.optionalDVNThreshold;
+        for (uint8 i = 0; i < _config.optionalDVNCount; ++i) {
+            if (_verified(_config.optionalDVNs[i], _headerHash, _payloadHash, _config.confirmations)) {
+                // increment the optional count if the optional DVN has signed
+                threshold--;
+                if (threshold == 0) {
+                    // early return if the optional threshold has hit
+                    return true;
+                }
+            }
+        }
+
+        // return false as a catch-all
+        return false;
+    }
+}

package/contracts/uln/SendUlnBase.sol

@@ -0,0 +1,129 @@
+// SPDX-License-Identifier: LZBL-1.2
+
+pragma solidity ^0.8.20;
+
+import { Packet } from "@layerzerolabs/lz-evm-protocol-v2/contracts/interfaces/ISendLib.sol";
+import { PacketV1Codec } from "@layerzerolabs/lz-evm-protocol-v2/contracts/messagelib/libs/PacketV1Codec.sol";
+
+import { ILayerZeroDVN } from "./interfaces/ILayerZeroDVN.sol";
+import { DVNOptions } from "./libs/DVNOptions.sol";
+import { UlnOptions } from "./libs/UlnOptions.sol";
+import { WorkerOptions } from "../SendLibBase.sol";
+import { UlnConfig, UlnBase } from "./UlnBase.sol";
+
+/// @dev includes the utility functions for checking ULN states and logics
+abstract contract SendUlnBase is UlnBase {
+    event DVNFeePaid(address[] requiredDVNs, address[] optionalDVNs, uint256[] fees);
+
+    function _splitUlnOptions(bytes calldata _options) internal pure returns (bytes memory, WorkerOptions[] memory) {
+        (bytes memory executorOpts, bytes memory dvnOpts) = UlnOptions.decode(_options);
+
+        if (dvnOpts.length == 0) {
+            return (executorOpts, new WorkerOptions[](0));
+        }
+
+        WorkerOptions[] memory workerOpts = new WorkerOptions[](1);
+        workerOpts[0] = WorkerOptions(DVNOptions.WORKER_ID, dvnOpts);
+        return (executorOpts, workerOpts);
+    }
+
+    /// ---------- pay and assign jobs ----------
+
+    function _payDVNs(
+        mapping(address => uint256) storage _fees,
+        Packet memory _packet,
+        WorkerOptions[] memory _options
+    ) internal returns (uint256 totalFee, bytes memory encodedPacket) {
+        bytes memory packetHeader = PacketV1Codec.encodePacketHeader(_packet);
+        bytes memory payload = PacketV1Codec.encodePayload(_packet);
+        bytes32 payloadHash = keccak256(payload);
+        uint32 dstEid = _packet.dstEid;
+        address sender = _packet.sender;
+        UlnConfig memory config = getUlnConfig(sender, dstEid);
+
+        // if options is not empty, it must be dvn options
+        bytes memory dvnOptions = _options.length == 0 ? bytes("") : _options[0].options;
+        uint256[] memory dvnFees;
+        (totalFee, dvnFees) = _assignJobs(
+            _fees,
+            config,
+            ILayerZeroDVN.AssignJobParam(dstEid, packetHeader, payloadHash, config.confirmations, sender),
+            dvnOptions
+        );
+        encodedPacket = abi.encodePacked(packetHeader, payload);
+
+        emit DVNFeePaid(config.requiredDVNs, config.optionalDVNs, dvnFees);
+    }
+
+    function _assignJobs(
+        mapping(address => uint256) storage _fees,
+        UlnConfig memory _ulnConfig,
+        ILayerZeroDVN.AssignJobParam memory _param,
+        bytes memory dvnOptions
+    ) internal returns (uint256 totalFee, uint256[] memory dvnFees) {
+        (bytes[] memory optionsArray, uint8[] memory dvnIds) = DVNOptions.groupDVNOptionsByIdx(dvnOptions);
+
+        uint8 dvnsLength = _ulnConfig.requiredDVNCount + _ulnConfig.optionalDVNCount;
+        dvnFees = new uint256[](dvnsLength);
+        for (uint8 i = 0; i < dvnsLength; ++i) {
+            address dvn = i < _ulnConfig.requiredDVNCount
+                ? _ulnConfig.requiredDVNs[i]
+                : _ulnConfig.optionalDVNs[i - _ulnConfig.requiredDVNCount];
+
+            bytes memory options = "";
+            for (uint256 j = 0; j < dvnIds.length; ++j) {
+                if (dvnIds[j] == i) {
+                    options = optionsArray[j];
+                    break;
+                }
+            }
+
+            dvnFees[i] = ILayerZeroDVN(dvn).assignJob(_param, options);
+            if (dvnFees[i] > 0) {
+                _fees[dvn] += dvnFees[i];
+                totalFee += dvnFees[i];
+            }
+        }
+    }
+
+    /// ---------- quote ----------
+    function _quoteDVNs(
+        address _sender,
+        uint32 _dstEid,
+        WorkerOptions[] memory _options
+    ) internal view returns (uint256 totalFee) {
+        UlnConfig memory config = getUlnConfig(_sender, _dstEid);
+
+        // if options is not empty, it must be dvn options
+        bytes memory dvnOptions = _options.length == 0 ? bytes("") : _options[0].options;
+        (bytes[] memory optionsArray, uint8[] memory dvnIndices) = DVNOptions.groupDVNOptionsByIdx(dvnOptions);
+
+        totalFee = _getFees(config, _dstEid, _sender, optionsArray, dvnIndices);
+    }
+
+    function _getFees(
+        UlnConfig memory _config,
+        uint32 _dstEid,
+        address _sender,
+        bytes[] memory _optionsArray,
+        uint8[] memory _dvnIds
+    ) internal view returns (uint256 totalFee) {
+        // here we merge 2 list of dvns into 1 to allocate the indexed dvn options to the right dvn
+        uint8 dvnsLength = _config.requiredDVNCount + _config.optionalDVNCount;
+        for (uint8 i = 0; i < dvnsLength; ++i) {
+            address dvn = i < _config.requiredDVNCount
+                ? _config.requiredDVNs[i]
+                : _config.optionalDVNs[i - _config.requiredDVNCount];
+
+            bytes memory options = "";
+            // it is a double loop here. however, if the list is short, the cost is very acceptable.
+            for (uint256 j = 0; j < _dvnIds.length; ++j) {
+                if (_dvnIds[j] == i) {
+                    options = _optionsArray[j];
+                    break;
+                }
+            }
+            totalFee += ILayerZeroDVN(dvn).getFee(_dstEid, _config.confirmations, _sender, options);
+        }
+    }
+}

package/contracts/uln/UlnBase.sol

@@ -0,0 +1,195 @@
+// SPDX-License-Identifier: LZBL-1.2
+
+pragma solidity ^0.8.20;
+
+import { Ownable } from "@openzeppelin/contracts/access/Ownable.sol";
+
+// the formal properties are documented in the setter functions
+struct UlnConfig {
+    uint64 confirmations;
+    // we store the length of required DVNs and optional DVNs instead of using DVN.length directly to save gas
+    uint8 requiredDVNCount; // 0 indicate DEFAULT, NIL_DVN_COUNT indicate NONE (to override the value of default)
+    uint8 optionalDVNCount; // 0 indicate DEFAULT, NIL_DVN_COUNT indicate NONE (to override the value of default)
+    uint8 optionalDVNThreshold; // (0, optionalDVNCount]
+    address[] requiredDVNs; // no duplicates. sorted an an ascending order. allowed overlap with optionalDVNs
+    address[] optionalDVNs; // no duplicates. sorted an an ascending order. allowed overlap with requiredDVNs
+}
+
+struct SetDefaultUlnConfigParam {
+    uint32 eid;
+    UlnConfig config;
+}
+
+/// @dev includes the utility functions for checking ULN states and logics
+abstract contract UlnBase is Ownable {
+    address private constant DEFAULT_CONFIG = address(0);
+    // reserved values for
+    uint8 internal constant DEFAULT = 0;
+    uint8 internal constant NIL_DVN_COUNT = type(uint8).max;
+    uint64 internal constant NIL_CONFIRMATIONS = type(uint64).max;
+    // 127 to prevent total number of DVNs (127 * 2) exceeding uint8.max (255)
+    // by limiting the total size, it would help constraint the design of DVNOptions
+    uint8 private constant MAX_COUNT = (type(uint8).max - 1) / 2;
+
+    mapping(address oapp => mapping(uint32 eid => UlnConfig)) internal ulnConfigs;
+
+    error LZ_ULN_Unsorted();
+    error LZ_ULN_InvalidRequiredDVNCount();
+    error LZ_ULN_InvalidOptionalDVNCount();
+    error LZ_ULN_AtLeastOneDVN();
+    error LZ_ULN_InvalidOptionalDVNThreshold();
+    error LZ_ULN_InvalidConfirmations();
+    error LZ_ULN_UnsupportedEid(uint32 eid);
+
+    event DefaultUlnConfigsSet(SetDefaultUlnConfigParam[] params);
+    event UlnConfigSet(address oapp, uint32 eid, UlnConfig config);
+
+    // ============================ OnlyOwner ===================================
+
+    /// @dev about the DEFAULT ULN config
+    /// 1) its values are all LITERAL (e.g. 0 is 0). whereas in the oapp ULN config, 0 (default value) points to the default ULN config
+    ///     this design enables the oapp to point to DEFAULT config without explicitly setting the config
+    /// 2) its configuration is more restrictive than the oapp ULN config that
+    ///     a) it must not use NIL value, where NIL is used only by oapps to indicate the LITERAL 0
+    ///     b) it must have at least one DVN
+    function setDefaultUlnConfigs(SetDefaultUlnConfigParam[] calldata _params) external onlyOwner {
+        for (uint256 i = 0; i < _params.length; ++i) {
+            SetDefaultUlnConfigParam calldata param = _params[i];
+
+            // 2.a must not use NIL
+            if (param.config.requiredDVNCount == NIL_DVN_COUNT) revert LZ_ULN_InvalidRequiredDVNCount();
+            if (param.config.optionalDVNCount == NIL_DVN_COUNT) revert LZ_ULN_InvalidOptionalDVNCount();
+            if (param.config.confirmations == NIL_CONFIRMATIONS) revert LZ_ULN_InvalidConfirmations();
+
+            // 2.b must have at least one dvn
+            _assertAtLeastOneDVN(param.config);
+
+            _setConfig(DEFAULT_CONFIG, param.eid, param.config);
+        }
+        emit DefaultUlnConfigsSet(_params);
+    }
+
+    // ============================ View ===================================
+    // @dev assuming most oapps use default, we get default as memory and custom as storage to save gas
+    function getUlnConfig(address _oapp, uint32 _remoteEid) public view returns (UlnConfig memory rtnConfig) {
+        UlnConfig storage defaultConfig = ulnConfigs[DEFAULT_CONFIG][_remoteEid];
+        UlnConfig storage customConfig = ulnConfigs[_oapp][_remoteEid];
+
+        // if confirmations is 0, use default
+        uint64 confirmations = customConfig.confirmations;
+        if (confirmations == DEFAULT) {
+            rtnConfig.confirmations = defaultConfig.confirmations;
+        } else if (confirmations != NIL_CONFIRMATIONS) {
+            // if confirmations is uint64.max, no block confirmations required
+            rtnConfig.confirmations = confirmations;
+        } // else do nothing, rtnConfig.confirmation is 0
+
+        if (customConfig.requiredDVNCount == DEFAULT) {
+            if (defaultConfig.requiredDVNCount > 0) {
+                // copy only if count > 0. save gas
+                rtnConfig.requiredDVNs = defaultConfig.requiredDVNs;
+                rtnConfig.requiredDVNCount = defaultConfig.requiredDVNCount;
+            } // else, do nothing
+        } else {
+            if (customConfig.requiredDVNCount != NIL_DVN_COUNT) {
+                rtnConfig.requiredDVNs = customConfig.requiredDVNs;
+                rtnConfig.requiredDVNCount = customConfig.requiredDVNCount;
+            } // else, do nothing
+        }
+
+        if (customConfig.optionalDVNCount == DEFAULT) {
+            if (defaultConfig.optionalDVNCount > 0) {
+                // copy only if count > 0. save gas
+                rtnConfig.optionalDVNs = defaultConfig.optionalDVNs;
+                rtnConfig.optionalDVNCount = defaultConfig.optionalDVNCount;
+                rtnConfig.optionalDVNThreshold = defaultConfig.optionalDVNThreshold;
+            }
+        } else {
+            if (customConfig.optionalDVNCount != NIL_DVN_COUNT) {
+                rtnConfig.optionalDVNs = customConfig.optionalDVNs;
+                rtnConfig.optionalDVNCount = customConfig.optionalDVNCount;
+                rtnConfig.optionalDVNThreshold = customConfig.optionalDVNThreshold;
+            }
+        }
+
+        // the final value must have at least one dvn
+        // it is possible that some default config result into 0 dvns
+        _assertAtLeastOneDVN(rtnConfig);
+    }
+
+    /// @dev Get the uln config without the default config for the given remoteEid.
+    function getAppUlnConfig(address _oapp, uint32 _remoteEid) external view returns (UlnConfig memory) {
+        return ulnConfigs[_oapp][_remoteEid];
+    }
+
+    // ============================ Internal ===================================
+    function _setUlnConfig(uint32 _remoteEid, address _oapp, UlnConfig memory _param) internal {
+        _setConfig(_oapp, _remoteEid, _param);
+
+        // get ULN config again as a catch all to ensure the config is valid
+        getUlnConfig(_oapp, _remoteEid);
+        emit UlnConfigSet(_oapp, _remoteEid, _param);
+    }
+
+    /// @dev a supported Eid must have a valid default uln config, which has at least one dvn
+    function _isSupportedEid(uint32 _remoteEid) internal view returns (bool) {
+        UlnConfig storage defaultConfig = ulnConfigs[DEFAULT_CONFIG][_remoteEid];
+        return defaultConfig.requiredDVNCount > 0 || defaultConfig.optionalDVNThreshold > 0;
+    }
+
+    function _assertSupportedEid(uint32 _remoteEid) internal view {
+        if (!_isSupportedEid(_remoteEid)) revert LZ_ULN_UnsupportedEid(_remoteEid);
+    }
+
+    // ============================ Private ===================================
+
+    function _assertAtLeastOneDVN(UlnConfig memory _config) private pure {
+        if (_config.requiredDVNCount == 0 && _config.optionalDVNThreshold == 0) revert LZ_ULN_AtLeastOneDVN();
+    }
+
+    /// @dev this private function is used in both setDefaultUlnConfigs and setUlnConfig
+    function _setConfig(address _oapp, uint32 _eid, UlnConfig memory _param) private {
+        // @dev required dvns
+        // if dvnCount == NONE, dvns list must be empty
+        // if dvnCount == DEFAULT, dvn list must be empty
+        // otherwise, dvnList.length == dvnCount and assert the list is valid
+        if (_param.requiredDVNCount == NIL_DVN_COUNT || _param.requiredDVNCount == DEFAULT) {
+            if (_param.requiredDVNs.length != 0) revert LZ_ULN_InvalidRequiredDVNCount();
+        } else {
+            if (_param.requiredDVNs.length != _param.requiredDVNCount || _param.requiredDVNCount > MAX_COUNT)
+                revert LZ_ULN_InvalidRequiredDVNCount();
+            _assertNoDuplicates(_param.requiredDVNs);
+        }
+
+        // @dev optional dvns
+        // if optionalDVNCount == NONE, optionalDVNs list must be empty and threshold must be 0
+        // if optionalDVNCount == DEFAULT, optionalDVNs list must be empty and threshold must be 0
+        // otherwise, optionalDVNs.length == optionalDVNCount, threshold > 0 && threshold <= optionalDVNCount and assert the list is valid
+
+        // example use case: an oapp uses the DEFAULT 'required' but
+        //     a) use a custom 1/1 dvn (practically a required dvn), or
+        //     b) use a custom 2/3 dvn
+        if (_param.optionalDVNCount == NIL_DVN_COUNT || _param.optionalDVNCount == DEFAULT) {
+            if (_param.optionalDVNs.length != 0) revert LZ_ULN_InvalidOptionalDVNCount();
+            if (_param.optionalDVNThreshold != 0) revert LZ_ULN_InvalidOptionalDVNThreshold();
+        } else {
+            if (_param.optionalDVNs.length != _param.optionalDVNCount || _param.optionalDVNCount > MAX_COUNT)
+                revert LZ_ULN_InvalidOptionalDVNCount();
+            if (_param.optionalDVNThreshold == 0 || _param.optionalDVNThreshold > _param.optionalDVNCount)
+                revert LZ_ULN_InvalidOptionalDVNThreshold();
+            _assertNoDuplicates(_param.optionalDVNs);
+        }
+        // don't assert valid count here, as it needs to be validated along side default config
+
+        ulnConfigs[_oapp][_eid] = _param;
+    }
+
+    function _assertNoDuplicates(address[] memory _dvns) private pure {
+        address lastDVN = address(0);
+        for (uint256 i = 0; i < _dvns.length; i++) {
+            address dvn = _dvns[i];
+            if (dvn <= lastDVN) revert LZ_ULN_Unsorted(); // to ensure no duplicates
+            lastDVN = dvn;
+        }
+    }
+}