@layerzerolabs/utils-upgradeable-evm-contracts 0.2.74

package/LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2026 - LayerZero Labs Ltd.
+
+Permission is hereby granted, free of charge, to any
+person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the
+Software without restriction, including without
+limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software
+is furnished to do so, subject to the following
+conditions:
+The above copyright notice and this permission notice
+shall be included in all copies or substantial portions
+of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
+SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

package/contracts/access/AccessControl2StepUpgradeable.sol

@@ -0,0 +1,144 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+import { IAccessControl2Step } from "@layerzerolabs/utils-evm-contracts/contracts/interfaces/IAccessControl2Step.sol";
+import { AccessControlUpgradeable } from "@openzeppelin/contracts-upgradeable/access/AccessControlUpgradeable.sol";
+import { AccessControlEnumerableUpgradeable } from "@openzeppelin/contracts-upgradeable/access/extensions/AccessControlEnumerableUpgradeable.sol";
+
+/**
+ * @title AccessControl2StepUpgradeable
+ * @author LayerZero Labs (tinom.eth)
+ * @custom:version 1.0.0
+ * @notice Abstract upgradeable contract that extends `AccessControlEnumerable` with a two-step transfer mechanism for
+ *         the `DEFAULT_ADMIN_ROLE`, similar to `AccessControlDefaultAdminRules`. It does not enforce delayed transfers.
+ * @dev The `DEFAULT_ADMIN_ROLE` cannot be granted or revoked through the standard `grantRole` and `revokeRole`
+ *      functions. Instead, a two-step process is enforced:
+ *      1. The current admin calls `beginDefaultAdminTransfer(newAdmin)`.
+ *      2. The pending admin calls `acceptDefaultAdminTransfer()`.
+ *      The current default admin can cancel a pending transfer via `beginDefaultAdminTransfer(address(0))`.
+ *      Renouncing the `DEFAULT_ADMIN_ROLE` is not permitted.
+ */
+abstract contract AccessControl2StepUpgradeable is IAccessControl2Step, AccessControlEnumerableUpgradeable {
+    /// @custom:storage-location erc7201:layerzerov2.storage.accesscontrol2step
+    struct AccessControl2StepStorage {
+        address _pendingDefaultAdmin;
+        address _currentDefaultAdmin;
+    }
+
+    // keccak256(abi.encode(uint256(keccak256("layerzerov2.storage.accesscontrol2step")) - 1)) & ~bytes32(uint256(0xff))
+    bytes32 private constant ACCESS_CONTROL_2_STEP_STORAGE_LOCATION =
+        0x9ab055b8fb8e38b861ceee93a65f20f7a2382a86570a6abe934fe7edfac60400;
+
+    /**
+     * @notice Internal function to get the contract storage.
+     * @return $ Storage pointer
+     */
+    function _getAccessControl2StepStorage() internal pure returns (AccessControl2StepStorage storage $) {
+        assembly {
+            $.slot := ACCESS_CONTROL_2_STEP_STORAGE_LOCATION
+        }
+    }
+
+    /**
+     * @notice Initializes the contract.
+     * @param _initialDefaultAdmin Default admin address
+     */
+    function __AccessControl2Step_init(address _initialDefaultAdmin) internal onlyInitializing {
+        __AccessControl2Step_init_unchained(_initialDefaultAdmin);
+    }
+
+    /**
+     * @notice Unchained initialization function for the contract.
+     * @param _initialDefaultAdmin Default admin address
+     */
+    function __AccessControl2Step_init_unchained(address _initialDefaultAdmin) internal onlyInitializing {
+        if (_initialDefaultAdmin == address(0)) {
+            revert InvalidDefaultAdmin(address(0));
+        }
+        AccessControl2StepStorage storage $ = _getAccessControl2StepStorage();
+        $._currentDefaultAdmin = _initialDefaultAdmin;
+        /// @dev Bypass `DEFAULT_ADMIN_ROLE` check.
+        super._grantRole(DEFAULT_ADMIN_ROLE, _initialDefaultAdmin);
+    }
+
+    // ============ Getters ============
+
+    /**
+     * @inheritdoc IAccessControl2Step
+     */
+    function defaultAdmin() public view virtual returns (address defaultAdminAddress) {
+        return _getAccessControl2StepStorage()._currentDefaultAdmin;
+    }
+
+    /**
+     * @inheritdoc IAccessControl2Step
+     */
+    function pendingDefaultAdmin() public view virtual returns (address pendingDefaultAdminAddress) {
+        return _getAccessControl2StepStorage()._pendingDefaultAdmin;
+    }
+
+    // ============ Setters ============
+
+    /**
+     * @inheritdoc IAccessControl2Step
+     */
+    function beginDefaultAdminTransfer(address _newAdmin) public virtual onlyRole(DEFAULT_ADMIN_ROLE) {
+        AccessControl2StepStorage storage $ = _getAccessControl2StepStorage();
+        $._pendingDefaultAdmin = _newAdmin;
+        emit DefaultAdminTransferStarted(_newAdmin);
+    }
+
+    /**
+     * @inheritdoc IAccessControl2Step
+     */
+    function acceptDefaultAdminTransfer() public virtual {
+        AccessControl2StepStorage storage $ = _getAccessControl2StepStorage();
+
+        address pendingAdmin = $._pendingDefaultAdmin;
+        if (pendingAdmin != _msgSender()) {
+            revert CallerNotPendingAdmin(pendingAdmin);
+        }
+
+        /// @dev Bypass `DEFAULT_ADMIN_ROLE` check.
+        super._revokeRole(DEFAULT_ADMIN_ROLE, $._currentDefaultAdmin);
+        super._grantRole(DEFAULT_ADMIN_ROLE, pendingAdmin);
+
+        $._currentDefaultAdmin = pendingAdmin;
+        delete $._pendingDefaultAdmin;
+    }
+
+    // ============ Overrides ============
+
+    /**
+     * @dev Override to prevent granting `DEFAULT_ADMIN_ROLE`.
+     * @inheritdoc AccessControlEnumerableUpgradeable
+     */
+    function _grantRole(bytes32 role, address account) internal virtual override returns (bool) {
+        if (role == DEFAULT_ADMIN_ROLE) {
+            revert AccessControlEnforcedDefaultAdminRules();
+        }
+        return super._grantRole(role, account);
+    }
+
+    /**
+     * @dev Override to prevent revoking `DEFAULT_ADMIN_ROLE`.
+     * @inheritdoc AccessControlEnumerableUpgradeable
+     */
+    function _revokeRole(bytes32 role, address account) internal virtual override returns (bool) {
+        if (role == DEFAULT_ADMIN_ROLE) {
+            revert AccessControlEnforcedDefaultAdminRules();
+        }
+        return super._revokeRole(role, account);
+    }
+
+    /**
+     * @dev Override to prevent updating the admin of the `DEFAULT_ADMIN_ROLE`.
+     * @inheritdoc AccessControlUpgradeable
+     */
+    function _setRoleAdmin(bytes32 role, bytes32 adminRole) internal virtual override {
+        if (role == DEFAULT_ADMIN_ROLE) {
+            revert AccessControlEnforcedDefaultAdminRules();
+        }
+        super._setRoleAdmin(role, adminRole);
+    }
+}

