// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.0.0) (utils/Address.sol)

pragma solidity ^0.8.20;

/**
 * @dev Collection of functions related to the address type
 */
library Address {
    /**
     * @dev The ETH balance of the account is not enough to perform the operation.
     */
    error AddressInsufficientBalance(address account);

    /**
     * @dev There's no code at `target` (it is not a contract).
     */
    error AddressEmptyCode(address target);

    /**
     * @dev A call to an address target failed. The target may have reverted.
     */
    error FailedInnerCall();

    /**
     * @dev Replacement for Solidity's `transfer`: sends `amount` wei to
     * `recipient`, forwarding all available gas and reverting on errors.
     *
     * https://eips.ethereum.org/EIPS/eip-1884[EIP1884] increases the gas cost
     * of certain opcodes, possibly making contracts go over the 2300 gas limit
     * imposed by `transfer`, making them unable to receive funds via
     * `transfer`. {sendValue} removes this limitation.
     *
     * https://consensys.net/diligence/blog/2019/09/stop-using-soliditys-transfer-now/[Learn more].
     *
     * IMPORTANT: because control is transferred to `recipient`, care must be
     * taken to not create reentrancy vulnerabilities. Consider using
     * {ReentrancyGuard} or the
     * https://solidity.readthedocs.io/en/v0.8.20/security-considerations.html#use-the-checks-effects-interactions-pattern[checks-effects-interactions pattern].
     */
    function sendValue(address payable recipient, uint256 amount) internal {
        if (address(this).balance < amount) {
            revert AddressInsufficientBalance(address(this));
        }

        (bool success, ) = recipient.call{value: amount}("");
        if (!success) {
            revert FailedInnerCall();
        }
    }

    /**
     * @dev Performs a Solidity function call using a low level `call`. A
     * plain `call` is an unsafe replacement for a function call: use this
     * function instead.
     *
     * If `target` reverts with a revert reason or custom error, it is bubbled
     * up by this function (like regular Solidity function calls). However, if
     * the call reverted with no returned reason, this function reverts with a
     * {FailedInnerCall} error.
     *
     * Returns the raw returned data. To convert to the expected return value,
     * use https://solidity.readthedocs.io/en/latest/units-and-global-variables.html?highlight=abi.decode#abi-encoding-and-decoding-functions[`abi.decode`].
     *
     * Requirements:
     *
     * - `target` must be a contract.
     * - calling `target` with `data` must not revert.
     */
    function functionCall(address target, bytes memory data) internal returns (bytes memory) {
        return functionCallWithValue(target, data, 0);
    }

    /**
     * @dev Same as {xref-Address-functionCall-address-bytes-}[`functionCall`],
     * but also transferring `value` wei to `target`.
     *
     * Requirements:
     *
     * - the calling contract must have an ETH balance of at least `value`.
     * - the called Solidity function must be `payable`.
     */
    function functionCallWithValue(address target, bytes memory data, uint256 value) internal returns (bytes memory) {
        if (address(this).balance < value) {
            revert AddressInsufficientBalance(address(this));
        }
        (bool success, bytes memory returndata) = target.call{value: value}(data);
        return verifyCallResultFromTarget(target, success, returndata);
    }

    /**
     * @dev Same as {xref-Address-functionCall-address-bytes-}[`functionCall`],
     * but performing a static call.
     */
    function functionStaticCall(address target, bytes memory data) internal view returns (bytes memory) {
        (bool success, bytes memory returndata) = target.staticcall(data);
        return verifyCallResultFromTarget(target, success, returndata);
    }

    /**
     * @dev Same as {xref-Address-functionCall-address-bytes-}[`functionCall`],
     * but performing a delegate call.
     */
    function functionDelegateCall(address target, bytes memory data) internal returns (bytes memory) {
        (bool success, bytes memory returndata) = target.delegatecall(data);
        return verifyCallResultFromTarget(target, success, returndata);
    }

    /**
     * @dev Tool to verify that a low level call to smart-contract was successful, and reverts if the target
     * was not a contract or bubbling up the revert reason (falling back to {FailedInnerCall}) in case of an
     * unsuccessful call.
     */
    function verifyCallResultFromTarget(
        address target,
        bool success,
        bytes memory returndata
    ) internal view returns (bytes memory) {
        if (!success) {
            _revert(returndata);
        } else {
            // only check if target is a contract if the call was successful and the return data is empty
            // otherwise we already know that it was a contract
            if (returndata.length == 0 && target.code.length == 0) {
                revert AddressEmptyCode(target);
            }
            return returndata;
        }
    }

    /**
     * @dev Tool to verify that a low level call was successful, and reverts if it wasn't, either by bubbling the
     * revert reason or with a default {FailedInnerCall} error.
     */
    function verifyCallResult(bool success, bytes memory returndata) internal pure returns (bytes memory) {
        if (!success) {
            _revert(returndata);
        } else {
            return returndata;
        }
    }

    /**
     * @dev Reverts with returndata if present. Otherwise reverts with {FailedInnerCall}.
     */
    function _revert(bytes memory returndata) private pure {
        // Look for revert reason and bubble it up if present
        if (returndata.length > 0) {
            // The easiest way to bubble the revert reason is using memory via assembly
            /// @solidity memory-safe-assembly
            assembly {
                let returndata_size := mload(returndata)
                revert(add(32, returndata), returndata_size)
            }
        } else {
            revert FailedInnerCall();
        }
    }
}

// SPDX-License-Identifier: MIT
pragma solidity >=0.8.19;

import "./Errors.sol" as CastingErrors;
import { MAX_UINT128, MAX_UINT40 } from "../Common.sol";
import { uMAX_SD1x18 } from "../sd1x18/Constants.sol";
import { SD1x18 } from "../sd1x18/ValueType.sol";
import { uMAX_SD59x18 } from "../sd59x18/Constants.sol";
import { SD59x18 } from "../sd59x18/ValueType.sol";
import { uMAX_UD2x18 } from "../ud2x18/Constants.sol";
import { UD2x18 } from "../ud2x18/ValueType.sol";
import { UD60x18 } from "./ValueType.sol";

/// @notice Casts a UD60x18 number into SD1x18.
/// @dev Requirements:
/// - x must be less than or equal to `uMAX_SD1x18`.
function intoSD1x18(UD60x18 x) pure returns (SD1x18 result) {
    uint256 xUint = UD60x18.unwrap(x);
    if (xUint > uint256(int256(uMAX_SD1x18))) {
        revert CastingErrors.PRBMath_UD60x18_IntoSD1x18_Overflow(x);
    }
    result = SD1x18.wrap(int64(uint64(xUint)));
}

/// @notice Casts a UD60x18 number into UD2x18.
/// @dev Requirements:
/// - x must be less than or equal to `uMAX_UD2x18`.
function intoUD2x18(UD60x18 x) pure returns (UD2x18 result) {
    uint256 xUint = UD60x18.unwrap(x);
    if (xUint > uMAX_UD2x18) {
        revert CastingErrors.PRBMath_UD60x18_IntoUD2x18_Overflow(x);
    }
    result = UD2x18.wrap(uint64(xUint));
}

/// @notice Casts a UD60x18 number into SD59x18.
/// @dev Requirements:
/// - x must be less than or equal to `uMAX_SD59x18`.
function intoSD59x18(UD60x18 x) pure returns (SD59x18 result) {
    uint256 xUint = UD60x18.unwrap(x);
    if (xUint > uint256(uMAX_SD59x18)) {
        revert CastingErrors.PRBMath_UD60x18_IntoSD59x18_Overflow(x);
    }
    result = SD59x18.wrap(int256(xUint));
}

/// @notice Casts a UD60x18 number into uint128.
/// @dev This is basically an alias for {unwrap}.
function intoUint256(UD60x18 x) pure returns (uint256 result) {
    result = UD60x18.unwrap(x);
}

/// @notice Casts a UD60x18 number into uint128.
/// @dev Requirements:
/// - x must be less than or equal to `MAX_UINT128`.
function intoUint128(UD60x18 x) pure returns (uint128 result) {
    uint256 xUint = UD60x18.unwrap(x);
    if (xUint > MAX_UINT128) {
        revert CastingErrors.PRBMath_UD60x18_IntoUint128_Overflow(x);
    }
    result = uint128(xUint);
}

/// @notice Casts a UD60x18 number into uint40.
/// @dev Requirements:
/// - x must be less than or equal to `MAX_UINT40`.
function intoUint40(UD60x18 x) pure returns (uint40 result) {
    uint256 xUint = UD60x18.unwrap(x);
    if (xUint > MAX_UINT40) {
        revert CastingErrors.PRBMath_UD60x18_IntoUint40_Overflow(x);
    }
    result = uint40(xUint);
}

/// @notice Alias for {wrap}.
function ud(uint256 x) pure returns (UD60x18 result) {
    result = UD60x18.wrap(x);
}

/// @notice Alias for {wrap}.
function ud60x18(uint256 x) pure returns (UD60x18 result) {
    result = UD60x18.wrap(x);
}

/// @notice Unwraps a UD60x18 number into uint256.
function unwrap(UD60x18 x) pure returns (uint256 result) {
    result = UD60x18.unwrap(x);
}

/// @notice Wraps a uint256 number into the UD60x18 value type.
function wrap(uint256 x) pure returns (UD60x18 result) {
    result = UD60x18.wrap(x);
}

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.0.0) (utils/structs/Checkpoints.sol)
// This file was procedurally generated from scripts/generate/templates/Checkpoints.js.

pragma solidity ^0.8.20;

import {Math} from "../math/Math.sol";

/**
 * @dev This library defines the `Trace*` struct, for checkpointing values as they change at different points in
 * time, and later looking up past values by block number. See {Votes} as an example.
 *
 * To create a history of checkpoints define a variable type `Checkpoints.Trace*` in your contract, and store a new
 * checkpoint for the current transaction block using the {push} function.
 */
library Checkpoints {
    /**
     * @dev A value was attempted to be inserted on a past checkpoint.
     */
    error CheckpointUnorderedInsertion();

    struct Trace224 {
        Checkpoint224[] _checkpoints;
    }

    struct Checkpoint224 {
        uint32 _key;
        uint224 _value;
    }

    /**
     * @dev Pushes a (`key`, `value`) pair into a Trace224 so that it is stored as the checkpoint.
     *
     * Returns previous value and new value.
     *
     * IMPORTANT: Never accept `key` as a user input, since an arbitrary `type(uint32).max` key set will disable the
     * library.
     */
    function push(Trace224 storage self, uint32 key, uint224 value) internal returns (uint224, uint224) {
        return _insert(self._checkpoints, key, value);
    }

    /**
     * @dev Returns the value in the first (oldest) checkpoint with key greater or equal than the search key, or zero if
     * there is none.
     */
    function lowerLookup(Trace224 storage self, uint32 key) internal view returns (uint224) {
        uint256 len = self._checkpoints.length;
        uint256 pos = _lowerBinaryLookup(self._checkpoints, key, 0, len);
        return pos == len ? 0 : _unsafeAccess(self._checkpoints, pos)._value;
    }

    /**
     * @dev Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero
     * if there is none.
     */
    function upperLookup(Trace224 storage self, uint32 key) internal view returns (uint224) {
        uint256 len = self._checkpoints.length;
        uint256 pos = _upperBinaryLookup(self._checkpoints, key, 0, len);
        return pos == 0 ? 0 : _unsafeAccess(self._checkpoints, pos - 1)._value;
    }

    /**
     * @dev Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero
     * if there is none.
     *
     * NOTE: This is a variant of {upperLookup} that is optimised to find "recent" checkpoint (checkpoints with high
     * keys).
     */
    function upperLookupRecent(Trace224 storage self, uint32 key) internal view returns (uint224) {
        uint256 len = self._checkpoints.length;

        uint256 low = 0;
        uint256 high = len;

        if (len > 5) {
            uint256 mid = len - Math.sqrt(len);
            if (key < _unsafeAccess(self._checkpoints, mid)._key) {
                high = mid;
            } else {
                low = mid + 1;
            }
        }

        uint256 pos = _upperBinaryLookup(self._checkpoints, key, low, high);

        return pos == 0 ? 0 : _unsafeAccess(self._checkpoints, pos - 1)._value;
    }

    /**
     * @dev Returns the value in the most recent checkpoint, or zero if there are no checkpoints.
     */
    function latest(Trace224 storage self) internal view returns (uint224) {
        uint256 pos = self._checkpoints.length;
        return pos == 0 ? 0 : _unsafeAccess(self._checkpoints, pos - 1)._value;
    }

    /**
     * @dev Returns whether there is a checkpoint in the structure (i.e. it is not empty), and if so the key and value
     * in the most recent checkpoint.
     */
    function latestCheckpoint(Trace224 storage self) internal view returns (bool exists, uint32 _key, uint224 _value) {
        uint256 pos = self._checkpoints.length;
        if (pos == 0) {
            return (false, 0, 0);
        } else {
            Checkpoint224 memory ckpt = _unsafeAccess(self._checkpoints, pos - 1);
            return (true, ckpt._key, ckpt._value);
        }
    }

    /**
     * @dev Returns the number of checkpoint.
     */
    function length(Trace224 storage self) internal view returns (uint256) {
        return self._checkpoints.length;
    }

    /**
     * @dev Returns checkpoint at given position.
     */
    function at(Trace224 storage self, uint32 pos) internal view returns (Checkpoint224 memory) {
        return self._checkpoints[pos];
    }

    /**
     * @dev Pushes a (`key`, `value`) pair into an ordered list of checkpoints, either by inserting a new checkpoint,
     * or by updating the last one.
     */
    function _insert(Checkpoint224[] storage self, uint32 key, uint224 value) private returns (uint224, uint224) {
        uint256 pos = self.length;

        if (pos > 0) {
            // Copying to memory is important here.
            Checkpoint224 memory last = _unsafeAccess(self, pos - 1);

            // Checkpoint keys must be non-decreasing.
            if (last._key > key) {
                revert CheckpointUnorderedInsertion();
            }

            // Update or push new checkpoint
            if (last._key == key) {
                _unsafeAccess(self, pos - 1)._value = value;
            } else {
                self.push(Checkpoint224({_key: key, _value: value}));
            }
            return (last._value, value);
        } else {
            self.push(Checkpoint224({_key: key, _value: value}));
            return (0, value);
        }
    }

    /**
     * @dev Return the index of the last (most recent) checkpoint with key lower or equal than the search key, or `high`
     * if there is none. `low` and `high` define a section where to do the search, with inclusive `low` and exclusive
     * `high`.
     *
     * WARNING: `high` should not be greater than the array's length.
     */
    function _upperBinaryLookup(
        Checkpoint224[] storage self,
        uint32 key,
        uint256 low,
        uint256 high
    ) private view returns (uint256) {
        while (low < high) {
            uint256 mid = Math.average(low, high);
            if (_unsafeAccess(self, mid)._key > key) {
                high = mid;
            } else {
                low = mid + 1;
            }
        }
        return high;
    }

    /**
     * @dev Return the index of the first (oldest) checkpoint with key is greater or equal than the search key, or
     * `high` if there is none. `low` and `high` define a section where to do the search, with inclusive `low` and
     * exclusive `high`.
     *
     * WARNING: `high` should not be greater than the array's length.
     */
    function _lowerBinaryLookup(
        Checkpoint224[] storage self,
        uint32 key,
        uint256 low,
        uint256 high
    ) private view returns (uint256) {
        while (low < high) {
            uint256 mid = Math.average(low, high);
            if (_unsafeAccess(self, mid)._key < key) {
                low = mid + 1;
            } else {
                high = mid;
            }
        }
        return high;
    }

    /**
     * @dev Access an element of the array without performing bounds check. The position is assumed to be within bounds.
     */
    function _unsafeAccess(
        Checkpoint224[] storage self,
        uint256 pos
    ) private pure returns (Checkpoint224 storage result) {
        assembly {
            mstore(0, self.slot)
            result.slot := add(keccak256(0, 0x20), pos)
        }
    }

    struct Trace208 {
        Checkpoint208[] _checkpoints;
    }

    struct Checkpoint208 {
        uint48 _key;
        uint208 _value;
    }

    /**
     * @dev Pushes a (`key`, `value`) pair into a Trace208 so that it is stored as the checkpoint.
     *
     * Returns previous value and new value.
     *
     * IMPORTANT: Never accept `key` as a user input, since an arbitrary `type(uint48).max` key set will disable the
     * library.
     */
    function push(Trace208 storage self, uint48 key, uint208 value) internal returns (uint208, uint208) {
        return _insert(self._checkpoints, key, value);
    }

    /**
     * @dev Returns the value in the first (oldest) checkpoint with key greater or equal than the search key, or zero if
     * there is none.
     */
    function lowerLookup(Trace208 storage self, uint48 key) internal view returns (uint208) {
        uint256 len = self._checkpoints.length;
        uint256 pos = _lowerBinaryLookup(self._checkpoints, key, 0, len);
        return pos == len ? 0 : _unsafeAccess(self._checkpoints, pos)._value;
    }

    /**
     * @dev Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero
     * if there is none.
     */
    function upperLookup(Trace208 storage self, uint48 key) internal view returns (uint208) {
        uint256 len = self._checkpoints.length;
        uint256 pos = _upperBinaryLookup(self._checkpoints, key, 0, len);
        return pos == 0 ? 0 : _unsafeAccess(self._checkpoints, pos - 1)._value;
    }

    /**
     * @dev Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero
     * if there is none.
     *
     * NOTE: This is a variant of {upperLookup} that is optimised to find "recent" checkpoint (checkpoints with high
     * keys).
     */
    function upperLookupRecent(Trace208 storage self, uint48 key) internal view returns (uint208) {
        uint256 len = self._checkpoints.length;

        uint256 low = 0;
        uint256 high = len;

        if (len > 5) {
            uint256 mid = len - Math.sqrt(len);
            if (key < _unsafeAccess(self._checkpoints, mid)._key) {
                high = mid;
            } else {
                low = mid + 1;
            }
        }

        uint256 pos = _upperBinaryLookup(self._checkpoints, key, low, high);

        return pos == 0 ? 0 : _unsafeAccess(self._checkpoints, pos - 1)._value;
    }

    /**
     * @dev Returns the value in the most recent checkpoint, or zero if there are no checkpoints.
     */
    function latest(Trace208 storage self) internal view returns (uint208) {
        uint256 pos = self._checkpoints.length;
        return pos == 0 ? 0 : _unsafeAccess(self._checkpoints, pos - 1)._value;
    }

    /**
     * @dev Returns whether there is a checkpoint in the structure (i.e. it is not empty), and if so the key and value
     * in the most recent checkpoint.
     */
    function latestCheckpoint(Trace208 storage self) internal view returns (bool exists, uint48 _key, uint208 _value) {
        uint256 pos = self._checkpoints.length;
        if (pos == 0) {
            return (false, 0, 0);
        } else {
            Checkpoint208 memory ckpt = _unsafeAccess(self._checkpoints, pos - 1);
            return (true, ckpt._key, ckpt._value);
        }
    }

    /**
     * @dev Returns the number of checkpoint.
     */
    function length(Trace208 storage self) internal view returns (uint256) {
        return self._checkpoints.length;
    }

    /**
     * @dev Returns checkpoint at given position.
     */
    function at(Trace208 storage self, uint32 pos) internal view returns (Checkpoint208 memory) {
        return self._checkpoints[pos];
    }

    /**
     * @dev Pushes a (`key`, `value`) pair into an ordered list of checkpoints, either by inserting a new checkpoint,
     * or by updating the last one.
     */
    function _insert(Checkpoint208[] storage self, uint48 key, uint208 value) private returns (uint208, uint208) {
        uint256 pos = self.length;

        if (pos > 0) {
            // Copying to memory is important here.
            Checkpoint208 memory last = _unsafeAccess(self, pos - 1);

            // Checkpoint keys must be non-decreasing.
            if (last._key > key) {
                revert CheckpointUnorderedInsertion();
            }

            // Update or push new checkpoint
            if (last._key == key) {
                _unsafeAccess(self, pos - 1)._value = value;
            } else {
                self.push(Checkpoint208({_key: key, _value: value}));
            }
            return (last._value, value);
        } else {
            self.push(Checkpoint208({_key: key, _value: value}));
            return (0, value);
        }
    }

    /**
     * @dev Return the index of the last (most recent) checkpoint with key lower or equal than the search key, or `high`
     * if there is none. `low` and `high` define a section where to do the search, with inclusive `low` and exclusive
     * `high`.
     *
     * WARNING: `high` should not be greater than the array's length.
     */
    function _upperBinaryLookup(
        Checkpoint208[] storage self,
        uint48 key,
        uint256 low,
        uint256 high
    ) private view returns (uint256) {
        while (low < high) {
            uint256 mid = Math.average(low, high);
            if (_unsafeAccess(self, mid)._key > key) {
                high = mid;
            } else {
                low = mid + 1;
            }
        }
        return high;
    }

    /**
     * @dev Return the index of the first (oldest) checkpoint with key is greater or equal than the search key, or
     * `high` if there is none. `low` and `high` define a section where to do the search, with inclusive `low` and
     * exclusive `high`.
     *
     * WARNING: `high` should not be greater than the array's length.
     */
    function _lowerBinaryLookup(
        Checkpoint208[] storage self,
        uint48 key,
        uint256 low,
        uint256 high
    ) private view returns (uint256) {
        while (low < high) {
            uint256 mid = Math.average(low, high);
            if (_unsafeAccess(self, mid)._key < key) {
                low = mid + 1;
            } else {
                high = mid;
            }
        }
        return high;
    }

    /**
     * @dev Access an element of the array without performing bounds check. The position is assumed to be within bounds.
     */
    function _unsafeAccess(
        Checkpoint208[] storage self,
        uint256 pos
    ) private pure returns (Checkpoint208 storage result) {
        assembly {
            mstore(0, self.slot)
            result.slot := add(keccak256(0, 0x20), pos)
        }
    }

    struct Trace160 {
        Checkpoint160[] _checkpoints;
    }

    struct Checkpoint160 {
        uint96 _key;
        uint160 _value;
    }

    /**
     * @dev Pushes a (`key`, `value`) pair into a Trace160 so that it is stored as the checkpoint.
     *
     * Returns previous value and new value.
     *
     * IMPORTANT: Never accept `key` as a user input, since an arbitrary `type(uint96).max` key set will disable the
     * library.
     */
    function push(Trace160 storage self, uint96 key, uint160 value) internal returns (uint160, uint160) {
        return _insert(self._checkpoints, key, value);
    }

    /**
     * @dev Returns the value in the first (oldest) checkpoint with key greater or equal than the search key, or zero if
     * there is none.
     */
    function lowerLookup(Trace160 storage self, uint96 key) internal view returns (uint160) {
        uint256 len = self._checkpoints.length;
        uint256 pos = _lowerBinaryLookup(self._checkpoints, key, 0, len);
        return pos == len ? 0 : _unsafeAccess(self._checkpoints, pos)._value;
    }

    /**
     * @dev Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero
     * if there is none.
     */
    function upperLookup(Trace160 storage self, uint96 key) internal view returns (uint160) {
        uint256 len = self._checkpoints.length;
        uint256 pos = _upperBinaryLookup(self._checkpoints, key, 0, len);
        return pos == 0 ? 0 : _unsafeAccess(self._checkpoints, pos - 1)._value;
    }

    /**
     * @dev Returns the value in the last (most recent) checkpoint with key lower or equal than the search key, or zero
     * if there is none.
     *
     * NOTE: This is a variant of {upperLookup} that is optimised to find "recent" checkpoint (checkpoints with high
     * keys).
     */
    function upperLookupRecent(Trace160 storage self, uint96 key) internal view returns (uint160) {
        uint256 len = self._checkpoints.length;

        uint256 low = 0;
        uint256 high = len;

        if (len > 5) {
            uint256 mid = len - Math.sqrt(len);
            if (key < _unsafeAccess(self._checkpoints, mid)._key) {
                high = mid;
            } else {
                low = mid + 1;
            }
        }

        uint256 pos = _upperBinaryLookup(self._checkpoints, key, low, high);

        return pos == 0 ? 0 : _unsafeAccess(self._checkpoints, pos - 1)._value;
    }

    /**
     * @dev Returns the value in the most recent checkpoint, or zero if there are no checkpoints.
     */
    function latest(Trace160 storage self) internal view returns (uint160) {
        uint256 pos = self._checkpoints.length;
        return pos == 0 ? 0 : _unsafeAccess(self._checkpoints, pos - 1)._value;
    }

    /**
     * @dev Returns whether there is a checkpoint in the structure (i.e. it is not empty), and if so the key and value
     * in the most recent checkpoint.
     */
    function latestCheckpoint(Trace160 storage self) internal view returns (bool exists, uint96 _key, uint160 _value) {
        uint256 pos = self._checkpoints.length;
        if (pos == 0) {
            return (false, 0, 0);
        } else {
            Checkpoint160 memory ckpt = _unsafeAccess(self._checkpoints, pos - 1);
            return (true, ckpt._key, ckpt._value);
        }
    }

    /**
     * @dev Returns the number of checkpoint.
     */
    function length(Trace160 storage self) internal view returns (uint256) {
        return self._checkpoints.length;
    }

    /**
     * @dev Returns checkpoint at given position.
     */
    function at(Trace160 storage self, uint32 pos) internal view returns (Checkpoint160 memory) {
        return self._checkpoints[pos];
    }

    /**
     * @dev Pushes a (`key`, `value`) pair into an ordered list of checkpoints, either by inserting a new checkpoint,
     * or by updating the last one.
     */
    function _insert(Checkpoint160[] storage self, uint96 key, uint160 value) private returns (uint160, uint160) {
        uint256 pos = self.length;

        if (pos > 0) {
            // Copying to memory is important here.
            Checkpoint160 memory last = _unsafeAccess(self, pos - 1);

            // Checkpoint keys must be non-decreasing.
            if (last._key > key) {
                revert CheckpointUnorderedInsertion();
            }

            // Update or push new checkpoint
            if (last._key == key) {
                _unsafeAccess(self, pos - 1)._value = value;
            } else {
                self.push(Checkpoint160({_key: key, _value: value}));
            }
            return (last._value, value);
        } else {
            self.push(Checkpoint160({_key: key, _value: value}));
            return (0, value);
        }
    }

    /**
     * @dev Return the index of the last (most recent) checkpoint with key lower or equal than the search key, or `high`
     * if there is none. `low` and `high` define a section where to do the search, with inclusive `low` and exclusive
     * `high`.
     *
     * WARNING: `high` should not be greater than the array's length.
     */
    function _upperBinaryLookup(
        Checkpoint160[] storage self,
        uint96 key,
        uint256 low,
        uint256 high
    ) private view returns (uint256) {
        while (low < high) {
            uint256 mid = Math.average(low, high);
            if (_unsafeAccess(self, mid)._key > key) {
                high = mid;
            } else {
                low = mid + 1;
            }
        }
        return high;
    }

    /**
     * @dev Return the index of the first (oldest) checkpoint with key is greater or equal than the search key, or
     * `high` if there is none. `low` and `high` define a section where to do the search, with inclusive `low` and
     * exclusive `high`.
     *
     * WARNING: `high` should not be greater than the array's length.
     */
    function _lowerBinaryLookup(
        Checkpoint160[] storage self,
        uint96 key,
        uint256 low,
        uint256 high
    ) private view returns (uint256) {
        while (low < high) {
            uint256 mid = Math.average(low, high);
            if (_unsafeAccess(self, mid)._key < key) {
                low = mid + 1;
            } else {
                high = mid;
            }
        }
        return high;
    }

    /**
     * @dev Access an element of the array without performing bounds check. The position is assumed to be within bounds.
     */
    function _unsafeAccess(
        Checkpoint160[] storage self,
        uint256 pos
    ) private pure returns (Checkpoint160 storage result) {
        assembly {
            mstore(0, self.slot)
            result.slot := add(keccak256(0, 0x20), pos)
        }
    }
}

