@layerzerolabs/utils-evm-contracts 0.2.74

package/.turbo/turbo-lint.log

@@ -0,0 +1,39 @@
+
+> @layerzerolabs/utils-evm-contracts@0.0.0 lint /home/runner/work/monorepo-internal/monorepo-internal/contracts/common/utils/evm/non-upgradeable
+> solhint --config solhint.config.js 'contracts/**/*.sol' --fix --noPrompt
+
+A new version of Solhint is available: 6.2.1
+Please consider updating your Solhint package.
+
+contracts/interfaces/IAllowlist.sol
+  44:5  warning  GC: [isBlacklisted] on Event [BlacklistUpdated] could be Indexed  gas-indexed-events
+  51:5  warning  GC: [isWhitelisted] on Event [WhitelistUpdated] could be Indexed  gas-indexed-events
+
+contracts/interfaces/IBurnableMintable.sol
+  5:1  warning  Missing @author tag in contract 'IBurnableMintable'  use-natspec
+  5:1  warning  Missing @notice tag in contract 'IBurnableMintable'  use-natspec
+
+contracts/interfaces/IFeeConfig.sol
+  27:5  warning  GC: [id] on Event [FeeBpsSet] could be Indexed             gas-indexed-events
+  27:5  warning  GC: [feeBps] on Event [FeeBpsSet] could be Indexed         gas-indexed-events
+  27:5  warning  GC: [enabled] on Event [FeeBpsSet] could be Indexed        gas-indexed-events
+  33:5  warning  GC: [feeBps] on Event [DefaultFeeBpsSet] could be Indexed  gas-indexed-events
+
+contracts/interfaces/IPause.sol
+  15:5  warning  GC: [paused] on Event [PauseSet] could be Indexed  gas-indexed-events
+
+contracts/interfaces/IPauseByID.sol
+  39:5  warning  GC: [id] on Event [PauseSet] could be Indexed             gas-indexed-events
+  39:5  warning  GC: [paused] on Event [PauseSet] could be Indexed         gas-indexed-events
+  39:5  warning  GC: [enabled] on Event [PauseSet] could be Indexed        gas-indexed-events
+  45:5  warning  GC: [paused] on Event [DefaultPauseSet] could be Indexed  gas-indexed-events
+
+contracts/interfaces/IRateLimiter.sol
+  134:5  warning  GC: [isExempt] on Event [RateLimitAddressExemptionUpdated] could be Indexed  gas-indexed-events
+
+✖ 14 problems (0 errors, 14 warnings)
+
+ -------------------------------------------------------------------------- 
+ ===> Join SOLHINT Community at: https://discord.com/invite/4TYGq3zpjs <=== 
+ -------------------------------------------------------------------------- 
+

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/interfaces/IAccessControl2Step.sol

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+import { IAccessControlEnumerable } from "@openzeppelin/contracts/access/extensions/IAccessControlEnumerable.sol";
+
+/**
+ * @title IAccessControl2Step
+ * @author LayerZero Labs (tinom.eth)
+ * @custom:version 1.0.0
+ * @notice Interface for the `AccessControl2Step` contract.
+ */
+interface IAccessControl2Step is IAccessControlEnumerable {
+    /**
+     * @notice Thrown when the intended default admin is invalid.
+     * @param defaultAdmin Invalid default admin address
+     */
+    error InvalidDefaultAdmin(address defaultAdmin);
+
+    /**
+     * @notice Thrown when one of the following rules is violated:
+     *         - The `DEFAULT_ADMIN_ROLE` must only be managed by itself.
+     *         - The `DEFAULT_ADMIN_ROLE` must only be held by one account at the time.
+     *         - Any `DEFAULT_ADMIN_ROLE` transfer must be in two steps.
+     */
+    error AccessControlEnforcedDefaultAdminRules();
+
+    /**
+     * @notice Thrown when the caller is not the pending admin.
+     * @param pendingAdmin Address of the pending admin
+     */
+    error CallerNotPendingAdmin(address pendingAdmin);
+
+    /**
+     * @notice Emitted when a `DEFAULT_ADMIN_ROLE` transfer is started.
+     * @param newAdmin Address of the new pending default admin
+     */
+    event DefaultAdminTransferStarted(address indexed newAdmin);
+
+    /**
+     * @notice Returns the address of the current `DEFAULT_ADMIN_ROLE` holder.
+     * @return defaultAdminAddress Address of the current `DEFAULT_ADMIN_ROLE` holder
+     */
+    function defaultAdmin() external view returns (address defaultAdminAddress);
+
+    /**
+     * @notice Returns the address of the account that can claim the `DEFAULT_ADMIN_ROLE` by calling
+     *         `acceptDefaultAdminTransfer`.
+     * @return pendingDefaultAdminAddress Address of the pending `DEFAULT_ADMIN_ROLE` account
+     */
+    function pendingDefaultAdmin() external view returns (address pendingDefaultAdminAddress);
+
+    /**
+     * @notice Starts a `DEFAULT_ADMIN_ROLE` transfer by setting a `pendingDefaultAdmin`.
+     * @dev It can cancel an existing pending transfer by setting the `newAdmin` to `address(0)`.
+     * @param newAdmin Address of the new pending default admin
+     */
+    function beginDefaultAdminTransfer(address newAdmin) external;
+
+    /**
+     * @notice Completes a `DEFAULT_ADMIN_ROLE` transfer previously started with `beginDefaultAdminTransfer`.
+     */
+    function acceptDefaultAdminTransfer() external;
+}

