@layerzerolabs/utils-upgradeable-evm-contracts 0.2.74

package/contracts/libs/EnumerableSetPagination.sol

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+import { EnumerableSet } from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
+
+/**
+ * @title EnumerableSetPagination
+ * @author LayerZero Labs (tinom.eth)
+ * @custom:version 1.0.0
+ * @notice Library providing pagination utilities for `EnumerableSet.AddressSet` and `EnumerableSet.UintSet`.
+ */
+library EnumerableSetPagination {
+    using EnumerableSet for EnumerableSet.AddressSet;
+    using EnumerableSet for EnumerableSet.UintSet;
+
+    /**
+     * @notice Returns a paginated subset of addresses from an `EnumerableSet`.
+     * @param _set `EnumerableSet.AddressSet` to paginate
+     * @param _offset Starting index
+     * @param _limit Maximum number of addresses to return
+     * @return addresses Array of addresses in the specified range
+     */
+    function paginate(
+        EnumerableSet.AddressSet storage _set,
+        uint256 _offset,
+        uint256 _limit
+    ) internal view returns (address[] memory addresses) {
+        uint256 total = _set.length();
+
+        if (_offset >= total) {
+            return new address[](0);
+        }
+
+        uint256 end = _offset + _limit;
+        if (end > total) {
+            end = total;
+        }
+
+        uint256 resultLength = end - _offset;
+        addresses = new address[](resultLength);
+
+        for (uint256 i = 0; i < resultLength; i++) {
+            addresses[i] = _set.at(_offset + i);
+        }
+    }
+
+    /**
+     * @notice Returns a paginated subset of `uint256` values from an `EnumerableSet`.
+     * @param _set `EnumerableSet.UintSet` to paginate
+     * @param _offset Starting index
+     * @param _limit Maximum number of values to return
+     * @return values Array of `uint256` values in the specified range
+     */
+    function paginate(
+        EnumerableSet.UintSet storage _set,
+        uint256 _offset,
+        uint256 _limit
+    ) internal view returns (uint256[] memory values) {
+        uint256 total = _set.length();
+
+        if (_offset >= total) {
+            return new uint256[](0);
+        }
+
+        uint256 end = _offset + _limit;
+        if (end > total) {
+            end = total;
+        }
+
+        uint256 resultLength = end - _offset;
+        values = new uint256[](resultLength);
+
+        for (uint256 i = 0; i < resultLength; i++) {
+            values[i] = _set.at(_offset + i);
+        }
+    }
+}

package/contracts/pause/PauseBaseUpgradeable.sol