// SPDX-License-Identifier: MIT
pragma solidity >=0.8.19;

// Common.sol
//
// Common mathematical functions used in both SD59x18 and UD60x18. Note that these global functions do not
// always operate with SD59x18 and UD60x18 numbers.

/*//////////////////////////////////////////////////////////////////////////
                                CUSTOM ERRORS
//////////////////////////////////////////////////////////////////////////*/

/// @notice Thrown when the resultant value in {mulDiv} overflows uint256.
error PRBMath_MulDiv_Overflow(uint256 x, uint256 y, uint256 denominator);

/// @notice Thrown when the resultant value in {mulDiv18} overflows uint256.
error PRBMath_MulDiv18_Overflow(uint256 x, uint256 y);

/// @notice Thrown when one of the inputs passed to {mulDivSigned} is `type(int256).min`.
error PRBMath_MulDivSigned_InputTooSmall();

/// @notice Thrown when the resultant value in {mulDivSigned} overflows int256.
error PRBMath_MulDivSigned_Overflow(int256 x, int256 y);

/*//////////////////////////////////////////////////////////////////////////
                                    CONSTANTS
//////////////////////////////////////////////////////////////////////////*/

/// @dev The maximum value a uint128 number can have.
uint128 constant MAX_UINT128 = type(uint128).max;

/// @dev The maximum value a uint40 number can have.
uint40 constant MAX_UINT40 = type(uint40).max;

/// @dev The unit number, which the decimal precision of the fixed-point types.
uint256 constant UNIT = 1e18;

/// @dev The unit number inverted mod 2^256.
uint256 constant UNIT_INVERSE = 78156646155174841979727994598816262306175212592076161876661_508869554232690281;

/// @dev The the largest power of two that divides the decimal value of `UNIT`. The logarithm of this value is the least significant
/// bit in the binary representation of `UNIT`.
uint256 constant UNIT_LPOTD = 262144;

/*//////////////////////////////////////////////////////////////////////////
                                    FUNCTIONS
//////////////////////////////////////////////////////////////////////////*/

/// @notice Calculates the binary exponent of x using the binary fraction method.
/// @dev Has to use 192.64-bit fixed-point numbers. See https://ethereum.stackexchange.com/a/96594/24693.
/// @param x The exponent as an unsigned 192.64-bit fixed-point number.
/// @return result The result as an unsigned 60.18-decimal fixed-point number.
/// @custom:smtchecker abstract-function-nondet
function exp2(uint256 x) pure returns (uint256 result) {
    unchecked {
        // Start from 0.5 in the 192.64-bit fixed-point format.
        result = 0x800000000000000000000000000000000000000000000000;

        // The following logic multiplies the result by $\sqrt{2^{-i}}$ when the bit at position i is 1. Key points:
        //
        // 1. Intermediate results will not overflow, as the starting point is 2^191 and all magic factors are under 2^65.
        // 2. The rationale for organizing the if statements into groups of 8 is gas savings. If the result of performing
        // a bitwise AND operation between x and any value in the array [0x80; 0x40; 0x20; 0x10; 0x08; 0x04; 0x02; 0x01] is 1,
        // we know that `x & 0xFF` is also 1.
        if (x & 0xFF00000000000000 > 0) {
            if (x & 0x8000000000000000 > 0) {
                result = (result * 0x16A09E667F3BCC909) >> 64;
            }
            if (x & 0x4000000000000000 > 0) {
                result = (result * 0x1306FE0A31B7152DF) >> 64;
            }
            if (x & 0x2000000000000000 > 0) {
                result = (result * 0x1172B83C7D517ADCE) >> 64;
            }
            if (x & 0x1000000000000000 > 0) {
                result = (result * 0x10B5586CF9890F62A) >> 64;
            }
            if (x & 0x800000000000000 > 0) {
                result = (result * 0x1059B0D31585743AE) >> 64;
            }
            if (x & 0x400000000000000 > 0) {
                result = (result * 0x102C9A3E778060EE7) >> 64;
            }
            if (x & 0x200000000000000 > 0) {
                result = (result * 0x10163DA9FB33356D8) >> 64;
            }
            if (x & 0x100000000000000 > 0) {
                result = (result * 0x100B1AFA5ABCBED61) >> 64;
            }
        }

        if (x & 0xFF000000000000 > 0) {
            if (x & 0x80000000000000 > 0) {
                result = (result * 0x10058C86DA1C09EA2) >> 64;
            }
            if (x & 0x40000000000000 > 0) {
                result = (result * 0x1002C605E2E8CEC50) >> 64;
            }
            if (x & 0x20000000000000 > 0) {
                result = (result * 0x100162F3904051FA1) >> 64;
            }
            if (x & 0x10000000000000 > 0) {
                result = (result * 0x1000B175EFFDC76BA) >> 64;
            }
            if (x & 0x8000000000000 > 0) {
                result = (result * 0x100058BA01FB9F96D) >> 64;
            }
            if (x & 0x4000000000000 > 0) {
                result = (result * 0x10002C5CC37DA9492) >> 64;
            }
            if (x & 0x2000000000000 > 0) {
                result = (result * 0x1000162E525EE0547) >> 64;
            }
            if (x & 0x1000000000000 > 0) {
                result = (result * 0x10000B17255775C04) >> 64;
            }
        }

        if (x & 0xFF0000000000 > 0) {
            if (x & 0x800000000000 > 0) {
                result = (result * 0x1000058B91B5BC9AE) >> 64;
            }
            if (x & 0x400000000000 > 0) {
                result = (result * 0x100002C5C89D5EC6D) >> 64;
            }
            if (x & 0x200000000000 > 0) {
                result = (result * 0x10000162E43F4F831) >> 64;
            }
            if (x & 0x100000000000 > 0) {
                result = (result * 0x100000B1721BCFC9A) >> 64;
            }
            if (x & 0x80000000000 > 0) {
                result = (result * 0x10000058B90CF1E6E) >> 64;
            }
            if (x & 0x40000000000 > 0) {
                result = (result * 0x1000002C5C863B73F) >> 64;
            }
            if (x & 0x20000000000 > 0) {
                result = (result * 0x100000162E430E5A2) >> 64;
            }
            if (x & 0x10000000000 > 0) {
                result = (result * 0x1000000B172183551) >> 64;
            }
        }

        if (x & 0xFF00000000 > 0) {
            if (x & 0x8000000000 > 0) {
                result = (result * 0x100000058B90C0B49) >> 64;
            }
            if (x & 0x4000000000 > 0) {
                result = (result * 0x10000002C5C8601CC) >> 64;
            }
            if (x & 0x2000000000 > 0) {
                result = (result * 0x1000000162E42FFF0) >> 64;
            }
            if (x & 0x1000000000 > 0) {
                result = (result * 0x10000000B17217FBB) >> 64;
            }
            if (x & 0x800000000 > 0) {
                result = (result * 0x1000000058B90BFCE) >> 64;
            }
            if (x & 0x400000000 > 0) {
                result = (result * 0x100000002C5C85FE3) >> 64;
            }
            if (x & 0x200000000 > 0) {
                result = (result * 0x10000000162E42FF1) >> 64;
            }
            if (x & 0x100000000 > 0) {
                result = (result * 0x100000000B17217F8) >> 64;
            }
        }

        if (x & 0xFF000000 > 0) {
            if (x & 0x80000000 > 0) {
                result = (result * 0x10000000058B90BFC) >> 64;
            }
            if (x & 0x40000000 > 0) {
                result = (result * 0x1000000002C5C85FE) >> 64;
            }
            if (x & 0x20000000 > 0) {
                result = (result * 0x100000000162E42FF) >> 64;
            }
            if (x & 0x10000000 > 0) {
                result = (result * 0x1000000000B17217F) >> 64;
            }
            if (x & 0x8000000 > 0) {
                result = (result * 0x100000000058B90C0) >> 64;
            }
            if (x & 0x4000000 > 0) {
                result = (result * 0x10000000002C5C860) >> 64;
            }
            if (x & 0x2000000 > 0) {
                result = (result * 0x1000000000162E430) >> 64;
            }
            if (x & 0x1000000 > 0) {
                result = (result * 0x10000000000B17218) >> 64;
            }
        }

        if (x & 0xFF0000 > 0) {
            if (x & 0x800000 > 0) {
                result = (result * 0x1000000000058B90C) >> 64;
            }
            if (x & 0x400000 > 0) {
                result = (result * 0x100000000002C5C86) >> 64;
            }
            if (x & 0x200000 > 0) {
                result = (result * 0x10000000000162E43) >> 64;
            }
            if (x & 0x100000 > 0) {
                result = (result * 0x100000000000B1721) >> 64;
            }
            if (x & 0x80000 > 0) {
                result = (result * 0x10000000000058B91) >> 64;
            }
            if (x & 0x40000 > 0) {
                result = (result * 0x1000000000002C5C8) >> 64;
            }
            if (x & 0x20000 > 0) {
                result = (result * 0x100000000000162E4) >> 64;
            }
            if (x & 0x10000 > 0) {
                result = (result * 0x1000000000000B172) >> 64;
            }
        }

        if (x & 0xFF00 > 0) {
            if (x & 0x8000 > 0) {
                result = (result * 0x100000000000058B9) >> 64;
            }
            if (x & 0x4000 > 0) {
                result = (result * 0x10000000000002C5D) >> 64;
            }
            if (x & 0x2000 > 0) {
                result = (result * 0x1000000000000162E) >> 64;
            }
            if (x & 0x1000 > 0) {
                result = (result * 0x10000000000000B17) >> 64;
            }
            if (x & 0x800 > 0) {
                result = (result * 0x1000000000000058C) >> 64;
            }
            if (x & 0x400 > 0) {
                result = (result * 0x100000000000002C6) >> 64;
            }
            if (x & 0x200 > 0) {
                result = (result * 0x10000000000000163) >> 64;
            }
            if (x & 0x100 > 0) {
                result = (result * 0x100000000000000B1) >> 64;
            }
        }

        if (x & 0xFF > 0) {
            if (x & 0x80 > 0) {
                result = (result * 0x10000000000000059) >> 64;
            }
            if (x & 0x40 > 0) {
                result = (result * 0x1000000000000002C) >> 64;
            }
            if (x & 0x20 > 0) {
                result = (result * 0x10000000000000016) >> 64;
            }
            if (x & 0x10 > 0) {
                result = (result * 0x1000000000000000B) >> 64;
            }
            if (x & 0x8 > 0) {
                result = (result * 0x10000000000000006) >> 64;
            }
            if (x & 0x4 > 0) {
                result = (result * 0x10000000000000003) >> 64;
            }
            if (x & 0x2 > 0) {
                result = (result * 0x10000000000000001) >> 64;
            }
            if (x & 0x1 > 0) {
                result = (result * 0x10000000000000001) >> 64;
            }
        }

        // In the code snippet below, two operations are executed simultaneously:
        //
        // 1. The result is multiplied by $(2^n + 1)$, where $2^n$ represents the integer part, and the additional 1
        // accounts for the initial guess of 0.5. This is achieved by subtracting from 191 instead of 192.
        // 2. The result is then converted to an unsigned 60.18-decimal fixed-point format.
        //
        // The underlying logic is based on the relationship $2^{191-ip} = 2^{ip} / 2^{191}$, where $ip$ denotes the,
        // integer part, $2^n$.
        result *= UNIT;
        result >>= (191 - (x >> 64));
    }
}