package/contracts/allowlist/AllowlistBaseUpgradeable.sol

@@ -0,0 +1,184 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+import { IAllowlist } from "@layerzerolabs/utils-evm-contracts/contracts/interfaces/IAllowlist.sol";
+import { Initializable } from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
+import { EnumerableSet } from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
+import { EnumerableSetPagination } from "./../libs/EnumerableSetPagination.sol";
+
+/**
+ * @title AllowlistBaseUpgradeable
+ * @author LayerZero Labs (tinom.eth)
+ * @custom:version 1.0.0
+ * @notice Abstract upgradeable contract that provides toggleable allowlist functionality between open, blacklist, and
+ *         whitelist modes.
+ * @dev No public management functions are exposed by this contract, wrappers should be used with access control.
+ *      Alternatively, refer to `AllowlistRBACUpgradeable` for a permissioned implementation.
+ */
+abstract contract AllowlistBaseUpgradeable is IAllowlist, Initializable {
+    using EnumerableSet for EnumerableSet.AddressSet;
+    using EnumerableSetPagination for EnumerableSet.AddressSet;
+
+    /// @custom:storage-location erc7201:layerzerov2.storage.allowlist
+    struct AllowlistStorage {
+        AllowlistMode mode;
+        EnumerableSet.AddressSet blacklistedSet;
+        EnumerableSet.AddressSet whitelistedSet;
+    }
+
+    // keccak256(abi.encode(uint256(keccak256("layerzerov2.storage.allowlist")) - 1)) & ~bytes32(uint256(0xff))
+    bytes32 private constant ALLOWLIST_STORAGE_LOCATION =
+        0xa9f917c522fb3fd8673bbc655e92a5c1f1ee3df7bf7ad06a1821b937d0205e00;
+
+    /**
+     * @notice Internal function to get the allowlist storage.
+     * @return $ Storage pointer
+     */
+    function _getAllowlistStorage() internal pure returns (AllowlistStorage storage $) {
+        assembly {
+            $.slot := ALLOWLIST_STORAGE_LOCATION
+        }
+    }
+
+    /**
+     * @notice Initializes the contract.
+     * @param _mode Initial mode
+     */
+    function __AllowlistBase_init(AllowlistMode _mode) internal onlyInitializing {
+        __AllowlistBase_init_unchained(_mode);
+    }
+
+    /**
+     * @notice Unchained initialization function for the contract.
+     * @param _mode Initial mode
+     */
+    function __AllowlistBase_init_unchained(AllowlistMode _mode) internal onlyInitializing {
+        /// @dev Not using `_setAllowlistMode` to avoid reverting if the mode is open.
+        AllowlistStorage storage $ = _getAllowlistStorage();
+        $.mode = _mode;
+        emit AllowlistModeUpdated(_mode);
+    }
+
+    /**
+     * @notice Modifier that reverts if the user is not allowlisted.
+     * @param _user User address
+     */
+    modifier onlyAllowlisted(address _user) {
+        if (!isAllowlisted(_user)) revert NotAllowlisted(_user, allowlistMode());
+        _;
+    }
+
+    /**
+     * @inheritdoc IAllowlist
+     */
+    function allowlistMode() public view virtual returns (AllowlistMode mode) {
+        return _getAllowlistStorage().mode;
+    }
+
+    /**
+     * @inheritdoc IAllowlist
+     */
+    function isBlacklisted(address _user) public view virtual returns (bool isUserBlacklisted) {
+        return _getAllowlistStorage().blacklistedSet.contains(_user);
+    }
+
+    /**
+     * @inheritdoc IAllowlist
+     */
+    function isWhitelisted(address _user) public view virtual returns (bool isUserWhitelisted) {
+        return _getAllowlistStorage().whitelistedSet.contains(_user);
+    }
+
+    /**
+     * @inheritdoc IAllowlist
+     */
+    function isAllowlisted(address _user) public view virtual returns (bool isUserAllowlisted) {
+        AllowlistMode currentMode = allowlistMode();
+        if (currentMode == AllowlistMode.Open) return true;
+        if (currentMode == AllowlistMode.Blacklist) return !isBlacklisted(_user);
+        /// @dev `currentMode == AllowlistMode.Whitelist`.
+        return isWhitelisted(_user);
+    }
+
+    /**
+     * @inheritdoc IAllowlist
+     */
+    function blacklistedCount() public view virtual returns (uint256 count) {
+        return _getAllowlistStorage().blacklistedSet.length();
+    }
+
+    /**
+     * @inheritdoc IAllowlist
+     */
+    function whitelistedCount() public view virtual returns (uint256 count) {
+        return _getAllowlistStorage().whitelistedSet.length();
+    }
+
+    /**
+     * @inheritdoc IAllowlist
+     */
+    function getBlacklist(uint256 _offset, uint256 _limit) public view virtual returns (address[] memory addresses) {
+        return _getAllowlistStorage().blacklistedSet.paginate(_offset, _limit);
+    }
+
+    /**
+     * @inheritdoc IAllowlist
+     */
+    function getWhitelist(uint256 _offset, uint256 _limit) public view virtual returns (address[] memory addresses) {
+        return _getAllowlistStorage().whitelistedSet.paginate(_offset, _limit);
+    }
+
+    // ============ Internal Functions to Wrap with Access Control ============
+
+    /**
+     * @notice Internal function to set the allowlist mode.
+     * @dev To be wrapped with access control.
+     * @param _mode New mode
+     */
+    function _setAllowlistMode(AllowlistMode _mode) internal virtual {
+        AllowlistStorage storage $ = _getAllowlistStorage();
+        if ($.mode == _mode) revert ModeAlreadySet(_mode);
+        $.mode = _mode;
+        emit AllowlistModeUpdated(_mode);
+    }
+
+    /**
+     * @notice Internal function to set the whitelist state for an array of users.
+     * @dev To be wrapped with access control.
+     * @param _params Array of users and whitelist states
+     */
+    function _setWhitelisted(SetAllowlistParam[] calldata _params) internal virtual {
+        AllowlistStorage storage $ = _getAllowlistStorage();
+        for (uint256 i = 0; i < _params.length; i++) {
+            SetAllowlistParam calldata param = _params[i];
+            bool addedOrRemoved;
+            if (param.isEnabled) {
+                addedOrRemoved = $.whitelistedSet.add(param.user);
+            } else {
+                addedOrRemoved = $.whitelistedSet.remove(param.user);
+            }
+            if (!addedOrRemoved) revert AllowlistStateIdempotent(param.user, param.isEnabled);
+            emit WhitelistUpdated(param.user, param.isEnabled);
+        }
+    }
+
+    /**
+     * @notice Internal function to set the blacklist state for an array of users.
+     * @dev To be wrapped with access control.
+     * @param _params Array of users and blacklist states
+     */
+    function _setBlacklisted(SetAllowlistParam[] calldata _params) internal virtual {
+        AllowlistStorage storage $ = _getAllowlistStorage();
+        for (uint256 i = 0; i < _params.length; i++) {
+            SetAllowlistParam calldata param = _params[i];
+            bool addedOrRemoved;
+            if (param.isEnabled) {
+                addedOrRemoved = $.blacklistedSet.add(param.user);
+            } else {
+                addedOrRemoved = $.blacklistedSet.remove(param.user);
+            }
+            if (!addedOrRemoved) revert AllowlistStateIdempotent(param.user, param.isEnabled);
+            emit BlacklistUpdated(param.user, param.isEnabled);
+        }
+    }
+}