package/contracts/interfaces/IAllowlist.sol

@@ -0,0 +1,145 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+/**
+ * @title IAllowlist
+ * @author LayerZero Labs (tinom.eth)
+ * @custom:version 1.0.0
+ * @notice Interface for the `Allowlist` contract.
+ */
+interface IAllowlist {
+    /**
+     * @notice Available allowlist modes.
+     *         - `Open`: No restrictions.
+     *         - `Blacklist`: Users in the blacklist are not allowed.
+     *         - `Whitelist`: Only users in the whitelist are allowed.
+     */
+    enum AllowlistMode {
+        Open,
+        Blacklist,
+        Whitelist
+    }
+
+    /**
+     * @notice Parameters for setting the allowlist state for a user.
+     * @param user User address
+     * @param isEnabled Whether the user is whitelisted or blacklisted, depends on function context
+     */
+    struct SetAllowlistParam {
+        address user;
+        bool isEnabled;
+    }
+
+    /**
+     * @notice Emitted when the allowlist mode is updated.
+     * @param newMode New mode
+     */
+    event AllowlistModeUpdated(AllowlistMode newMode);
+
+    /**
+     * @notice Emitted when a user's blacklist state is updated.
+     * @param user User address
+     * @param isBlacklisted Whether the user is now blacklisted
+     */
+    event BlacklistUpdated(address indexed user, bool isBlacklisted);
+
+    /**
+     * @notice Emitted when a user's whitelist state is updated.
+     * @param user User address
+     * @param isWhitelisted Whether the user is now whitelisted
+     */
+    event WhitelistUpdated(address indexed user, bool isWhitelisted);
+
+    /**
+     * @notice Thrown when the intended allowlist mode is already set.
+     * @param mode Current mode
+     */
+    error ModeAlreadySet(AllowlistMode mode);
+
+    /**
+     * @notice Thrown when a user is already in the desired state (blacklist or whitelist).
+     * @param user User address
+     * @param isEnabled The desired state that the user is already in
+     */
+    error AllowlistStateIdempotent(address user, bool isEnabled);
+
+    /**
+     * @notice Thrown when a user is not allowlisted.
+     * @param user User address
+     * @param mode Current mode
+     */
+    error NotAllowlisted(address user, AllowlistMode mode);
+
+    /**
+     * @notice Returns the current allowlist mode.
+     * @return mode Current mode
+     */
+    function allowlistMode() external view returns (AllowlistMode mode);
+
+    /**
+     * @notice Returns the blacklist state for a user.
+     * @param _user User address
+     * @return isUserBlacklisted Whether the user is blacklisted
+     */
+    function isBlacklisted(address _user) external view returns (bool isUserBlacklisted);
+
+    /**
+     * @notice Returns the whitelist state for a user.
+     * @param _user User address
+     * @return isUserWhitelisted Whether the user is whitelisted
+     */
+    function isWhitelisted(address _user) external view returns (bool isUserWhitelisted);
+
+    /**
+     * @notice Checks if a user is allowlisted under the current mode.
+     * @param _user User address
+     * @return isUserAllowlisted Whether the user is allowlisted
+     */
+    function isAllowlisted(address _user) external view returns (bool isUserAllowlisted);
+
+    /**
+     * @notice Returns the total count of blacklisted addresses.
+     * @return count Total number of blacklisted addresses
+     */
+    function blacklistedCount() external view returns (uint256 count);
+
+    /**
+     * @notice Returns the total count of whitelisted addresses.
+     * @return count Total number of whitelisted addresses
+     */
+    function whitelistedCount() external view returns (uint256 count);
+
+    /**
+     * @notice Returns a paginated list of blacklisted addresses.
+     * @param _offset Starting index
+     * @param _limit Maximum number of addresses to return
+     * @return addresses Array of blacklisted addresses
+     */
+    function getBlacklist(uint256 _offset, uint256 _limit) external view returns (address[] memory addresses);
+
+    /**
+     * @notice Returns a paginated list of whitelisted addresses.
+     * @param _offset Starting index
+     * @param _limit Maximum number of addresses to return
+     * @return addresses Array of whitelisted addresses
+     */
+    function getWhitelist(uint256 _offset, uint256 _limit) external view returns (address[] memory addresses);
+
+    /**
+     * @notice Sets the allowlist mode.
+     * @param _mode New allowlist mode
+     */
+    function setAllowlistMode(AllowlistMode _mode) external;
+
+    /**
+     * @notice Sets the blacklist state for an array of users.
+     * @param _params Array of users and blacklist states
+     */
+    function setBlacklisted(SetAllowlistParam[] calldata _params) external;
+
+    /**
+     * @notice Sets the whitelist state for an array of users.
+     * @param _params Array of users and whitelist states
+     */
+    function setWhitelisted(SetAllowlistParam[] calldata _params) external;
+}