/// @notice Finds the zero-based index of the first 1 in the binary representation of x.
///
/// @dev See the note on "msb" in this Wikipedia article: https://en.wikipedia.org/wiki/Find_first_set
///
/// Each step in this implementation is equivalent to this high-level code:
///
/// ```solidity
/// if (x >= 2 ** 128) {
///     x >>= 128;
///     result += 128;
/// }
/// ```
///
/// Where 128 is replaced with each respective power of two factor. See the full high-level implementation here:
/// https://gist.github.com/PaulRBerg/f932f8693f2733e30c4d479e8e980948
///
/// The Yul instructions used below are:
///
/// - "gt" is "greater than"
/// - "or" is the OR bitwise operator
/// - "shl" is "shift left"
/// - "shr" is "shift right"
///
/// @param x The uint256 number for which to find the index of the most significant bit.
/// @return result The index of the most significant bit as a uint256.
/// @custom:smtchecker abstract-function-nondet
function msb(uint256 x) pure returns (uint256 result) {
    // 2^128
    assembly ("memory-safe") {
        let factor := shl(7, gt(x, 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF))
        x := shr(factor, x)
        result := or(result, factor)
    }
    // 2^64
    assembly ("memory-safe") {
        let factor := shl(6, gt(x, 0xFFFFFFFFFFFFFFFF))
        x := shr(factor, x)
        result := or(result, factor)
    }
    // 2^32
    assembly ("memory-safe") {
        let factor := shl(5, gt(x, 0xFFFFFFFF))
        x := shr(factor, x)
        result := or(result, factor)
    }
    // 2^16
    assembly ("memory-safe") {
        let factor := shl(4, gt(x, 0xFFFF))
        x := shr(factor, x)
        result := or(result, factor)
    }
    // 2^8
    assembly ("memory-safe") {
        let factor := shl(3, gt(x, 0xFF))
        x := shr(factor, x)
        result := or(result, factor)
    }
    // 2^4
    assembly ("memory-safe") {
        let factor := shl(2, gt(x, 0xF))
        x := shr(factor, x)
        result := or(result, factor)
    }
    // 2^2
    assembly ("memory-safe") {
        let factor := shl(1, gt(x, 0x3))
        x := shr(factor, x)
        result := or(result, factor)
    }
    // 2^1
    // No need to shift x any more.
    assembly ("memory-safe") {
        let factor := gt(x, 0x1)
        result := or(result, factor)
    }
}

/// @notice Calculates x*y÷denominator with 512-bit precision.
///
/// @dev Credits to Remco Bloemen under MIT license https://xn--2-umb.com/21/muldiv.
///
/// Notes:
/// - The result is rounded toward zero.
///
/// Requirements:
/// - The denominator must not be zero.
/// - The result must fit in uint256.
///
/// @param x The multiplicand as a uint256.
/// @param y The multiplier as a uint256.
/// @param denominator The divisor as a uint256.
/// @return result The result as a uint256.
/// @custom:smtchecker abstract-function-nondet
function mulDiv(uint256 x, uint256 y, uint256 denominator) pure returns (uint256 result) {
    // 512-bit multiply [prod1 prod0] = x * y. Compute the product mod 2^256 and mod 2^256 - 1, then use
    // use the Chinese Remainder Theorem to reconstruct the 512-bit result. The result is stored in two 256
    // variables such that product = prod1 * 2^256 + prod0.
    uint256 prod0; // Least significant 256 bits of the product
    uint256 prod1; // Most significant 256 bits of the product
    assembly ("memory-safe") {
        let mm := mulmod(x, y, not(0))
        prod0 := mul(x, y)
        prod1 := sub(sub(mm, prod0), lt(mm, prod0))
    }

    // Handle non-overflow cases, 256 by 256 division.
    if (prod1 == 0) {
        unchecked {
            return prod0 / denominator;
        }
    }

    // Make sure the result is less than 2^256. Also prevents denominator == 0.
    if (prod1 >= denominator) {
        revert PRBMath_MulDiv_Overflow(x, y, denominator);
    }

    ////////////////////////////////////////////////////////////////////////////
    // 512 by 256 division
    ////////////////////////////////////////////////////////////////////////////

    // Make division exact by subtracting the remainder from [prod1 prod0].
    uint256 remainder;
    assembly ("memory-safe") {
        // Compute remainder using the mulmod Yul instruction.
        remainder := mulmod(x, y, denominator)

        // Subtract 256 bit number from 512-bit number.
        prod1 := sub(prod1, gt(remainder, prod0))
        prod0 := sub(prod0, remainder)
    }

    unchecked {
        // Calculate the largest power of two divisor of the denominator using the unary operator ~. This operation cannot overflow
        // because the denominator cannot be zero at this point in the function execution. The result is always >= 1.
        // For more detail, see https://cs.stackexchange.com/q/138556/92363.
        uint256 lpotdod = denominator & (~denominator + 1);
        uint256 flippedLpotdod;

        assembly ("memory-safe") {
            // Factor powers of two out of denominator.
            denominator := div(denominator, lpotdod)

            // Divide [prod1 prod0] by lpotdod.
            prod0 := div(prod0, lpotdod)

            // Get the flipped value `2^256 / lpotdod`. If the `lpotdod` is zero, the flipped value is one.
            // `sub(0, lpotdod)` produces the two's complement version of `lpotdod`, which is equivalent to flipping all the bits.
            // However, `div` interprets this value as an unsigned value: https://ethereum.stackexchange.com/q/147168/24693
            flippedLpotdod := add(div(sub(0, lpotdod), lpotdod), 1)
        }

        // Shift in bits from prod1 into prod0.
        prod0 |= prod1 * flippedLpotdod;

        // Invert denominator mod 2^256. Now that denominator is an odd number, it has an inverse modulo 2^256 such
        // that denominator * inv = 1 mod 2^256. Compute the inverse by starting with a seed that is correct for
        // four bits. That is, denominator * inv = 1 mod 2^4.
        uint256 inverse = (3 * denominator) ^ 2;

        // Use the Newton-Raphson iteration to improve the precision. Thanks to Hensel's lifting lemma, this also works
        // in modular arithmetic, doubling the correct bits in each step.
        inverse *= 2 - denominator * inverse; // inverse mod 2^8
        inverse *= 2 - denominator * inverse; // inverse mod 2^16
        inverse *= 2 - denominator * inverse; // inverse mod 2^32
        inverse *= 2 - denominator * inverse; // inverse mod 2^64
        inverse *= 2 - denominator * inverse; // inverse mod 2^128
        inverse *= 2 - denominator * inverse; // inverse mod 2^256

        // Because the division is now exact we can divide by multiplying with the modular inverse of denominator.
        // This will give us the correct result modulo 2^256. Since the preconditions guarantee that the outcome is
        // less than 2^256, this is the final result. We don't need to compute the high bits of the result and prod1
        // is no longer required.
        result = prod0 * inverse;
    }
}

/// @notice Calculates x*y÷1e18 with 512-bit precision.
///
/// @dev A variant of {mulDiv} with constant folding, i.e. in which the denominator is hard coded to 1e18.
///
/// Notes:
/// - The body is purposely left uncommented; to understand how this works, see the documentation in {mulDiv}.
/// - The result is rounded toward zero.
/// - We take as an axiom that the result cannot be `MAX_UINT256` when x and y solve the following system of equations:
///
/// $$
/// \begin{cases}
///     x * y = MAX\_UINT256 * UNIT \\
///     (x * y) \% UNIT \geq \frac{UNIT}{2}
/// \end{cases}
/// $$
///
/// Requirements:
/// - Refer to the requirements in {mulDiv}.
/// - The result must fit in uint256.
///
/// @param x The multiplicand as an unsigned 60.18-decimal fixed-point number.
/// @param y The multiplier as an unsigned 60.18-decimal fixed-point number.
/// @return result The result as an unsigned 60.18-decimal fixed-point number.
/// @custom:smtchecker abstract-function-nondet
function mulDiv18(uint256 x, uint256 y) pure returns (uint256 result) {
    uint256 prod0;
    uint256 prod1;
    assembly ("memory-safe") {
        let mm := mulmod(x, y, not(0))
        prod0 := mul(x, y)
        prod1 := sub(sub(mm, prod0), lt(mm, prod0))
    }

    if (prod1 == 0) {
        unchecked {
            return prod0 / UNIT;
        }
    }

    if (prod1 >= UNIT) {
        revert PRBMath_MulDiv18_Overflow(x, y);
    }

    uint256 remainder;
    assembly ("memory-safe") {
        remainder := mulmod(x, y, UNIT)
        result :=
            mul(
                or(
                    div(sub(prod0, remainder), UNIT_LPOTD),
                    mul(sub(prod1, gt(remainder, prod0)), add(div(sub(0, UNIT_LPOTD), UNIT_LPOTD), 1))
                ),
                UNIT_INVERSE
            )
    }
}

/// @notice Calculates x*y÷denominator with 512-bit precision.
///
/// @dev This is an extension of {mulDiv} for signed numbers, which works by computing the signs and the absolute values separately.
///
/// Notes:
/// - The result is rounded toward zero.
///
/// Requirements:
/// - Refer to the requirements in {mulDiv}.
/// - None of the inputs can be `type(int256).min`.
/// - The result must fit in int256.
///
/// @param x The multiplicand as an int256.
/// @param y The multiplier as an int256.
/// @param denominator The divisor as an int256.
/// @return result The result as an int256.
/// @custom:smtchecker abstract-function-nondet
function mulDivSigned(int256 x, int256 y, int256 denominator) pure returns (int256 result) {
    if (x == type(int256).min || y == type(int256).min || denominator == type(int256).min) {
        revert PRBMath_MulDivSigned_InputTooSmall();
    }

    // Get hold of the absolute values of x, y and the denominator.
    uint256 xAbs;
    uint256 yAbs;
    uint256 dAbs;
    unchecked {
        xAbs = x < 0 ? uint256(-x) : uint256(x);
        yAbs = y < 0 ? uint256(-y) : uint256(y);
        dAbs = denominator < 0 ? uint256(-denominator) : uint256(denominator);
    }

    // Compute the absolute value of x*y÷denominator. The result must fit in int256.
    uint256 resultAbs = mulDiv(xAbs, yAbs, dAbs);
    if (resultAbs > uint256(type(int256).max)) {
        revert PRBMath_MulDivSigned_Overflow(x, y);
    }

    // Get the signs of x, y and the denominator.
    uint256 sx;
    uint256 sy;
    uint256 sd;
    assembly ("memory-safe") {
        // "sgt" is the "signed greater than" assembly instruction and "sub(0,1)" is -1 in two's complement.
        sx := sgt(x, sub(0, 1))
        sy := sgt(y, sub(0, 1))
        sd := sgt(denominator, sub(0, 1))
    }

    // XOR over sx, sy and sd. What this does is to check whether there are 1 or 3 negative signs in the inputs.
    // If there are, the result should be negative. Otherwise, it should be positive.
    unchecked {
        result = sx ^ sy ^ sd == 0 ? -int256(resultAbs) : int256(resultAbs);
    }
}

/// @notice Calculates the square root of x using the Babylonian method.
///
/// @dev See https://en.wikipedia.org/wiki/Methods_of_computing_square_roots#Babylonian_method.
///
/// Notes:
/// - If x is not a perfect square, the result is rounded down.
/// - Credits to OpenZeppelin for the explanations in comments below.
///
/// @param x The uint256 number for which to calculate the square root.
/// @return result The result as a uint256.
/// @custom:smtchecker abstract-function-nondet
function sqrt(uint256 x) pure returns (uint256 result) {
    if (x == 0) {
        return 0;
    }

    // For our first guess, we calculate the biggest power of 2 which is smaller than the square root of x.
    //
    // We know that the "msb" (most significant bit) of x is a power of 2 such that we have:
    //
    // $$
    // msb(x) <= x <= 2*msb(x)$
    // $$
    //
    // We write $msb(x)$ as $2^k$, and we get:
    //
    // $$
    // k = log_2(x)
    // $$
    //
    // Thus, we can write the initial inequality as:
    //
    // $$
    // 2^{log_2(x)} <= x <= 2*2^{log_2(x)+1} \\
    // sqrt(2^k) <= sqrt(x) < sqrt(2^{k+1}) \\
    // 2^{k/2} <= sqrt(x) < 2^{(k+1)/2} <= 2^{(k/2)+1}
    // $$
    //
    // Consequently, $2^{log_2(x) /2} is a good first approximation of sqrt(x) with at least one correct bit.
    uint256 xAux = uint256(x);
    result = 1;
    if (xAux >= 2 ** 128) {
        xAux >>= 128;
        result <<= 64;
    }
    if (xAux >= 2 ** 64) {
        xAux >>= 64;
        result <<= 32;
    }
    if (xAux >= 2 ** 32) {
        xAux >>= 32;
        result <<= 16;
    }
    if (xAux >= 2 ** 16) {
        xAux >>= 16;
        result <<= 8;
    }
    if (xAux >= 2 ** 8) {
        xAux >>= 8;
        result <<= 4;
    }
    if (xAux >= 2 ** 4) {
        xAux >>= 4;
        result <<= 2;
    }
    if (xAux >= 2 ** 2) {
        result <<= 1;
    }

    // At this point, `result` is an estimation with at least one bit of precision. We know the true value has at
    // most 128 bits, since it is the square root of a uint256. Newton's method converges quadratically (precision
    // doubles at every iteration). We thus need at most 7 iteration to turn our partial result with one bit of
    // precision into the expected uint128 result.
    unchecked {
        result = (result + x / result) >> 1;
        result = (result + x / result) >> 1;
        result = (result + x / result) >> 1;
        result = (result + x / result) >> 1;
        result = (result + x / result) >> 1;
        result = (result + x / result) >> 1;
        result = (result + x / result) >> 1;

        // If x is not a perfect square, round the result toward zero.
        uint256 roundedResult = x / result;
        if (result >= roundedResult) {
            result = roundedResult;
        }
    }
}

// SPDX-License-Identifier: UNLICENSED

pragma solidity 0.8.25;

import {UD60x18} from "@prb/math/src/UD60x18.sol";

/// @dev Pseudo-address used to represent ETH in transactions
/// This address is used to differentiate between ETH and other tokens
address constant ETH_PSEUDO_ADDRESS = 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE;

/// @dev Address of the Wrapped Ether (WETH) contract on Ethereum mainnet
address constant WETH_ADDRESS = 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2;

/// @dev Address of the Tether (USDT) contract on Ethereum mainnet
address constant USDT_ADDRESS = 0xdAC17F958D2ee523a2206206994597C13D831ec7;

/// @dev Wildcard address used for special conditions or permissions
/// Often used to represent "any address" in access control or similar contexts
address constant WILDCARD_ADDRESS = 0xFFfFfFffFFfffFFfFFfFFFFFffFFFffffFfFFFfF;

/// @dev Represents 1 Ether in the UD60x18 fixed-point format
/// Used for precise calculations involving Ether amounts
UD60x18 constant UD_ONE_ETHER = UD60x18.wrap(1 ether);

/// @dev Function selector for the internal withdraw function
/// Calculated as the first 4 bytes of the keccak256 hash of "withdraw(uint256,uint256,address)"
bytes4 constant INTERNAL_WITHDRAW_SELECTOR = bytes4(keccak256("withdraw(uint256,uint256,address)"));

/// @dev Function selector for the internal deposit function
/// Calculated as the first 4 bytes of the keccak256 hash of "deposit(uint256,uint256,bool,bool)"
bytes4 constant INTERNAL_DEPOSIT_SELECTOR = bytes4(keccak256("deposit(uint256,uint256,bool,bool)"));

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.0.1) (utils/Context.sol)

pragma solidity ^0.8.20;

/**
 * @dev Provides information about the current execution context, including the
 * sender of the transaction and its data. While these are generally available
 * via msg.sender and msg.data, they should not be accessed in such a direct
 * manner, since when dealing with meta-transactions the account sending and
 * paying for execution may not be the actual sender (as far as an application
 * is concerned).
 *
 * This contract is only required for intermediate, library-like contracts.
 */
abstract contract Context {
    function _msgSender() internal view virtual returns (address) {
        return msg.sender;
    }

    function _msgData() internal view virtual returns (bytes calldata) {
        return msg.data;
    }

    function _contextSuffixLength() internal view virtual returns (uint256) {
        return 0;
    }
}

// SPDX-License-Identifier: MIT
pragma solidity >=0.8.19;

import { uMAX_UD60x18, uUNIT } from "./Constants.sol";
import { PRBMath_UD60x18_Convert_Overflow } from "./Errors.sol";
import { UD60x18 } from "./ValueType.sol";

/// @notice Converts a UD60x18 number to a simple integer by dividing it by `UNIT`.
/// @dev The result is rounded toward zero.
/// @param x The UD60x18 number to convert.
/// @return result The same number in basic integer form.
function convert(UD60x18 x) pure returns (uint256 result) {
    result = UD60x18.unwrap(x) / uUNIT;
}

/// @notice Converts a simple integer to UD60x18 by multiplying it by `UNIT`.
///
/// @dev Requirements:
/// - x must be less than or equal to `MAX_UD60x18 / UNIT`.
///
/// @param x The basic integer to convert.
/// @param result The same number converted to UD60x18.
function convert(uint256 x) pure returns (UD60x18 result) {
    if (x > uMAX_UD60x18 / uUNIT) {
        revert PRBMath_UD60x18_Convert_Overflow(x);
    }
    unchecked {
        result = UD60x18.wrap(x * uUNIT);
    }
}

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.0.0) (utils/structs/EnumerableMap.sol)
// This file was procedurally generated from scripts/generate/templates/EnumerableMap.js.

pragma solidity ^0.8.20;

import {EnumerableSet} from "./EnumerableSet.sol";