package/contracts/allowlist/AllowlistRBACUpgradeable.sol

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+import { IAllowlist } from "@layerzerolabs/utils-evm-contracts/contracts/interfaces/IAllowlist.sol";
+import { AccessControl2StepUpgradeable } from "./../access/AccessControl2StepUpgradeable.sol";
+import { AllowlistBaseUpgradeable } from "./AllowlistBaseUpgradeable.sol";
+
+/**
+ * @title AllowlistRBACUpgradeable
+ * @author LayerZero Labs (tinom.eth)
+ * @custom:version 1.0.0
+ * @notice Abstract upgradeable contract that provides toggleable allowlist functionality between open, blacklist, and
+ *         whitelist modes.
+ * @dev Exposes public management functions through `AccessControl2StepUpgradeable`.
+ */
+abstract contract AllowlistRBACUpgradeable is AllowlistBaseUpgradeable, AccessControl2StepUpgradeable {
+    /// @notice Role for setting the blacklist state for users.
+    bytes32 public constant BLACKLISTER_ROLE = keccak256("BLACKLISTER_ROLE");
+
+    /// @notice Role for setting the whitelist state for users.
+    bytes32 public constant WHITELISTER_ROLE = keccak256("WHITELISTER_ROLE");
+
+    /**
+     * @notice Initializes the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __AllowlistRBAC_init() internal onlyInitializing {}
+
+    /**
+     * @notice Unchained initialization function for the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __AllowlistRBAC_init_unchained() internal onlyInitializing {}
+
+    /**
+     * @inheritdoc IAllowlist
+     */
+    function setAllowlistMode(AllowlistMode _mode) public virtual onlyRole(DEFAULT_ADMIN_ROLE) {
+        _setAllowlistMode(_mode);
+    }
+
+    /**
+     * @inheritdoc IAllowlist
+     */
+    function setBlacklisted(SetAllowlistParam[] calldata _params) public virtual onlyRole(BLACKLISTER_ROLE) {
+        _setBlacklisted(_params);
+    }
+
+    /**
+     * @inheritdoc IAllowlist
+     */
+    function setWhitelisted(SetAllowlistParam[] calldata _params) public virtual onlyRole(WHITELISTER_ROLE) {
+        _setWhitelisted(_params);
+    }
+}