@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+import { IPause } from "@layerzerolabs/utils-evm-contracts/contracts/interfaces/IPause.sol";
+import { Initializable } from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
+
+/**
+ * @title PauseBaseUpgradeable
+ * @author LayerZero Labs (tinom.eth)
+ * @custom:version 1.0.0
+ * @notice Abstract upgradeable contract that implements pause configuration and enforcement.
+ * @dev No public management functions are exposed by this contract, wrappers should be used with access control.
+ *      Alternatively, refer to `PauseRBACUpgradeable` for a permissioned implementation.
+ */
+abstract contract PauseBaseUpgradeable is IPause, Initializable {
+    /// @custom:storage-location erc7201:layerzerov2.storage.pause
+    struct PauseStorage {
+        bool paused;
+    }
+
+    // keccak256(abi.encode(uint256(keccak256("layerzerov2.storage.pause")) - 1)) & ~bytes32(uint256(0xff))
+    bytes32 private constant PAUSE_STORAGE_LOCATION =
+        0x27be0a968b102c71096101138efa2fc0db00aea7b287f10fdc298bfd2d4ec000;
+
+    /**
+     * @notice Internal function to get the pause storage.
+     * @return $ Storage pointer
+     */
+    function _getPauseStorage() internal pure returns (PauseStorage storage $) {
+        assembly {
+            $.slot := PAUSE_STORAGE_LOCATION
+        }
+    }
+
+    /**
+     * @notice Initializes the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __PauseBase_init() internal onlyInitializing {}
+
+    /**
+     * @notice Unchained initialization function for the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __PauseBase_init_unchained() internal onlyInitializing {}
+
+    /**
+     * @notice Modifier that reverts if the system is paused.
+     */
+    modifier whenNotPaused() {
+        if (_getPaused()) revert Paused();
+        _;
+    }
+
+    /**
+     * @inheritdoc IPause
+     */
+    function isPaused() public view virtual returns (bool paused) {
+        return _getPaused();
+    }
+
+    /**
+     * @notice Retrieves the pause status.
+     * @return paused Whether the system is paused
+     */
+    function _getPaused() internal view virtual returns (bool) {
+        PauseStorage storage $ = _getPauseStorage();
+        return $.paused;
+    }
+
+    /**
+     * @notice Enforces that the system is not paused.
+     * @dev Reverts with `Paused` error if the system is paused.
+     */
+    function _assertNotPaused() internal view virtual {
+        if (_getPaused()) revert Paused();
+    }
+
+    /**
+     * @notice Internal function to set the pause status.
+     * @param _paused New pause status
+     */
+    function _setPaused(bool _paused) internal virtual {
+        PauseStorage storage $ = _getPauseStorage();
+        if ($.paused == _paused) revert PauseStateIdempotent(_paused);
+        $.paused = _paused;
+        emit PauseSet(_paused);
+    }
+
+    // ============ Internal Functions to Wrap with Access Control ============
+
+    /**
+     * @notice Internal function to set the pause status to true.
+     * @dev To be wrapped with access control.
+     */
+    function _pause() internal virtual {
+        _setPaused(true);
+    }
+
+    /**
+     * @notice Internal function to set the pause status to false.
+     * @dev To be wrapped with access control.
+     */
+    function _unpause() internal virtual {
+        _setPaused(false);
+    }
+}

package/contracts/pause/PauseRBACUpgradeable.sol

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+import { IPause } from "@layerzerolabs/utils-evm-contracts/contracts/interfaces/IPause.sol";
+import { AccessControl2StepUpgradeable } from "./../access/AccessControl2StepUpgradeable.sol";
+import { PauseBaseUpgradeable } from "./PauseBaseUpgradeable.sol";
+
+/**
+ * @title PauseRBACUpgradeable
+ * @author LayerZero Labs (tinom.eth)
+ * @custom:version 1.0.0
+ * @notice Abstract upgradeable contract that provides pause functionality.
+ * @dev Exposes public management functions through `AccessControl2StepUpgradeable`.
+ */
+abstract contract PauseRBACUpgradeable is PauseBaseUpgradeable, AccessControl2StepUpgradeable {
+    /// @notice Role for pausing the contract.
+    bytes32 public constant PAUSER_ROLE = keccak256("PAUSER_ROLE");
+
+    /// @notice Role for unpausing the contract.
+    bytes32 public constant UNPAUSER_ROLE = keccak256("UNPAUSER_ROLE");
+
+    /**
+     * @notice Initializes the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __PauseRBAC_init() internal onlyInitializing {}
+
+    /**
+     * @notice Unchained initialization function for the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __PauseRBAC_init_unchained() internal onlyInitializing {}
+
+    /**
+     * @inheritdoc IPause
+     */
+    function pause() public virtual onlyRole(PAUSER_ROLE) {
+        _pause();
+    }
+
+    /**
+     * @inheritdoc IPause
+     */
+    function unpause() public virtual onlyRole(UNPAUSER_ROLE) {
+        _unpause();
+    }
+}

package/contracts/pause-by-id/PauseByIDBaseUpgradeable.sol