/**
 * @dev Library for managing an enumerable variant of Solidity's
 * https://solidity.readthedocs.io/en/latest/types.html#mapping-types[`mapping`]
 * type.
 *
 * Maps have the following properties:
 *
 * - Entries are added, removed, and checked for existence in constant time
 * (O(1)).
 * - Entries are enumerated in O(n). No guarantees are made on the ordering.
 *
 * ```solidity
 * contract Example {
 *     // Add the library methods
 *     using EnumerableMap for EnumerableMap.UintToAddressMap;
 *
 *     // Declare a set state variable
 *     EnumerableMap.UintToAddressMap private myMap;
 * }
 * ```
 *
 * The following map types are supported:
 *
 * - `uint256 -> address` (`UintToAddressMap`) since v3.0.0
 * - `address -> uint256` (`AddressToUintMap`) since v4.6.0
 * - `bytes32 -> bytes32` (`Bytes32ToBytes32Map`) since v4.6.0
 * - `uint256 -> uint256` (`UintToUintMap`) since v4.7.0
 * - `bytes32 -> uint256` (`Bytes32ToUintMap`) since v4.7.0
 *
 * [WARNING]
 * ====
 * Trying to delete such a structure from storage will likely result in data corruption, rendering the structure
 * unusable.
 * See https://github.com/ethereum/solidity/pull/11843[ethereum/solidity#11843] for more info.
 *
 * In order to clean an EnumerableMap, you can either remove all elements one by one or create a fresh instance using an
 * array of EnumerableMap.
 * ====
 */
library EnumerableMap {
    using EnumerableSet for EnumerableSet.Bytes32Set;

    // To implement this library for multiple types with as little code repetition as possible, we write it in
    // terms of a generic Map type with bytes32 keys and values. The Map implementation uses private functions,
    // and user-facing implementations such as `UintToAddressMap` are just wrappers around the underlying Map.
    // This means that we can only create new EnumerableMaps for types that fit in bytes32.

    /**
     * @dev Query for a nonexistent map key.
     */
    error EnumerableMapNonexistentKey(bytes32 key);

    struct Bytes32ToBytes32Map {
        // Storage of keys
        EnumerableSet.Bytes32Set _keys;
        mapping(bytes32 key => bytes32) _values;
    }

    /**
     * @dev Adds a key-value pair to a map, or updates the value for an existing
     * key. O(1).
     *
     * Returns true if the key was added to the map, that is if it was not
     * already present.
     */
    function set(Bytes32ToBytes32Map storage map, bytes32 key, bytes32 value) internal returns (bool) {
        map._values[key] = value;
        return map._keys.add(key);
    }

    /**
     * @dev Removes a key-value pair from a map. O(1).
     *
     * Returns true if the key was removed from the map, that is if it was present.
     */
    function remove(Bytes32ToBytes32Map storage map, bytes32 key) internal returns (bool) {
        delete map._values[key];
        return map._keys.remove(key);
    }

    /**
     * @dev Returns true if the key is in the map. O(1).
     */
    function contains(Bytes32ToBytes32Map storage map, bytes32 key) internal view returns (bool) {
        return map._keys.contains(key);
    }

    /**
     * @dev Returns the number of key-value pairs in the map. O(1).
     */
    function length(Bytes32ToBytes32Map storage map) internal view returns (uint256) {
        return map._keys.length();
    }

    /**
     * @dev Returns the key-value pair stored at position `index` in the map. O(1).
     *
     * Note that there are no guarantees on the ordering of entries inside the
     * array, and it may change when more entries are added or removed.
     *
     * Requirements:
     *
     * - `index` must be strictly less than {length}.
     */
    function at(Bytes32ToBytes32Map storage map, uint256 index) internal view returns (bytes32, bytes32) {
        bytes32 key = map._keys.at(index);
        return (key, map._values[key]);
    }

    /**
     * @dev Tries to returns the value associated with `key`. O(1).
     * Does not revert if `key` is not in the map.
     */
    function tryGet(Bytes32ToBytes32Map storage map, bytes32 key) internal view returns (bool, bytes32) {
        bytes32 value = map._values[key];
        if (value == bytes32(0)) {
            return (contains(map, key), bytes32(0));
        } else {
            return (true, value);
        }
    }

    /**
     * @dev Returns the value associated with `key`. O(1).
     *
     * Requirements:
     *
     * - `key` must be in the map.
     */
    function get(Bytes32ToBytes32Map storage map, bytes32 key) internal view returns (bytes32) {
        bytes32 value = map._values[key];
        if (value == 0 && !contains(map, key)) {
            revert EnumerableMapNonexistentKey(key);
        }
        return value;
    }

    /**
     * @dev Return the an array containing all the keys
     *
     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
     * uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block.
     */
    function keys(Bytes32ToBytes32Map storage map) internal view returns (bytes32[] memory) {
        return map._keys.values();
    }

    // UintToUintMap

    struct UintToUintMap {
        Bytes32ToBytes32Map _inner;
    }

    /**
     * @dev Adds a key-value pair to a map, or updates the value for an existing
     * key. O(1).
     *
     * Returns true if the key was added to the map, that is if it was not
     * already present.
     */
    function set(UintToUintMap storage map, uint256 key, uint256 value) internal returns (bool) {
        return set(map._inner, bytes32(key), bytes32(value));
    }

    /**
     * @dev Removes a value from a map. O(1).
     *
     * Returns true if the key was removed from the map, that is if it was present.
     */
    function remove(UintToUintMap storage map, uint256 key) internal returns (bool) {
        return remove(map._inner, bytes32(key));
    }

    /**
     * @dev Returns true if the key is in the map. O(1).
     */
    function contains(UintToUintMap storage map, uint256 key) internal view returns (bool) {
        return contains(map._inner, bytes32(key));
    }

    /**
     * @dev Returns the number of elements in the map. O(1).
     */
    function length(UintToUintMap storage map) internal view returns (uint256) {
        return length(map._inner);
    }

    /**
     * @dev Returns the element stored at position `index` in the map. O(1).
     * Note that there are no guarantees on the ordering of values inside the
     * array, and it may change when more values are added or removed.
     *
     * Requirements:
     *
     * - `index` must be strictly less than {length}.
     */
    function at(UintToUintMap storage map, uint256 index) internal view returns (uint256, uint256) {
        (bytes32 key, bytes32 value) = at(map._inner, index);
        return (uint256(key), uint256(value));
    }

    /**
     * @dev Tries to returns the value associated with `key`. O(1).
     * Does not revert if `key` is not in the map.
     */
    function tryGet(UintToUintMap storage map, uint256 key) internal view returns (bool, uint256) {
        (bool success, bytes32 value) = tryGet(map._inner, bytes32(key));
        return (success, uint256(value));
    }

    /**
     * @dev Returns the value associated with `key`. O(1).
     *
     * Requirements:
     *
     * - `key` must be in the map.
     */
    function get(UintToUintMap storage map, uint256 key) internal view returns (uint256) {
        return uint256(get(map._inner, bytes32(key)));
    }

    /**
     * @dev Return the an array containing all the keys
     *
     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
     * uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block.
     */
    function keys(UintToUintMap storage map) internal view returns (uint256[] memory) {
        bytes32[] memory store = keys(map._inner);
        uint256[] memory result;

        /// @solidity memory-safe-assembly
        assembly {
            result := store
        }

        return result;
    }

    // UintToAddressMap

    struct UintToAddressMap {
        Bytes32ToBytes32Map _inner;
    }

    /**
     * @dev Adds a key-value pair to a map, or updates the value for an existing
     * key. O(1).
     *
     * Returns true if the key was added to the map, that is if it was not
     * already present.
     */
    function set(UintToAddressMap storage map, uint256 key, address value) internal returns (bool) {
        return set(map._inner, bytes32(key), bytes32(uint256(uint160(value))));
    }

    /**
     * @dev Removes a value from a map. O(1).
     *
     * Returns true if the key was removed from the map, that is if it was present.
     */
    function remove(UintToAddressMap storage map, uint256 key) internal returns (bool) {
        return remove(map._inner, bytes32(key));
    }

    /**
     * @dev Returns true if the key is in the map. O(1).
     */
    function contains(UintToAddressMap storage map, uint256 key) internal view returns (bool) {
        return contains(map._inner, bytes32(key));
    }

    /**
     * @dev Returns the number of elements in the map. O(1).
     */
    function length(UintToAddressMap storage map) internal view returns (uint256) {
        return length(map._inner);
    }

    /**
     * @dev Returns the element stored at position `index` in the map. O(1).
     * Note that there are no guarantees on the ordering of values inside the
     * array, and it may change when more values are added or removed.
     *
     * Requirements:
     *
     * - `index` must be strictly less than {length}.
     */
    function at(UintToAddressMap storage map, uint256 index) internal view returns (uint256, address) {
        (bytes32 key, bytes32 value) = at(map._inner, index);
        return (uint256(key), address(uint160(uint256(value))));
    }

    /**
     * @dev Tries to returns the value associated with `key`. O(1).
     * Does not revert if `key` is not in the map.
     */
    function tryGet(UintToAddressMap storage map, uint256 key) internal view returns (bool, address) {
        (bool success, bytes32 value) = tryGet(map._inner, bytes32(key));
        return (success, address(uint160(uint256(value))));
    }

    /**
     * @dev Returns the value associated with `key`. O(1).
     *
     * Requirements:
     *
     * - `key` must be in the map.
     */
    function get(UintToAddressMap storage map, uint256 key) internal view returns (address) {
        return address(uint160(uint256(get(map._inner, bytes32(key)))));
    }

    /**
     * @dev Return the an array containing all the keys
     *
     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
     * uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block.
     */
    function keys(UintToAddressMap storage map) internal view returns (uint256[] memory) {
        bytes32[] memory store = keys(map._inner);
        uint256[] memory result;

        /// @solidity memory-safe-assembly
        assembly {
            result := store
        }

        return result;
    }

    // AddressToUintMap

    struct AddressToUintMap {
        Bytes32ToBytes32Map _inner;
    }

    /**
     * @dev Adds a key-value pair to a map, or updates the value for an existing
     * key. O(1).
     *
     * Returns true if the key was added to the map, that is if it was not
     * already present.
     */
    function set(AddressToUintMap storage map, address key, uint256 value) internal returns (bool) {
        return set(map._inner, bytes32(uint256(uint160(key))), bytes32(value));
    }

    /**
     * @dev Removes a value from a map. O(1).
     *
     * Returns true if the key was removed from the map, that is if it was present.
     */
    function remove(AddressToUintMap storage map, address key) internal returns (bool) {
        return remove(map._inner, bytes32(uint256(uint160(key))));
    }

    /**
     * @dev Returns true if the key is in the map. O(1).
     */
    function contains(AddressToUintMap storage map, address key) internal view returns (bool) {
        return contains(map._inner, bytes32(uint256(uint160(key))));
    }

    /**
     * @dev Returns the number of elements in the map. O(1).
     */
    function length(AddressToUintMap storage map) internal view returns (uint256) {
        return length(map._inner);
    }

    /**
     * @dev Returns the element stored at position `index` in the map. O(1).
     * Note that there are no guarantees on the ordering of values inside the
     * array, and it may change when more values are added or removed.
     *
     * Requirements:
     *
     * - `index` must be strictly less than {length}.
     */
    function at(AddressToUintMap storage map, uint256 index) internal view returns (address, uint256) {
        (bytes32 key, bytes32 value) = at(map._inner, index);
        return (address(uint160(uint256(key))), uint256(value));
    }

    /**
     * @dev Tries to returns the value associated with `key`. O(1).
     * Does not revert if `key` is not in the map.
     */
    function tryGet(AddressToUintMap storage map, address key) internal view returns (bool, uint256) {
        (bool success, bytes32 value) = tryGet(map._inner, bytes32(uint256(uint160(key))));
        return (success, uint256(value));
    }

    /**
     * @dev Returns the value associated with `key`. O(1).
     *
     * Requirements:
     *
     * - `key` must be in the map.
     */
    function get(AddressToUintMap storage map, address key) internal view returns (uint256) {
        return uint256(get(map._inner, bytes32(uint256(uint160(key)))));
    }

    /**
     * @dev Return the an array containing all the keys
     *
     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
     * uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block.
     */
    function keys(AddressToUintMap storage map) internal view returns (address[] memory) {
        bytes32[] memory store = keys(map._inner);
        address[] memory result;

        /// @solidity memory-safe-assembly
        assembly {
            result := store
        }

        return result;
    }

    // Bytes32ToUintMap

    struct Bytes32ToUintMap {
        Bytes32ToBytes32Map _inner;
    }

    /**
     * @dev Adds a key-value pair to a map, or updates the value for an existing
     * key. O(1).
     *
     * Returns true if the key was added to the map, that is if it was not
     * already present.
     */
    function set(Bytes32ToUintMap storage map, bytes32 key, uint256 value) internal returns (bool) {
        return set(map._inner, key, bytes32(value));
    }

    /**
     * @dev Removes a value from a map. O(1).
     *
     * Returns true if the key was removed from the map, that is if it was present.
     */
    function remove(Bytes32ToUintMap storage map, bytes32 key) internal returns (bool) {
        return remove(map._inner, key);
    }

    /**
     * @dev Returns true if the key is in the map. O(1).
     */
    function contains(Bytes32ToUintMap storage map, bytes32 key) internal view returns (bool) {
        return contains(map._inner, key);
    }

    /**
     * @dev Returns the number of elements in the map. O(1).
     */
    function length(Bytes32ToUintMap storage map) internal view returns (uint256) {
        return length(map._inner);
    }

    /**
     * @dev Returns the element stored at position `index` in the map. O(1).
     * Note that there are no guarantees on the ordering of values inside the
     * array, and it may change when more values are added or removed.
     *
     * Requirements:
     *
     * - `index` must be strictly less than {length}.
     */
    function at(Bytes32ToUintMap storage map, uint256 index) internal view returns (bytes32, uint256) {
        (bytes32 key, bytes32 value) = at(map._inner, index);
        return (key, uint256(value));
    }

    /**
     * @dev Tries to returns the value associated with `key`. O(1).
     * Does not revert if `key` is not in the map.
     */
    function tryGet(Bytes32ToUintMap storage map, bytes32 key) internal view returns (bool, uint256) {
        (bool success, bytes32 value) = tryGet(map._inner, key);
        return (success, uint256(value));
    }

    /**
     * @dev Returns the value associated with `key`. O(1).
     *
     * Requirements:
     *
     * - `key` must be in the map.
     */
    function get(Bytes32ToUintMap storage map, bytes32 key) internal view returns (uint256) {
        return uint256(get(map._inner, key));
    }

    /**
     * @dev Return the an array containing all the keys
     *
     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
     * uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block.
     */
    function keys(Bytes32ToUintMap storage map) internal view returns (bytes32[] memory) {
        bytes32[] memory store = keys(map._inner);
        bytes32[] memory result;

        /// @solidity memory-safe-assembly
        assembly {
            result := store
        }

        return result;
    }
}

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.0.0) (utils/structs/EnumerableSet.sol)
// This file was procedurally generated from scripts/generate/templates/EnumerableSet.js.

pragma solidity ^0.8.20;

/**
 * @dev Library for managing
 * https://en.wikipedia.org/wiki/Set_(abstract_data_type)[sets] of primitive
 * types.
 *
 * Sets have the following properties:
 *
 * - Elements are added, removed, and checked for existence in constant time
 * (O(1)).
 * - Elements are enumerated in O(n). No guarantees are made on the ordering.
 *
 * ```solidity
 * contract Example {
 *     // Add the library methods
 *     using EnumerableSet for EnumerableSet.AddressSet;
 *
 *     // Declare a set state variable
 *     EnumerableSet.AddressSet private mySet;
 * }
 * ```
 *
 * As of v3.3.0, sets of type `bytes32` (`Bytes32Set`), `address` (`AddressSet`)
 * and `uint256` (`UintSet`) are supported.
 *
 * [WARNING]
 * ====
 * Trying to delete such a structure from storage will likely result in data corruption, rendering the structure
 * unusable.
 * See https://github.com/ethereum/solidity/pull/11843[ethereum/solidity#11843] for more info.
 *
 * In order to clean an EnumerableSet, you can either remove all elements one by one or create a fresh instance using an
 * array of EnumerableSet.
 * ====
 */