package/contracts/interfaces/IBurnableMintable.sol

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+/// @title Interface for burnable and mintable tokens
+interface IBurnableMintable {
+    /**
+     * @notice Burns tokens from a specified account
+     * @param _from Address from which tokens will be burned
+     * @param _amount Amount of tokens to be burned
+     * @return success Indicates whether the operation was successful
+     */
+    function burn(address _from, uint256 _amount) external returns (bool success);
+
+    /**
+     * @notice Mints tokens to a specified account
+     * @param _to Address to which tokens will be minted
+     * @param _amount Amount of tokens to be minted
+     * @return success Indicates whether the operation was successful
+     */
+    function mint(address _to, uint256 _amount) external returns (bool success);
+}

package/contracts/interfaces/IFeeConfig.sol

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+/**
+ * @title IFeeConfig
+ * @author LayerZero Labs (@TRileySchwarz, tinom.eth)
+ * @custom:version 1.0.0
+ * @notice Interface for the `FeeConfig` contract.
+ */
+interface IFeeConfig {
+    /**
+     * @notice Configuration for a fee.
+     * @param feeBps Fee basis points (BPS)
+     * @param enabled False to fallback to the default fee basis points (BPS)
+     */
+    struct FeeConfig {
+        uint16 feeBps;
+        bool enabled;
+    }
+
+    /**
+     * @notice Emitted when the fee basis points (BPS) are set for a specific destination ID.
+     * @param id Destination ID
+     * @param feeBps Fee basis points (BPS)
+     * @param enabled Whether the fee is enabled for the destination
+     */
+    event FeeBpsSet(uint256 id, uint16 feeBps, bool enabled);
+
+    /**
+     * @notice Emitted when the default fee basis points (BPS) are set.
+     * @param feeBps Default fee basis points (BPS)
+     */
+    event DefaultFeeBpsSet(uint16 feeBps);
+
+    /**
+     * @notice Thrown when the fee basis points (BPS) are invalid.
+     * @param feeBps Invalid fee basis points (BPS)
+     */
+    error InvalidBps(uint16 feeBps);
+
+    /**
+     * @notice Retrieves the fee for a destination ID and amount.
+     * @param _id Destination ID
+     * @param _amount Amount to calculate the fee for
+     * @return fee Fee amount
+     */
+    function getFee(uint256 _id, uint256 _amount) external view returns (uint256 fee);
+
+    /**
+     * @notice Retrieves the pre-fee amount required to yield a given post-fee amount.
+     * @param _id Destination ID
+     * @param _amountAfterFee Desired amount after fees
+     * @return amountBeforeFee Required amount before fees
+     */
+    function getAmountBeforeFee(uint256 _id, uint256 _amountAfterFee) external view returns (uint256 amountBeforeFee);
+
+    /**
+     * @notice Retrieves default fee basis points (BPS) used if no fee is configured for the destination ID.
+     * @return fee Default fee basis points (BPS)
+     */
+    function defaultFeeBps() external view returns (uint16 fee);
+
+    /**
+     * @notice Retrieves the configured fee for a given ID.
+     * @param _id Destination ID
+     * @return config Configured fee for the destination ID
+     */
+    function feeBps(uint256 _id) external view returns (FeeConfig memory config);
+
+    /**
+     * @notice Set the default fee basis points (BPS) for all destinations.
+     * @param _feeBps New default fee basis points (BPS)
+     */
+    function setDefaultFeeBps(uint16 _feeBps) external;
+
+    /**
+     * @notice Sets the fee basis points for a specific destination ID.
+     * @param _id Destination ID
+     * @param _feeBps Fee basis points to set
+     * @param _enabled Whether the fee is enabled for the destination
+     */
+    function setFeeBps(uint256 _id, uint16 _feeBps, bool _enabled) external;
+}