package/contracts/fee-accounting/FeeHandlerBaseUpgradeable.sol

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+import { IFeeHandler } from "@layerzerolabs/utils-evm-contracts/contracts/interfaces/IFeeHandler.sol";
+import { Initializable } from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
+
+/**
+ * @title FeeHandlerBaseUpgradeable
+ * @author LayerZero Labs (tinom.eth)
+ * @custom:version 1.0.0
+ * @notice Abstract upgradeable contract that stores the fee deposit address, for push-based fee handling.
+ * @dev Fee transfer logic is handled by the inheriting contract. This contract only manages the `feeDeposit` state.
+ * @dev No public management functions are exposed by this contract, wrappers should be used with access control.
+ *      Alternatively, refer to `FeeHandlerRBACUpgradeable` for a permissioned implementation.
+ * @dev Does not include fee configuration (BPS / calculation). See `FeeConfigBaseUpgradeable` for that.
+ */
+abstract contract FeeHandlerBaseUpgradeable is IFeeHandler, Initializable {
+    /// @custom:storage-location erc7201:layerzerov2.storage.feehandler
+    struct FeeHandlerStorage {
+        address feeDeposit;
+    }
+
+    // keccak256(abi.encode(uint256(keccak256("layerzerov2.storage.feehandler")) - 1)) & ~bytes32(uint256(0xff))
+    bytes32 private constant FEE_HANDLER_STORAGE_LOCATION =
+        0xe32e0c5f1df3081ca85b86156deac82a46e8fb7b21b412e09f7ccdc5fca29900;
+
+    /**
+     * @notice Internal function to get the fee handler storage.
+     * @return $ Storage pointer
+     */
+    function _getFeeHandlerStorage() internal pure returns (FeeHandlerStorage storage $) {
+        assembly {
+            $.slot := FEE_HANDLER_STORAGE_LOCATION
+        }
+    }
+
+    /**
+     * @notice Initializes the contract with a fee deposit.
+     * @param _feeDeposit Address that will receive any accrued fees
+     */
+    function __FeeHandlerBase_init(address _feeDeposit) internal onlyInitializing {
+        __FeeHandlerBase_init_unchained(_feeDeposit);
+    }
+
+    /**
+     * @notice Unchained initialization function for the contract.
+     * @param _feeDeposit Address that will receive any accrued fees
+     */
+    function __FeeHandlerBase_init_unchained(address _feeDeposit) internal onlyInitializing {
+        _setFeeDeposit(_feeDeposit);
+    }
+
+    /**
+     * @inheritdoc IFeeHandler
+     */
+    function feeDeposit() public view virtual returns (address deposit) {
+        return _getFeeHandlerStorage().feeDeposit;
+    }
+
+    /**
+     * @notice Sets the fee deposit address.
+     * @param _feeDeposit New fee deposit address
+     */
+    function _setFeeDeposit(address _feeDeposit) internal virtual {
+        if (_feeDeposit == address(0)) revert InvalidFeeDeposit();
+        _getFeeHandlerStorage().feeDeposit = _feeDeposit;
+        emit FeeDepositSet(_feeDeposit);
+    }
+}