library EnumerableSet {
    // To implement this library for multiple types with as little code
    // repetition as possible, we write it in terms of a generic Set type with
    // bytes32 values.
    // The Set implementation uses private functions, and user-facing
    // implementations (such as AddressSet) are just wrappers around the
    // underlying Set.
    // This means that we can only create new EnumerableSets for types that fit
    // in bytes32.

    struct Set {
        // Storage of set values
        bytes32[] _values;
        // Position is the index of the value in the `values` array plus 1.
        // Position 0 is used to mean a value is not in the set.
        mapping(bytes32 value => uint256) _positions;
    }

    /**
     * @dev Add a value to a set. O(1).
     *
     * Returns true if the value was added to the set, that is if it was not
     * already present.
     */
    function _add(Set storage set, bytes32 value) private returns (bool) {
        if (!_contains(set, value)) {
            set._values.push(value);
            // The value is stored at length-1, but we add 1 to all indexes
            // and use 0 as a sentinel value
            set._positions[value] = set._values.length;
            return true;
        } else {
            return false;
        }
    }

    /**
     * @dev Removes a value from a set. O(1).
     *
     * Returns true if the value was removed from the set, that is if it was
     * present.
     */
    function _remove(Set storage set, bytes32 value) private returns (bool) {
        // We cache the value's position to prevent multiple reads from the same storage slot
        uint256 position = set._positions[value];

        if (position != 0) {
            // Equivalent to contains(set, value)
            // To delete an element from the _values array in O(1), we swap the element to delete with the last one in
            // the array, and then remove the last element (sometimes called as 'swap and pop').
            // This modifies the order of the array, as noted in {at}.

            uint256 valueIndex = position - 1;
            uint256 lastIndex = set._values.length - 1;

            if (valueIndex != lastIndex) {
                bytes32 lastValue = set._values[lastIndex];

                // Move the lastValue to the index where the value to delete is
                set._values[valueIndex] = lastValue;
                // Update the tracked position of the lastValue (that was just moved)
                set._positions[lastValue] = position;
            }

            // Delete the slot where the moved value was stored
            set._values.pop();

            // Delete the tracked position for the deleted slot
            delete set._positions[value];

            return true;
        } else {
            return false;
        }
    }

    /**
     * @dev Returns true if the value is in the set. O(1).
     */
    function _contains(Set storage set, bytes32 value) private view returns (bool) {
        return set._positions[value] != 0;
    }

    /**
     * @dev Returns the number of values on the set. O(1).
     */
    function _length(Set storage set) private view returns (uint256) {
        return set._values.length;
    }

    /**
     * @dev Returns the value stored at position `index` in the set. O(1).
     *
     * Note that there are no guarantees on the ordering of values inside the
     * array, and it may change when more values are added or removed.
     *
     * Requirements:
     *
     * - `index` must be strictly less than {length}.
     */
    function _at(Set storage set, uint256 index) private view returns (bytes32) {
        return set._values[index];
    }

    /**
     * @dev Return the entire set in an array
     *
     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
     * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block.
     */
    function _values(Set storage set) private view returns (bytes32[] memory) {
        return set._values;
    }

    // Bytes32Set

    struct Bytes32Set {
        Set _inner;
    }

    /**
     * @dev Add a value to a set. O(1).
     *
     * Returns true if the value was added to the set, that is if it was not
     * already present.
     */
    function add(Bytes32Set storage set, bytes32 value) internal returns (bool) {
        return _add(set._inner, value);
    }

    /**
     * @dev Removes a value from a set. O(1).
     *
     * Returns true if the value was removed from the set, that is if it was
     * present.
     */
    function remove(Bytes32Set storage set, bytes32 value) internal returns (bool) {
        return _remove(set._inner, value);
    }

    /**
     * @dev Returns true if the value is in the set. O(1).
     */
    function contains(Bytes32Set storage set, bytes32 value) internal view returns (bool) {
        return _contains(set._inner, value);
    }

    /**
     * @dev Returns the number of values in the set. O(1).
     */
    function length(Bytes32Set storage set) internal view returns (uint256) {
        return _length(set._inner);
    }

    /**
     * @dev Returns the value stored at position `index` in the set. O(1).
     *
     * Note that there are no guarantees on the ordering of values inside the
     * array, and it may change when more values are added or removed.
     *
     * Requirements:
     *
     * - `index` must be strictly less than {length}.
     */
    function at(Bytes32Set storage set, uint256 index) internal view returns (bytes32) {
        return _at(set._inner, index);
    }

    /**
     * @dev Return the entire set in an array
     *
     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
     * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block.
     */
    function values(Bytes32Set storage set) internal view returns (bytes32[] memory) {
        bytes32[] memory store = _values(set._inner);
        bytes32[] memory result;

        /// @solidity memory-safe-assembly
        assembly {
            result := store
        }

        return result;
    }

    // AddressSet

    struct AddressSet {
        Set _inner;
    }

    /**
     * @dev Add a value to a set. O(1).
     *
     * Returns true if the value was added to the set, that is if it was not
     * already present.
     */
    function add(AddressSet storage set, address value) internal returns (bool) {
        return _add(set._inner, bytes32(uint256(uint160(value))));
    }

    /**
     * @dev Removes a value from a set. O(1).
     *
     * Returns true if the value was removed from the set, that is if it was
     * present.
     */
    function remove(AddressSet storage set, address value) internal returns (bool) {
        return _remove(set._inner, bytes32(uint256(uint160(value))));
    }

    /**
     * @dev Returns true if the value is in the set. O(1).
     */
    function contains(AddressSet storage set, address value) internal view returns (bool) {
        return _contains(set._inner, bytes32(uint256(uint160(value))));
    }

    /**
     * @dev Returns the number of values in the set. O(1).
     */
    function length(AddressSet storage set) internal view returns (uint256) {
        return _length(set._inner);
    }

    /**
     * @dev Returns the value stored at position `index` in the set. O(1).
     *
     * Note that there are no guarantees on the ordering of values inside the
     * array, and it may change when more values are added or removed.
     *
     * Requirements:
     *
     * - `index` must be strictly less than {length}.
     */
    function at(AddressSet storage set, uint256 index) internal view returns (address) {
        return address(uint160(uint256(_at(set._inner, index))));
    }

    /**
     * @dev Return the entire set in an array
     *
     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
     * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block.
     */
    function values(AddressSet storage set) internal view returns (address[] memory) {
        bytes32[] memory store = _values(set._inner);
        address[] memory result;

        /// @solidity memory-safe-assembly
        assembly {
            result := store
        }

        return result;
    }

    // UintSet

    struct UintSet {
        Set _inner;
    }

    /**
     * @dev Add a value to a set. O(1).
     *
     * Returns true if the value was added to the set, that is if it was not
     * already present.
     */
    function add(UintSet storage set, uint256 value) internal returns (bool) {
        return _add(set._inner, bytes32(value));
    }

    /**
     * @dev Removes a value from a set. O(1).
     *
     * Returns true if the value was removed from the set, that is if it was
     * present.
     */
    function remove(UintSet storage set, uint256 value) internal returns (bool) {
        return _remove(set._inner, bytes32(value));
    }

    /**
     * @dev Returns true if the value is in the set. O(1).
     */
    function contains(UintSet storage set, uint256 value) internal view returns (bool) {
        return _contains(set._inner, bytes32(value));
    }

    /**
     * @dev Returns the number of values in the set. O(1).
     */
    function length(UintSet storage set) internal view returns (uint256) {
        return _length(set._inner);
    }

    /**
     * @dev Returns the value stored at position `index` in the set. O(1).
     *
     * Note that there are no guarantees on the ordering of values inside the
     * array, and it may change when more values are added or removed.
     *
     * Requirements:
     *
     * - `index` must be strictly less than {length}.
     */
    function at(UintSet storage set, uint256 index) internal view returns (uint256) {
        return uint256(_at(set._inner, index));
    }

    /**
     * @dev Return the entire set in an array
     *
     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
     * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block.
     */
    function values(UintSet storage set) internal view returns (uint256[] memory) {
        bytes32[] memory store = _values(set._inner);
        uint256[] memory result;

        /// @solidity memory-safe-assembly
        assembly {
            result := store
        }

        return result;
    }
}

// SPDX-License-Identifier: UNLICENSED

pragma solidity 0.8.25;

/**
 * @notice The VerificationLevel enum represents the different levels of verification for a project
 * - **UNTRUSTED:** Untrusted verification (projects that might be scams)
 * - **NONE:** No verification
 * - **BASIC:** Basic verification
 * - **AUDITED:** Audited verification
 * - **CERTIFIED:** Certified verification (only for projects that have been verified by the team)
 * - **OFFICIAL:** Official verification (only for projects deployed by the team)
 */
enum VerificationLevel {
  UNTRUSTED,
  NONE,
  BASIC,
  AUDITED,
  CERTIFIED,
  OFFICIAL
}

library VerificationStrings {
  /**
   * @notice Converts a VerificationLevel to a string
   * @param level VerificationLevel to convert
   * @return stringLevel String representation of the VerificationLevel
   */
  function toString(VerificationLevel level) internal pure returns (string memory stringLevel) {
    return
      level == VerificationLevel.UNTRUSTED ? "Untrusted" : level == VerificationLevel.NONE
        ? "None"
        : level == VerificationLevel.BASIC
        ? "Basic"
        : level == VerificationLevel.AUDITED
        ? "Audited"
        : level == VerificationLevel.CERTIFIED
        ? "Certified"
        : "Official";
  }
}

/**
 * @notice The type of options that can be enabled or disabled
 * @notice This enum defines the following options:
 * - **VSHARES_ENABLED:** Allows the issuing of virtual shares by the project manager
 * - **CERTIFICATE_CREATE_ENABLED:** Allows the creation of new certificates
 * - **CERTIFICATE_CREATE_CAP_ENABLED:** Limits the amount of certificates that can be created
 * - **CERTIFICATE_ALLOW_MERGE:** Allows the merge of 2 or more certificates into a single certificate
 * - **CERTIFICATE_ALLOW_SPLIT:** Allows the split of a certificate into 2 certificates
 * - **CERTIFICATE_ALLOW_LIQUIDATION:** Allows the liquidation of all assets in a certificate at market rates
 * - **CERTIFICATE_ALLOW_DEPOSIT:** Allows the accounts to deposit tokens
 * - **CERTIFICATE_DEPOSIT_CAP_ENABLED:** Limits the amount of tokens that can be deposited in a certificate
 */
enum OptionType {
  VSHARES_ENABLED,
  CERTIFICATE_CREATE_ENABLED,
  CERTIFICATE_CREATE_CAP_ENABLED,
  CERTIFICATE_ALLOW_MERGE,
  CERTIFICATE_ALLOW_SPLIT,
  CERTIFICATE_ALLOW_LIQUIDATION,
  CERTIFICATE_ALLOW_DEPOSIT,
  CERTIFICATE_DEPOSIT_CAP_ENABLED
}

/**
 * @notice The type of reward distribution
 * - **UPON_CYCLE_END:** Will release all tokens upon cycle end
 * - **PROGRESSIVE:** Will release tokens gradually over the cycle in a per second basis
 */
enum DistributionType {
  UPON_CYCLE_END,
  PROGRESSIVE
}

/**
 * @notice The type of shares that can be issued
 * - **UNKNOWN:** Represents an unknown share type
 * - **VSHARE:** Represents the share of a certificate that does not contain actual tokens
 * but are matched 1:1 with the equivalent amount of t-shares
 * - **TSHARE:** Represents the share of a certificate that is deposited with actual tokens
 */
enum ShareType {
  UNKNOWN,
  TSHARE,
  VSHARE
}

/**
 * @notice The type of supply action for global shares management
 * - **INCREASE:** Increase the supply
 * - **DECREASE:** Decrease the supply
 */
enum SupplyAction {
  INCREASE,
  DECREASE
}

// SPDX-License-Identifier: MIT
pragma solidity >=0.8.19;

import { UD2x18 } from "./ValueType.sol";

/// @notice Thrown when trying to cast a UD2x18 number that doesn't fit in SD1x18.
error PRBMath_UD2x18_IntoSD1x18_Overflow(UD2x18 x);

/// @notice Thrown when trying to cast a UD2x18 number that doesn't fit in uint40.
error PRBMath_UD2x18_IntoUint40_Overflow(UD2x18 x);

// SPDX-License-Identifier: UNLICENSED

pragma solidity 0.8.25;

import {ShareType, VerificationLevel} from "./Enums.sol";
import {SettingsFlags, SettingsData} from "./Structs.sol";

/**
 * @title IEvents
 * @dev The IEvents contract defines the events used by the project
 * @dev It is an Interface so that it can be imported and used in other contracts
 */
interface IEvents {
  /**
   * @notice Emitted when the settings of the project are updated
   * @param flags The settings flags of the project
   * @param data The settings data of the project
   */
  event SettingsUpdated(SettingsFlags flags, SettingsData data);

  /**
   * @notice Emitted when the verification level of the project is updated
   * @param level The new verification level
   */
  event VerificationLevelUpdated(VerificationLevel level);

  /**
   * @notice Emitted when a new cycle is started
   * @param cycleId The ID of the new cycle
   * @param startTime The timestamp of when the cycle started
   * @param finishTime The timestamp of when the cycle will end
   */
  event CycleStart(uint256 indexed cycleId, uint256 startTime, uint256 finishTime);

  /**
   * @notice Emitted when a Cycle finishes
   * @param cycleId The ID of the cycle
   * @param finishTime The timestamp of when the cycle finished
   * @dev A Cycle only finishes upon a call is made to the contract after the finish time
   * @dev So the timestamp of this event is not the exact time the cycle finished
   */
  event CycleFinish(uint256 indexed cycleId, uint256 finishTime);

  /**
   * @notice Emitted when a cycle is extended
   * @param cycleId The ID of the cycle
   * @param secondsExtended The amount of seconds extended
   * @param newFinishTime The timestamp of when the cycle will end
   */
  event CycleDurationExtended(
    uint256 indexed cycleId,
    uint256 secondsExtended,
    uint256 newFinishTime
  );

  /**
   * @notice Emitted when a reward token slot is added to the pool
   * @param rewardTokenAddress The address of the reward token
   */
  event RewardSlotCreate(address indexed rewardTokenAddress);

  /**
   * @notice Emitted when a reward is paid to a certificate
   * @param accountAddress The address of the account that received the reward
   * @param tokenAddress The address of the reward token
   * @param rewardAmount The amount of reward tokens paid
   */
  event RewardPayment(
    address indexed accountAddress,
    address indexed tokenAddress,
    uint256 rewardAmount
  );

  /**
   * @notice Emitted when an account creates a new certificate
   * @param accountAddress The address of the account
   * @param certificateId The ID of the newly created certificate
   * @param shareType The type of share (TSHARE or VSHARE)
   */
  event CertificateCreate(
    address indexed accountAddress,
    uint256 indexed certificateId,
    ShareType shareType
  );

  /**
   * @notice Emitted when an account deposits tokens
   * @param accountAddress The address of the account
   * @param certificateId The ID of the certificate
   * @param amount The amount of tokens deposited
   */
  event CertificateDeposit(
    address indexed accountAddress,
    uint256 indexed certificateId,
    uint256 amount
  );

  /**
   * @notice Emitted when an account deposits tokens on behalf of another account
   * @param senderAddress The address of the user who called depositFor
   * @param certificateId The ID of the certificate
   * @param amount The amount of tokens deposited
   */
  event CertificateDepositFor(
    address indexed senderAddress,
    uint256 indexed certificateId,
    uint256 amount
  );

  /**
   * @notice Emitted when an account withdraws tokens
   * @param accountAddress The address of the account
   * @param certificateId The ID of the certificate
   * @param amount The amount of tokens withdrawn
   */
  event CertificateWithdrawal(
    address indexed accountAddress,
    uint256 indexed certificateId,
    uint256 amount
  );

  /**
   * @notice Emitted when the early withdrawal fee is applied
   * @param certificateId The ID of the certificate
   * @param fullAmount The full amount of tokens withdrawn
   * @param feeAmount The amount of tokens taken as a fee
   */
  event EarlyWithdrawalFeeApplied(
    uint256 indexed certificateId,
    uint256 fullAmount,
    uint256 feeAmount
  );

  /**
   * @notice Emitted when the deposit fee is applied
   * @param certificateId The ID of the certificate
   * @param receivedTokenAmount The amount of tokens received
   * @param depositFee The amount of tokens taken as a fee
   */
  event DepositFeeApplied(
    uint256 indexed certificateId,
    uint256 receivedTokenAmount,
    uint256 depositFee
  );

  /**
   * @notice Emitted when an account withdraws a certificate's rewards
   * @param accountAddress The address of the account
   * @param certificateId The ID of the certificate
   * @param tokenAddress The address of the reward token
   * @param rewardAmount The amount of rewards withdrawn
   */
  event CertificateRewardsPay(
    address indexed accountAddress,
    uint256 indexed certificateId,
    address indexed tokenAddress,
    uint256 rewardAmount
  );

  /**
   * @notice Emitted when a certificate is liquidated (all tokens withdrawn and rewards paid sold for ETH)
   * @param certificateId The ID of the certificate
   * @param beneficiary The address of the beneficiary
   * @param amountInETH The sum of tokens liquidated in ETH
   */
  event CertificateLiquidation(
    uint256 indexed certificateId,
    address indexed beneficiary,
    uint256 amountInETH
  );

  /**
   * @notice Emitted when a certificate is exited (all tokens withdrawn and rewards paid)
   * @param certificateId The ID of the certificate
   * @param beneficiary The address of the beneficiary
   */
  event CertificateExit(uint256 indexed certificateId, address indexed beneficiary);

  /**
   * @notice Emitted when a certificate is burned
   * @param certificateId The ID of the certificate
   */
  event CertificateBurned(uint256 indexed certificateId);

  /**
   * @notice Emitted when a token is recovered
   * @param tokenAddress The address of the token that was recovered
   * @param amount The amount of tokens that were recovered
   */
  event TokenRecovered(address tokenAddress, uint256 amount);

  /**
   * @notice Emitted when ETH is recovered
   * @param amount The amount of ETH that was recovered
   */
  event EtherRecovered(uint256 amount);

  /**
   * @notice Emitted when a certificate is split
   * @param certificateId1 The ID of the original certificate
   * @param certificateId2 The ID of the newly created certificate
   */
  event CertificateSplit(uint256 indexed certificateId1, uint256 indexed certificateId2);

  /**
   * @notice Emitted when a certificate is liquidated
   * @param certificateId The ID of the certificate
   * @param amountInETH The sum of tokens liquidated in ETH
   */
  event CertificateLiquidation(uint256 indexed certificateId, uint256 amountInETH);

  /**
   * @notice Emitted when unredeemed rewards are withdrawn by the admin
   * @param tokenAddress The address of the reward token
   * @param amount The amount of tokens withdrawn
   */
  event UnredeemedRewardsWithdrawal(address indexed tokenAddress, uint256 amount);

  /**
   * @notice Emitted when a certificate is frozen
   * @param certificateId The ID of the certificate
   * @param frozenUntil The timestamp of when the certificate will be unfrozen
   */
  event CertificateFreeze(uint256 indexed certificateId, uint256 frozenUntil);

  /**
   * @notice Emitted when two certificates are merged
   * @param certificateId1 The ID of the first certificate
   * @param certificateId2 The ID of the second certificate
   */
  event CertificatesMerge(uint256 indexed certificateId1, uint256 indexed certificateId2);

  /**
   * @notice Emitted when new rewards are added to the pool
   * @param tokenAddress The address of the reward token
   * @param amount The amount of tokens added
   */
  event RewardDeposit(address indexed tokenAddress, uint256 amount);

  /**
   * @notice Emitted when an ERC20 token is recovered
   * @param tokenAddress The address of the token that was recovered
   * @param amount The amount of tokens that were recovered
   */
  event ERC20Recovered(address tokenAddress, uint256 amount);

  /**
   * @notice Emitted when ETH is recovered
   * @param amount The amount of ETH that was recovered
   */
  event ETHRecovered(uint256 amount);
}

// SPDX-License-Identifier: MIT
pragma solidity >=0.8.19;

import { wrap } from "./Casting.sol";
import { UD60x18 } from "./ValueType.sol";

/// @notice Implements the checked addition operation (+) in the UD60x18 type.
function add(UD60x18 x, UD60x18 y) pure returns (UD60x18 result) {
    result = wrap(x.unwrap() + y.unwrap());
}

/// @notice Implements the AND (&) bitwise operation in the UD60x18 type.
function and(UD60x18 x, uint256 bits) pure returns (UD60x18 result) {
    result = wrap(x.unwrap() & bits);
}

/// @notice Implements the AND (&) bitwise operation in the UD60x18 type.
function and2(UD60x18 x, UD60x18 y) pure returns (UD60x18 result) {
    result = wrap(x.unwrap() & y.unwrap());
}

/// @notice Implements the equal operation (==) in the UD60x18 type.
function eq(UD60x18 x, UD60x18 y) pure returns (bool result) {
    result = x.unwrap() == y.unwrap();
}

/// @notice Implements the greater than operation (>) in the UD60x18 type.
function gt(UD60x18 x, UD60x18 y) pure returns (bool result) {
    result = x.unwrap() > y.unwrap();
}

/// @notice Implements the greater than or equal to operation (>=) in the UD60x18 type.
function gte(UD60x18 x, UD60x18 y) pure returns (bool result) {
    result = x.unwrap() >= y.unwrap();
}

/// @notice Implements a zero comparison check function in the UD60x18 type.
function isZero(UD60x18 x) pure returns (bool result) {
    // This wouldn't work if x could be negative.
    result = x.unwrap() == 0;
}

/// @notice Implements the left shift operation (<<) in the UD60x18 type.
function lshift(UD60x18 x, uint256 bits) pure returns (UD60x18 result) {
    result = wrap(x.unwrap() << bits);
}

/// @notice Implements the lower than operation (<) in the UD60x18 type.
function lt(UD60x18 x, UD60x18 y) pure returns (bool result) {
    result = x.unwrap() < y.unwrap();
}

