arr00-testing-oz-contracts 0.0.0 → 5.8.0

package/utils/RateLimiter.sol

@@ -0,0 +1,310 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Contracts (last updated v5.8.0) (utils/RateLimiter.sol)
+pragma solidity ^0.8.27;
+
+import {Math} from "./math/Math.sol";
+import {SafeCast} from "./math/SafeCast.sol";
+import {Checkpoints} from "./structs/Checkpoints.sol";
+import {Time} from "./types/Time.sol";
+
+/**
+ * @dev This library provides primitives for limiting the rate at which an action can be performed.
+ *
+ * Two complementary strategies are available, each represented by a storage struct that the consumer keeps in its
+ * own storage:
+ *
+ * - {RefillingBucket}: a token bucket that refills linearly over time. The bucket starts full; each consumption
+ *   draws from it, and it is refilled over time. Suitable when the protected resource regenerates continuously and bursts
+ *   of size up to the bucket's capacity are allowed. Storage cost is constant regardless of consumption history.
+ *
+ * - {SlidingWindow}: a moving-window counter that caps the cumulative consumption over any `window`-second
+ *   interval. Suitable when a strict cap on usage within a rolling window is required. Each successful consumption
+ *   appends a checkpoint, making it a more expensive option with a larger storage footprint.
+ *
+ * === Limiter vs. entries
+ *
+ * Each storage struct is a _limiter_: it pairs a single, shared configuration (the `window`, together with the
+ * `capacity` of a {RefillingBucket} or the `limit` of a {SlidingWindow}) with a mapping of independent _entries_
+ * keyed by `bytes32`. Every operation takes a `key` and applies only to that entry.
+ *
+ * All entries in a limiter share the same configuration, but each entry tracks its own consumption independently:
+ * consuming from one `key` never affects the availability of another. This lets a single limiter enforce the same
+ * rate limit separately across many subjects--for example one entry per caller, per token, or per protected
+ * function--simply by choosing the `key` accordingly. Using a constant `key` (e.g. `bytes32(0)`) reduces the
+ * limiter to a single global rate limit.
+ *
+ * Configuration is changed for the whole limiter at once with {updateSettings}, whereas {state}, {used},
+ * {available}, {tryConsume}, {consume} and {reset} act on the individual entry identified by `key`.
+ *
+ * Example usage (one independent rate limit per caller, all sharing the same capacity and window):
+ *
+ * ```solidity
+ * using RateLimiter for RateLimiter.RefillingBucket;
+ *
+ * RateLimiter.RefillingBucket private _rateLimiter;
+ *
+ * function withdraw(uint256 amount) external {
+ *     _rateLimiter.consume(bytes32(uint256(uint160(msg.sender))), amount);
+ *     // ...
+ * }
+ * ```
+ */
+library RateLimiter {
+    using Checkpoints for Checkpoints.Trace208;
+
+    /**
+     * @dev The requested quantity exceeds the currently available capacity.
+     */
+    error RateLimitExceeded();
+
+    // ================================================ RefillingBucket ================================================
+    /**
+     * @dev The per-`key` state of a {RefillingBucket} entry.
+     *
+     * `lastUsed` and `lastTimepoint` record the used quantity and the time it was recorded at the entry's last
+     * update. The current state is reconstructed lazily from these two fields on read (see {state}), keeping storage
+     * cost constant at one packed slot per entry regardless of how many times the entry has been consumed.
+     *
+     * WARNING: Manually updating any of the parameters may result in incorrect behavior. Only interact with the
+     * {RefillingBucket} through the dedicated functions.
+     */
+    struct RefillingBucketItem {
+        uint208 _lastUsed;
+        uint48 _lastTimepoint;
+    }
+
+    /**
+     * @dev A token-bucket limiter: shared configuration plus a mapping of independent per-`key` buckets.
+     *
+     * `capacity` and `window` are shared by every entry: each bucket has a maximum `capacity` and refills at a rate
+     * of `capacity / window` per second, so that an empty bucket fully refills in `window` seconds. `items` holds the
+     * individual buckets, each tracking its own consumption under its `key` (see {RefillingBucketItem}).
+     *
+     * WARNING: Manually updating any of the parameters may result in incorrect behavior. Only interact with the
+     * {RefillingBucket} through the dedicated functions.
+     */
+    struct RefillingBucket {
+        uint208 _capacity;
+        uint48 _window;
+        mapping(bytes32 key => RefillingBucketItem) _items;
+    }
+
+    /**
+     * @dev Returns the current `used` and `available` quantities for the `key` bucket, accounting for the time-based
+     * refill that has accrued since that entry's last update.
+     *
+     * NOTE: A `window` of 0 is treated as 1 second in the refill computation: the effective refill rate becomes
+     * `capacity` per second, and an uninitialized limiter (`capacity = window = 0`) reports as an empty bucket.
+     */
+    function state(
+        RefillingBucket storage self,
+        bytes32 key
+    ) internal view returns (uint256 used_, uint256 available_) {
+        uint208 capacity_ = self._capacity; // cache
+        RefillingBucketItem storage item_ = self._items[key]; // cache
+
+        used_ = Math.saturatingSub(
+            item_._lastUsed,
+            Math.mulDiv(Time.timestamp() - item_._lastTimepoint, capacity_, Math.max(self._window, 1))
+        );
+        available_ = Math.saturatingSub(capacity_, used_);
+    }
+
+    /**
+     * @dev Returns the currently used quantity. See {state-struct-RateLimiter-RefillingBucket-bytes32}.
+     */
+    function used(RefillingBucket storage self, bytes32 key) internal view returns (uint256 used_) {
+        (used_, ) = state(self, key);
+    }
+
+    /**
+     * @dev Returns the currently available quantity. See {state-struct-RateLimiter-RefillingBucket-bytes32}.
+     */
+    function available(RefillingBucket storage self, bytes32 key) internal view returns (uint256 available_) {
+        (, available_) = state(self, key);
+    }
+
+    /**
+     * @dev Attempts to consume `quantity` from the `key` bucket. Returns `true` on success, `false` if that entry's
+     * available quantity is insufficient.
+     *
+     * A `quantity` of 0 is always accepted and does not modify storage.
+     */
+    function tryConsume(RefillingBucket storage self, bytes32 key, uint256 quantity) internal returns (bool) {
+        if (quantity == 0) {
+            return true;
+        }
+        (uint256 used_, uint256 available_) = state(self, key);
+        if (quantity <= available_) {
+            self._items[key] = RefillingBucketItem({
+                _lastTimepoint: Time.timestamp(),
+                _lastUsed: SafeCast.toUint208(used_ + quantity)
+            });
+            return true;
+        } else {
+            return false;
+        }
+    }
+
+    /**
+     * @dev Consumes `quantity` from the `key` bucket. Reverts with {RateLimitExceeded} if that entry's available
+     * quantity is insufficient. See {tryConsume-struct-RateLimiter-RefillingBucket-bytes32-uint256}.
+     */
+    function consume(RefillingBucket storage self, bytes32 key, uint256 quantity) internal {
+        require(tryConsume(self, key, quantity), RateLimitExceeded());
+    }
+
+    /**
+     * @dev Resets the `key` bucket to a fully-available state. Other entries are unaffected.
+     */
+    function reset(RefillingBucket storage self, bytes32 key) internal {
+        delete self._items[key];
+    }
+
+    /**
+     * @dev Updates the shared `capacity` and `window` of the limiter, affecting every entry.
+     *
+     * NOTE: The new settings will retroactively affect all the keys. The new replenishing rate (capacity / window) is
+     * applied from the last update timepoint of each key. Therefore, if the new settings correspond to a faster
+     * replenishing rate, some quantity may become available immediately. Conversely, if the new settings correspond
+     * to a slower replenishing rate, some quantity that would otherwise be available immediately may become
+     * unavailable. This side effect can be mitigated by calling {sync} on the relevant keys before updating the
+     * settings. There is no mechanism to automatically sync all the keys in a single operation.
+     */
+    function updateSettings(RefillingBucket storage self, uint48 newWindow, uint208 newCapacity) internal {
+        self._capacity = newCapacity;
+        self._window = newWindow;
+    }
+
+    /**
+     * @dev Refreshes the `key` bucket by applying the accrued refill since its last update timepoint to `lastUsed`
+     * and `lastTimepoint`, effectively moving that entry's timepoint forward to now. This can be used to mitigate the
+     * side effect of {updateSettings-struct-RateLimiter-RefillingBucket-uint48-uint208} when the replenishing rate is
+     * modified. It must be called per key; there is no mechanism to sync all entries at once.
+     */
+    function sync(RefillingBucket storage self, bytes32 key) internal {
+        self._items[key] = RefillingBucketItem({_lastTimepoint: Time.timestamp(), _lastUsed: uint208(used(self, key))});
+    }
+
+    // ================================================= SlidingWindow =================================================
+    /**
+     * @dev A moving-window limiter: shared configuration plus a mapping of independent per-`key` counters.
+     *
+     * `limit` and `window` are shared by every entry, and cap the cumulative consumption of each entry within any
+     * `window`-second interval. `items` holds the individual counters: each entry keeps its own checkpoint history
+     * (a `Checkpoints.Trace208`) under its `key`, recording the running cumulative total. An entry's current `used`
+     * quantity is the difference between its cumulative total at `block.timestamp` and at `block.timestamp - window`.
+     *
+     * NOTE: The cumulative total of each entry is stored as a `uint208`. Once it reaches `2²⁰⁸ - 1`, further
+     * consumption of that entry will revert in {SafeCast}. This bound is unreachable for any realistic `limit`, but
+     * consumers should be aware of it.
+     *
+     * NOTE: An entry's checkpoint history is not a reliable log of past consumptions--previous entries may be
+     * overwritten in place. The storage footprint of an entry grows with the number of
+     * {tryConsume-struct-RateLimiter-SlidingWindow-bytes32-uint256} calls on that `key` that succeed with a non-zero
+     * `quantity`.
+     *
+     * WARNING: Manually updating any of the parameters may result in incorrect behavior. Only interact with the
+     * {SlidingWindow} through the dedicated functions.
+     */
+    struct SlidingWindow {
+        uint208 _limit;
+        uint48 _window;
+        mapping(bytes32 key => Checkpoints.Trace208) _items;
+    }
+
+    /**
+     * @dev Returns the current `used` and `available` quantities for the `key` counter, computed as that entry's
+     * cumulative consumption over the last `window` seconds.
+     *
+     * NOTE: A `window` of 0 is treated as 1 second in the rolling-window lookup, and an uninitialized limiter
+     * (`limit = window = 0`) reports as a counter with no available quantity.
+     */
+    function state(SlidingWindow storage self, bytes32 key) internal view returns (uint256 used_, uint256 available_) {
+        Checkpoints.Trace208 storage item_ = self._items[key]; // cache
+
+        used_ = Math.saturatingSub(
+            item_.latest(),
+            item_.upperLookupRecent(uint48(Math.saturatingSub(Time.timestamp(), Math.max(self._window, 1))))
+        );
+        available_ = Math.saturatingSub(self._limit, used_);
+    }
+
+    /**
+     * @dev Returns the quantity currently used by the `key` counter within the sliding window. See
+     * {state-struct-RateLimiter-SlidingWindow-bytes32}.
+     */
+    function used(SlidingWindow storage self, bytes32 key) internal view returns (uint256 used_) {
+        (used_, ) = state(self, key);
+    }
+
+    /**
+     * @dev Returns the quantity currently available to the `key` counter within the rolling window. See
+     * {state-struct-RateLimiter-SlidingWindow-bytes32}.
+     */
+    function available(SlidingWindow storage self, bytes32 key) internal view returns (uint256 available_) {
+        (, available_) = state(self, key);
+    }
+
+    /**
+     * @dev Attempts to record a consumption of `quantity` against the `key` counter. Returns `true` on success,
+     * `false` if that entry's available quantity within the current window is insufficient.
+     *
+     * A `quantity` of 0 is always accepted and does not modify storage.
+     */
+    function tryConsume(SlidingWindow storage self, bytes32 key, uint256 quantity) internal returns (bool) {
+        if (quantity == 0) {
+            return true;
+        }
+        (uint256 used_, uint256 available_) = state(self, key);
+        if (quantity <= available_) {
+            if (used_ == 0) {
+                reset(self, key);
+            }
+            Checkpoints.Trace208 storage item_ = self._items[key]; // cache
+            item_.push(Time.timestamp(), SafeCast.toUint208(item_.latest() + quantity));
+            return true;
+        } else {
+            return false;
+        }
+    }
+
+    /**
+     * @dev Records a consumption of `quantity` against the `key` counter. Reverts with {RateLimitExceeded} if that
+     * entry's available quantity within the current window is insufficient. See
+     * {tryConsume-struct-RateLimiter-SlidingWindow-bytes32-uint256}.
+     */
+    function consume(SlidingWindow storage self, bytes32 key, uint256 quantity) internal {
+        require(tryConsume(self, key, quantity), RateLimitExceeded());
+    }
+
+    /**
+     * @dev Resets the `key` counter to a fully-available state. Other entries are unaffected.
+     *
+     * NOTE: This will reset that entry's entire history, meaning it can also be used to recover from the cumulative
+     * total approaching the `uint208` ceiling. The underlying storage slots holding past checkpoints are not zeroed
+     * out. As a consequence, there is no gas refunded, but future
+     * {consume-struct-RateLimiter-SlidingWindow-bytes32-uint256} and
+     * {tryConsume-struct-RateLimiter-SlidingWindow-bytes32-uint256} operations are cheaper from reusing "dirty" slots.
+     */
+    function reset(SlidingWindow storage self, bytes32 key) internal {
+        Checkpoints.Checkpoint208[] storage trace = self._items[key]._checkpoints;
+        assembly ("memory-safe") {
+            sstore(trace.slot, 0)
+        }
+    }
+
+    /**
+     * @dev Updates the shared `limit` and `window` of the limiter, affecting every entry.
+     *
+     * NOTE: Changing the settings does not modify the recorded consumption history; it only changes how that
+     * history is interpreted. Increasing `window` acts on whatever history each key still has: a key that
+     * retained older consumptions has them brought back into the larger window, while a key whose history was
+     * reset before the update (incidentally or deliberately) is unaffected. Decreasing `window` conversely
+     * causes older consumptions to drop out sooner.
+     */
+    function updateSettings(SlidingWindow storage self, uint48 newWindow, uint208 newLimit) internal {
+        self._limit = newLimit;
+        self._window = newWindow;
+    }
+}