package/contracts/fee-accounting/FeeHandlerRBACUpgradeable.sol

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+import { IFeeHandler } from "@layerzerolabs/utils-evm-contracts/contracts/interfaces/IFeeHandler.sol";
+import { AccessControl2StepUpgradeable } from "./../access/AccessControl2StepUpgradeable.sol";
+import { FeeHandlerBaseUpgradeable } from "./FeeHandlerBaseUpgradeable.sol";
+
+/**
+ * @title FeeHandlerRBACUpgradeable
+ * @author LayerZero Labs (tinom.eth)
+ * @custom:version 1.0.0
+ * @notice Abstract upgradeable contract that stores the fee deposit address, for push-based fee handling.
+ * @dev Exposes public management functions through `AccessControl2StepUpgradeable`.
+ */
+abstract contract FeeHandlerRBACUpgradeable is FeeHandlerBaseUpgradeable, AccessControl2StepUpgradeable {
+    /**
+     * @notice Initializes the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __FeeHandlerRBAC_init() internal onlyInitializing {}
+
+    /**
+     * @notice Unchained initialization function for the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __FeeHandlerRBAC_init_unchained() internal onlyInitializing {}
+
+    /**
+     * @inheritdoc IFeeHandler
+     */
+    function setFeeDeposit(address _feeDeposit) public virtual onlyRole(DEFAULT_ADMIN_ROLE) {
+        _setFeeDeposit(_feeDeposit);
+    }
+}