/// @notice Implements the lower than or equal to operation (<=) in the UD60x18 type.
function lte(UD60x18 x, UD60x18 y) pure returns (bool result) {
    result = x.unwrap() <= y.unwrap();
}

/// @notice Implements the checked modulo operation (%) in the UD60x18 type.
function mod(UD60x18 x, UD60x18 y) pure returns (UD60x18 result) {
    result = wrap(x.unwrap() % y.unwrap());
}

/// @notice Implements the not equal operation (!=) in the UD60x18 type.
function neq(UD60x18 x, UD60x18 y) pure returns (bool result) {
    result = x.unwrap() != y.unwrap();
}

/// @notice Implements the NOT (~) bitwise operation in the UD60x18 type.
function not(UD60x18 x) pure returns (UD60x18 result) {
    result = wrap(~x.unwrap());
}

/// @notice Implements the OR (|) bitwise operation in the UD60x18 type.
function or(UD60x18 x, UD60x18 y) pure returns (UD60x18 result) {
    result = wrap(x.unwrap() | y.unwrap());
}

/// @notice Implements the right shift operation (>>) in the UD60x18 type.
function rshift(UD60x18 x, uint256 bits) pure returns (UD60x18 result) {
    result = wrap(x.unwrap() >> bits);
}

/// @notice Implements the checked subtraction operation (-) in the UD60x18 type.
function sub(UD60x18 x, UD60x18 y) pure returns (UD60x18 result) {
    result = wrap(x.unwrap() - y.unwrap());
}

/// @notice Implements the unchecked addition operation (+) in the UD60x18 type.
function uncheckedAdd(UD60x18 x, UD60x18 y) pure returns (UD60x18 result) {
    unchecked {
        result = wrap(x.unwrap() + y.unwrap());
    }
}

/// @notice Implements the unchecked subtraction operation (-) in the UD60x18 type.
function uncheckedSub(UD60x18 x, UD60x18 y) pure returns (UD60x18 result) {
    unchecked {
        result = wrap(x.unwrap() - y.unwrap());
    }
}

/// @notice Implements the XOR (^) bitwise operation in the UD60x18 type.
function xor(UD60x18 x, UD60x18 y) pure returns (UD60x18 result) {
    result = wrap(x.unwrap() ^ y.unwrap());
}

// SPDX-License-Identifier: MIT
// openZeppelin Contracts v4.4.1 (access/IAccessControlEnumerable.sol)

pragma solidity 0.8.25;

import "./IAccessControlUpgradeable.sol";

/**
 * @dev External interface of AccessControlEnumerable declared to support ERC165 detection.
 */
interface IAccessControlEnumerableUpgradeable is IAccessControlUpgradeable {
  /**
   * @dev Returns one of the accounts that have `role`. `index` must be a
   * value between 0 and {getRoleMemberCount}, non-inclusive.
   *
   * Role bearers are not sorted in any particular way, and their ordering may
   * change at any point.
   *
   * WARNING: When using and {getRoleMemberCount}, make sure
   * you perform all queries on the same block. See the following
   * https://forum.openzeppelin.com/t/iterating-over-elements-on-enumerableset-in-openzeppelin-contracts/2296[forum post]
   * for more information.
   */
  function getRoleMember(bytes32 role, uint256 index) external view returns (address);

  /**
   * @dev Returns the number of accounts that have `role`. Can be used
   * together with to enumerate all bearers of a role.
   */
  function getRoleMemberCount(bytes32 role) external view returns (uint256);
}

// SPDX-License-Identifier: UNLICENSED

pragma solidity 0.8.25;

import {
  IAccessControlEnumerableUpgradeable
} from "../../helpers/access/IAccessControlEnumerableUpgradeable.sol";

import {AvailableRoles} from "../../types/Structs.sol";

/**
 * @title IAccessControlFacet
 * @notice Extends the AccessControlEnumerableUpgradeable contract interface
 * @dev This contract allows for the management and reading of access control roles
 */
interface IAccessControlFacet is IAccessControlEnumerableUpgradeable {
  /**
   * @notice Gets the available roles for the project
   * @return availableRoles The available roles
   */
  function getAvailableRoles() external pure returns (AvailableRoles memory availableRoles);
}

// SPDX-License-Identifier: MIT
// openZeppelin Contracts v4.4.1 (access/IAccessControl.sol)

pragma solidity 0.8.25;

/**
 * @dev External interface of AccessControl declared to support ERC165 detection.
 */
interface IAccessControlUpgradeable {
  /**
   * @dev Emitted when `newAdminRole` is set as ``role``'s admin role, replacing `previousAdminRole`
   *
   * `DEFAULT_ADMIN_ROLE` is the starting admin for all roles, despite
   * not being emitted signaling this.
   *
   * _Available since v3.1._
   */
  event RoleAdminChanged(
    bytes32 indexed role,
    bytes32 indexed previousAdminRole,
    bytes32 indexed newAdminRole
  );

  /**
   * @dev Emitted when `account` is granted `role`.
   *
   * `sender` is the account that originated the contract call, an admin role
   * bearer except when using {AccessControl-_setupRole}.
   */
  event RoleGranted(bytes32 indexed role, address indexed account, address indexed sender);

  /**
   * @dev Emitted when `account` is revoked `role`.
   *
   * `sender` is the account that originated the contract call:
   *   - if using `revokeRole`, it is the admin role bearer
   *   - if using `renounceRole`, it is the role bearer (i.e. `account`)
   */
  event RoleRevoked(bytes32 indexed role, address indexed account, address indexed sender);

  /**
   * @dev Returns `true` if `account` has been granted `role`.
   */
  function hasRole(bytes32 role, address account) external view returns (bool);

  /**
   * @dev Returns the admin role that controls `role`. See and
   * {revokeRole}.
   *
   * To change a role's admin, use {AccessControl-_setRoleAdmin}.
   */
  function getRoleAdmin(bytes32 role) external view returns (bytes32);

  /**
   * @dev Grants `role` to `account`.
   *
   * If `account` had not been already granted `role`, emits a {RoleGranted}
   * event.
   *
   * Requirements:
   *
   * - the caller must have ``role``'s admin role.
   */
  function grantRole(bytes32 role, address account) external;

  /**
   * @dev Revokes `role` from `account`.
   *
   * If `account` had been granted `role`, emits a event.
   *
   * Requirements:
   *
   * - the caller must have ``role``'s admin role.
   */
  function revokeRole(bytes32 role, address account) external;

  /**
   * @dev Revokes `role` from the calling account.
   *
   * Roles are often managed via and {revokeRole}: this function's
   * purpose is to provide a mechanism for accounts to lose their privileges
   * if they are compromised (such as when a trusted device is misplaced).
   *
   * If the calling account had been granted `role`, emits a {RoleRevoked}
   * event.
   *
   * Requirements:
   *
   * - the caller must be `account`.
   */
  function renounceRole(bytes32 role, address account) external;
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import "./IAuthorizationUtilsV0.sol";
import "./ITemplateUtilsV0.sol";
import "./IWithdrawalUtilsV0.sol";

interface IAirnodeRrpV0 is
    IAuthorizationUtilsV0,
    ITemplateUtilsV0,
    IWithdrawalUtilsV0
{
    event SetSponsorshipStatus(
        address indexed sponsor,
        address indexed requester,
        bool sponsorshipStatus
    );

    event MadeTemplateRequest(
        address indexed airnode,
        bytes32 indexed requestId,
        uint256 requesterRequestCount,
        uint256 chainId,
        address requester,
        bytes32 templateId,
        address sponsor,
        address sponsorWallet,
        address fulfillAddress,
        bytes4 fulfillFunctionId,
        bytes parameters
    );

    event MadeFullRequest(
        address indexed airnode,
        bytes32 indexed requestId,
        uint256 requesterRequestCount,
        uint256 chainId,
        address requester,
        bytes32 endpointId,
        address sponsor,
        address sponsorWallet,
        address fulfillAddress,
        bytes4 fulfillFunctionId,
        bytes parameters
    );

    event FulfilledRequest(
        address indexed airnode,
        bytes32 indexed requestId,
        bytes data
    );

    event FailedRequest(
        address indexed airnode,
        bytes32 indexed requestId,
        string errorMessage
    );

    function setSponsorshipStatus(address requester, bool sponsorshipStatus)
        external;

    function makeTemplateRequest(
        bytes32 templateId,
        address sponsor,
        address sponsorWallet,
        address fulfillAddress,
        bytes4 fulfillFunctionId,
        bytes calldata parameters
    ) external returns (bytes32 requestId);

    function makeFullRequest(
        address airnode,
        bytes32 endpointId,
        address sponsor,
        address sponsorWallet,
        address fulfillAddress,
        bytes4 fulfillFunctionId,
        bytes calldata parameters
    ) external returns (bytes32 requestId);

    function fulfill(
        bytes32 requestId,
        address airnode,
        address fulfillAddress,
        bytes4 fulfillFunctionId,
        bytes calldata data,
        bytes calldata signature
    ) external returns (bool callSuccess, bytes memory callData);

    function fail(
        bytes32 requestId,
        address airnode,
        address fulfillAddress,
        bytes4 fulfillFunctionId,
        string calldata errorMessage
    ) external;

    function sponsorToRequesterToSponsorshipStatus(
        address sponsor,
        address requester
    ) external view returns (bool sponsorshipStatus);

    function requesterToRequestCountPlusOne(address requester)
        external
        view
        returns (uint256 requestCountPlusOne);

    function requestIsAwaitingFulfillment(bytes32 requestId)
        external
        view
        returns (bool isAwaitingFulfillment);
}

// SPDX-License-Identifier: UNLICENSED

pragma solidity 0.8.25;

/**
 * @title IAssetRecoveryFacet
 * @notice The AssetRecoveryFacet contract interface
 * @notice **This is a security feature to ensure that no assets are locked in the contract**
 * @dev This contract allows for the recovery of assets from the contract
 */
interface IAssetRecoveryFacet {
  /**
   * @notice Recovers an ERC20 token from the contract
   * @notice **This ensures that the token is not the deposit token or a reward token**
   * @param tokenAddress The address of the token to recover
   * @dev Only the admin can call this function
   */
  function recoverERC20(address tokenAddress) external;

  /**
   * @notice Recovers all ETH from the contract
   * @notice **This is safe because the contract is not supposed to hold any ETH, just WETH**
   * @dev Only the admin can call this function
   */
  function recoverETH() external;
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

interface IAuthorizationUtilsV0 {
    function checkAuthorizationStatus(
        address[] calldata authorizers,
        address airnode,
        bytes32 requestId,
        bytes32 endpointId,
        address sponsor,
        address requester
    ) external view returns (bool status);

    function checkAuthorizationStatuses(
        address[] calldata authorizers,
        address airnode,
        bytes32[] calldata requestIds,
        bytes32[] calldata endpointIds,
        address[] calldata sponsors,
        address[] calldata requesters
    ) external view returns (bool[] memory statuses);
}

// SPDX-License-Identifier: UNLICENSED

pragma solidity 0.8.25;

/**
 * @title IBalanceFacet
 * @notice The BalanceFacet contract interface
 * @dev This contract allows for the management of certificate balances
 */
interface IBalanceFacet {
  /**
   * @notice Returns the balance of a certificate
   * @param certificateId The Certificate ID to get the balance for
   * @return balance The balance of the certificate
   */
  function balanceOf(uint256 certificateId) external view returns (uint256 balance);

  /**
   * @notice Deposits tokens in the pool to earn rewards
   * @param certificateId The Certificate to deposit tokens for
   * @param amount The amount of tokens to deposit
   */
  function deposit(uint256 certificateId, uint256 amount) external;

  /**
   * @notice Deposits tokens in the pool to earn rewards
   * @param certificateId The Certificate to deposit tokens for
   * @param amount The amount of tokens to deposit
   * @param ignoreEarlyWithdrawal Whether to ignore the early withdrawal period
   * @param ignoreTransferFrom Whether to ignore the transferFrom call
   * @dev This function is only callable by the contract itself
   */
  function deposit(
    uint256 certificateId,
    uint256 amount,
    bool ignoreEarlyWithdrawal,
    bool ignoreTransferFrom
  ) external;

  /**
   * @notice Deposits tokens in the pool to earn rewards in behalf of a user
   * @param certificateId The Certificate ID to deposit tokens for
   * @param amount The amount of tokens to deposit
   * @dev This function is only callable by the project manager
   */
  function depositFor(uint256 certificateId, uint256 amount) external;

  /**
   * @notice Withdraws tokens from the pool
   * @param certificateId The Certificate to withdraw tokens from
   * @param desiredAmount The amount of tokens to withdraw
   * @return withdrawAmount The amount of tokens actually withdrawn after fees
   */
  function withdraw(
    uint256 certificateId,
    uint256 desiredAmount
  ) external returns (uint256 withdrawAmount);

  /**
   * @notice Withdraws tokens from the pool
   * @param certificateId The Certificate to withdraw tokens from
   * @param amount The amount of tokens to withdraw
   * @param overrideRecipient The address to send the tokens to
   * @return withdrawAmount The amount of tokens actually withdrawn after fees
   */
  function withdraw(
    uint256 certificateId,
    uint256 amount,
    address overrideRecipient
  ) external returns (uint256 withdrawAmount);

  /**
   * @notice Enforces that the minimum deposit is reached for other facets
   * @param certificateId The Certificate ID to check the minimum deposit for
   * @param amount The amount to check against the minimum deposit
   * @dev This function will revert if the minimum deposit is not reached
   */
  function enforceMinimumDeposit(uint256 certificateId, uint256 amount) external view;
}

// SPDX-License-Identifier: UNLICENSED

pragma solidity 0.8.25;

/**
 * @title ICertificateFacet
 * @notice The CertificateFacet contract interface
 * @dev This contract allows for the management of certificates
 */
interface ICertificateFacet {
  /**
   * @notice Gets the certificate owner
   * @param certificateId The certificate ID to check
   * @return ownerAddress The address of the certificate owner
   */
  function ownerOf(uint256 certificateId) external view returns (address ownerAddress);

  /**
   * @notice Checks if a certificate is frozen
   * @param certificateId The certificate ID to check
   * @return isFrozen Whether the certificate is frozen
   * @return frozenUntil The time remaining until the certificate is unfrozen
   */
  function isCertificateFrozen(
    uint256 certificateId
  ) external view returns (bool isFrozen, uint256 frozenUntil);

  /**
   * @notice Creates a new certificate that wraps token shares and mints a new NFT
   * @notice representing the certificate. The certificate ID is returned.
   * @param shareAmount The amount of token shares to be added to the certificate
   * @return newCertificateId The newly created certificate ID
   */
  function createTShareCertificate(uint256 shareAmount) external returns (uint256 newCertificateId);

  /**
   * @notice Creates a new certificate that wraps virtual shares and mints new NFTs
   * @notice representing the certificates. The certificate IDs are returned.
   * @param shareAmount The amount of virtual shares to be added to the certificate
   * @param certificateCount The number of certificates to create
   * @return certificateIds The newly created certificate IDs in an array
   */
  function createVShareCertificate(
    uint256 shareAmount,
    uint256 certificateCount
  ) external returns (uint256[] memory certificateIds);

  /**
   * @notice Merges two certificates of the same type and returns the new certificate ID
   * @param certificateId1 The first certificate ID to merge
   * @param certificateId2 The second certificate ID to merge
   * @return newCertificateId Is actually `certificateId1` if the merge was successful
   */
  function mergeCertificates(
    uint256 certificateId1,
    uint256 certificateId2
  ) external returns (uint256 newCertificateId);

  /**
   * @notice Splits a certificate into two certificates and returns the new certificate ID
   * @param certificateId The certificate ID to split
   * @param percentageToKeep The percentage of the certificate to keep `(1_000 = 1%)`
   * @return originalCertificateId The original certificate ID
   * @return newCertificateId The new certificate ID
   */
  function splitCertificate(
    uint256 certificateId,
    uint256 percentageToKeep
  ) external returns (uint256 originalCertificateId, uint256 newCertificateId);

  /**
   * @notice Updates the certificate state. This function is called by various facets
   *         to update the certificate state when certain actions are performed.
   * @param certificateId The certificate ID to update
   */
  function updateCertificateState(uint256 certificateId) external;

  /**
   * @notice Receives a notification from the certificate manager that a certificate
   *         has been burned. This function will withdraw the deposit and rewards
   *         from the certificate and remove it from the ledger.
   * @param certificateId The certificate ID that has been burned
   * @dev This function can only be called by the CertificateNFTManager contract.
   */
  function certificateBurnedCallback(uint256 certificateId) external;

  /**
   * @notice Ensures that the caller is the certificate owner.
   * @param certificateId The Certificate to check.
   * @param account The account to check.
   * @dev This function will revert if the certificate owner is not the account.
   */
  function enforceCertificateOwnership(uint256 certificateId, address account) external view;

  /**
   * @notice Ensures that the certificate is not frozen
   * @param certificateId The Certificate to check
   * @notice This function will revert if the certificate is frozen
   */
  function enforceCertificateNotFrozen(uint256 certificateId) external view;

  /**
   * @notice Freezes the NFT certificate transfer when it's balance is changed
   *         or rewards are withdrawn
   * @param certificateId The Certificate to freeze
   */
  function freezeCertificateTransfer(uint256 certificateId) external;
}

// SPDX-License-Identifier: UNLICENSED

pragma solidity 0.8.25;

import {EnumerableMap} from "@openzeppelin/contracts/utils/structs/EnumerableMap.sol";
import {EnumerableSet} from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
import {
  IERC721Enumerable
} from "@openzeppelin/contracts/token/ERC721/extensions/IERC721Enumerable.sol";

import {IEvents} from "../types/Events.sol";

interface ICertificateNFTManager is IERC721Enumerable, IEvents {
  /**
   * @notice Keeps track of certificates for a project
   * @param projectAddress Address of the project
   * @param certificateId Id of the certificate
   */
  struct TokenAttachedCertificate {
    address projectAddress;
    uint256 certificateId;
  }

  /**
   * @notice Keeps track of tokens for an account
   * @param globalTokens A set of all token ids owned by the account
   * @param participatingProjects A map of project addresses to the amount of tokens owned by the account in that project
   * @param tokensByProject Mapping of project addresses to sets of tokenIds owned by the account in that project
   */
  struct AccountTracker {
    EnumerableSet.UintSet globalTokens;
    EnumerableMap.AddressToUintMap participatingProjects;
    mapping(address => EnumerableSet.UintSet) tokensByProject;
  }

  /**
   * @notice Keeps track of token metadata
   * so it can be used on pagination without the caller needing to decode the token id
   * into project address and certificate id
   * @param tokenId The NFT token id
   * @param projectAddress `ProjectDiamond` address
   * @param certificateId Certificate id within the project
   */
  struct TokenTriplet {
    uint256 tokenId;
    address projectAddress;
    uint256 certificateId;
  }

  /**
   * @notice Emitted whenever a certificate is updated
   * @param tokenId The token id
   * @dev This allows for automatic metadata updates on Marketplaces
   */
  event MetadataUpdate(uint256 tokenId);