package/utils/ReentrancyGuard.sol

@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Contracts (last updated v5.5.0) (utils/ReentrancyGuard.sol)
+
+pragma solidity ^0.8.20;
+
+import {StorageSlot} from "./StorageSlot.sol";
+
+/**
+ * @dev Contract module that helps prevent reentrant calls to a function.
+ *
+ * Inheriting from `ReentrancyGuard` will make the {nonReentrant} modifier
+ * available, which can be applied to functions to make sure there are no nested
+ * (reentrant) calls to them.
+ *
+ * Note that because there is a single `nonReentrant` guard, functions marked as
+ * `nonReentrant` may not call one another. This can be worked around by making
+ * those functions `private`, and then adding `external` `nonReentrant` entry
+ * points to them.
+ *
+ * TIP: If EIP-1153 (transient storage) is available on the chain you're deploying at,
+ * consider using {ReentrancyGuardTransient} instead.
+ *
+ * TIP: If you would like to learn more about reentrancy and alternative ways
+ * to protect against it, check out our blog post
+ * https://blog.openzeppelin.com/reentrancy-after-istanbul/[Reentrancy After Istanbul].
+ *
+ * IMPORTANT: Deprecated. This storage-based reentrancy guard will be removed and replaced
+ * by the {ReentrancyGuardTransient} variant in v6.0.
+ *
+ * @custom:stateless
+ */
+abstract contract ReentrancyGuard {
+    using StorageSlot for bytes32;
+
+    // keccak256(abi.encode(uint256(keccak256("openzeppelin.storage.ReentrancyGuard")) - 1)) & ~bytes32(uint256(0xff))
+    bytes32 private constant REENTRANCY_GUARD_STORAGE =
+        0x9b779b17422d0df92223018b32b4d1fa46e071723d6817e2486d003becc55f00;
+
+    // Booleans are more expensive than uint256 or any type that takes up a full
+    // word because each write operation emits an extra SLOAD to first read the
+    // slot's contents, replace the bits taken up by the boolean, and then write
+    // back. This is the compiler's defense against contract upgrades and
+    // pointer aliasing, and it cannot be disabled.
+
+    // The values being non-zero value makes deployment a bit more expensive,
+    // but in exchange the refund on every call to nonReentrant will be lower in
+    // amount. Since refunds are capped to a percentage of the total
+    // transaction's gas, it is best to keep them low in cases like this one, to
+    // increase the likelihood of the full refund coming into effect.
+    uint256 private constant NOT_ENTERED = 1;
+    uint256 private constant ENTERED = 2;
+
+    /**
+     * @dev Unauthorized reentrant call.
+     */
+    error ReentrancyGuardReentrantCall();
+
+    constructor() {
+        _reentrancyGuardStorageSlot().getUint256Slot().value = NOT_ENTERED;
+    }
+
+    /**
+     * @dev Prevents a contract from calling itself, directly or indirectly.
+     * Calling a `nonReentrant` function from another `nonReentrant`
+     * function is not supported. It is possible to prevent this from happening
+     * by making the `nonReentrant` function external, and making it call a
+     * `private` function that does the actual work.
+     */
+    modifier nonReentrant() {
+        _nonReentrantBefore();
+        _;
+        _nonReentrantAfter();
+    }
+
+    /**
+     * @dev A `view` only version of {nonReentrant}. Use to block view functions
+     * from being called, preventing reading from inconsistent contract state.
+     *
+     * CAUTION: This is a "view" modifier and does not change the reentrancy
+     * status. Use it only on view functions. For payable or non-payable functions,
+     * use the standard {nonReentrant} modifier instead.
+     */
+    modifier nonReentrantView() {
+        _nonReentrantBeforeView();
+        _;
+    }
+
+    function _nonReentrantBeforeView() private view {
+        if (_reentrancyGuardEntered()) {
+            revert ReentrancyGuardReentrantCall();
+        }
+    }
+
+    function _nonReentrantBefore() private {
+        // On the first call to nonReentrant, _status will be NOT_ENTERED
+        _nonReentrantBeforeView();
+
+        // Any calls to nonReentrant after this point will fail
+        _reentrancyGuardStorageSlot().getUint256Slot().value = ENTERED;
+    }
+
+    function _nonReentrantAfter() private {
+        // By storing the original value once again, a refund is triggered (see
+        // https://eips.ethereum.org/EIPS/eip-2200)
+        _reentrancyGuardStorageSlot().getUint256Slot().value = NOT_ENTERED;
+    }
+
+    /**
+     * @dev Returns true if the reentrancy guard is currently set to "entered", which indicates there is a
+     * `nonReentrant` function in the call stack.
+     */
+    function _reentrancyGuardEntered() internal view returns (bool) {
+        return _reentrancyGuardStorageSlot().getUint256Slot().value == ENTERED;
+    }
+
+    function _reentrancyGuardStorageSlot() internal pure virtual returns (bytes32) {
+        return REENTRANCY_GUARD_STORAGE;
+    }
+}