package/contracts/interfaces/IFeeHandler.sol

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+/**
+ * @title IFeeHandler
+ * @author LayerZero Labs (tinom.eth)
+ * @custom:version 1.0.0
+ * @notice Interface for the `FeeHandler` contract.
+ */
+interface IFeeHandler {
+    /**
+     * @notice Thrown when the fee deposit address is invalid.
+     */
+    error InvalidFeeDeposit();
+
+    /**
+     * @notice Emitted when the fee deposit is updated.
+     * @param feeDeposit New fee deposit address
+     */
+    event FeeDepositSet(address indexed feeDeposit);
+
+    /**
+     * @notice Returns the address to which fees are forwarded.
+     * @return deposit Address that will receive any accrued fees
+     */
+    function feeDeposit() external view returns (address deposit);
+
+    /**
+     * @notice Sets the fee deposit address.
+     * @param _feeDeposit Address that will receive any accrued fees
+     */
+    function setFeeDeposit(address _feeDeposit) external;
+}

package/contracts/interfaces/IFundRecovery.sol

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+/**
+ * @title IFundRecovery
+ * @author LayerZero Labs (tinom.eth)
+ * @custom:version 1.0.0
+ * @notice Interface for ERC20 contracts implementing fund recovery functionality.
+ */
+interface IFundRecovery {
+    /**
+     * @notice Recovers funds from a non-allowlisted address.
+     * @dev Only recovers from non-allowlisted `_from` address.
+     * @param _from Address to recover funds from
+     * @param _to Address to send the recovered funds to
+     * @param _amount Amount of funds to recover
+     */
+    function recoverFunds(address _from, address _to, uint256 _amount) external;
+}

package/contracts/interfaces/IPause.sol

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+/**
+ * @title IPause
+ * @author LayerZero Labs (tinom.eth)
+ * @custom:version 1.0.0
+ * @notice Interface for the `Pause` contract.
+ */
+interface IPause {
+    /**
+     * @notice Emitted when the pause status is set.
+     * @param paused Pause status
+     */
+    event PauseSet(bool paused);
+
+    /**
+     * @notice Thrown when attempting to perform an action while paused.
+     */
+    error Paused();
+
+    /**
+     * @notice Thrown when setting pause state is idempotent (no change).
+     * @param isPaused Whether system is paused
+     */
+    error PauseStateIdempotent(bool isPaused);
+
+    /**
+     * @notice Checks if the system is paused.
+     * @return paused Whether the system is paused
+     */
+    function isPaused() external view returns (bool paused);
+
+    /**
+     * @notice Pauses the system.
+     */
+    function pause() external;
+
+    /**
+     * @notice Unpauses the system.
+     */
+    function unpause() external;
+}