  /**
   * @notice Emitted whenever the main hub address is updated by the super admin
   * @param oldMainHubAddress The old main hub address
   * @param newMainHubAddress The new main hub address
   */
  event MainHubChange(address oldMainHubAddress, address newMainHubAddress);

  /**
   * @notice Emitted whenever the metadata base URI is updated by the super admin
   * @param oldBaseURI The old base URI
   * @param newBaseURI The new base URI
   */
  event MetadataBaseURIChange(string oldBaseURI, string newBaseURI);

  /**
   * @notice Returns the current `MainHub` address connected to the contract
   * @return hubAddress The `MainHub` address
   */
  function mainHubAddress() external view returns (address hubAddress);

  /**
   * @notice Sets the connected `MainHub` address
   * @param mainHubAddress The new `MainHub` address
   */
  function setMainHub(address mainHubAddress) external;

  /**
   * @dev Mints a new token.
   * @notice This function can only be called by a validated
   *         `ProjectDiamond` within the connected `MainHub` instance.
   * @param beneficiary The address of the token beneficiary (account to receive the token)
   * @param certificateId The certificate id within the caller project
   * @return newTokenId The newly minted token id
   * @dev The `ProjectDiamond` address is inferred from `msg.sender`
   */
  function createFromCertificate(
    address beneficiary,
    uint256 certificateId
  ) external returns (uint256 newTokenId);

  /**
   * @notice Returns the certificate owner based on the project address and certificate id
   * @param projectAddress The address of the token project
   * @param certificateId The certificate id within the project
   * @return ownerAddress The certificate owner account address
   */
  function getCertificateOwner(
    address projectAddress,
    uint256 certificateId
  ) external view returns (address ownerAddress);

  /**
   * @notice Returns the project address connected to the NFT token
   * @param tokenId The token id
   * @return projectAddress The token project address connected to the token id
   */
  function getTokenProjectAddress(uint256 tokenId) external view returns (address projectAddress);

  /**
   * @notice Returns a NFT token id derived from the project address and certificate id
   * @param projectAddress The address of the token project
   * @param certificateId The certificate id within the project
   * @return tokenId The resulting token id
   * @dev The token id is the `uint256` representation of the
   * `keccak256` hash of the token project address and the certificate id
   */
  function getTokenId(
    address projectAddress,
    uint256 certificateId
  ) external pure returns (uint256 tokenId);

  /**
   * @notice Returns the token triplet for a token id
   * @param tokenId The token id
   * @return triplet The token triplet
   * @dev The token triplet contains the token id, project address and certificate id
   */
  function getTokenTriplet(uint256 tokenId) external view returns (TokenTriplet memory triplet);

  /**
   * @notice Returns the count of tokens a user has globally
   * @param account The account address
   * @return tokenCount The count of tokens the user has
   * @dev This includes all tokens across all projects
   */
  function getAccountTokenCount(address account) external view returns (uint256 tokenCount);

  /**
   * @notice Returns all the tokens an account has globally, paginated.
   * @param account The account address
   * @param offset The offset to start from.
   * @param limit The limit of tokens to return.
   * @return tokens The tokens array.
   * @dev This includes all tokens across all projects
   */
  function getAccountPaginatedTokens(
    address account,
    uint256 offset,
    uint256 limit
  ) external view returns (TokenTriplet[] memory tokens);

  /**
   * @notice Returns the projects an account has at least 1 token in, paginated.
   * @param account The account address
   * @param offset The offset to start from.
   * @param limit The limit of projects to return.
   * @return projectAddresses The project addresses array.
   */
  function getAccountPaginatedProjects(
    address account,
    uint256 offset,
    uint256 limit
  ) external view returns (address[] memory projectAddresses);

  /**
   * @notice Returns the amount of tokens a user has scoped to a specific project
   * @param account The account address
   * @param projectAddress The project address
   * @return tokenCount The amount of tokens
   */
  function getAccountTokenCountByProject(
    address account,
    address projectAddress
  ) external view returns (uint256 tokenCount);

  /**
   * @notice Returns the token ids an account has, per project, paginated.
   * @param account The account address
   * @param projectAddress The project address
   * @param offset The offset to start from
   * @param limit The limit of tokens to return
   * @return triplets The tokens triplets array
   */
  function getAccountPaginatedTokensByProject(
    address account,
    address projectAddress,
    uint256 offset,
    uint256 limit
  ) external view returns (TokenTriplet[] memory triplets);

  /**
   * @notice It is called by a `ProjectDiamond` when a certificate needs to be burned.
   * Merging certificates, for example, is a common use case
   * @param certificateId The certificate id
   * @dev This function validates if the caller is a valid `ProjectDiamond` inside the `MainHub`.
   */
  function certificateBurnedCallback(uint256 certificateId) external;

  /**
   * @notice It is called by a `ProjectDiamond` when a certificate NFT needs to be updated
   * @notice This is useful for updating metadata on Marketplaces
   * @param certificateId The certificate id
   * @dev This function does not validate the caller and can be used to force metadata updates
   */
  function certificateUpdatedCallback(uint256 certificateId) external;

  /**
   * @notice Represents the URI for the contract metadata
   * @return uri The contract URI
   * @dev It inherits baseURI set by the platform
   */
  function contractURI() external view returns (string memory uri);

  /**
   * @notice Represents the URI for the token metadata
   * @param tokenId The token id
   * @return uri The token URI
   * @dev It inherits baseURI set by the platform
   */
  function tokenURI(uint256 tokenId) external view returns (string memory uri);

  /**
   * @notice Sets the token metadata base URI to be used as a prefix for the tokenURI
   * @param newMetadataBaseURI The new metadata base URI
   * @dev This function can only be called by a platform super admin
   */
  function setMetadataBaseURI(string memory newMetadataBaseURI) external;
}

// SPDX-License-Identifier: UNLICENSED

pragma solidity 0.8.25;

/**
 * @title ICycleFacet
 * @notice ICycleFacet is the interface for the CycleFacet contract.
 * @dev This contract is responsible for managing the cycle state of the project.
 */
interface ICycleFacet {
  /**
   * @notice Updates the state of the cycle. This function is called by various facets
   *         to update the cycle state when certain actions are performed.
   * @param cycleId The cycle ID.
   * @dev This function is payable to allow delegatecalls to it while the caller is receiving ether.
   */
  function updateCycleState(uint256 cycleId) external payable;

  /**
   * @notice Returns the remaining time (in seconds) for the cycle to end.
   * @param cycleId The cycle ID.
   * @return remainingTime The time remaining (in seconds) for the cycle to end.
   */
  function cycleTimeRemaining(uint256 cycleId) external view returns (uint256 remainingTime);

  /**
   * @notice Returns the last time the cycle is applicable. This timestamp is a `Math.min` of the
   *        cycle finish time and the current `block.timestamp`.
   * @param cycleId The cycle ID.
   * @return lastTimeApplicable The last time the cycle is applicable.
   */
  function lastTimeCycleApplicable(
    uint256 cycleId
  ) external view returns (uint256 lastTimeApplicable);

  /**
   * @notice Starts a new cycle.
   * @param cycleDuration The duration of the cycle (in seconds).
   * @param issueCertificateIfNone A flag to issue a certificate upon cycle start if none exists.
   */
  function startNewCycle(uint256 cycleDuration, bool issueCertificateIfNone) external;

  /**
   * @notice Extends the duration of the cycle.
   * @param secondsToIncrease The number of seconds to increase the cycle duration by.
   * @dev The cycle duration cannot be less than 60 seconds.
   * @dev The extension is only applicable if the manager owns 100% of the certificates.
   * @dev Only the manager can call this function.
   */
  function extendCycleDuration(uint256 secondsToIncrease) external;
}

// SPDX-License-Identifier: MIT

pragma solidity 0.8.25;

/**
 * @title IDiamondCut
 * @notice Inspired by [EIP-2535 Diamond interface](https://eips.ethereum.org/EIPS/eip-2535)
 * @dev This interface is used by the diamondCut function of the Diamond contract
 * to execute a cut on the diamond
 */
interface IDiamondCut {
  /**
   * @notice Enum for the action to be taken on a given facet
   * - **Add:** Add a new facet to the diamond
   * - **Replace:** Replace the functions of a facet in the diamond
   * - **Remove:** Remove a facet from the diamond
   */
  enum FacetCutAction {
    Add,
    Replace,
    Remove
  }

  /**
   * @notice Represents a cut to a diamond
   * @param facetAddress The facet address to be added, replaced, or removed
   * @param action The action to be taken on the given facet
   * @param functionSelectors The selectors to be added or removed
   */
  struct FacetCut {
    address facetAddress;
    FacetCutAction action;
    bytes4[] functionSelectors;
  }

  /**
   * @notice Add/replace/remove any number of functions and optionally execute a function with
   * delegatecall
   * @param diamondCutFacetCut Contains the facet addresses and function selectors
   * @param initAddress The address of the contract or facet to execute initCalldata
   * @param initCalldata A function call, including function selector and arguments
   * @dev initCalldata is executed with delegatecall on initAddress
   */
  function diamondCut(
    FacetCut[] calldata diamondCutFacetCut,
    address initAddress,
    bytes calldata initCalldata
  ) external;

  /**
   * @notice Event emitted when diamondCut is called
   * @param diamondCut Contains the facet addresses and function selectors
   * @param initAddress The address of the contract or facet to execute initCalldata
   * @param initCalldata A function call, including function selector and arguments
   * @dev initCalldata is executed with delegatecall on initAddress
   */
  event DiamondCut(FacetCut[] diamondCut, address initAddress, bytes initCalldata);
}

// SPDX-License-Identifier: UNLICENSED

pragma solidity 0.8.25;

import {InitArgs} from "../types/Structs.sol";

/**
 * @title IDiamondInit
 * @notice Inspired by [EIP-2535 Diamond interface](https://eips.ethereum.org/EIPS/eip-2535)
 * @dev The IDiamondInit contract defines the init function used by the diamond
 * @dev It is an Interface so that it can be imported and used in other contracts
 */
interface IDiamondInit {
  /**
   * @notice The init function is called by the diamondCut function
   * @param args The arguments needed to initialize the diamond
   */
  function init(InitArgs calldata args) external;
}

// SPDX-License-Identifier: MIT

pragma solidity 0.8.25;

/**
 * @title IDiamondLoupe
 * @notice Inspired by [EIP-2535 Diamond interface](https://eips.ethereum.org/EIPS/eip-2535)
 * @dev A loupe is a small magnifying glass used to look at diamonds.
 * These functions look at diamonds and facet addresses and are expected to be called frequently by tools.
 */
interface IDiamondLoupe {
  /**
   * @notice Facet
   * @param facetAddress The facet address.
   * @param functionSelectors The function selectors.
   */
  struct Facet {
    address facetAddress;
    bytes4[] functionSelectors;
  }

  /**
   * @notice Gets all facet addresses and their four byte function selectors.
   * @return facets The facet addresses and their four byte function selectors.
   */
  function facets() external view returns (Facet[] memory facets);

  /**
   * @notice Gets all the function selectors supported by a specific facet.
   * @param facet The facet address.
   * @return facetFunctionSelectors The facet function selectors.
   */
  function facetFunctionSelectors(
    address facet
  ) external view returns (bytes4[] memory facetFunctionSelectors);

  /**
   * @notice Get all the facet addresses used by a diamond.
   * @return facetAddresses Facet addresses list
   */
  function facetAddresses() external view returns (address[] memory facetAddresses);

  /**
   * @notice Gets the facet that supports the given selector.
   * @dev If facet is not found return address(0).
   * @param functionSelector The function selector.
   * @return facetAddress The facet address.
   */
  function facetAddress(bytes4 functionSelector) external view returns (address facetAddress);
}

// SPDX-License-Identifier: MIT

pragma solidity 0.8.25;

interface IERC165 {
  /**
   * @notice Checks if the contract supports an interface
   * @param interfaceId The interface identifier, as specified in ERC-165
   * @return isSupported `true` if the contract supports `interfaceId`, `false` otherwise
   * @dev This function uses less than 30,000 gas
   */
  function supportsInterface(bytes4 interfaceId) external view returns (bool isSupported);
}

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.0.0) (token/ERC20/IERC20.sol)

pragma solidity ^0.8.20;

/**
 * @dev Interface of the ERC20 standard as defined in the EIP.
 */
interface IERC20 {
    /**
     * @dev Emitted when `value` tokens are moved from one account (`from`) to
     * another (`to`).
     *
     * Note that `value` may be zero.
     */
    event Transfer(address indexed from, address indexed to, uint256 value);

    /**
     * @dev Emitted when the allowance of a `spender` for an `owner` is set by
     * a call to {approve}. `value` is the new allowance.
     */
    event Approval(address indexed owner, address indexed spender, uint256 value);

    /**
     * @dev Returns the value of tokens in existence.
     */
    function totalSupply() external view returns (uint256);

    /**
     * @dev Returns the value of tokens owned by `account`.
     */
    function balanceOf(address account) external view returns (uint256);

    /**
     * @dev Moves a `value` amount of tokens from the caller's account to `to`.
     *
     * Returns a boolean value indicating whether the operation succeeded.
     *
     * Emits a {Transfer} event.
     */
    function transfer(address to, uint256 value) external returns (bool);

    /**
     * @dev Returns the remaining number of tokens that `spender` will be
     * allowed to spend on behalf of `owner` through {transferFrom}. This is
     * zero by default.
     *
     * This value changes when {approve} or {transferFrom} are called.
     */
    function allowance(address owner, address spender) external view returns (uint256);

    /**
     * @dev Sets a `value` amount of tokens as the allowance of `spender` over the
     * caller's tokens.
     *
     * Returns a boolean value indicating whether the operation succeeded.
     *
     * IMPORTANT: Beware that changing an allowance with this method brings the risk
     * that someone may use both the old and the new allowance by unfortunate
     * transaction ordering. One possible solution to mitigate this race
     * condition is to first reduce the spender's allowance to 0 and set the
     * desired value afterwards:
     * https://github.com/ethereum/EIPs/issues/20#issuecomment-263524729
     *
     * Emits an {Approval} event.
     */
    function approve(address spender, uint256 value) external returns (bool);

    /**
     * @dev Moves a `value` amount of tokens from `from` to `to` using the
     * allowance mechanism. `value` is then deducted from the caller's
     * allowance.
     *
     * Returns a boolean value indicating whether the operation succeeded.
     *
     * Emits a {Transfer} event.
     */
    function transferFrom(address from, address to, uint256 value) external returns (bool);
}

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.0.0) (token/ERC20/extensions/IERC20Permit.sol)

pragma solidity ^0.8.20;

/**
 * @dev Interface of the ERC20 Permit extension allowing approvals to be made via signatures, as defined in
 * https://eips.ethereum.org/EIPS/eip-2612[EIP-2612].
 *
 * Adds the {permit} method, which can be used to change an account's ERC20 allowance (see {IERC20-allowance}) by
 * presenting a message signed by the account. By not relying on {IERC20-approve}, the token holder account doesn't
 * need to send a transaction, and thus is not required to hold Ether at all.
 *
 * ==== Security Considerations
 *
 * There are two important considerations concerning the use of `permit`. The first is that a valid permit signature
 * expresses an allowance, and it should not be assumed to convey additional meaning. In particular, it should not be
 * considered as an intention to spend the allowance in any specific way. The second is that because permits have
 * built-in replay protection and can be submitted by anyone, they can be frontrun. A protocol that uses permits should
 * take this into consideration and allow a `permit` call to fail. Combining these two aspects, a pattern that may be
 * generally recommended is:
 *
 * ```solidity
 * function doThingWithPermit(..., uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s) public {
 *     try token.permit(msg.sender, address(this), value, deadline, v, r, s) {} catch {}
 *     doThing(..., value);
 * }
 *
 * function doThing(..., uint256 value) public {
 *     token.safeTransferFrom(msg.sender, address(this), value);
 *     ...
 * }
 * ```
 *
 * Observe that: 1) `msg.sender` is used as the owner, leaving no ambiguity as to the signer intent, and 2) the use of
 * `try/catch` allows the permit to fail and makes the code tolerant to frontrunning. (See also
 * {SafeERC20-safeTransferFrom}).
 *
 * Additionally, note that smart contract wallets (such as Argent or Safe) are not able to produce permit signatures, so
 * contracts should have entry points that don't rely on permit.
 */
interface IERC20Permit {
    /**
     * @dev Sets `value` as the allowance of `spender` over ``owner``'s tokens,
     * given ``owner``'s signed approval.
     *
     * IMPORTANT: The same issues {IERC20-approve} has related to transaction
     * ordering also apply here.
     *
     * Emits an {Approval} event.
     *
     * Requirements:
     *
     * - `spender` cannot be the zero address.
     * - `deadline` must be a timestamp in the future.
     * - `v`, `r` and `s` must be a valid `secp256k1` signature from `owner`
     * over the EIP712-formatted function arguments.
     * - the signature must use ``owner``'s current nonce (see {nonces}).
     *
     * For more information on the signature format, see the
     * https://eips.ethereum.org/EIPS/eip-2612#specification[relevant EIP
     * section].
     *
     * CAUTION: See Security Considerations above.
     */
    function permit(
        address owner,
        address spender,
        uint256 value,
        uint256 deadline,
        uint8 v,
        bytes32 r,
        bytes32 s
    ) external;

    /**
     * @dev Returns the current nonce for `owner`. This value must be
     * included whenever a signature is generated for {permit}.
     *
     * Every successful call to {permit} increases ``owner``'s nonce by one. This
     * prevents a signature from being used multiple times.
     */
    function nonces(address owner) external view returns (uint256);

    /**
     * @dev Returns the domain separator used in the encoding of the signature for {permit}, as defined by {EIP712}.
     */
    // solhint-disable-next-line func-name-mixedcase
    function DOMAIN_SEPARATOR() external view returns (bytes32);
}

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.0.0) (token/ERC721/IERC721.sol)

pragma solidity ^0.8.20;

import {IERC165} from "../../utils/introspection/IERC165.sol";

/**
 * @dev Required interface of an ERC721 compliant contract.
 */
interface IERC721 is IERC165 {
    /**
     * @dev Emitted when `tokenId` token is transferred from `from` to `to`.
     */
    event Transfer(address indexed from, address indexed to, uint256 indexed tokenId);

    /**
     * @dev Emitted when `owner` enables `approved` to manage the `tokenId` token.
     */
    event Approval(address indexed owner, address indexed approved, uint256 indexed tokenId);

    /**
     * @dev Emitted when `owner` enables or disables (`approved`) `operator` to manage all of its assets.
     */
    event ApprovalForAll(address indexed owner, address indexed operator, bool approved);

    /**
     * @dev Returns the number of tokens in ``owner``'s account.
     */
    function balanceOf(address owner) external view returns (uint256 balance);

    /**
     * @dev Returns the owner of the `tokenId` token.
     *
     * Requirements:
     *
     * - `tokenId` must exist.
     */
    function ownerOf(uint256 tokenId) external view returns (address owner);