package/utils/ReentrancyGuardTransient.sol

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Contracts (last updated v5.5.0) (utils/ReentrancyGuardTransient.sol)
+
+pragma solidity ^0.8.24;
+
+import {TransientSlot} from "./TransientSlot.sol";
+
+/**
+ * @dev Variant of {ReentrancyGuard} that uses transient storage.
+ *
+ * NOTE: This variant only works on networks where EIP-1153 is available.
+ *
+ * _Available since v5.1._
+ *
+ * @custom:stateless
+ */
+abstract contract ReentrancyGuardTransient {
+    using TransientSlot for *;
+
+    // keccak256(abi.encode(uint256(keccak256("openzeppelin.storage.ReentrancyGuard")) - 1)) & ~bytes32(uint256(0xff))
+    bytes32 private constant REENTRANCY_GUARD_STORAGE =
+        0x9b779b17422d0df92223018b32b4d1fa46e071723d6817e2486d003becc55f00;
+
+    /**
+     * @dev Unauthorized reentrant call.
+     */
+    error ReentrancyGuardReentrantCall();
+
+    /**
+     * @dev Prevents a contract from calling itself, directly or indirectly.
+     * Calling a `nonReentrant` function from another `nonReentrant`
+     * function is not supported. It is possible to prevent this from happening
+     * by making the `nonReentrant` function external, and making it call a
+     * `private` function that does the actual work.
+     */
+    modifier nonReentrant() {
+        _nonReentrantBefore();
+        _;
+        _nonReentrantAfter();
+    }
+
+    /**
+     * @dev A `view` only version of {nonReentrant}. Use to block view functions
+     * from being called, preventing reading from inconsistent contract state.
+     *
+     * CAUTION: This is a "view" modifier and does not change the reentrancy
+     * status. Use it only on view functions. For payable or non-payable functions,
+     * use the standard {nonReentrant} modifier instead.
+     */
+    modifier nonReentrantView() {
+        _nonReentrantBeforeView();
+        _;
+    }
+
+    function _nonReentrantBeforeView() private view {
+        if (_reentrancyGuardEntered()) {
+            revert ReentrancyGuardReentrantCall();
+        }
+    }
+
+    function _nonReentrantBefore() private {
+        // On the first call to nonReentrant, REENTRANCY_GUARD_STORAGE.asBoolean().tload() will be false
+        _nonReentrantBeforeView();
+
+        // Any calls to nonReentrant after this point will fail
+        _reentrancyGuardStorageSlot().asBoolean().tstore(true);
+    }
+
+    function _nonReentrantAfter() private {
+        _reentrancyGuardStorageSlot().asBoolean().tstore(false);
+    }
+
+    /**
+     * @dev Returns true if the reentrancy guard is currently set to "entered", which indicates there is a
+     * `nonReentrant` function in the call stack.
+     */
+    function _reentrancyGuardEntered() internal view returns (bool) {
+        return _reentrancyGuardStorageSlot().asBoolean().tload();
+    }
+
+    function _reentrancyGuardStorageSlot() internal pure virtual returns (bytes32) {
+        return REENTRANCY_GUARD_STORAGE;
+    }
+}