package/contracts/interfaces/IPauseByID.sol

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+/**
+ * @title IPauseByID
+ * @author LayerZero Labs (tinom.eth)
+ * @custom:version 1.0.0
+ * @notice Interface for the `PauseByID` contract.
+ */
+interface IPauseByID {
+    /**
+     * @notice Configuration for a pause setting.
+     * @param paused Whether transfers are paused for this ID
+     * @param enabled False to fallback to the default pause setting
+     */
+    struct PauseConfig {
+        bool paused;
+        bool enabled;
+    }
+
+    /**
+     * @notice Parameter for setting pause state.
+     * @param id Destination ID
+     * @param paused Whether transfers are paused for this ID
+     * @param enabled Whether the pause config is enabled for the destination
+     */
+    struct SetPausedParam {
+        uint256 id;
+        bool paused;
+        bool enabled;
+    }
+
+    /**
+     * @notice Emitted when the pause status is set for a specific destination ID.
+     * @param id Destination ID
+     * @param paused Whether transfers are paused for this ID
+     * @param enabled Whether the pause config is enabled for the destination
+     */
+    event PauseSet(uint256 id, bool paused, bool enabled);
+
+    /**
+     * @notice Emitted when the default pause status is set.
+     * @param paused Default pause status
+     */
+    event DefaultPauseSet(bool paused);
+
+    /**
+     * @notice Thrown when attempting to transfer while paused.
+     * @param id Destination ID that is paused
+     */
+    error Paused(uint256 id);
+
+    /**
+     * @notice Thrown when setting pause state is idempotent (no change).
+     * @param isPaused Whether transfers are paused
+     */
+    error PauseStateIdempotent(bool isPaused);
+
+    /**
+     * @notice Checks if transfers to a destination ID are paused.
+     * @param _id Destination ID
+     * @return paused Whether transfers are paused
+     */
+    function isPaused(uint256 _id) external view returns (bool paused);
+
+    /**
+     * @notice Retrieves default pause status used if no pause config is set for the destination ID.
+     * @return paused Default pause status
+     */
+    function defaultPaused() external view returns (bool paused);
+
+    /**
+     * @notice Retrieves the configured pause setting for a given ID.
+     * @param _id Destination ID
+     * @return config Configured pause setting for the destination ID
+     */
+    function pauseConfig(uint256 _id) external view returns (PauseConfig memory config);
+
+    /**
+     * @notice Set the default pause status for all destinations.
+     * @param _paused New default pause status
+     */
+    function setDefaultPaused(bool _paused) external;
+
+    /**
+     * @notice Sets the pause status for an array of destination IDs.
+     * @param _params Array of pause configurations
+     */
+    function setPaused(SetPausedParam[] calldata _params) external;
+}

package/contracts/interfaces/IRateLimiter.sol