    /**
     * @dev Safely transfers `tokenId` token from `from` to `to`.
     *
     * Requirements:
     *
     * - `from` cannot be the zero address.
     * - `to` cannot be the zero address.
     * - `tokenId` token must exist and be owned by `from`.
     * - If the caller is not `from`, it must be approved to move this token by either {approve} or {setApprovalForAll}.
     * - If `to` refers to a smart contract, it must implement {IERC721Receiver-onERC721Received}, which is called upon
     *   a safe transfer.
     *
     * Emits a {Transfer} event.
     */
    function safeTransferFrom(address from, address to, uint256 tokenId, bytes calldata data) external;

    /**
     * @dev Safely transfers `tokenId` token from `from` to `to`, checking first that contract recipients
     * are aware of the ERC721 protocol to prevent tokens from being forever locked.
     *
     * Requirements:
     *
     * - `from` cannot be the zero address.
     * - `to` cannot be the zero address.
     * - `tokenId` token must exist and be owned by `from`.
     * - If the caller is not `from`, it must have been allowed to move this token by either {approve} or
     *   {setApprovalForAll}.
     * - If `to` refers to a smart contract, it must implement {IERC721Receiver-onERC721Received}, which is called upon
     *   a safe transfer.
     *
     * Emits a {Transfer} event.
     */
    function safeTransferFrom(address from, address to, uint256 tokenId) external;

    /**
     * @dev Transfers `tokenId` token from `from` to `to`.
     *
     * WARNING: Note that the caller is responsible to confirm that the recipient is capable of receiving ERC721
     * or else they may be permanently lost. Usage of {safeTransferFrom} prevents loss, though the caller must
     * understand this adds an external call which potentially creates a reentrancy vulnerability.
     *
     * Requirements:
     *
     * - `from` cannot be the zero address.
     * - `to` cannot be the zero address.
     * - `tokenId` token must be owned by `from`.
     * - If the caller is not `from`, it must be approved to move this token by either {approve} or {setApprovalForAll}.
     *
     * Emits a {Transfer} event.
     */
    function transferFrom(address from, address to, uint256 tokenId) external;

    /**
     * @dev Gives permission to `to` to transfer `tokenId` token to another account.
     * The approval is cleared when the token is transferred.
     *
     * Only a single account can be approved at a time, so approving the zero address clears previous approvals.
     *
     * Requirements:
     *
     * - The caller must own the token or be an approved operator.
     * - `tokenId` must exist.
     *
     * Emits an {Approval} event.
     */
    function approve(address to, uint256 tokenId) external;

    /**
     * @dev Approve or remove `operator` as an operator for the caller.
     * Operators can call {transferFrom} or {safeTransferFrom} for any token owned by the caller.
     *
     * Requirements:
     *
     * - The `operator` cannot be the address zero.
     *
     * Emits an {ApprovalForAll} event.
     */
    function setApprovalForAll(address operator, bool approved) external;

    /**
     * @dev Returns the account approved for `tokenId` token.
     *
     * Requirements:
     *
     * - `tokenId` must exist.
     */
    function getApproved(uint256 tokenId) external view returns (address operator);

    /**
     * @dev Returns if the `operator` is allowed to manage all of the assets of `owner`.
     *
     * See {setApprovalForAll}
     */
    function isApprovedForAll(address owner, address operator) external view returns (bool);
}

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.0.0) (token/ERC721/extensions/IERC721Enumerable.sol)

pragma solidity ^0.8.20;

import {IERC721} from "../IERC721.sol";

/**
 * @title ERC-721 Non-Fungible Token Standard, optional enumeration extension
 * @dev See https://eips.ethereum.org/EIPS/eip-721
 */
interface IERC721Enumerable is IERC721 {
    /**
     * @dev Returns the total amount of tokens stored by the contract.
     */
    function totalSupply() external view returns (uint256);

    /**
     * @dev Returns a token ID owned by `owner` at a given `index` of its token list.
     * Use along with {balanceOf} to enumerate all of ``owner``'s tokens.
     */
    function tokenOfOwnerByIndex(address owner, uint256 index) external view returns (uint256);

    /**
     * @dev Returns a token ID at a given `index` of all the tokens stored by the contract.
     * Use along with {totalSupply} to enumerate all tokens.
     */
    function tokenByIndex(uint256 index) external view returns (uint256);
}

// SPDX-License-Identifier: UNLICENSED

pragma solidity 0.8.25;

/**
 * @title IExitAndLiquidationFacet
 * @notice The ExitAndLiquidationFacet contract interface
 * @dev This contract allows for the exiting and liquidation of certificates
 */
interface IExitAndLiquidationFacet {
  /**
   * @notice Exits or Liquidates a certificate
   * - Exiting a certificate will withdraw the user's funds and rewards
   * - Liquidating a certificate will sell the user's funds and rewards at market and transfer the ether proceeds to the user
   * @param certificateId Certificate ID to exit
   * @param slippageTolerance Slippage tolerance for the exit
   * @param shouldLiquidate Whether to liquidate the certificate
   * @dev When `shouldLiquidate === true`, liquidation must be enabled for the project
   * @dev When liquidating, the `slippageTolerance` must be greater than `0`
   */
  function exitOrLiquidate(
    uint256 certificateId,
    uint256 slippageTolerance,
    bool shouldLiquidate
  ) external;
}

// SPDX-License-Identifier: UNLICENSED

pragma solidity 0.8.25;

import {ProjectArgs} from "../types/Structs.sol";

import {IDiamondCut} from "./IDiamondCut.sol";
import {IDiamondInit} from "./IDiamondInit.sol";

interface IMainHub {
  // ---------------------------------------------
  // enums
  // ---------------------------------------------

  /**
   * @notice ChargeType is an enum to represent the different types of charges
   * - **PERCENTAGE** The charge is a percentage of the original amount
   * - **FLAT** The charge is a flat amount
   */
  enum ChargeType {
    PERCENTAGE,
    FLAT
  }

  /**
   * @notice FeeType is an enum to represent the different types of fees
   * - **PROJECT_CREATION** The fee for creating a project
   * - **REWARD_SLOT_CREATION** The fee for creating a reward slot
   * - **REWARD_DEPOSIT** The fee for depositing rewards
   * - **EARLY_WITHDRAWAL** The fee for early withdrawal (taken from the project owner when a user withdraws early from a reward slot)
   * - **CERTIFICATE_LIQUIDATION** The fee for liquidating a certificate
   * - **REWARD_COMPOUNDING** The fee for compounding rewards
   */
  enum FeeType {
    PROJECT_CREATION,
    REWARD_SLOT_CREATION,
    REWARD_DEPOSIT,
    EARLY_WITHDRAWAL,
    CERTIFICATE_LIQUIDATION,
    REWARD_COMPOUNDING
  }

  // ---------------------------------------------
  // structs
  // ---------------------------------------------

  /**
   * @notice FeeToken is a struct to represent the token used for fees
   * @param tokenAddress The address of the token
   * @param isEther Whether the token is Ether
   * @param isAnyToken Whether to accept any token
   */
  struct FeeToken {
    address tokenAddress;
    bool isEther;
    bool isAnyToken;
  }

  /**
   * @notice HolderDiscount is a struct to represent the discount for holders
   * @param percentage The percentage of the discount
   * @param requiredBalance The required balance to receive the discount
   */
  struct HolderDiscount {
    uint256 percentage;
    uint256 requiredBalance;
  }

  /**
   * @notice HolderDiscountTier is a struct to represent the discount tiers for holders
   * @param tokenAddress The address of the token
   * @param discountTiers The discount tiers
   */
  struct HolderDiscountTier {
    address tokenAddress;
    HolderDiscount[] discountTiers;
  }

  /**
   * @notice PlatformFee is a struct to represent the fees for the platform
   * @param chargeType The type of charge (percentage or flat)
   * @param chargeAmount The amount of the charge
   * @param feeToken The token used for the fee
   * @param holderDiscountTier The discount tier for holders
   */
  struct PlatformFee {
    ChargeType chargeType;
    uint256 chargeAmount;
    FeeToken feeToken;
    HolderDiscountTier holderDiscountTier;
  }

  /**
   * @notice RoyaltyFee is a struct to represent the royalty fee for a project
   * @param active Whether the royalty fee is active
   * @param percentage The percentage of the royalty fee
   */
  struct RoyaltyFee {
    bool active;
    uint256 percentage;
  }

  /**
   * @notice ProjectDiamondData is a struct to represent the diamond data for a project
   * @param diamondCutFacetAddress The address of the diamond cut facet
   * @param diamondInitAddress The address of the diamond init
   * @param cuts The facet cuts for the diamond
   */
  struct ProjectDiamondData {
    address diamondCutFacetAddress;
    address diamondInitAddress;
    IDiamondCut.FacetCut[] cuts;
  }

  // ---------------------------------------------
  // errors
  // ---------------------------------------------

  /**
   * @notice Error for when the address is the zero address
   * @dev Used when the zero address could catastrophically affect the system
   */
  error ZeroAddress();

  /**
   * @notice Error for when the address is not a project
   */
  error NotAProject();

  /**
   * @notice Error for when the charge type for quoting/payment is invalid
   */
  error InvalidChargeType();

  /**
   * @notice Error for when the sent ether is insufficient
   */
  error InsufficientEth();

  /**
   * @notice Error for when the fee cannot be sent to the recipient
   */
  error SendFeeFailed();

  /**
   * @notice Error for when ETH is sent directly to the MainHub
   */
  error CannotReceiveEther();

  /**
   * @notice Error for when the fee is too high
   */
  error FeeTooHigh();

  /**
   * @notice Error for when the token for payment is not a valid token
   * @param expectedTokenAddress The expected token address
   * @param receivedTokenAddress The received token address
   */
  error InvalidPaymentToken(address expectedTokenAddress, address receivedTokenAddress);

  /**
   * @notice Error for when the allowance is insufficient
   */
  error InsufficientAllowance();

  /**
   * @notice Error for when the token balance is insufficient
   * @param expectedBalance The expected balance
   * @param actualBalance The actual balance
   */
  error InsufficientTokenBalance(uint256 expectedBalance, uint256 actualBalance);

  // ---------------------------------------------
  // events
  // ---------------------------------------------

  /**
   * @notice Event emitted when a project is created
   * @param projectAddress The address of the project
   * @param baseTokenAddress The address of the base token
   */
  event ProjectCreated(address indexed projectAddress, address indexed baseTokenAddress);

  event FeeRecipientAddressChange(address oldFeeRecipientAddress, address newFeeRecipientAddress);

  event SuperAdminAddressChange(address oldSuperAdminAddress, address newSuperAdminAddress);

  event CertificateNFTManagerAddressChange(
    address oldCertificateNFTManagerAddress,
    address newCertificateNFTManagerAddress
  );

  event TokenRouterAddressChange(address oldTokenRouterAddress, address newTokenRouterAddress);

  /**
   * @notice Event emitted when a project diamond data is changed
   * @param newDiamondData The new diamond data, see ProjectDiamondData struct
   */
  event ProjectDiamondDataChange(ProjectDiamondData newDiamondData);

  /**
   * @notice Event emitted when a royalty fee is changed
   * @param projectAddress (indexed) The project address
   * @param newRoyaltyFee The new royalty fee, see RoyaltyFee struct
   */
  event RoyaltyFeeChange(address indexed projectAddress, RoyaltyFee newRoyaltyFee);

  /**
   * @notice Event emitted when a royalty fee is removed
   * @param projectAddress (indexed) The project address
   */
  event RoyaltyFeeRemoval(address indexed projectAddress);

  /**
   * @notice Event emitted when a platform fee is changed
   * @param beneficiary {indexed} The beneficiary of the fee
   * @param feeType {indexed} The type of fee (FeeType enum)
   * @param newFee The new fee details, see PlatformFee struct
   */
  event PlatformFeeChange(address indexed beneficiary, FeeType indexed feeType, PlatformFee newFee);

  // ---------------------------------------------
  // getters
  // ---------------------------------------------

  /**
   * @notice Returns the version of the MainHub.
   */
  function version() external pure returns (uint256);

  /**
   * @notice Returns the root admin address for projects created by the main hub.
   */
  function superAdminAddress() external view returns (address);

  /**
   * @notice Returns the current platform fee recipient address.
   * @return feeRecipient The fee recipient address.
   */
  function feeRecipientAddress() external view returns (address feeRecipient);

  /**
   * @notice Returns the `CertificateNFTManager` address.
   * @dev This contract controls the NFT minting and ownerships.
   * @return nftManagerAddress The `CertificateNFTManager` address.
   */
  function getCertificateNFTManagerAddress() external view returns (address nftManagerAddress);

  /**
   * @notice Returns the `TokenRouter` address.
   * @dev The `TokenRouter` is used to interact with Uniswap, among other things.
   * @return tokenRouterAddress The `TokenRouter` address.
   */
  function getTokenRouterAddress() external view returns (address tokenRouterAddress);

  /**
   * @notice Checks if an address is a project.
   * @param projectAddress The project address.
   * @return isProject Whether the address is a project.
   */
  function isProject(address projectAddress) external view returns (bool isProject);

  /**
   * @notice Returns the projects count.
   * @return projectsCount The projects count.
   * @dev This function is used for pagination.
   */
  function getProjectsCount() external view returns (uint256 projectsCount);

  /**
   * @notice Returns the projects paginated.
   * @param offset The offset to start from.
   * @param limit The limit.
   * @return projects The projects.
   */
  function getPaginatedProjects(
    uint256 offset,
    uint256 limit
  ) external view returns (address[] memory projects);

  /**
   * @notice Returns the deposit tokens count.
   * @return tokensCount The deposit tokens count.
   * @dev This function is used for pagination.
   */
  function getDepositTokensCount() external view returns (uint256 tokensCount);

  /**
   * @notice Returns the deposit tokens paginated.
   * @param offset The offset.
   * @param limit The limit.
   * @return tokens The deposit tokens.
   */
  function getPaginatedDepositTokens(
    uint256 offset,
    uint256 limit
  ) external view returns (address[] memory tokens);

  /**
   * @notice Returns paginated projects by deposit token.
   * @param depositTokenAddress The deposit token address.
   * @param offset The offset.
   * @param limit The limit.
   */
  function getPaginatedProjectsByDepositToken(
    address depositTokenAddress,
    uint256 offset,
    uint256 limit
  ) external view returns (address[] memory projects);

  /**
   * @notice Gets the unique deployer addresses count.
   * @return count The deployer addresses count.
   * @dev This function is used for pagination.
   */
  function getDeployerAddressesCount() external view returns (uint256 count);

  /**
   * @notice Returns the unique deployer addresses in paginated format.
   * @param offset The offset to start from.
   * @param limit The limit of deployer addresses to return.
   * @return deployerAddresses The deployer addresses array.
   */
  function getPaginatedDeployerAddresses(
    uint256 offset,
    uint256 limit
  ) external view returns (address[] memory deployerAddresses);

  /**
   * @notice Returns the count of projects deployed by an address.
   * @dev This function is used for pagination.
   * @param deployerAddress The deployer address.
   * @return The count of projects deployed by the address.
   */
  function getProjectsCountByDeployerAddress(
    address deployerAddress
  ) external view returns (uint256);

  /**
   * @notice Returns paginated projects by deployer address.
   * @param deployerAddress The deployer address.
   * @param offset The offset.
   * @param limit The limit.
   * @return projects The projects.
   */
  function getPaginatedProjectsByDeployerAddress(
    address deployerAddress,
    uint256 offset,
    uint256 limit
  ) external view returns (address[] memory projects);

  /**
   * @notice Returns a preview quote for a specific fee.
   * @param feeType The fee type.
   * @param accountPaying The account paying the fee.
   * @param originalAmount The original amount.
   * @return chargeToken The token address to charge.
   * @return chargeAmount The amount to charge.
   */
  function previewFee(
    FeeType feeType,
    address accountPaying,
    uint256 originalAmount
  ) external view returns (address chargeToken, uint256 chargeAmount);

  /**
   * @notice Returns the certificate manager address.
   * @return nftManagerAddress The certificate manager address.
   */
  function certificateNFTManagerAddress() external view returns (address nftManagerAddress);

  /**
   * @notice This function is used to get the fee details.
   * @param feeType The fee type.
   * @param accountPaying The account paying the fee.
   * @return feeDetails The fee details.
   */
  function getPlatformFee(
    FeeType feeType,
    address accountPaying
  ) external view returns (PlatformFee memory feeDetails);

  /**
   * @notice This function is used to get the current royalty fee.
   * @param projectAddress The project address.
   * @return royaltyFee The current royalty fee.
   */
  function getRoyaltyFee(address projectAddress) external view returns (uint256 royaltyFee);

  // ---------------------------------------------
  // setters
  // ---------------------------------------------

  /**
   * @notice Sets the certificate manager address.
   * @param newCertificateNFTManagerAddress The address of the certificate manager.
   * @dev Only the root admin can call this function.
   */
  function setCertificateNFTManagerAddress(address newCertificateNFTManagerAddress) external;

  /**
   * @notice Sets the fee recipient address.
   * @param newFeeRecipientAddress The address of the fee recipient.
   * @dev Only the root admin can call this function.
   */
  function setFeeRecipientAddress(address newFeeRecipientAddress) external;

  /**
   * @notice Sets the super admin address.
   * @param newSuperAdminAddress The address of the super admin.
   * @dev Only the root admin can call this function.
   */
  function setSuperAdminAddress(address newSuperAdminAddress) external;

  /**
   * @notice Sets the TokenRouter address.
   * @param newTokenRouterAddress The address of the TokenRouter.
   * @dev Only the root admin can call this function.
   */
  function setTokenRouterAddress(address newTokenRouterAddress) external;

  /**
   * @notice Sets the project facet cuts.
   * @param data The project diamond data.
   * @dev Only the root admin can call this function.
   */
  function setProjectDiamondData(ProjectDiamondData calldata data) external;

  /**
   * @notice Sets the platform fee.
   * @param feeType The fee type.
   * @param platformFee The platform fee.
   * @param accountOverride The account to override the fee for.
   * @dev Only the root admin can call this function.
   */
  function setPlatformFee(
    FeeType feeType,
    PlatformFee calldata platformFee,
    address accountOverride
  ) external;

  /**
   * @notice Sets the royalty fee in the Marketplace for a project.
   * @param projectAddress The project address to set the royalty fee for.
   * @param royaltyFee The royalty fee to set bps (1/100000).
   * @dev Use address(0) for global default.
   */
  function setRoyaltyFee(address projectAddress, uint256 royaltyFee) external;

  /**
   * @notice This function effectively charges the fee.
   * @param feeType The fee type.
   * @param accountPaying The account paying the fee.
   * @param paymentTokenAddress The payment token address suggested by the project (will be checked against the fee token)
   * @param originalAmount The original amount.
   * @return chargeAmount The amount charged.
   */
  function payFee(
    FeeType feeType,
    address accountPaying,
    address paymentTokenAddress,
    uint256 originalAmount
  ) external returns (uint256 chargeAmount);

  // ---------------------------------------------
  // project creation
  // ---------------------------------------------

  /**
   * @notice Creates a project.
   * @param projectArgs The init args.
   * @return projectAddress The project address.
   */
  function createProject(
    ProjectArgs calldata projectArgs
  ) external payable returns (address projectAddress);
}