package/contracts/fee-config/FeeConfigBaseUpgradeable.sol

@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+import { IFeeConfig } from "@layerzerolabs/utils-evm-contracts/contracts/interfaces/IFeeConfig.sol";
+import { Initializable } from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
+
+/**
+ * @title FeeConfigBaseUpgradeable
+ * @author LayerZero Labs (@TRileySchwarz, tinom.eth)
+ * @custom:version 1.0.0
+ * @notice Abstract upgradeable contract that implements fee configuration and calculation.
+ * @dev No public management functions are exposed by this contract, wrappers should be used with access control.
+ *      Alternatively, refer to `FeeConfigRBACUpgradeable` for a permissioned implementation.
+ * @dev Does not include fee receiver management. See `FeeHandlerBaseUpgradeable` for that.
+ */
+abstract contract FeeConfigBaseUpgradeable is IFeeConfig, Initializable {
+    /// @notice Constant with which fee basis points (BPS) are divided to get the fee amount.
+    uint16 public constant BPS_DENOMINATOR = 10_000;
+
+    /// @custom:storage-location erc7201:layerzerov2.storage.feeconfig
+    struct FeeConfigStorage {
+        uint16 defaultFeeBps;
+        mapping(uint256 id => FeeConfig config) feeBps;
+    }
+
+    // keccak256(abi.encode(uint256(keccak256("layerzerov2.storage.feeconfig")) - 1)) & ~bytes32(uint256(0xff))
+    bytes32 private constant FEE_CONFIG_STORAGE_LOCATION =
+        0x19c40dd5c7b9d6e4dbe259e67955cccfb75eaf6c218fbfbd413bfcd8248dd800;
+
+    /**
+     * @notice Internal function to get the fee config storage.
+     * @return $ Storage pointer
+     */
+    function _getFeeConfigStorage() internal pure returns (FeeConfigStorage storage $) {
+        assembly {
+            $.slot := FEE_CONFIG_STORAGE_LOCATION
+        }
+    }
+
+    /**
+     * @notice Initializes the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __FeeConfigBase_init() internal onlyInitializing {}
+
+    /**
+     * @notice Unchained initialization function for the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __FeeConfigBase_init_unchained() internal onlyInitializing {}
+
+    /**
+     * @inheritdoc IFeeConfig
+     */
+    function getFee(uint256 _id, uint256 _amount) public view virtual returns (uint256 fee) {
+        uint16 bps = _getFeeBps(_id);
+        /// @dev If `amount * bps < BPS_DENOMINATOR`, there is no fee.
+        return bps == 0 ? 0 : (_amount * bps) / BPS_DENOMINATOR;
+    }
+
+    /**
+     * @inheritdoc IFeeConfig
+     */
+    function getAmountBeforeFee(
+        uint256 _id,
+        uint256 _amountAfterFee
+    ) public view virtual returns (uint256 amountBeforeFee) {
+        uint16 bps = _getFeeBps(_id);
+        if (bps == BPS_DENOMINATOR) return 0;
+        if (bps == 0) return _amountAfterFee;
+        return (_amountAfterFee * BPS_DENOMINATOR) / (BPS_DENOMINATOR - bps);
+    }
+
+    /**
+     * @inheritdoc IFeeConfig
+     */
+    function defaultFeeBps() public view virtual returns (uint16 fee) {
+        FeeConfigStorage storage $ = _getFeeConfigStorage();
+        return $.defaultFeeBps;
+    }
+
+    /**
+     * @inheritdoc IFeeConfig
+     */
+    function feeBps(uint256 _id) public view virtual returns (FeeConfig memory config) {
+        FeeConfigStorage storage $ = _getFeeConfigStorage();
+        return $.feeBps[_id];
+    }
+
+    /**
+     * @notice Retrieves the fee basis points (BPS) for a specific destination ID.
+     * @param _id Destination ID
+     * @return bps Fee basis points (BPS) for the destination ID
+     */
+    function _getFeeBps(uint256 _id) internal view virtual returns (uint16) {
+        FeeConfigStorage storage $ = _getFeeConfigStorage();
+        FeeConfig storage config = $.feeBps[_id];
+        return config.enabled ? config.feeBps : $.defaultFeeBps;
+    }
+
+    // ============ Internal Functions to Wrap with Access Control ============
+
+    /**
+     * @notice Internal function to set the default fee basis points (BPS) for all destinations.
+     * @dev To be wrapped with access control.
+     * @param _feeBps New default fee basis points (BPS)
+     */
+    function _setDefaultFeeBps(uint16 _feeBps) internal virtual {
+        if (_feeBps > BPS_DENOMINATOR) revert IFeeConfig.InvalidBps(_feeBps);
+        FeeConfigStorage storage $ = _getFeeConfigStorage();
+        $.defaultFeeBps = _feeBps;
+        emit DefaultFeeBpsSet(_feeBps);
+    }
+
+    /**
+     * @notice Internal function to set the fee basis points (BPS) for a specific destination ID.
+     * @dev To be wrapped with access control.
+     * @param _id Destination ID
+     * @param _feeBps New fee basis points (BPS)
+     * @param _enabled Whether the fee is enabled for the destination
+     */
+    function _setFeeBps(uint256 _id, uint16 _feeBps, bool _enabled) internal virtual {
+        if (_feeBps > BPS_DENOMINATOR) revert IFeeConfig.InvalidBps(_feeBps);
+        FeeConfigStorage storage $ = _getFeeConfigStorage();
+        $.feeBps[_id] = FeeConfig(_feeBps, _enabled);
+        emit FeeBpsSet(_id, _feeBps, _enabled);
+    }
+}