@@ -0,0 +1,244 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.22;
+
+/**
+ * @title IRateLimiter
+ * @author LayerZero Labs (tinom.eth)
+ * @custom:version 1.0.0
+ * @notice Interface for the `RateLimiter` contract.
+ */
+interface IRateLimiter {
+    /**
+     * @notice Global configuration for the rate limiter.
+     * @param useGlobalState Whether to use global state for the rate limiter, instead of per-ID rules
+     * @param isGloballyDisabled Whether the rate limiter is globally disabled
+     */
+    struct RateLimitGlobalConfig {
+        bool useGlobalState;
+        bool isGloballyDisabled;
+    }
+
+    /**
+     * @notice Rate limit state for a given ID.
+     * @param outboundUsage Current usage of the outbound rate limit
+     * @param inboundUsage Current usage of the inbound rate limit
+     * @param lastUpdated Last updated timestamp
+     * @param configBitmap Bitmap of the rate limit configuration
+     * @param outboundLimit Limit of the outbound rate limit
+     * @param outboundWindow Window of the outbound rate limit
+     * @param inboundLimit Limit of the inbound rate limit
+     * @param inboundWindow Window of the inbound rate limit
+     */
+    struct RateLimit {
+        uint96 outboundUsage;
+        uint96 inboundUsage;
+        uint40 lastUpdated;
+        uint24 configBitmap;
+        uint96 outboundLimit;
+        uint32 outboundWindow;
+        uint96 inboundLimit;
+        uint32 inboundWindow;
+    }
+
+    /**
+     * @notice Rate limit configuration.
+     * @param overrideDefaultConfig Whether to override the default configuration
+     * @param outboundEnabled Whether the outbound rate limit is enabled
+     * @param inboundEnabled Whether the inbound rate limit is enabled
+     * @param netAccountingEnabled Whether net accounting is enabled
+     * @param addressExemptionEnabled Whether address exemption is enabled
+     * @param outboundLimit Limit of the outbound rate limit
+     * @param inboundLimit Limit of the inbound rate limit
+     * @param outboundWindow Window of the outbound rate limit
+     * @param inboundWindow Window of the inbound rate limit
+     */
+    struct RateLimitConfig {
+        bool overrideDefaultConfig;
+        bool outboundEnabled;
+        bool inboundEnabled;
+        bool netAccountingEnabled;
+        bool addressExemptionEnabled;
+        uint96 outboundLimit;
+        uint96 inboundLimit;
+        uint32 outboundWindow;
+        uint32 inboundWindow;
+    }
+
+    /**
+     * @notice Parameters for setting a rate limit configuration.
+     * @param id ID of the rate limit configuration
+     * @param config Configuration to set
+     */
+    struct SetRateLimitConfigParam {
+        uint256 id;
+        RateLimitConfig config;
+    }
+
+    /**
+     * @notice Rate limit state.
+     * @param outboundUsage Current usage of the outbound rate limit
+     * @param inboundUsage Current usage of the inbound rate limit
+     * @param lastUpdated Last updated timestamp
+     */
+    struct RateLimitState {
+        uint96 outboundUsage;
+        uint96 inboundUsage;
+        uint40 lastUpdated;
+    }
+
+    /**
+     * @notice Parameters for setting a rate limit state.
+     * @param id ID of the rate limit state
+     * @param state State to set
+     */
+    struct SetRateLimitStateParam {
+        uint256 id;
+        RateLimitState state;
+    }
+
+    /**
+     * @notice Parameter for setting a rate limit address exemption.
+     * @param user Address of the user
+     * @param isExempt Whether the address should be exempt from the rate limit
+     */
+    struct SetRateLimitAddressExemptionParam {
+        address user;
+        bool isExempt;
+    }
+
+    /**
+     * @notice Emitted when the global rate limiter configuration is updated.
+     * @param globalConfig Updated global configuration
+     */
+    event RateLimitGlobalConfigUpdated(RateLimitGlobalConfig globalConfig);
+
+    /**
+     * @notice Emitted when a rate limit configuration is updated.
+     * @param id ID of the rate limit configuration
+     * @param config Parameters for the updated rate limit configuration
+     */
+    event RateLimitConfigUpdated(uint256 indexed id, RateLimitConfig config);
+
+    /**
+     * @notice Emitted when a rate limit state is updated.
+     * @param id ID of the rate limit state
+     * @param state Parameters for the updated rate limit state
+     */
+    event RateLimitStateUpdated(uint256 indexed id, RateLimitState state);
+
+    /**
+     * @notice Emitted when a rate limit address exemption is updated.
+     * @param user Address of the user
+     * @param isExempt Whether the address is exempt
+     */
+    event RateLimitAddressExemptionUpdated(address indexed user, bool isExempt);
+
+    /**
+     * @notice Thrown when the scaled decimals are invalid.
+     * @param scaledDecimals Scaled decimals
+     */
+    error InvalidScaledDecimals(uint8 scaledDecimals);
+
+    /**
+     * @notice Thrown when a rate limit state is set to a timestamp in the future.
+     * @param lastUpdated Last updated timestamp
+     * @param currentTimestamp Current block timestamp
+     */
+    error LastUpdatedInFuture(uint40 lastUpdated, uint40 currentTimestamp);
+
+    /**
+     * @notice Thrown when a rate limit is exceeded.
+     * @param availableAmount Remaining capacity of the rate limit
+     * @param requestedAmount Amount requested
+     */
+    error RateLimitExceeded(uint256 availableAmount, uint256 requestedAmount);
+
+    /**
+     * @notice Thrown when a user is already in the desired state (exempt or not exempt).
+     * @param user User address
+     * @param isExempt Whether the address is exempt
+     */
+    error ExemptionStateIdempotent(address user, bool isExempt);
+
+    /**
+     * @notice Returns the global configuration for the rate limiter.
+     * @return globalConfig Global configuration
+     */
+    function getRateLimitGlobalConfig() external view returns (RateLimitGlobalConfig memory globalConfig);
+
+    /**
+     * @notice Returns the rate limit state and configuration for a given ID.
+     * @dev May return unscaled state if `SCALE_DECIMALS` is set, use `getRateLimitUsages` for scaled values.
+     * @dev Reads the rate limit state from storage without checking defaults.
+     * @param _id ID of the rate limit
+     * @return rateLimit Rate limit state and configuration
+     */
+    function rateLimits(uint256 _id) external view returns (RateLimit memory rateLimit);
+
+    /**
+     * @notice Returns the address exemption status for a given user.
+     * @param _user Address of the user
+     * @return isExempt Whether the address is exempt
+     */
+    function isRateLimitAddressExempt(address _user) external view returns (bool isExempt);
+
+    /**
+     * @notice Calculates decayed usages and capacities for a rate limit.
+     * @dev Potentially scaled up by `SCALE_DECIMALS`.
+     * @dev Checks config and falls back to default if necessary.
+     * @dev If a rate limit is disabled in a given direction, the available amount is `type(uint256).max`.
+     * @param _id ID of the rate limit
+     * @return outboundUsage Scaled current usage of the outbound rate limit
+     * @return outboundAvailableAmount Scaled capacity of the outbound rate limit
+     * @return inboundUsage Scaled current usage of the inbound rate limit
+     * @return inboundAvailableAmount Scaled capacity of the inbound rate limit
+     */
+    function getRateLimitUsages(
+        uint256 _id
+    )
+        external
+        view
+        returns (
+            uint256 outboundUsage,
+            uint256 outboundAvailableAmount,
+            uint256 inboundUsage,
+            uint256 inboundAvailableAmount
+        );
+
+    /**
+     * @notice Sets the global configuration for the rate limiter.
+     * @param _globalConfig Global configuration to set
+     */
+    function setRateLimitGlobalConfig(RateLimitGlobalConfig memory _globalConfig) external;
+
+    /**
+     * @notice Sets ID-specific configurations for the rate limiter.
+     * @dev Configurations must be significantly larger than windows to avoid precision loss when calculating decays.
+     * @dev It does not checkpoint rate limits for the configured IDs.
+     * @param _params Array of configurations to set
+     */
+    function setRateLimitConfigs(SetRateLimitConfigParam[] calldata _params) external;
+
+    /**
+     * @notice Sets ID-specific states for the rate limiter.
+     * @dev States cannot be set to a timestamp in the future.
+     * @param _params Array of states to set
+     */
+    function setRateLimitStates(SetRateLimitStateParam[] calldata _params) external;
+
+    /**
+     * @notice Sets address exemptions for the rate limiter.
+     * @dev Only in effect if `addressExemptionEnabled` is true for an ID.
+     * @param _exemptions Array of exemptions to set
+     */
+    function setRateLimitAddressExemptions(SetRateLimitAddressExemptionParam[] calldata _exemptions) external;
+
+    /**
+     * @notice Checkpoints rate limits for multiple IDs, updating decayed usages to storage.
+     * @dev Recommended to be called atomically before setting new limits or windows through `setRateLimitConfigs`, to
+     *      avoid retroactively applying decays. Alternatively, `setRateLimitStates` can be called to explicitly set
+     *      the desired usages.
+     * @param _ids Array of rate limit IDs to checkpoint
+     */
+    function checkpointRateLimits(uint256[] calldata _ids) external;
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@layerzerolabs/utils-evm-contracts",
+  "version": "0.2.74",
+  "private": false,
+  "description": "LayerZero Labs reference EVM utility implementations",
+  "license": "MIT",
+  "devDependencies": {
+    "@layerzerolabs/test-devtools-evm-foundry": "8.0.1",
+    "@layerzerolabs/toolbox-foundry": "^0.1.13",
+    "@openzeppelin/contracts": "^5.0.2",
+    "solhint": "^6.0.1",
+    "@layerzerolabs/solhint-configuration": "0.2.74",
+    "@layerzerolabs/typescript-configuration": "0.2.74",
+    "@layerzerolabs/vm-tooling-evm": "0.2.74",
+    "@layerzerolabs/tsup-configuration": "0.2.74"
+  },
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "externalRepoConfig": {
+    "targets": [
+      "audit-external",
+      "monorepo-external"
+    ]
+  },
+  "scripts": {
+    "clean-artifacts": "rm -rf artifacts* cache hh-cache*",
+    "lint": "solhint --config solhint.config.js 'contracts/**/*.sol' --fix --noPrompt"
+  }
+}

package/solhint.config.js

@@ -0,0 +1,3 @@
+const baseConfig = require('@layerzerolabs/solhint-configuration');
+
+module.exports = baseConfig;