@@ -0,0 +1,127 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+import { IPauseByID } from "@layerzerolabs/utils-evm-contracts/contracts/interfaces/IPauseByID.sol";
+import { Initializable } from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
+
+/**
+ * @title PauseByIDBaseUpgradeable
+ * @author LayerZero Labs (tinom.eth)
+ * @custom:version 1.0.0
+ * @notice Abstract upgradeable contract that implements pause configuration and enforcement per ID.
+ * @dev No public management functions are exposed by this contract, wrappers should be used with access control.
+ *      Alternatively, refer to `PauseByIDRBACUpgradeable` for a permissioned implementation.
+ */
+abstract contract PauseByIDBaseUpgradeable is IPauseByID, Initializable {
+    /// @custom:storage-location erc7201:layerzerov2.storage.pausebyid
+    struct PauseByIDStorage {
+        bool defaultPaused;
+        mapping(uint256 id => PauseConfig config) pauseConfigs;
+    }
+
+    // keccak256(abi.encode(uint256(keccak256("layerzerov2.storage.pausebyid")) - 1)) & ~bytes32(uint256(0xff))
+    bytes32 private constant PAUSE_BY_ID_STORAGE_LOCATION =
+        0xac2cb783706dc5ac6b91d3675ceaddc73634a37f082a72b77dcdd25ee1f51300;
+
+    /**
+     * @notice Internal function to get the pause storage.
+     * @return $ Storage pointer
+     */
+    function _getPauseByIDStorage() internal pure returns (PauseByIDStorage storage $) {
+        assembly {
+            $.slot := PAUSE_BY_ID_STORAGE_LOCATION
+        }
+    }
+
+    /**
+     * @notice Initializes the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __PauseByIDBase_init() internal onlyInitializing {}
+
+    /**
+     * @notice Unchained initialization function for the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __PauseByIDBase_init_unchained() internal onlyInitializing {}
+
+    /**
+     * @notice Modifier that reverts if the destination ID is paused.
+     * @param _id Destination ID
+     */
+    modifier whenNotPaused(uint256 _id) {
+        if (_getPaused(_id)) revert Paused(_id);
+        _;
+    }
+
+    /**
+     * @inheritdoc IPauseByID
+     */
+    function isPaused(uint256 _id) public view virtual returns (bool paused) {
+        return _getPaused(_id);
+    }
+
+    /**
+     * @inheritdoc IPauseByID
+     */
+    function defaultPaused() public view virtual returns (bool paused) {
+        PauseByIDStorage storage $ = _getPauseByIDStorage();
+        return $.defaultPaused;
+    }
+
+    /**
+     * @inheritdoc IPauseByID
+     */
+    function pauseConfig(uint256 _id) public view virtual returns (PauseConfig memory config) {
+        PauseByIDStorage storage $ = _getPauseByIDStorage();
+        return $.pauseConfigs[_id];
+    }
+
+    /**
+     * @notice Retrieves the pause status for a specific destination ID.
+     * @param _id Destination ID
+     * @return paused Whether transfers are paused for the destination ID
+     */
+    function _getPaused(uint256 _id) internal view virtual returns (bool) {
+        PauseByIDStorage storage $ = _getPauseByIDStorage();
+        PauseConfig storage config = $.pauseConfigs[_id];
+        return config.enabled ? config.paused : $.defaultPaused;
+    }
+
+    /**
+     * @notice Enforces that transfers to a destination ID are not paused.
+     * @dev Reverts with `Paused` error if the destination is paused.
+     * @param _id Destination ID
+     */
+    function _assertNotPaused(uint256 _id) internal view virtual {
+        if (_getPaused(_id)) revert Paused(_id);
+    }
+
+    // ============ Internal Functions to Wrap with Access Control ============
+
+    /**
+     * @notice Internal function to set the default pause status for all destinations.
+     * @dev To be wrapped with access control.
+     * @param _paused New default pause status
+     */
+    function _setDefaultPaused(bool _paused) internal virtual {
+        PauseByIDStorage storage $ = _getPauseByIDStorage();
+        if ($.defaultPaused == _paused) revert PauseStateIdempotent(_paused);
+        $.defaultPaused = _paused;
+        emit DefaultPauseSet(_paused);
+    }
+
+    /**
+     * @notice Internal function to set the pause status for an array of destination IDs.
+     * @dev To be wrapped with access control.
+     * @param _params Array of pause configurations
+     */
+    function _setPaused(SetPausedParam[] calldata _params) internal virtual {
+        PauseByIDStorage storage $ = _getPauseByIDStorage();
+        for (uint256 i = 0; i < _params.length; i++) {
+            SetPausedParam calldata param = _params[i];
+            $.pauseConfigs[param.id] = PauseConfig(param.paused, param.enabled);
+            emit PauseSet(param.id, param.paused, param.enabled);
+        }
+    }
+}