package/utils/RelayedCall.sol

@@ -0,0 +1,145 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Contracts (last updated v5.7.0) (utils/RelayedCall.sol)
+
+pragma solidity ^0.8.20;
+
+/**
+ * @dev Library for performing external calls through dynamically deployed relay contracts that hide the original
+ * caller's address from the target contract. This pattern is used in ERC-4337's EntryPoint for account factory
+ * calls and ERC-6942 for safe factory interactions.
+ *
+ * When privileged contracts need to make arbitrary external calls based on user input, calling the target directly
+ * can be risky because the target sees the privileged contract as `msg.sender` and could exploit this trust
+ * relationship. This library solves this by deploying minimal relay contracts that act as intermediaries, ensuring
+ * the target only sees the unprivileged relay address as `msg.sender`.
+ *
+ * For example, instead of `target.call(data)` where the target sees this contract as `msg.sender`, use
+ * {relayCall} where the target sees a relay address as `msg.sender`.
+ *
+ * NOTE: This library uses the PUSH0 opcode that was introduced in the Shanghai hardfork. While this instruction is
+ * now widely supported, developers using the library on exotic chains should verify that their target chain has
+ * supports for EIP-3855.
+ */
+library RelayedCall {
+    /// @dev Relays a call to the target contract through a dynamically deployed relay contract.
+    function relayCall(address target, bytes memory data) internal returns (bool success, bytes memory retData) {
+        return relayCall(target, 0, data, bytes32(0));
+    }
+
+    /// @dev Same as {relayCall-address-bytes} but with a value.
+    function relayCall(
+        address target,
+        uint256 value,
+        bytes memory data
+    ) internal returns (bool success, bytes memory retData) {
+        return relayCall(target, value, data, bytes32(0));
+    }
+
+    /// @dev Same as {relayCall-address-bytes} but with a salt.
+    function relayCall(
+        address target,
+        bytes memory data,
+        bytes32 salt
+    ) internal returns (bool success, bytes memory retData) {
+        return relayCall(target, 0, data, salt);
+    }
+
+    /// @dev Same as {relayCall-address-bytes} but with a salt and a value.
+    function relayCall(
+        address target,
+        uint256 value,
+        bytes memory data,
+        bytes32 salt
+    ) internal returns (bool success, bytes memory retData) {
+        return getRelayer(salt).call{value: value}(abi.encodePacked(target, data));
+    }
+
+    /// @dev Same as {getRelayer} but with a `bytes32(0)` default salt.
+    function getRelayer() internal returns (address) {
+        return getRelayer(bytes32(0));
+    }
+
+    /// @dev Returns the relayer address for a given salt.
+    function getRelayer(bytes32 salt) internal returns (address relayer) {
+        // [Relayer details]
+        //
+        // deployment prefix: 60475f8160095f39f3
+        // deployed bytecode: 73<addr>331460133611166022575f5ffd5b6014360360145f375f5f601436035f345f3560601c5af13d5f5f3e5f3d91604557fd5bf3
+        //
+        // offset | bytecode    | opcode         | stack
+        // -------|-------------|----------------|--------
+        // 0x0000 | 73<factory> | push20 <addr>  | <factory>
+        // 0x0015 | 33          | address        | <caller> <factory>
+        // 0x0016 | 14          | eq             | access
+        // 0x0017 | 6013        | push1 0x13     | 0x13 access
+        // 0x0019 | 36          | calldatasize   | cds 0x13 access
+        // 0x001a | 11          | gt             | (cds>0x13) access
+        // 0x001b | 16          | and            | (cds>0x13 && access)
+        // 0x001c | 6022        | push1 0x22     | 0x22 (cds>0x13 && access)
+        // 0x001e | 57          | jumpi          |
+        // 0x001f | 5f          | push0          | 0
+        // 0x0020 | 5f          | push0          | 0 0
+        // 0x0021 | fd          | revert         |
+        // 0x0022 | 5b          | jumpdest       |
+        // 0x0023 | 6014        | push1 0x14     | 0x14
+        // 0x0025 | 36          | calldatasize   | cds 0x14
+        // 0x0026 | 03          | sub            | (cds-0x14)
+        // 0x0027 | 6014        | push1 0x14     | 0x14 (cds-0x14)
+        // 0x0029 | 5f          | push0          | 0 0x14 (cds-0x14)
+        // 0x002a | 37          | calldatacopy   |
+        // 0x002b | 5f          | push0          | 0
+        // 0x002c | 5f          | push0          | 0 0
+        // 0x002d | 6014        | push1 0x14     | 0x14 0 0
+        // 0x002f | 36          | calldatasize   | cds 0x14 0 0
+        // 0x0030 | 03          | sub            | (cds-0x14) 0 0
+        // 0x0031 | 5f          | push0          | 0 (cds-0x14) 0 0
+        // 0x0032 | 34          | callvalue      | value 0 (cds-0x14) 0 0
+        // 0x0033 | 5f          | push0          | 0 value 0 (cds-0x14) 0 0
+        // 0x0034 | 35          | calldataload   | cd[0] value 0 (cds-0x14) 0 0
+        // 0x0035 | 6060        | push1 0x60     | 0x60 cd[0] value 0 (cds-0x14) 0 0
+        // 0x0037 | 1c          | shr            | target value 0 (cds-0x14) 0 0
+        // 0x0038 | 5a          | gas            | gas target value 0 (cds-0x14) 0 0
+        // 0x0039 | f1          | call           | suc
+        // 0x003a | 3d          | returndatasize | rds suc
+        // 0x003b | 5f          | push0          | 0 rds suc
+        // 0x003c | 5f          | push0          | 0 0 rds suc
+        // 0x003d | 3e          | returndatacopy | suc
+        // 0x003e | 5f          | push0          | 0 suc
+        // 0x003f | 3d          | returndatasize | rds 0 suc
+        // 0x0040 | 91          | swap2          | suc 0 rds
+        // 0x0041 | 6045        | push1 0x45     | 0x45 suc 0 rds
+        // 0x0043 | 57          | jumpi          | 0 rds
+        // 0x0044 | fd          | revert         |
+        // 0x0045 | 5b          | jumpdest       | 0 rds
+        // 0x0046 | f3          | return         |
+
+        assembly ("memory-safe") {
+            let fmp := mload(0x40)
+
+            // build initcode at FMP
+            mstore(add(fmp, 0x46), 0x60145f375f5f601436035f345f3560601c5af13d5f5f3e5f3d91604557fd5bf3)
+            mstore(add(fmp, 0x26), 0x331460133611166022575f5ffd5b60143603)
+            mstore(add(fmp, 0x14), address())
+            mstore(add(fmp, 0x00), 0x60475f8160095f39f373)
+            let initcodehash := keccak256(add(fmp, 0x16), 0x50)
+
+            // compute create2 address
+            mstore(0x40, initcodehash)
+            mstore(0x20, salt)
+            mstore(0x00, address())
+            mstore8(0x0b, 0xff)
+            relayer := and(keccak256(0x0b, 0x55), shr(96, not(0)))
+
+            // is relayer not yet deployed, deploy it
+            if iszero(extcodesize(relayer)) {
+                if iszero(create2(0, add(fmp, 0x16), 0x50, salt)) {
+                    returndatacopy(fmp, 0x00, returndatasize())
+                    revert(fmp, returndatasize())
+                }
+            }
+
+            // cleanup fmp space used as scratch
+            mstore(0x40, fmp)
+        }
+    }
+}