package/contracts/fee-config/FeeConfigRBACUpgradeable.sol

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+import { IFeeConfig } from "@layerzerolabs/utils-evm-contracts/contracts/interfaces/IFeeConfig.sol";
+import { AccessControl2StepUpgradeable } from "./../access/AccessControl2StepUpgradeable.sol";
+import { FeeConfigBaseUpgradeable } from "./FeeConfigBaseUpgradeable.sol";
+
+/**
+ * @title FeeConfigRBACUpgradeable
+ * @author LayerZero Labs (@TRileySchwarz, tinom.eth)
+ * @custom:version 1.0.0
+ * @notice Abstract upgradeable contract that implements fee configuration and calculation.
+ * @dev Exposes public management functions through `AccessControl2StepUpgradeable`.
+ */
+abstract contract FeeConfigRBACUpgradeable is FeeConfigBaseUpgradeable, AccessControl2StepUpgradeable {
+    /// @notice Role for setting fee basis points.
+    bytes32 public constant FEE_CONFIG_MANAGER_ROLE = keccak256("FEE_CONFIG_MANAGER_ROLE");
+
+    /**
+     * @notice Initializes the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __FeeConfigRBAC_init() internal onlyInitializing {}
+
+    /**
+     * @notice Unchained initialization function for the contract.
+     * @dev This function is empty on purpose, as no custom logic is needed.
+     */
+    function __FeeConfigRBAC_init_unchained() internal onlyInitializing {}
+
+    /**
+     * @inheritdoc IFeeConfig
+     */
+    function setDefaultFeeBps(uint16 _feeBps) public virtual onlyRole(FEE_CONFIG_MANAGER_ROLE) {
+        _setDefaultFeeBps(_feeBps);
+    }
+
+    /**
+     * @inheritdoc IFeeConfig
+     */
+    function setFeeBps(uint256 _id, uint16 _feeBps, bool _enabled) public virtual onlyRole(FEE_CONFIG_MANAGER_ROLE) {
+        _setFeeBps(_id, _feeBps, _enabled);
+    }
+}