package/contracts/pause-by-id/PauseByIDRBACUpgradeable.sol

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+import { IPauseByID } from "@layerzerolabs/utils-evm-contracts/contracts/interfaces/IPauseByID.sol";
+import { AccessControl2StepUpgradeable } from "./../access/AccessControl2StepUpgradeable.sol";
+import { PauseByIDBaseUpgradeable } from "./PauseByIDBaseUpgradeable.sol";
+
+/**
+ * @title PauseByIDRBACUpgradeable
+ * @author LayerZero Labs (tinom.eth)
+ * @custom:version 1.0.0
+ * @notice Abstract upgradeable contract that implements pause configuration and enforcement per ID.
+ * @dev Exposes public management functions through `AccessControl2StepUpgradeable`.
+ */
+abstract contract PauseByIDRBACUpgradeable is PauseByIDBaseUpgradeable, AccessControl2StepUpgradeable {
+    /// @notice Role for pausing the contract.
+    bytes32 public constant PAUSER_ROLE = keccak256("PAUSER_ROLE");
+
+    /// @notice Role for unpausing the contract.
+    bytes32 public constant UNPAUSER_ROLE = keccak256("UNPAUSER_ROLE");
+
+    /**
+     * @notice Initializes the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __PauseByIDRBAC_init() internal onlyInitializing {}
+
+    /**
+     * @notice Unchained initialization function for the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __PauseByIDRBAC_init_unchained() internal onlyInitializing {}
+
+    /**
+     * @inheritdoc IPauseByID
+     */
+    function setDefaultPaused(bool _paused) public virtual {
+        _paused ? _checkRole(PAUSER_ROLE) : _checkRole(UNPAUSER_ROLE);
+        _setDefaultPaused(_paused);
+    }
+
+    /**
+     * @dev Caller must have both `PAUSER_ROLE` and `UNPAUSER_ROLE` if setting mixed pause states.
+     *      Role checks are based on the effective pause state, accounting for the `enabled` flag and `defaultPaused`
+     *      fallback.
+     * @dev Requires the more restrictive `UNPAUSER_ROLE` for no-ops.
+     * @inheritdoc IPauseByID
+     */
+    function setPaused(SetPausedParam[] calldata _params) public virtual {
+        bool needsPauser;
+        bool needsUnpauser;
+        bool _defaultPaused = defaultPaused();
+
+        for (uint256 i = 0; i < _params.length; i++) {
+            /// @dev Determine if the operation effectively pauses or unpauses the ID.
+            ///      It's safe to ignore `_params[i].paused` if the ID is not enabled, since it'll be ignored and this
+            ///      function is the entrypoint for ID configuration, which disallows privilege escalation.
+            if (_params[i].enabled ? _params[i].paused : _defaultPaused) {
+                needsPauser = true;
+            } else {
+                needsUnpauser = true;
+            }
+
+            /// @dev Early exit if both roles are needed.
+            if (needsPauser && needsUnpauser) break;
+        }
+
+        if (needsPauser) _checkRole(PAUSER_ROLE);
+        /// @dev Avoid unauthorized no-ops.
+        if (needsUnpauser || !needsPauser) _checkRole(UNPAUSER_ROLE);
+
+        _setPaused(_params);
+    }
+}