// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.0.0) (access/manager/AccessManaged.sol)

pragma solidity ^0.8.20;
import {AuthorityUtils} from "@openzeppelin/contracts/access/manager/AuthorityUtils.sol";
import {IAccessManager} from "@openzeppelin/contracts/access/manager/IAccessManager.sol";
import {IAccessManaged} from "@openzeppelin/contracts/access/manager/IAccessManaged.sol";
import {ContextUpgradeable} from "@openzeppelin/contracts-upgradeable/utils/ContextUpgradeable.sol";
import {Initializable} from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";

/**
 * @dev Constant representing the function selector for setting up the context manager
 * @dev This selector (0x87ef0b87) is used to identify the context manager setup operation
 * @custom:security Used for access control and context management operations
 */
bytes4 constant CONTEXT_MANAGER_SETUP = bytes4(0x87ef0b87);

/**
 * @dev Constant representing the function selector for clearing the context manager
 * @dev This selector (0xdb99bddd) is used to identify the context manager clear operation
 * @custom:security Used for access control and context management operations
 */
bytes4 constant CONTEXT_MANAGER_CLEAR = bytes4(0xdb99bddd);

/**
 * @dev This contract module makes available a {restricted} modifier. Functions decorated with this modifier will be
 * permissioned according to an "authority": a contract like {AccessManager} that follows the {IAuthority} interface,
 * implementing a policy that allows certain callers to access certain functions.
 *
 * IMPORTANT: The `restricted` modifier should never be used on `internal` functions, judiciously used in `public`
 * functions, and ideally only used in `external` functions. See {restricted}.
 */
abstract contract AccessManagedUpgradeable is Initializable, ContextUpgradeable, IAccessManaged {
    /// @custom:storage-location erc7201:openzeppelin.storage.AccessManaged
    struct AccessManagedStorage {
        address _authority;
        bool _consumingSchedule;
    }

    // keccak256(abi.encode(uint256(keccak256("openzeppelin.storage.AccessManaged")) - 1)) & ~bytes32(uint256(0xff))
    bytes32 private constant ACCESS_MANAGED_STORAGE_LOCATION =
        0xf3177357ab46d8af007ab3fdb9af81da189e1068fefdc0073dca88a2cab40a00;

    function _getAccessManagedStorage() internal pure returns (AccessManagedStorage storage $) {
        assembly {
            $.slot := ACCESS_MANAGED_STORAGE_LOCATION
        }
    }

    /**
     * @dev Initializes the contract connected to an initial authority.
     */
    function __AccessManaged_init(address initialAuthority) internal onlyInitializing {
        // solhint-disable-previous-line func-name-mixedcase
        __AccessManaged_init_unchained(initialAuthority);
    }

    function __AccessManaged_init_unchained(address initialAuthority) internal onlyInitializing {
        // solhint-disable-previous-line func-name-mixedcase
        _setAuthority(initialAuthority);
    }

    /**
     * @dev Restricts access to a function as defined by the connected Authority for this contract and the
     * caller and selector of the function that entered the contract.
     *
     * [IMPORTANT]
     * ====
     * In general, this modifier should only be used on `external` functions. It is okay to use it on `public`
     * functions that are used as external entry points and are not called internally. Unless you know what you're
     * doing, it should never be used on `internal` functions. Failure to follow these rules can have critical security
     * implications! This is because the permissions are determined by the function that entered the contract, i.e. the
     * function at the bottom of the call stack, and not the function where the modifier is visible in the source code.
     * ====
     *
     * [WARNING]
     * ====
     * Avoid adding this modifier to the https://docs.soliditylang.org/en/v0.8.20/contracts.html#receive-ether-function[`receive()`]
     * function or the https://docs.soliditylang.org/en/v0.8.20/contracts.html#fallback-function[`fallback()`]. These
     * functions are the only execution paths where a function selector cannot be unambiguosly determined from the calldata
     * since the selector defaults to `0x00000000` in the `receive()` function and similarly in the `fallback()` function
     * if no calldata is provided. (See {_checkCanCall}).
     *
     * The `receive()` function will always panic whereas the `fallback()` may panic depending on the calldata length.
     * ====
     */
    modifier restricted() {
        _checkCanCall(_msgSender(), _msgData());
        _;
    }

    /// @inheritdoc IAccessManaged
    function authority() public view virtual returns (address) {
        AccessManagedStorage storage $ = _getAccessManagedStorage();
        return $._authority;
    }

    /// @inheritdoc IAccessManaged
    function setAuthority(address newAuthority) public virtual {
        address caller = _msgSender();
        if (caller != authority()) {
            revert AccessManagedUnauthorized(caller);
        }
        if (newAuthority.code.length == 0) {
            revert AccessManagedInvalidAuthority(newAuthority);
        }
        _setAuthority(newAuthority);
    }

    /// @inheritdoc IAccessManaged
    function isConsumingScheduledOp() public view virtual returns (bytes4) {
        AccessManagedStorage storage $ = _getAccessManagedStorage();
        return $._consumingSchedule ? this.isConsumingScheduledOp.selector : bytes4(0);
    }

    /**
     * @dev Transfers control to a new authority. Internal function with no access restriction. Allows bypassing the
     * permissions set by the current authority.
     */
    function _setAuthority(address newAuthority) internal virtual {
        AccessManagedStorage storage $ = _getAccessManagedStorage();
        $._authority = newAuthority;
        emit AuthorityUpdated(newAuthority);
    }

    /**
     * @dev Reverts if the caller is not allowed to call the function identified by a selector. Panics if the calldata
     * is less than 4 bytes long.
     */
    function _checkCanCall(address caller_, bytes calldata data_) internal virtual {
        bytes4 sig = bytes4(data_[0:4]);
        if (sig == CONTEXT_MANAGER_SETUP || sig == CONTEXT_MANAGER_CLEAR) {
            caller_ = msg.sender;
        }

        AccessManagedStorage storage $ = _getAccessManagedStorage();
        (bool immediate, uint32 delay) = AuthorityUtils.canCallWithDelay(
            authority(),
            caller_,
            address(this),
            bytes4(data_[0:4])
        );
        if (!immediate) {
            if (delay > 0) {
                $._consumingSchedule = true;
                IAccessManager(authority()).consumeScheduledOp(caller_, data_);
                $._consumingSchedule = false;
            } else {
                revert AccessManagedUnauthorized(caller_);
            }
        }
    }
}

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.0.0) (access/manager/AccessManager.sol)

pragma solidity ^0.8.20;

import {IAccessManager} from "./IAccessManager.sol";
import {IAccessManaged} from "./IAccessManaged.sol";
import {Address} from "../../utils/Address.sol";
import {Context} from "../../utils/Context.sol";
import {Multicall} from "../../utils/Multicall.sol";
import {Math} from "../../utils/math/Math.sol";
import {Time} from "../../utils/types/Time.sol";

/**
 * @dev AccessManager is a central contract to store the permissions of a system.
 *
 * A smart contract under the control of an AccessManager instance is known as a target, and will inherit from the
 * {AccessManaged} contract, be connected to this contract as its manager and implement the {AccessManaged-restricted}
 * modifier on a set of functions selected to be permissioned. Note that any function without this setup won't be
 * effectively restricted.
 *
 * The restriction rules for such functions are defined in terms of "roles" identified by an `uint64` and scoped
 * by target (`address`) and function selectors (`bytes4`). These roles are stored in this contract and can be
 * configured by admins (`ADMIN_ROLE` members) after a delay (see {getTargetAdminDelay}).
 *
 * For each target contract, admins can configure the following without any delay:
 *
 * * The target's {AccessManaged-authority} via {updateAuthority}.
 * * Close or open a target via {setTargetClosed} keeping the permissions intact.
 * * The roles that are allowed (or disallowed) to call a given function (identified by its selector) through {setTargetFunctionRole}.
 *
 * By default every address is member of the `PUBLIC_ROLE` and every target function is restricted to the `ADMIN_ROLE` until configured otherwise.
 * Additionally, each role has the following configuration options restricted to this manager's admins:
 *
 * * A role's admin role via {setRoleAdmin} who can grant or revoke roles.
 * * A role's guardian role via {setRoleGuardian} who's allowed to cancel operations.
 * * A delay in which a role takes effect after being granted through {setGrantDelay}.
 * * A delay of any target's admin action via {setTargetAdminDelay}.
 * * A role label for discoverability purposes with {labelRole}.
 *
 * Any account can be added and removed into any number of these roles by using the {grantRole} and {revokeRole} functions
 * restricted to each role's admin (see {getRoleAdmin}).
 *
 * Since all the permissions of the managed system can be modified by the admins of this instance, it is expected that
 * they will be highly secured (e.g., a multisig or a well-configured DAO).
 *
 * NOTE: This contract implements a form of the {IAuthority} interface, but {canCall} has additional return data so it
 * doesn't inherit `IAuthority`. It is however compatible with the `IAuthority` interface since the first 32 bytes of
 * the return data are a boolean as expected by that interface.
 *
 * NOTE: Systems that implement other access control mechanisms (for example using {Ownable}) can be paired with an
 * {AccessManager} by transferring permissions (ownership in the case of {Ownable}) directly to the {AccessManager}.
 * Users will be able to interact with these contracts through the {execute} function, following the access rules
 * registered in the {AccessManager}. Keep in mind that in that context, the msg.sender seen by restricted functions
 * will be {AccessManager} itself.
 *
 * WARNING: When granting permissions over an {Ownable} or {AccessControl} contract to an {AccessManager}, be very
 * mindful of the danger associated with functions such as {{Ownable-renounceOwnership}} or
 * {{AccessControl-renounceRole}}.
 */
contract AccessManager is Context, Multicall, IAccessManager {
    using Time for *;

    // Structure that stores the details for a target contract.
    struct TargetConfig {
        mapping(bytes4 selector => uint64 roleId) allowedRoles;
        Time.Delay adminDelay;
        bool closed;
    }

    // Structure that stores the details for a role/account pair. This structures fit into a single slot.
    struct Access {
        // Timepoint at which the user gets the permission.
        // If this is either 0 or in the future, then the role permission is not available.
        uint48 since;
        // Delay for execution. Only applies to restricted() / execute() calls.
        Time.Delay delay;
    }

    // Structure that stores the details of a role.
    struct Role {
        // Members of the role.
        mapping(address user => Access access) members;
        // Admin who can grant or revoke permissions.
        uint64 admin;
        // Guardian who can cancel operations targeting functions that need this role.
        uint64 guardian;
        // Delay in which the role takes effect after being granted.
        Time.Delay grantDelay;
    }

    // Structure that stores the details for a scheduled operation. This structure fits into a single slot.
    struct Schedule {
        // Moment at which the operation can be executed.
        uint48 timepoint;
        // Operation nonce to allow third-party contracts to identify the operation.
        uint32 nonce;
    }

    uint64 public constant ADMIN_ROLE = type(uint64).min; // 0
    uint64 public constant PUBLIC_ROLE = type(uint64).max; // 2**64-1

    mapping(address target => TargetConfig mode) private _targets;
    mapping(uint64 roleId => Role) private _roles;
    mapping(bytes32 operationId => Schedule) private _schedules;

    // Used to identify operations that are currently being executed via {execute}.
    // This should be transient storage when supported by the EVM.
    bytes32 private _executionId;

    /**
     * @dev Check that the caller is authorized to perform the operation, following the restrictions encoded in
     * {_getAdminRestrictions}.
     */
    modifier onlyAuthorized() {
        _checkAuthorized();
        _;
    }

    constructor(address initialAdmin) {
        if (initialAdmin == address(0)) {
            revert AccessManagerInvalidInitialAdmin(address(0));
        }

        // admin is active immediately and without any execution delay.
        _grantRole(ADMIN_ROLE, initialAdmin, 0, 0);
    }

    // =================================================== GETTERS ====================================================
    /// @inheritdoc IAccessManager
    function canCall(
        address caller,
        address target,
        bytes4 selector
    ) public view virtual returns (bool immediate, uint32 delay) {
        if (isTargetClosed(target)) {
            return (false, 0);
        } else if (caller == address(this)) {
            // Caller is AccessManager, this means the call was sent through {execute} and it already checked
            // permissions. We verify that the call "identifier", which is set during {execute}, is correct.
            return (_isExecuting(target, selector), 0);
        } else {
            uint64 roleId = getTargetFunctionRole(target, selector);
            (bool isMember, uint32 currentDelay) = hasRole(roleId, caller);
            return isMember ? (currentDelay == 0, currentDelay) : (false, 0);
        }
    }

    /// @inheritdoc IAccessManager
    function expiration() public view virtual returns (uint32) {
        return 1 weeks;
    }

    /// @inheritdoc IAccessManager
    function minSetback() public view virtual returns (uint32) {
        return 5 days;
    }

    /// @inheritdoc IAccessManager
    function isTargetClosed(address target) public view virtual returns (bool) {
        return _targets[target].closed;
    }

    /// @inheritdoc IAccessManager
    function getTargetFunctionRole(address target, bytes4 selector) public view virtual returns (uint64) {
        return _targets[target].allowedRoles[selector];
    }

    /// @inheritdoc IAccessManager
    function getTargetAdminDelay(address target) public view virtual returns (uint32) {
        return _targets[target].adminDelay.get();
    }

    /// @inheritdoc IAccessManager
    function getRoleAdmin(uint64 roleId) public view virtual returns (uint64) {
        return _roles[roleId].admin;
    }

    /// @inheritdoc IAccessManager
    function getRoleGuardian(uint64 roleId) public view virtual returns (uint64) {
        return _roles[roleId].guardian;
    }

    /// @inheritdoc IAccessManager
    function getRoleGrantDelay(uint64 roleId) public view virtual returns (uint32) {
        return _roles[roleId].grantDelay.get();
    }

    /// @inheritdoc IAccessManager
    function getAccess(
        uint64 roleId,
        address account
    ) public view virtual returns (uint48 since, uint32 currentDelay, uint32 pendingDelay, uint48 effect) {
        Access storage access = _roles[roleId].members[account];

        since = access.since;
        (currentDelay, pendingDelay, effect) = access.delay.getFull();

        return (since, currentDelay, pendingDelay, effect);
    }

    /// @inheritdoc IAccessManager
    function hasRole(
        uint64 roleId,
        address account
    ) public view virtual returns (bool isMember, uint32 executionDelay) {
        if (roleId == PUBLIC_ROLE) {
            return (true, 0);
        } else {
            (uint48 hasRoleSince, uint32 currentDelay, , ) = getAccess(roleId, account);
            return (hasRoleSince != 0 && hasRoleSince <= Time.timestamp(), currentDelay);
        }
    }

    // =============================================== ROLE MANAGEMENT ===============================================
    /// @inheritdoc IAccessManager
    function labelRole(uint64 roleId, string calldata label) public virtual onlyAuthorized {
        if (roleId == ADMIN_ROLE || roleId == PUBLIC_ROLE) {
            revert AccessManagerLockedRole(roleId);
        }
        emit RoleLabel(roleId, label);
    }

    /// @inheritdoc IAccessManager
    function grantRole(uint64 roleId, address account, uint32 executionDelay) public virtual onlyAuthorized {
        _grantRole(roleId, account, getRoleGrantDelay(roleId), executionDelay);
    }

    /// @inheritdoc IAccessManager
    function revokeRole(uint64 roleId, address account) public virtual onlyAuthorized {
        _revokeRole(roleId, account);
    }

    /// @inheritdoc IAccessManager
    function renounceRole(uint64 roleId, address callerConfirmation) public virtual {
        if (callerConfirmation != _msgSender()) {
            revert AccessManagerBadConfirmation();
        }
        _revokeRole(roleId, callerConfirmation);
    }

    /// @inheritdoc IAccessManager
    function setRoleAdmin(uint64 roleId, uint64 admin) public virtual onlyAuthorized {
        _setRoleAdmin(roleId, admin);
    }

    /// @inheritdoc IAccessManager
    function setRoleGuardian(uint64 roleId, uint64 guardian) public virtual onlyAuthorized {
        _setRoleGuardian(roleId, guardian);
    }

    /// @inheritdoc IAccessManager
    function setGrantDelay(uint64 roleId, uint32 newDelay) public virtual onlyAuthorized {
        _setGrantDelay(roleId, newDelay);
    }

    /**
     * @dev Internal version of {grantRole} without access control. Returns true if the role was newly granted.
     *
     * Emits a {RoleGranted} event.
     */
    function _grantRole(
        uint64 roleId,
        address account,
        uint32 grantDelay,
        uint32 executionDelay
    ) internal virtual returns (bool) {
        if (roleId == PUBLIC_ROLE) {
            revert AccessManagerLockedRole(roleId);
        }

        bool newMember = _roles[roleId].members[account].since == 0;
        uint48 since;

        if (newMember) {
            since = Time.timestamp() + grantDelay;
            _roles[roleId].members[account] = Access({since: since, delay: executionDelay.toDelay()});
        } else {
            // No setback here. Value can be reset by doing revoke + grant, effectively allowing the admin to perform
            // any change to the execution delay within the duration of the role admin delay.
            (_roles[roleId].members[account].delay, since) = _roles[roleId].members[account].delay.withUpdate(
                executionDelay,
                0
            );
        }

        emit RoleGranted(roleId, account, executionDelay, since, newMember);
        return newMember;
    }

    /**
     * @dev Internal version of {revokeRole} without access control. This logic is also used by {renounceRole}.
     * Returns true if the role was previously granted.
     *
     * Emits a {RoleRevoked} event if the account had the role.
     */
    function _revokeRole(uint64 roleId, address account) internal virtual returns (bool) {
        if (roleId == PUBLIC_ROLE) {
            revert AccessManagerLockedRole(roleId);
        }

        if (_roles[roleId].members[account].since == 0) {
            return false;
        }

        delete _roles[roleId].members[account];

        emit RoleRevoked(roleId, account);
        return true;
    }

    /**
     * @dev Internal version of {setRoleAdmin} without access control.
     *
     * Emits a {RoleAdminChanged} event.
     *
     * NOTE: Setting the admin role as the `PUBLIC_ROLE` is allowed, but it will effectively allow
     * anyone to set grant or revoke such role.
     */
    function _setRoleAdmin(uint64 roleId, uint64 admin) internal virtual {
        if (roleId == ADMIN_ROLE || roleId == PUBLIC_ROLE) {
            revert AccessManagerLockedRole(roleId);
        }

        _roles[roleId].admin = admin;

        emit RoleAdminChanged(roleId, admin);
    }

    /**
     * @dev Internal version of {setRoleGuardian} without access control.
     *
     * Emits a {RoleGuardianChanged} event.
     *
     * NOTE: Setting the guardian role as the `PUBLIC_ROLE` is allowed, but it will effectively allow
     * anyone to cancel any scheduled operation for such role.
     */
    function _setRoleGuardian(uint64 roleId, uint64 guardian) internal virtual {
        if (roleId == ADMIN_ROLE || roleId == PUBLIC_ROLE) {
            revert AccessManagerLockedRole(roleId);
        }

        _roles[roleId].guardian = guardian;

        emit RoleGuardianChanged(roleId, guardian);
    }

    /**
     * @dev Internal version of {setGrantDelay} without access control.
     *
     * Emits a {RoleGrantDelayChanged} event.
     */
    function _setGrantDelay(uint64 roleId, uint32 newDelay) internal virtual {
        if (roleId == PUBLIC_ROLE) {
            revert AccessManagerLockedRole(roleId);
        }

        uint48 effect;
        (_roles[roleId].grantDelay, effect) = _roles[roleId].grantDelay.withUpdate(newDelay, minSetback());

        emit RoleGrantDelayChanged(roleId, newDelay, effect);
    }

    // ============================================= FUNCTION MANAGEMENT ==============================================
    /// @inheritdoc IAccessManager
    function setTargetFunctionRole(
        address target,
        bytes4[] calldata selectors,
        uint64 roleId
    ) public virtual onlyAuthorized {
        for (uint256 i = 0; i < selectors.length; ++i) {
            _setTargetFunctionRole(target, selectors[i], roleId);
        }
    }

    /**
     * @dev Internal version of {setTargetFunctionRole} without access control.
     *
     * Emits a {TargetFunctionRoleUpdated} event.
     */
    function _setTargetFunctionRole(address target, bytes4 selector, uint64 roleId) internal virtual {
        _targets[target].allowedRoles[selector] = roleId;
        emit TargetFunctionRoleUpdated(target, selector, roleId);
    }

    /// @inheritdoc IAccessManager
    function setTargetAdminDelay(address target, uint32 newDelay) public virtual onlyAuthorized {
        _setTargetAdminDelay(target, newDelay);
    }

    /**
     * @dev Internal version of {setTargetAdminDelay} without access control.
     *
     * Emits a {TargetAdminDelayUpdated} event.
     */
    function _setTargetAdminDelay(address target, uint32 newDelay) internal virtual {
        uint48 effect;
        (_targets[target].adminDelay, effect) = _targets[target].adminDelay.withUpdate(newDelay, minSetback());

        emit TargetAdminDelayUpdated(target, newDelay, effect);
    }

    // =============================================== MODE MANAGEMENT ================================================
    /// @inheritdoc IAccessManager
    function setTargetClosed(address target, bool closed) public virtual onlyAuthorized {
        _setTargetClosed(target, closed);
    }

    /**
     * @dev Set the closed flag for a contract. This is an internal setter with no access restrictions.
     *
     * Emits a {TargetClosed} event.
     */
    function _setTargetClosed(address target, bool closed) internal virtual {
        if (target == address(this)) {
            revert AccessManagerLockedAccount(target);
        }
        _targets[target].closed = closed;
        emit TargetClosed(target, closed);
    }

    // ============================================== DELAYED OPERATIONS ==============================================
    /// @inheritdoc IAccessManager
    function getSchedule(bytes32 id) public view virtual returns (uint48) {
        uint48 timepoint = _schedules[id].timepoint;
        return _isExpired(timepoint) ? 0 : timepoint;
    }

    /// @inheritdoc IAccessManager
    function getNonce(bytes32 id) public view virtual returns (uint32) {
        return _schedules[id].nonce;
    }

    /// @inheritdoc IAccessManager
    function schedule(
        address target,
        bytes calldata data,
        uint48 when
    ) public virtual returns (bytes32 operationId, uint32 nonce) {
        address caller = _msgSender();

        // Fetch restrictions that apply to the caller on the targeted function
        (, uint32 setback) = _canCallExtended(caller, target, data);

        uint48 minWhen = Time.timestamp() + setback;

        // if call with delay is not authorized, or if requested timing is too soon
        if (setback == 0 || (when > 0 && when < minWhen)) {
            revert AccessManagerUnauthorizedCall(caller, target, _checkSelector(data));
        }

        // Reuse variable due to stack too deep
        when = uint48(Math.max(when, minWhen)); // cast is safe: both inputs are uint48

        // If caller is authorised, schedule operation
        operationId = hashOperation(caller, target, data);

        _checkNotScheduled(operationId);

        unchecked {
            // It's not feasible to overflow the nonce in less than 1000 years
            nonce = _schedules[operationId].nonce + 1;
        }
        _schedules[operationId].timepoint = when;
        _schedules[operationId].nonce = nonce;
        emit OperationScheduled(operationId, nonce, when, caller, target, data);

        // Using named return values because otherwise we get stack too deep
    }

    /**
     * @dev Reverts if the operation is currently scheduled and has not expired.
     * (Note: This function was introduced due to stack too deep errors in schedule.)
     */
    function _checkNotScheduled(bytes32 operationId) private view {
        uint48 prevTimepoint = _schedules[operationId].timepoint;
        if (prevTimepoint != 0 && !_isExpired(prevTimepoint)) {
            revert AccessManagerAlreadyScheduled(operationId);
        }
    }

    /// @inheritdoc IAccessManager
    // Reentrancy is not an issue because permissions are checked on msg.sender. Additionally,
    // _consumeScheduledOp guarantees a scheduled operation is only executed once.
    // slither-disable-next-line reentrancy-no-eth
    function execute(address target, bytes calldata data) public payable virtual returns (uint32) {
        address caller = _msgSender();

        // Fetch restrictions that apply to the caller on the targeted function
        (bool immediate, uint32 setback) = _canCallExtended(caller, target, data);

        // If caller is not authorised, revert
        if (!immediate && setback == 0) {
            revert AccessManagerUnauthorizedCall(caller, target, _checkSelector(data));
        }

        bytes32 operationId = hashOperation(caller, target, data);
        uint32 nonce;

        // If caller is authorised, check operation was scheduled early enough
        // Consume an available schedule even if there is no currently enforced delay
        if (setback != 0 || getSchedule(operationId) != 0) {
            nonce = _consumeScheduledOp(operationId);
        }

        // Mark the target and selector as authorised
        bytes32 executionIdBefore = _executionId;
        _executionId = _hashExecutionId(target, _checkSelector(data));

        // Perform call
        Address.functionCallWithValue(target, data, msg.value);

        // Reset execute identifier
        _executionId = executionIdBefore;

        return nonce;
    }

    /// @inheritdoc IAccessManager
    function cancel(address caller, address target, bytes calldata data) public virtual returns (uint32) {
        address msgsender = _msgSender();
        bytes4 selector = _checkSelector(data);

        bytes32 operationId = hashOperation(caller, target, data);
        if (_schedules[operationId].timepoint == 0) {
            revert AccessManagerNotScheduled(operationId);
        } else if (caller != msgsender) {
            // calls can only be canceled by the account that scheduled them, a global admin, or by a guardian of the required role.
            (bool isAdmin, ) = hasRole(ADMIN_ROLE, msgsender);
            (bool isGuardian, ) = hasRole(getRoleGuardian(getTargetFunctionRole(target, selector)), msgsender);
            if (!isAdmin && !isGuardian) {
                revert AccessManagerUnauthorizedCancel(msgsender, caller, target, selector);
            }
        }

        delete _schedules[operationId].timepoint; // reset the timepoint, keep the nonce
        uint32 nonce = _schedules[operationId].nonce;
        emit OperationCanceled(operationId, nonce);

        return nonce;
    }

    /// @inheritdoc IAccessManager
    function consumeScheduledOp(address caller, bytes calldata data) public virtual {
        address target = _msgSender();
        if (IAccessManaged(target).isConsumingScheduledOp() != IAccessManaged.isConsumingScheduledOp.selector) {
            revert AccessManagerUnauthorizedConsume(target);
        }
        _consumeScheduledOp(hashOperation(caller, target, data));
    }

    /**
     * @dev Internal variant of {consumeScheduledOp} that operates on bytes32 operationId.
     *
     * Returns the nonce of the scheduled operation that is consumed.
     */
    function _consumeScheduledOp(bytes32 operationId) internal virtual returns (uint32) {
        uint48 timepoint = _schedules[operationId].timepoint;
        uint32 nonce = _schedules[operationId].nonce;

        if (timepoint == 0) {
            revert AccessManagerNotScheduled(operationId);
        } else if (timepoint > Time.timestamp()) {
            revert AccessManagerNotReady(operationId);
        } else if (_isExpired(timepoint)) {
            revert AccessManagerExpired(operationId);
        }

        delete _schedules[operationId].timepoint; // reset the timepoint, keep the nonce
        emit OperationExecuted(operationId, nonce);

        return nonce;
    }

    /// @inheritdoc IAccessManager
    function hashOperation(address caller, address target, bytes calldata data) public view virtual returns (bytes32) {
        return keccak256(abi.encode(caller, target, data));
    }

    // ==================================================== OTHERS ====================================================
    /// @inheritdoc IAccessManager
    function updateAuthority(address target, address newAuthority) public virtual onlyAuthorized {
        IAccessManaged(target).setAuthority(newAuthority);
    }

    // ================================================= ADMIN LOGIC ==================================================
    /**
     * @dev Check if the current call is authorized according to admin logic.
     */
    function _checkAuthorized() private {
        address caller = _msgSender();
        (bool immediate, uint32 delay) = _canCallSelf(caller, _msgData());
        if (!immediate) {
            if (delay == 0) {
                (, uint64 requiredRole, ) = _getAdminRestrictions(_msgData());
                revert AccessManagerUnauthorizedAccount(caller, requiredRole);
            } else {
                _consumeScheduledOp(hashOperation(caller, address(this), _msgData()));
            }
        }
    }

    /**
     * @dev Get the admin restrictions of a given function call based on the function and arguments involved.
     *
     * Returns:
     * - bool restricted: does this data match a restricted operation
     * - uint64: which role is this operation restricted to
     * - uint32: minimum delay to enforce for that operation (max between operation's delay and admin's execution delay)
     */
    function _getAdminRestrictions(
        bytes calldata data
    ) private view returns (bool restricted, uint64 roleAdminId, uint32 executionDelay) {
        if (data.length < 4) {
            return (false, 0, 0);
        }

        bytes4 selector = _checkSelector(data);

        // Restricted to ADMIN with no delay beside any execution delay the caller may have
        if (
            selector == this.labelRole.selector ||
            selector == this.setRoleAdmin.selector ||
            selector == this.setRoleGuardian.selector ||
            selector == this.setGrantDelay.selector ||
            selector == this.setTargetAdminDelay.selector
        ) {
            return (true, ADMIN_ROLE, 0);
        }

        // Restricted to ADMIN with the admin delay corresponding to the target
        if (
            selector == this.updateAuthority.selector ||
            selector == this.setTargetClosed.selector ||
            selector == this.setTargetFunctionRole.selector
        ) {
            // First argument is a target.
            address target = abi.decode(data[0x04:0x24], (address));
            uint32 delay = getTargetAdminDelay(target);
            return (true, ADMIN_ROLE, delay);
        }

        // Restricted to that role's admin with no delay beside any execution delay the caller may have.
        if (selector == this.grantRole.selector || selector == this.revokeRole.selector) {
            // First argument is a roleId.
            uint64 roleId = abi.decode(data[0x04:0x24], (uint64));
            return (true, getRoleAdmin(roleId), 0);
        }

        return (false, 0, 0);
    }

    // =================================================== HELPERS ====================================================
    /**
     * @dev An extended version of {canCall} for internal usage that checks {_canCallSelf}
     * when the target is this contract.
     *
     * Returns:
     * - bool immediate: whether the operation can be executed immediately (with no delay)
     * - uint32 delay: the execution delay
     */
    function _canCallExtended(
        address caller,
        address target,
        bytes calldata data
    ) private view returns (bool immediate, uint32 delay) {
        if (target == address(this)) {
            return _canCallSelf(caller, data);
        } else {
            return data.length < 4 ? (false, 0) : canCall(caller, target, _checkSelector(data));
        }
    }

    /**
     * @dev A version of {canCall} that checks for admin restrictions in this contract.
     */
    function _canCallSelf(address caller, bytes calldata data) private view returns (bool immediate, uint32 delay) {
        if (data.length < 4) {
            return (false, 0);
        }

        if (caller == address(this)) {
            // Caller is AccessManager, this means the call was sent through {execute} and it already checked
            // permissions. We verify that the call "identifier", which is set during {execute}, is correct.
            return (_isExecuting(address(this), _checkSelector(data)), 0);
        }

        (bool enabled, uint64 roleId, uint32 operationDelay) = _getAdminRestrictions(data);
        if (!enabled) {
            return (false, 0);
        }

        (bool inRole, uint32 executionDelay) = hasRole(roleId, caller);
        if (!inRole) {
            return (false, 0);
        }

        // downcast is safe because both options are uint32
        delay = uint32(Math.max(operationDelay, executionDelay));
        return (delay == 0, delay);
    }

    /**
     * @dev Returns true if a call with `target` and `selector` is being executed via {executed}.
     */
    function _isExecuting(address target, bytes4 selector) private view returns (bool) {
        return _executionId == _hashExecutionId(target, selector);
    }

    /**
     * @dev Returns true if a schedule timepoint is past its expiration deadline.
     */
    function _isExpired(uint48 timepoint) private view returns (bool) {
        return timepoint + expiration() <= Time.timestamp();
    }

    /**
     * @dev Extracts the selector from calldata. Panics if data is not at least 4 bytes
     */
    function _checkSelector(bytes calldata data) private pure returns (bytes4) {
        return bytes4(data[0:4]);
    }

    /**
     * @dev Hashing function for execute protection
     */
    function _hashExecutionId(address target, bytes4 selector) private pure returns (bytes32) {
        return keccak256(abi.encode(target, selector));
    }
}

// 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: BUSL-1.1
pragma solidity 0.8.26;

import {PlasmaVaultStorageLib} from "./PlasmaVaultStorageLib.sol";
import {Math} from "@openzeppelin/contracts/utils/math/Math.sol";

/**
 * @title Asset Distribution Protection Library - Risk Management System for Plasma Vault
 * @notice Library enforcing market exposure limits and risk distribution across DeFi protocols
 * @dev Core risk management component that:
 * 1. Enforces maximum exposure limits per market
 * 2. Tracks and validates asset distribution
 * 3. Provides activation/deactivation controls
 * 4. Maintains market-specific limit configurations
 *
 * Key Components:
 * - Market Limit System: Percentage-based exposure controls
 * - Activation Controls: System-wide protection toggle
 * - Limit Validation: Real-time balance checks
 * - Storage Integration: Uses PlasmaVaultStorageLib for persistent state
 *
 * Integration Points:
 * - Used by PlasmaVault for operation validation
 * - Managed through PlasmaVaultGovernance
 * - Coordinates with FusesLib for market balance data
 * - Works with balance fuses for position tracking
 *
 * Security Considerations:
 * - Prevents over-concentration in single markets
 * - Enforces risk distribution across protocols
 * - Maintains system-wide risk parameters
 * - Critical for vault's risk management
 *
 * @custom:security-contact security@ipor.io
 */

/**
 * @notice Market balance tracking structure for limit validation
 * @dev Used during balance updates and limit checks
 *
 * Storage Layout:
 * - marketId: Maps to protocol-specific market identifiers
 * - balanceInMarket: Standardized 18-decimal balance representation
 *
 * Integration Context:
 * - Used by checkLimits() for validation
 * - Populated during balance updates
 * - Coordinates with balance fuses
 */
struct MarketToCheck {
    /// @notice The unique identifier of the market
    /// @dev Same ID used in fuse contracts and market configurations
    uint256 marketId;
    /// @notice The current balance allocated to this market
    /// @dev Amount represented in 18 decimals for consistent comparison
    uint256 balanceInMarket;
}

/**
 * @notice Aggregated vault state for market limit validation
 * @dev Combines total vault value with per-market positions
 *
 * Components:
 * - Total vault balance for percentage calculations
 * - Array of market positions for limit checking
 *
 * Integration Context:
 * - Used during vault operations
 * - Critical for limit enforcement
 * - Updated on balance changes
 */
struct DataToCheck {
    /// @notice Total value of assets in the Plasma Vault
    /// @dev Amount represented in 18 decimals for consistent comparison
    uint256 totalBalanceInVault;
    /// @notice Array of markets and their current balances to validate
    MarketToCheck[] marketsToCheck;
}

/**
 * @notice Market-specific exposure limit configuration
 * @dev Defines maximum allowed allocation per market
 *
 * Configuration Notes:
 * - Uses fixed-point percentages (1e18 = 100%)
 * - Market ID must match protocol identifiers
 * - Zero marketId is reserved for system control
 *
 * Integration Context:
 * - Set through governance
 * - Used in limit validation
 * - Critical for risk management
 */
struct MarketLimit {
    /// @notice The unique identifier of the market
    /// @dev Must match the marketId used in fuse contracts
    uint256 marketId;
    /// @notice Maximum percentage of total vault assets allowed in this market
    /// @dev Uses fixed-point notation where 1e18 represents 100%
    uint256 limitInPercentage;
}

library AssetDistributionProtectionLib {
    /// @dev Represents 100% in fixed-point notation (1e18)
    uint256 private constant ONE_HUNDRED_PERCENT = 1e18;

    /// @notice Emitted when market limits protection is activated
    event MarketsLimitsActivated();
    /// @notice Emitted when market limits protection is deactivated
    event MarketsLimitsDeactivated();
    /// @notice Emitted when a market's limit is updated
    /// @param marketId The ID of the market whose limit was updated
    /// @param newLimit The new limit value in percentage (1e18 = 100%)
    event MarketLimitUpdated(uint256 marketId, uint256 newLimit);

    /// @notice Thrown when a market's balance exceeds its configured limit
    error MarketLimitExceeded(uint256 marketId, uint256 balanceInMarket, uint256 limit);
    /// @notice Thrown when attempting to set a limit above 100%
    error MarketLimitSetupInPercentageIsTooHigh(uint256 limit);
    /// @notice Thrown when using an invalid market ID (0 is reserved)
    error WrongMarketId(uint256 marketId);

    /**
     * @notice Activates the market exposure protection system
     * @dev Enables limit enforcement through sentinel value
     *
     * Storage Updates:
     * 1. Sets activation flag in slot 0
     * 2. Emits activation event
     *
     * Integration Context:
     * - Called by PlasmaVaultGovernance
     * - Affects all subsequent vault operations
     * - Requires prior limit configuration
     *
     * Security Considerations:
     * - Only callable through governance
     * - Critical for risk management activation
     * - Must have limits configured before use
     *
     * @custom:events Emits MarketsLimitsActivated
     * @custom:access Restricted to ATOMIST_ROLE via PlasmaVaultGovernance
     */
    function activateMarketsLimits() internal {
        PlasmaVaultStorageLib.getMarketsLimits().limitInPercentage[0] = 1;
        emit MarketsLimitsActivated();
    }

    /**
     * @notice Deactivates the market exposure protection system
     * @dev Disables limit enforcement by clearing sentinel
     *
     * Storage Updates:
     * 1. Clears activation flag in slot 0
     * 2. Emits deactivation event
     *
     * Integration Context:
     * - Called by PlasmaVaultGovernance
     * - Emergency risk control feature
     * - Affects all market operations
     *
     * Security Notes:
     * - Only callable through governance
     * - Should be used with caution
     * - Removes all limit protections
     *
     * @custom:events Emits MarketsLimitsDeactivated
     * @custom:access Restricted to ATOMIST_ROLE via PlasmaVaultGovernance
     */
    function deactivateMarketsLimits() internal {
        PlasmaVaultStorageLib.getMarketsLimits().limitInPercentage[0] = 0;
        emit MarketsLimitsDeactivated();
    }

    /**
     * @notice Configures exposure limits for multiple markets
     * @dev Sets maximum allowed allocation percentages
     *
     * Limit Configuration:
     * - Percentages use 1e18 as 100%
     * - Each market can have unique limit
     * - Zero marketId is reserved
     * - The sum of limits may exceed 100%
     *
     * Storage Updates:
     * 1. Validates each market config
     * 2. Updates limit mappings
     * 3. Emits update events
     *
     * Error Conditions:
     * - Reverts if marketId is 0
     * - Reverts if limit > 100%
     *
     * @param marketsLimits_ Array of market limit configurations
     * @custom:events Emits MarketLimitUpdated for each update
     * @custom:access Restricted to ATOMIST_ROLE via PlasmaVaultGovernance
     */
    function setupMarketsLimits(MarketLimit[] calldata marketsLimits_) internal {
        uint256 len = marketsLimits_.length;
        for (uint256 i; i < len; ++i) {
            if (marketsLimits_[i].marketId == 0) {
                revert WrongMarketId(marketsLimits_[i].marketId);
            }
            if (marketsLimits_[i].limitInPercentage > ONE_HUNDRED_PERCENT) {
                revert MarketLimitSetupInPercentageIsTooHigh(marketsLimits_[i].limitInPercentage);
            }
            PlasmaVaultStorageLib.getMarketsLimits().limitInPercentage[marketsLimits_[i].marketId] = marketsLimits_[i]
                .limitInPercentage;
            emit MarketLimitUpdated(marketsLimits_[i].marketId, marketsLimits_[i].limitInPercentage);
        }
    }

    /**
     * @notice Validates market positions against configured limits
     * @dev Core protection logic for asset distribution
     *
     * Validation Process:
     * 1. Checks system activation
     * 2. Calculates absolute limits
     * 3. Compares current positions
     * 4. Reverts if limits exceeded
     *
     * Integration Context:
     * - Called during vault operations
     * - Critical for risk management
     * - Affects all market interactions
     *
     * Error Handling:
     * - Reverts with MarketLimitExceeded
     * - Includes detailed error data
     * - Prevents limit violations
     *
     * @param data_ Struct containing vault state and positions
     * @custom:security Non-reentrant via PlasmaVault
     */
    function checkLimits(DataToCheck memory data_) internal view {
        if (!isMarketsLimitsActivated()) {
            return;
        }

        uint256 len = data_.marketsToCheck.length;
        uint256 limit;

        for (uint256 i; i < len; ++i) {
            limit = Math.mulDiv(
                PlasmaVaultStorageLib.getMarketsLimits().limitInPercentage[data_.marketsToCheck[i].marketId],
                data_.totalBalanceInVault,
                ONE_HUNDRED_PERCENT
            );
            if (limit < data_.marketsToCheck[i].balanceInMarket) {
                revert MarketLimitExceeded(
                    data_.marketsToCheck[i].marketId,
                    data_.marketsToCheck[i].balanceInMarket,
                    limit
                );
            }
        }
    }

    /**
     * @notice Checks activation status of market limits
     * @dev Uses sentinel value in storage slot 0
     *
     * Storage Pattern:
     * - Slot 0 reserved for activation flag
     * - Non-zero value indicates active
     * - Part of protection system state
     *
     * Integration Context:
     * - Used by checkLimits()
     * - Part of protection logic
     * - Critical for system control
     *
     * @return bool True if market limits are enforced
     */
    function isMarketsLimitsActivated() internal view returns (bool) {
        return PlasmaVaultStorageLib.getMarketsLimits().limitInPercentage[0] != 0;
    }
}

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.0.0) (access/manager/AuthorityUtils.sol)

pragma solidity ^0.8.20;

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

library AuthorityUtils {
    /**
     * @dev Since `AccessManager` implements an extended IAuthority interface, invoking `canCall` with backwards compatibility
     * for the preexisting `IAuthority` interface requires special care to avoid reverting on insufficient return data.
     * This helper function takes care of invoking `canCall` in a backwards compatible way without reverting.
     */
    function canCallWithDelay(
        address authority,
        address caller,
        address target,
        bytes4 selector
    ) internal view returns (bool immediate, uint32 delay) {
        (bool success, bytes memory data) = authority.staticcall(
            abi.encodeCall(IAuthority.canCall, (caller, target, selector))
        );
        if (success) {
            if (data.length >= 0x40) {
                (immediate, delay) = abi.decode(data, (bool, uint32));
            } else if (data.length >= 0x20) {
                immediate = abi.decode(data, (bool));
            }
        }
        return (immediate, delay);
    }
}

// SPDX-License-Identifier: BUSL-1.1
pragma solidity 0.8.26;

import {Address} from "@openzeppelin/contracts/utils/Address.sol";
import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
import {FuseAction} from "../interfaces/IPlasmaVault.sol";
import {PlasmaVaultStorageLib} from "./PlasmaVaultStorageLib.sol";
import {PlasmaVault} from "../vaults/PlasmaVault.sol";
import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";

/// @notice Data structure for callback execution results
/// @param asset The token address that needs approval
/// @param addressToApprove The address to approve token spending
/// @param amountToApprove The amount of tokens to approve
/// @param actionData Encoded FuseAction array to execute after callback
struct CallbackData {
    address asset;
    address addressToApprove;
    uint256 amountToApprove;
    bytes actionData;
}

/// @title Callback Handler Library for Plasma Vault
/// @notice Manages callback execution and handler registration for the Plasma Vault system
/// @dev This library is used during Fuse execution to handle callbacks from external protocols
library CallbackHandlerLib {
    using Address for address;
    using SafeERC20 for ERC20;

    /// @notice Emitted when a callback handler is updated
    /// @param handler The address of the new callback handler
    /// @param sender The address that will trigger the callback
    /// @param sig The function signature that will trigger the callback
    event CallbackHandlerUpdated(address indexed handler, address indexed sender, bytes4 indexed sig);

    /// @notice Thrown when no handler is found for a callback
    error HandlerNotFound();

    /**
     * @notice Handles callbacks during Fuse execution in the Plasma Vault system
     * @dev Manages the execution flow of protocol callbacks during Fuse operations
     * - Can only be called during PlasmaVault.execute()
     * - Requires PlasmaVaultLib.isExecutionStarted() to be true
     * - Uses delegatecall for handler execution
     *
     * Execution Flow:
     * 1. Retrieves handler based on msg.sender and msg.sig hash
     * 2. Executes handler via delegatecall with original msg.data
     * 3. Processes handler return data if present:
     *    - Decodes as CallbackData struct
     *    - Executes additional FuseActions
     *    - Sets token approvals
     *
     * Integration Context:
     * - Called by PlasmaVault's fallback function
     * - Part of protocol integration system
     * - Enables complex multi-step operations
     * - Supports protocol-specific callbacks:
     *   - Compound supply/borrow callbacks
     *   - Aave flashloan callbacks
     *   - Other protocol-specific operations
     *
     * Error Conditions:
     * - Reverts with HandlerNotFound if no handler registered
     * - Bubbles up handler execution errors
     * - Validates handler return data format
     *
     * Security Considerations:
     * - Only executable during Fuse operations
     * - Handler must be pre-registered
     * - Uses safe delegatecall pattern
     * - Critical for protocol integration security
     *
     * Gas Considerations:
     * - Single storage read for handler lookup
     * - Dynamic gas cost based on handler logic
     * - Additional gas for FuseAction execution
     * - Token approval costs if required
     */
    function handleCallback() internal {
        /// @dev msg.sender - is the address of a contract which execute callback, msg.sig - is the signature of the function
        address handler = PlasmaVaultStorageLib.getCallbackHandler().callbackHandler[
            keccak256(abi.encodePacked(msg.sender, msg.sig))
        ];

        if (handler == address(0)) {
            revert HandlerNotFound();
        }

        bytes memory data = handler.functionCall(msg.data);

        if (data.length == 0) {
            return;
        }

        CallbackData memory calls = abi.decode(data, (CallbackData));

        PlasmaVault(address(this)).executeInternal(abi.decode(calls.actionData, (FuseAction[])));

        ERC20(calls.asset).forceApprove(calls.addressToApprove, calls.amountToApprove);
    }

    /**
     * @notice Updates or registers a callback handler in the Plasma Vault system
     * @dev Manages the registration and update of protocol-specific callback handlers
     * - Only callable through PlasmaVaultGovernance by ATOMIST_ROLE
     * - Updates PlasmaVaultStorageLib.CallbackHandler mapping
     * - Critical for protocol integration configuration
     *
     * Storage Updates:
     * 1. Maps handler to combination of sender and function signature
     * 2. Overwrites existing handler if present
     * 3. Emits CallbackHandlerUpdated event
     *
     * Integration Context:
     * - Called by PlasmaVaultGovernance.updateCallbackHandler()
     * - Part of protocol integration setup
     * - Used during vault configuration
     * - Supports protocol-specific handlers:
     *   - Compound callback handlers
     *   - Aave callback handlers
     *   - Other protocol-specific handlers
     *
     * Handler Requirements:
     * - Must implement standardized return format (CallbackData)
     * - Should handle protocol-specific callback logic
     * - Must maintain vault security invariants
     * - Should be stateless and reentrant-safe
     *
     * Security Considerations:
     * - Access restricted to ATOMIST_ROLE
     * - Handler address must be validated
     * - Critical for callback security
     * - Affects vault's protocol integration security
     * - Must verify handler compatibility
     *
     * Use Cases:
     * - Initial protocol integration setup
     * - Handler upgrades and maintenance
     * - Protocol version migrations
     * - Security patches
     *
     * @param handler_ The address of the callback handler contract
     * @param sender_ The address of the protocol contract that triggers callbacks
     * @param sig_ The function signature that identifies the callback
     * @custom:events Emits CallbackHandlerUpdated when successful
     *
     * Gas Considerations:
     * - One SSTORE for mapping update
     * - Event emission cost
     */
    function updateCallbackHandler(address handler_, address sender_, bytes4 sig_) internal {
        PlasmaVaultStorageLib.getCallbackHandler().callbackHandler[
            keccak256(abi.encodePacked(sender_, sig_))
        ] = handler_;
        emit CallbackHandlerUpdated(handler_, sender_, sig_);
    }
}

// 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: BUSL-1.1
pragma solidity 0.8.26;

import {IContextClient} from "./IContextClient.sol";
import {ContextClientStorageLib} from "./ContextClientStorageLib.sol";
import {AccessManagedUpgradeable} from "../access/AccessManagedUpgradeable.sol";

/**
 * @title ContextClient
 * @notice Contract that manages context for operations requiring sender context
 * @dev Implements IContextClient interface using ContextClientStorageLib for storage
 *
 * Role-based permissions:
 * - TECH_CONTEXT_MANAGER_ROLE: Can setup and clear context
 * - No other roles have direct access to context management
 *
 * Function permissions:
 * - setupContext: Restricted to TECH_CONTEXT_MANAGER_ROLE
 * - clearContext: Restricted to TECH_CONTEXT_MANAGER_ROLE
 * - getSenderFromContext: Internal function, no direct role restrictions
 *
 * Security considerations:
 * - Context operations are restricted to authorized managers only
 * - Single context enforcement prevents context manipulation
 * - Clear separation between context setup and usage
 *
 * @custom:security-contact security@yourproject.com
 */
abstract contract ContextClient is IContextClient, AccessManagedUpgradeable {
    /// @dev Custom errors for context-related operations
    /// @notice Thrown when attempting to set context when one is already active
    error ContextAlreadySet();
    /// @notice Thrown when attempting to clear or access context when none is set
    error ContextNotSet();
    /// @notice Thrown when an unauthorized address attempts to interact with protected functions
    error UnauthorizedSender();

    /**
     * @notice Sets up the context with the provided sender address
     * @param sender_ The address to set as the context sender
     * @dev Only callable by authorized contracts through the restricted modifier
     * @dev Uses ContextClientStorageLib for persistent storage
     * @custom:security Non-reentrant by design through single context restriction
     * @custom:access Restricted to TECH_CONTEXT_MANAGER_ROLE only
     * @custom:throws ContextAlreadySet if a context is currently active
     */
    function setupContext(address sender_) external override restricted {
        if (ContextClientStorageLib.isContextSenderSet()) {
            revert ContextAlreadySet();
        }

        ContextClientStorageLib.setContextSender(sender_);

        emit ContextSet(sender_);
    }

    /**
     * @notice Clears the current context
     * @dev Only callable by authorized contracts through the restricted modifier
     * @dev Uses ContextClientStorageLib for persistent storage
     * @custom:security Should always be called after context operations are complete
     * @custom:access Restricted to TECH_CONTEXT_MANAGER_ROLE only
     * @custom:throws ContextNotSet if no context is currently set
     */
    function clearContext() external override restricted {
        address currentSender = ContextClientStorageLib.getSenderFromContext();

        if (currentSender == address(0)) {
            revert ContextNotSet();
        }

        ContextClientStorageLib.clearContextStorage();

        emit ContextCleared(currentSender);
    }

    /**
     * @notice Retrieves the sender address from the current context
     * @dev Internal view function for derived contracts to access context
     * @return address The sender address stored in the current context
     * @custom:security Ensure proper access control in derived contracts
     * @custom:access Internal function - access controlled by inheriting contracts
     */
    function _getSenderFromContext() internal view returns (address) {
        return ContextClientStorageLib.getSenderFromContext();
    }
}

// SPDX-License-Identifier: BUSL-1.1
pragma solidity 0.8.26;

/// @title ContextClientStorageLib
/// @notice Library for managing context sender storage in DeFi vault operations
/// @dev Implements a storage pattern using an isolated storage slot to maintain sender context
/// @custom:security This library is critical for maintaining caller context across contract interactions
/// @custom:security-contact security@ipor.io
library ContextClientStorageLib {
    /// @dev Unique storage slot for context sender data
    /// @dev Calculated as: keccak256(abi.encode(uint256(keccak256("io.ipor.context.client.sender.storage")) - 1)) & ~bytes32(uint256(0xff))
    /// @dev The last byte is cleared to allow for additional storage patterns
    /// @dev This specific slot ensures no storage collision with other contract storage
    /// @custom:security Uses ERC-7201 namespaced storage pattern to prevent storage collisions
    bytes32 private constant CONTEXT_SENDER_STORAGE_SLOT =
        0x68262fe08792a71a690eb5eb2de15df1b0f463dd786bf92bdbd5f0f0d1ae8b00;

    /// @dev Structure holding the context sender information
    /// @custom:storage-location erc7201:io.ipor.context.client.storage
    /// @custom:security Isolated storage pattern to prevent unauthorized access and storage collisions
    struct ContextSenderStorage {
        /// @dev The address of the current context sender
        /// @dev If address(0), no context is set, indicating direct interaction
        /// @dev Used to track the original caller across multiple contract interactions
        address contextSender;
    }

    /// @notice Sets the context sender address for the current transaction context
    /// @dev Should be called at the beginning of a context-dependent operation
    /// @dev Critical for maintaining caller context in complex vault operations
    /// @param sender_ The address to set as the context sender
    /// @custom:security Only callable by authorized contracts in the system
    /// @custom:security-risk HIGH - Incorrect context setting can lead to unauthorized access
    function setContextSender(address sender_) internal {
        ContextSenderStorage storage $ = _getContextSenderStorage();
        $.contextSender = sender_;
    }

    /// @notice Clears the current context by setting the sender to address(0)
    /// @dev Must be called at the end of context-dependent operations
    /// @dev Prevents context leaking between different operations
    /// @custom:security Critical for security to prevent context pollution
    /// @custom:security-risk MEDIUM - Failing to clear context could lead to unauthorized access
    function clearContextStorage() internal {
        ContextSenderStorage storage $ = _getContextSenderStorage();
        $.contextSender = address(0);
    }

    /// @notice Retrieves the current context sender address
    /// @dev Returns the currently set context sender without modification
    /// @return The address of the current context sender
    /// @custom:security Returns address(0) if no context is set
    function getContextSender() internal view returns (address) {
        ContextSenderStorage storage $ = _getContextSenderStorage();
        return $.contextSender;
    }

    /// @notice Verifies if a valid context sender is currently set
    /// @dev Used to determine if we're operating within a delegated context
    /// @return bool True if a valid context sender is set, false otherwise
    /// @custom:security Used for control flow in permission checks
    function isContextSenderSet() internal view returns (bool) {
        ContextSenderStorage storage $ = _getContextSenderStorage();
        return $.contextSender != address(0);
    }

    /// @notice Gets the effective sender address for the current operation
    /// @dev Core function for determining the actual caller in vault operations
    /// @return address The effective sender address (context sender or msg.sender)
    /// @custom:security Critical for access control and permission validation
    /// @custom:security-risk HIGH - Core component of permission system
    function getSenderFromContext() internal view returns (address) {
        address sender = getContextSender();

        if (sender == address(0)) {
            return msg.sender;
        }

        return sender;
    }

    /// @dev Internal function to access the context storage slot
    /// @return $ Storage pointer to the ContextSenderStorage struct
    /// @custom:security Uses assembly to access a specific storage slot
    /// @custom:security Uses ERC-7201 namespaced storage pattern
    function _getContextSenderStorage() private pure returns (ContextSenderStorage storage $) {
        assembly {
            $.slot := CONTEXT_SENDER_STORAGE_SLOT
        }
    }
}

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

pragma solidity ^0.8.20;
import {Initializable} from "../proxy/utils/Initializable.sol";

/**
 * @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 ContextUpgradeable is Initializable {
    function __Context_init() internal onlyInitializing {
    }

    function __Context_init_unchained() internal onlyInitializing {
    }
    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
// OpenZeppelin Contracts (last updated v5.0.0) (token/ERC20/ERC20.sol)

pragma solidity ^0.8.20;

import {IERC20} from "./IERC20.sol";
import {IERC20Metadata} from "./extensions/IERC20Metadata.sol";
import {Context} from "../../utils/Context.sol";
import {IERC20Errors} from "../../interfaces/draft-IERC6093.sol";

/**
 * @dev Implementation of the {IERC20} interface.
 *
 * This implementation is agnostic to the way tokens are created. This means
 * that a supply mechanism has to be added in a derived contract using {_mint}.
 *
 * TIP: For a detailed writeup see our guide
 * https://forum.openzeppelin.com/t/how-to-implement-erc20-supply-mechanisms/226[How
 * to implement supply mechanisms].
 *
 * The default value of {decimals} is 18. To change this, you should override
 * this function so it returns a different value.
 *
 * We have followed general OpenZeppelin Contracts guidelines: functions revert
 * instead returning `false` on failure. This behavior is nonetheless
 * conventional and does not conflict with the expectations of ERC20
 * applications.
 *
 * Additionally, an {Approval} event is emitted on calls to {transferFrom}.
 * This allows applications to reconstruct the allowance for all accounts just
 * by listening to said events. Other implementations of the EIP may not emit
 * these events, as it isn't required by the specification.
 */
abstract contract ERC20 is Context, IERC20, IERC20Metadata, IERC20Errors {
    mapping(address account => uint256) private _balances;

    mapping(address account => mapping(address spender => uint256)) private _allowances;

    uint256 private _totalSupply;

    string private _name;
    string private _symbol;

    /**
     * @dev Sets the values for {name} and {symbol}.
     *
     * All two of these values are immutable: they can only be set once during
     * construction.
     */
    constructor(string memory name_, string memory symbol_) {
        _name = name_;
        _symbol = symbol_;
    }

    /**
     * @dev Returns the name of the token.
     */
    function name() public view virtual returns (string memory) {
        return _name;
    }

    /**
     * @dev Returns the symbol of the token, usually a shorter version of the
     * name.
     */
    function symbol() public view virtual returns (string memory) {
        return _symbol;
    }

    /**
     * @dev Returns the number of decimals used to get its user representation.
     * For example, if `decimals` equals `2`, a balance of `505` tokens should
     * be displayed to a user as `5.05` (`505 / 10 ** 2`).
     *
     * Tokens usually opt for a value of 18, imitating the relationship between
     * Ether and Wei. This is the default value returned by this function, unless
     * it's overridden.
     *
     * NOTE: This information is only used for _display_ purposes: it in
     * no way affects any of the arithmetic of the contract, including
     * {IERC20-balanceOf} and {IERC20-transfer}.
     */
    function decimals() public view virtual returns (uint8) {
        return 18;
    }

    /**
     * @dev See {IERC20-totalSupply}.
     */
    function totalSupply() public view virtual returns (uint256) {
        return _totalSupply;
    }

    /**
     * @dev See {IERC20-balanceOf}.
     */
    function balanceOf(address account) public view virtual returns (uint256) {
        return _balances[account];
    }

    /**
     * @dev See {IERC20-transfer}.
     *
     * Requirements:
     *
     * - `to` cannot be the zero address.
     * - the caller must have a balance of at least `value`.
     */
    function transfer(address to, uint256 value) public virtual returns (bool) {
        address owner = _msgSender();
        _transfer(owner, to, value);
        return true;
    }

    /**
     * @dev See {IERC20-allowance}.
     */
    function allowance(address owner, address spender) public view virtual returns (uint256) {
        return _allowances[owner][spender];
    }

    /**
     * @dev See {IERC20-approve}.
     *
     * NOTE: If `value` is the maximum `uint256`, the allowance is not updated on
     * `transferFrom`. This is semantically equivalent to an infinite approval.
     *
     * Requirements:
     *
     * - `spender` cannot be the zero address.
     */
    function approve(address spender, uint256 value) public virtual returns (bool) {
        address owner = _msgSender();
        _approve(owner, spender, value);
        return true;
    }

    /**
     * @dev See {IERC20-transferFrom}.
     *
     * Emits an {Approval} event indicating the updated allowance. This is not
     * required by the EIP. See the note at the beginning of {ERC20}.
     *
     * NOTE: Does not update the allowance if the current allowance
     * is the maximum `uint256`.
     *
     * Requirements:
     *
     * - `from` and `to` cannot be the zero address.
     * - `from` must have a balance of at least `value`.
     * - the caller must have allowance for ``from``'s tokens of at least
     * `value`.
     */
    function transferFrom(address from, address to, uint256 value) public virtual returns (bool) {
        address spender = _msgSender();
        _spendAllowance(from, spender, value);
        _transfer(from, to, value);
        return true;
    }

    /**
     * @dev Moves a `value` amount of tokens from `from` to `to`.
     *
     * This internal function is equivalent to {transfer}, and can be used to
     * e.g. implement automatic token fees, slashing mechanisms, etc.
     *
     * Emits a {Transfer} event.
     *
     * NOTE: This function is not virtual, {_update} should be overridden instead.
     */
    function _transfer(address from, address to, uint256 value) internal {
        if (from == address(0)) {
            revert ERC20InvalidSender(address(0));
        }
        if (to == address(0)) {
            revert ERC20InvalidReceiver(address(0));
        }
        _update(from, to, value);
    }

    /**
     * @dev Transfers a `value` amount of tokens from `from` to `to`, or alternatively mints (or burns) if `from`
     * (or `to`) is the zero address. All customizations to transfers, mints, and burns should be done by overriding
     * this function.
     *
     * Emits a {Transfer} event.
     */
    function _update(address from, address to, uint256 value) internal virtual {
        if (from == address(0)) {
            // Overflow check required: The rest of the code assumes that totalSupply never overflows
            _totalSupply += value;
        } else {
            uint256 fromBalance = _balances[from];
            if (fromBalance < value) {
                revert ERC20InsufficientBalance(from, fromBalance, value);
            }
            unchecked {
                // Overflow not possible: value <= fromBalance <= totalSupply.
                _balances[from] = fromBalance - value;
            }
        }

        if (to == address(0)) {
            unchecked {
                // Overflow not possible: value <= totalSupply or value <= fromBalance <= totalSupply.
                _totalSupply -= value;
            }
        } else {
            unchecked {
                // Overflow not possible: balance + value is at most totalSupply, which we know fits into a uint256.
                _balances[to] += value;
            }
        }

        emit Transfer(from, to, value);
    }

    /**
     * @dev Creates a `value` amount of tokens and assigns them to `account`, by transferring it from address(0).
     * Relies on the `_update` mechanism
     *
     * Emits a {Transfer} event with `from` set to the zero address.
     *
     * NOTE: This function is not virtual, {_update} should be overridden instead.
     */
    function _mint(address account, uint256 value) internal {
        if (account == address(0)) {
            revert ERC20InvalidReceiver(address(0));
        }
        _update(address(0), account, value);
    }

    /**
     * @dev Destroys a `value` amount of tokens from `account`, lowering the total supply.
     * Relies on the `_update` mechanism.
     *
     * Emits a {Transfer} event with `to` set to the zero address.
     *
     * NOTE: This function is not virtual, {_update} should be overridden instead
     */
    function _burn(address account, uint256 value) internal {
        if (account == address(0)) {
            revert ERC20InvalidSender(address(0));
        }
        _update(account, address(0), value);
    }

    /**
     * @dev Sets `value` as the allowance of `spender` over the `owner` s tokens.
     *
     * This internal function is equivalent to `approve`, and can be used to
     * e.g. set automatic allowances for certain subsystems, etc.
     *
     * Emits an {Approval} event.
     *
     * Requirements:
     *
     * - `owner` cannot be the zero address.
     * - `spender` cannot be the zero address.
     *
     * Overrides to this logic should be done to the variant with an additional `bool emitEvent` argument.
     */
    function _approve(address owner, address spender, uint256 value) internal {
        _approve(owner, spender, value, true);
    }

    /**
     * @dev Variant of {_approve} with an optional flag to enable or disable the {Approval} event.
     *
     * By default (when calling {_approve}) the flag is set to true. On the other hand, approval changes made by
     * `_spendAllowance` during the `transferFrom` operation set the flag to false. This saves gas by not emitting any
     * `Approval` event during `transferFrom` operations.
     *
     * Anyone who wishes to continue emitting `Approval` events on the`transferFrom` operation can force the flag to
     * true using the following override:
     * ```
     * function _approve(address owner, address spender, uint256 value, bool) internal virtual override {
     *     super._approve(owner, spender, value, true);
     * }
     * ```
     *
     * Requirements are the same as {_approve}.
     */
    function _approve(address owner, address spender, uint256 value, bool emitEvent) internal virtual {
        if (owner == address(0)) {
            revert ERC20InvalidApprover(address(0));
        }
        if (spender == address(0)) {
            revert ERC20InvalidSpender(address(0));
        }
        _allowances[owner][spender] = value;
        if (emitEvent) {
            emit Approval(owner, spender, value);
        }
    }

    /**
     * @dev Updates `owner` s allowance for `spender` based on spent `value`.
     *
     * Does not update the allowance value in case of infinite allowance.
     * Revert if not enough allowance is available.
     *
     * Does not emit an {Approval} event.
     */
    function _spendAllowance(address owner, address spender, uint256 value) internal virtual {
        uint256 currentAllowance = allowance(owner, spender);
        if (currentAllowance != type(uint256).max) {
            if (currentAllowance < value) {
                revert ERC20InsufficientAllowance(spender, currentAllowance, value);
            }
            unchecked {
                _approve(owner, spender, currentAllowance - value, false);
            }
        }
    }
}

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

pragma solidity ^0.8.20;

import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import {IERC20Metadata} from "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol";
import {ContextUpgradeable} from "../../utils/ContextUpgradeable.sol";
import {IERC20Errors} from "@openzeppelin/contracts/interfaces/draft-IERC6093.sol";
import {Initializable} from "../../proxy/utils/Initializable.sol";

/**
 * @dev Implementation of the {IERC20} interface.
 *
 * This implementation is agnostic to the way tokens are created. This means
 * that a supply mechanism has to be added in a derived contract using {_mint}.
 *
 * TIP: For a detailed writeup see our guide
 * https://forum.openzeppelin.com/t/how-to-implement-erc20-supply-mechanisms/226[How
 * to implement supply mechanisms].
 *
 * The default value of {decimals} is 18. To change this, you should override
 * this function so it returns a different value.
 *
 * We have followed general OpenZeppelin Contracts guidelines: functions revert
 * instead returning `false` on failure. This behavior is nonetheless
 * conventional and does not conflict with the expectations of ERC20
 * applications.
 *
 * Additionally, an {Approval} event is emitted on calls to {transferFrom}.
 * This allows applications to reconstruct the allowance for all accounts just
 * by listening to said events. Other implementations of the EIP may not emit
 * these events, as it isn't required by the specification.
 */
abstract contract ERC20Upgradeable is Initializable, ContextUpgradeable, IERC20, IERC20Metadata, IERC20Errors {
    /// @custom:storage-location erc7201:openzeppelin.storage.ERC20
    struct ERC20Storage {
        mapping(address account => uint256) _balances;

        mapping(address account => mapping(address spender => uint256)) _allowances;

        uint256 _totalSupply;

        string _name;
        string _symbol;
    }

    // keccak256(abi.encode(uint256(keccak256("openzeppelin.storage.ERC20")) - 1)) & ~bytes32(uint256(0xff))
    bytes32 private constant ERC20StorageLocation = 0x52c63247e1f47db19d5ce0460030c497f067ca4cebf71ba98eeadabe20bace00;

    function _getERC20Storage() private pure returns (ERC20Storage storage $) {
        assembly {
            $.slot := ERC20StorageLocation
        }
    }

    /**
     * @dev Sets the values for {name} and {symbol}.
     *
     * All two of these values are immutable: they can only be set once during
     * construction.
     */
    function __ERC20_init(string memory name_, string memory symbol_) internal onlyInitializing {
        __ERC20_init_unchained(name_, symbol_);
    }

    function __ERC20_init_unchained(string memory name_, string memory symbol_) internal onlyInitializing {
        ERC20Storage storage $ = _getERC20Storage();
        $._name = name_;
        $._symbol = symbol_;
    }

    /**
     * @dev Returns the name of the token.
     */
    function name() public view virtual returns (string memory) {
        ERC20Storage storage $ = _getERC20Storage();
        return $._name;
    }

    /**
     * @dev Returns the symbol of the token, usually a shorter version of the
     * name.
     */
    function symbol() public view virtual returns (string memory) {
        ERC20Storage storage $ = _getERC20Storage();
        return $._symbol;
    }

    /**
     * @dev Returns the number of decimals used to get its user representation.
     * For example, if `decimals` equals `2`, a balance of `505` tokens should
     * be displayed to a user as `5.05` (`505 / 10 ** 2`).
     *
     * Tokens usually opt for a value of 18, imitating the relationship between
     * Ether and Wei. This is the default value returned by this function, unless
     * it's overridden.
     *
     * NOTE: This information is only used for _display_ purposes: it in
     * no way affects any of the arithmetic of the contract, including
     * {IERC20-balanceOf} and {IERC20-transfer}.
     */
    function decimals() public view virtual returns (uint8) {
        return 18;
    }

    /**
     * @dev See {IERC20-totalSupply}.
     */
    function totalSupply() public view virtual returns (uint256) {
        ERC20Storage storage $ = _getERC20Storage();
        return $._totalSupply;
    }

    /**
     * @dev See {IERC20-balanceOf}.
     */
    function balanceOf(address account) public view virtual returns (uint256) {
        ERC20Storage storage $ = _getERC20Storage();
        return $._balances[account];
    }

    /**
     * @dev See {IERC20-transfer}.
     *
     * Requirements:
     *
     * - `to` cannot be the zero address.
     * - the caller must have a balance of at least `value`.
     */
    function transfer(address to, uint256 value) public virtual returns (bool) {
        address owner = _msgSender();
        _transfer(owner, to, value);
        return true;
    }

    /**
     * @dev See {IERC20-allowance}.
     */
    function allowance(address owner, address spender) public view virtual returns (uint256) {
        ERC20Storage storage $ = _getERC20Storage();
        return $._allowances[owner][spender];
    }

    /**
     * @dev See {IERC20-approve}.
     *
     * NOTE: If `value` is the maximum `uint256`, the allowance is not updated on
     * `transferFrom`. This is semantically equivalent to an infinite approval.
     *
     * Requirements:
     *
     * - `spender` cannot be the zero address.
     */
    function approve(address spender, uint256 value) public virtual returns (bool) {
        address owner = _msgSender();
        _approve(owner, spender, value);
        return true;
    }

    /**
     * @dev See {IERC20-transferFrom}.
     *
     * Emits an {Approval} event indicating the updated allowance. This is not
     * required by the EIP. See the note at the beginning of {ERC20}.
     *
     * NOTE: Does not update the allowance if the current allowance
     * is the maximum `uint256`.
     *
     * Requirements:
     *
     * - `from` and `to` cannot be the zero address.
     * - `from` must have a balance of at least `value`.
     * - the caller must have allowance for ``from``'s tokens of at least
     * `value`.
     */
    function transferFrom(address from, address to, uint256 value) public virtual returns (bool) {
        address spender = _msgSender();
        _spendAllowance(from, spender, value);
        _transfer(from, to, value);
        return true;
    }

    /**
     * @dev Moves a `value` amount of tokens from `from` to `to`.
     *
     * This internal function is equivalent to {transfer}, and can be used to
     * e.g. implement automatic token fees, slashing mechanisms, etc.
     *
     * Emits a {Transfer} event.
     *
     * NOTE: This function is not virtual, {_update} should be overridden instead.
     */
    function _transfer(address from, address to, uint256 value) internal {
        if (from == address(0)) {
            revert ERC20InvalidSender(address(0));
        }
        if (to == address(0)) {
            revert ERC20InvalidReceiver(address(0));
        }
        _update(from, to, value);
    }

    /**
     * @dev Transfers a `value` amount of tokens from `from` to `to`, or alternatively mints (or burns) if `from`
     * (or `to`) is the zero address. All customizations to transfers, mints, and burns should be done by overriding
     * this function.
     *
     * Emits a {Transfer} event.
     */
    function _update(address from, address to, uint256 value) internal virtual {
        ERC20Storage storage $ = _getERC20Storage();
        if (from == address(0)) {
            // Overflow check required: The rest of the code assumes that totalSupply never overflows
            $._totalSupply += value;
        } else {
            uint256 fromBalance = $._balances[from];
            if (fromBalance < value) {
                revert ERC20InsufficientBalance(from, fromBalance, value);
            }
            unchecked {
                // Overflow not possible: value <= fromBalance <= totalSupply.
                $._balances[from] = fromBalance - value;
            }
        }

        if (to == address(0)) {
            unchecked {
                // Overflow not possible: value <= totalSupply or value <= fromBalance <= totalSupply.
                $._totalSupply -= value;
            }
        } else {
            unchecked {
                // Overflow not possible: balance + value is at most totalSupply, which we know fits into a uint256.
                $._balances[to] += value;
            }
        }

        emit Transfer(from, to, value);
    }

    /**
     * @dev Creates a `value` amount of tokens and assigns them to `account`, by transferring it from address(0).
     * Relies on the `_update` mechanism
     *
     * Emits a {Transfer} event with `from` set to the zero address.
     *
     * NOTE: This function is not virtual, {_update} should be overridden instead.
     */
    function _mint(address account, uint256 value) internal {
        if (account == address(0)) {
            revert ERC20InvalidReceiver(address(0));
        }
        _update(address(0), account, value);
    }

    /**
     * @dev Destroys a `value` amount of tokens from `account`, lowering the total supply.
     * Relies on the `_update` mechanism.
     *
     * Emits a {Transfer} event with `to` set to the zero address.
     *
     * NOTE: This function is not virtual, {_update} should be overridden instead
     */
    function _burn(address account, uint256 value) internal {
        if (account == address(0)) {
            revert ERC20InvalidSender(address(0));
        }
        _update(account, address(0), value);
    }

    /**
     * @dev Sets `value` as the allowance of `spender` over the `owner` s tokens.
     *
     * This internal function is equivalent to `approve`, and can be used to
     * e.g. set automatic allowances for certain subsystems, etc.
     *
     * Emits an {Approval} event.
     *
     * Requirements:
     *
     * - `owner` cannot be the zero address.
     * - `spender` cannot be the zero address.
     *
     * Overrides to this logic should be done to the variant with an additional `bool emitEvent` argument.
     */
    function _approve(address owner, address spender, uint256 value) internal {
        _approve(owner, spender, value, true);
    }

    /**
     * @dev Variant of {_approve} with an optional flag to enable or disable the {Approval} event.
     *
     * By default (when calling {_approve}) the flag is set to true. On the other hand, approval changes made by
     * `_spendAllowance` during the `transferFrom` operation set the flag to false. This saves gas by not emitting any
     * `Approval` event during `transferFrom` operations.
     *
     * Anyone who wishes to continue emitting `Approval` events on the`transferFrom` operation can force the flag to
     * true using the following override:
     * ```
     * function _approve(address owner, address spender, uint256 value, bool) internal virtual override {
     *     super._approve(owner, spender, value, true);
     * }
     * ```
     *
     * Requirements are the same as {_approve}.
     */
    function _approve(address owner, address spender, uint256 value, bool emitEvent) internal virtual {
        ERC20Storage storage $ = _getERC20Storage();
        if (owner == address(0)) {
            revert ERC20InvalidApprover(address(0));
        }
        if (spender == address(0)) {
            revert ERC20InvalidSpender(address(0));
        }
        $._allowances[owner][spender] = value;
        if (emitEvent) {
            emit Approval(owner, spender, value);
        }
    }

    /**
     * @dev Updates `owner` s allowance for `spender` based on spent `value`.
     *
     * Does not update the allowance value in case of infinite allowance.
     * Revert if not enough allowance is available.
     *
     * Does not emit an {Approval} event.
     */
    function _spendAllowance(address owner, address spender, uint256 value) internal virtual {
        uint256 currentAllowance = allowance(owner, spender);
        if (currentAllowance != type(uint256).max) {
            if (currentAllowance < value) {
                revert ERC20InsufficientAllowance(spender, currentAllowance, value);
            }
            unchecked {
                _approve(owner, spender, currentAllowance - value, false);
            }
        }
    }
}

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

pragma solidity ^0.8.20;

import {IERC20, IERC20Metadata, ERC20} from "../ERC20.sol";
import {SafeERC20} from "../utils/SafeERC20.sol";
import {IERC4626} from "../../../interfaces/IERC4626.sol";
import {Math} from "../../../utils/math/Math.sol";

/**
 * @dev Implementation of the ERC4626 "Tokenized Vault Standard" as defined in
 * https://eips.ethereum.org/EIPS/eip-4626[EIP-4626].
 *
 * This extension allows the minting and burning of "shares" (represented using the ERC20 inheritance) in exchange for
 * underlying "assets" through standardized {deposit}, {mint}, {redeem} and {burn} workflows. This contract extends
 * the ERC20 standard. Any additional extensions included along it would affect the "shares" token represented by this
 * contract and not the "assets" token which is an independent contract.
 *
 * [CAUTION]
 * ====
 * In empty (or nearly empty) ERC-4626 vaults, deposits are at high risk of being stolen through frontrunning
 * with a "donation" to the vault that inflates the price of a share. This is variously known as a donation or inflation
 * attack and is essentially a problem of slippage. Vault deployers can protect against this attack by making an initial
 * deposit of a non-trivial amount of the asset, such that price manipulation becomes infeasible. Withdrawals may
 * similarly be affected by slippage. Users can protect against this attack as well as unexpected slippage in general by
 * verifying the amount received is as expected, using a wrapper that performs these checks such as
 * https://github.com/fei-protocol/ERC4626#erc4626router-and-base[ERC4626Router].
 *
 * Since v4.9, this implementation uses virtual assets and shares to mitigate that risk. The `_decimalsOffset()`
 * corresponds to an offset in the decimal representation between the underlying asset's decimals and the vault
 * decimals. This offset also determines the rate of virtual shares to virtual assets in the vault, which itself
 * determines the initial exchange rate. While not fully preventing the attack, analysis shows that the default offset
 * (0) makes it non-profitable, as a result of the value being captured by the virtual shares (out of the attacker's
 * donation) matching the attacker's expected gains. With a larger offset, the attack becomes orders of magnitude more
 * expensive than it is profitable. More details about the underlying math can be found
 * xref:erc4626.adoc#inflation-attack[here].
 *
 * The drawback of this approach is that the virtual shares do capture (a very small) part of the value being accrued
 * to the vault. Also, if the vault experiences losses, the users try to exit the vault, the virtual shares and assets
 * will cause the first user to exit to experience reduced losses in detriment to the last users that will experience
 * bigger losses. Developers willing to revert back to the pre-v4.9 behavior just need to override the
 * `_convertToShares` and `_convertToAssets` functions.
 *
 * To learn more, check out our xref:ROOT:erc4626.adoc[ERC-4626 guide].
 * ====
 */
abstract contract ERC4626 is ERC20, IERC4626 {
    using Math for uint256;

    IERC20 private immutable _asset;
    uint8 private immutable _underlyingDecimals;

    /**
     * @dev Attempted to deposit more assets than the max amount for `receiver`.
     */
    error ERC4626ExceededMaxDeposit(address receiver, uint256 assets, uint256 max);

    /**
     * @dev Attempted to mint more shares than the max amount for `receiver`.
     */
    error ERC4626ExceededMaxMint(address receiver, uint256 shares, uint256 max);

    /**
     * @dev Attempted to withdraw more assets than the max amount for `receiver`.
     */
    error ERC4626ExceededMaxWithdraw(address owner, uint256 assets, uint256 max);

    /**
     * @dev Attempted to redeem more shares than the max amount for `receiver`.
     */
    error ERC4626ExceededMaxRedeem(address owner, uint256 shares, uint256 max);

    /**
     * @dev Set the underlying asset contract. This must be an ERC20-compatible contract (ERC20 or ERC777).
     */
    constructor(IERC20 asset_) {
        (bool success, uint8 assetDecimals) = _tryGetAssetDecimals(asset_);
        _underlyingDecimals = success ? assetDecimals : 18;
        _asset = asset_;
    }

    /**
     * @dev Attempts to fetch the asset decimals. A return value of false indicates that the attempt failed in some way.
     */
    function _tryGetAssetDecimals(IERC20 asset_) private view returns (bool, uint8) {
        (bool success, bytes memory encodedDecimals) = address(asset_).staticcall(
            abi.encodeCall(IERC20Metadata.decimals, ())
        );
        if (success && encodedDecimals.length >= 32) {
            uint256 returnedDecimals = abi.decode(encodedDecimals, (uint256));
            if (returnedDecimals <= type(uint8).max) {
                return (true, uint8(returnedDecimals));
            }
        }
        return (false, 0);
    }

    /**
     * @dev Decimals are computed by adding the decimal offset on top of the underlying asset's decimals. This
     * "original" value is cached during construction of the vault contract. If this read operation fails (e.g., the
     * asset has not been created yet), a default of 18 is used to represent the underlying asset's decimals.
     *
     * See {IERC20Metadata-decimals}.
     */
    function decimals() public view virtual override(IERC20Metadata, ERC20) returns (uint8) {
        return _underlyingDecimals + _decimalsOffset();
    }

    /** @dev See {IERC4626-asset}. */
    function asset() public view virtual returns (address) {
        return address(_asset);
    }

    /** @dev See {IERC4626-totalAssets}. */
    function totalAssets() public view virtual returns (uint256) {
        return _asset.balanceOf(address(this));
    }

    /** @dev See {IERC4626-convertToShares}. */
    function convertToShares(uint256 assets) public view virtual returns (uint256) {
        return _convertToShares(assets, Math.Rounding.Floor);
    }

    /** @dev See {IERC4626-convertToAssets}. */
    function convertToAssets(uint256 shares) public view virtual returns (uint256) {
        return _convertToAssets(shares, Math.Rounding.Floor);
    }

    /** @dev See {IERC4626-maxDeposit}. */
    function maxDeposit(address) public view virtual returns (uint256) {
        return type(uint256).max;
    }

    /** @dev See {IERC4626-maxMint}. */
    function maxMint(address) public view virtual returns (uint256) {
        return type(uint256).max;
    }

    /** @dev See {IERC4626-maxWithdraw}. */
    function maxWithdraw(address owner) public view virtual returns (uint256) {
        return _convertToAssets(balanceOf(owner), Math.Rounding.Floor);
    }

    /** @dev See {IERC4626-maxRedeem}. */
    function maxRedeem(address owner) public view virtual returns (uint256) {
        return balanceOf(owner);
    }

    /** @dev See {IERC4626-previewDeposit}. */
    function previewDeposit(uint256 assets) public view virtual returns (uint256) {
        return _convertToShares(assets, Math.Rounding.Floor);
    }

    /** @dev See {IERC4626-previewMint}. */
    function previewMint(uint256 shares) public view virtual returns (uint256) {
        return _convertToAssets(shares, Math.Rounding.Ceil);
    }

    /** @dev See {IERC4626-previewWithdraw}. */
    function previewWithdraw(uint256 assets) public view virtual returns (uint256) {
        return _convertToShares(assets, Math.Rounding.Ceil);
    }

    /** @dev See {IERC4626-previewRedeem}. */
    function previewRedeem(uint256 shares) public view virtual returns (uint256) {
        return _convertToAssets(shares, Math.Rounding.Floor);
    }

    /** @dev See {IERC4626-deposit}. */
    function deposit(uint256 assets, address receiver) public virtual returns (uint256) {
        uint256 maxAssets = maxDeposit(receiver);
        if (assets > maxAssets) {
            revert ERC4626ExceededMaxDeposit(receiver, assets, maxAssets);
        }

        uint256 shares = previewDeposit(assets);
        _deposit(_msgSender(), receiver, assets, shares);

        return shares;
    }

    /** @dev See {IERC4626-mint}.
     *
     * As opposed to {deposit}, minting is allowed even if the vault is in a state where the price of a share is zero.
     * In this case, the shares will be minted without requiring any assets to be deposited.
     */
    function mint(uint256 shares, address receiver) public virtual returns (uint256) {
        uint256 maxShares = maxMint(receiver);
        if (shares > maxShares) {
            revert ERC4626ExceededMaxMint(receiver, shares, maxShares);
        }

        uint256 assets = previewMint(shares);
        _deposit(_msgSender(), receiver, assets, shares);

        return assets;
    }

    /** @dev See {IERC4626-withdraw}. */
    function withdraw(uint256 assets, address receiver, address owner) public virtual returns (uint256) {
        uint256 maxAssets = maxWithdraw(owner);
        if (assets > maxAssets) {
            revert ERC4626ExceededMaxWithdraw(owner, assets, maxAssets);
        }

        uint256 shares = previewWithdraw(assets);
        _withdraw(_msgSender(), receiver, owner, assets, shares);

        return shares;
    }

    /** @dev See {IERC4626-redeem}. */
    function redeem(uint256 shares, address receiver, address owner) public virtual returns (uint256) {
        uint256 maxShares = maxRedeem(owner);
        if (shares > maxShares) {
            revert ERC4626ExceededMaxRedeem(owner, shares, maxShares);
        }

        uint256 assets = previewRedeem(shares);
        _withdraw(_msgSender(), receiver, owner, assets, shares);

        return assets;
    }

    /**
     * @dev Internal conversion function (from assets to shares) with support for rounding direction.
     */
    function _convertToShares(uint256 assets, Math.Rounding rounding) internal view virtual returns (uint256) {
        return assets.mulDiv(totalSupply() + 10 ** _decimalsOffset(), totalAssets() + 1, rounding);
    }

    /**
     * @dev Internal conversion function (from shares to assets) with support for rounding direction.
     */
    function _convertToAssets(uint256 shares, Math.Rounding rounding) internal view virtual returns (uint256) {
        return shares.mulDiv(totalAssets() + 1, totalSupply() + 10 ** _decimalsOffset(), rounding);
    }

    /**
     * @dev Deposit/mint common workflow.
     */
    function _deposit(address caller, address receiver, uint256 assets, uint256 shares) internal virtual {
        // If _asset is ERC777, `transferFrom` can trigger a reentrancy BEFORE the transfer happens through the
        // `tokensToSend` hook. On the other hand, the `tokenReceived` hook, that is triggered after the transfer,
        // calls the vault, which is assumed not malicious.
        //
        // Conclusion: we need to do the transfer before we mint so that any reentrancy would happen before the
        // assets are transferred and before the shares are minted, which is a valid state.
        // slither-disable-next-line reentrancy-no-eth
        SafeERC20.safeTransferFrom(_asset, caller, address(this), assets);
        _mint(receiver, shares);

        emit Deposit(caller, receiver, assets, shares);
    }

    /**
     * @dev Withdraw/redeem common workflow.
     */
    function _withdraw(
        address caller,
        address receiver,
        address owner,
        uint256 assets,
        uint256 shares
    ) internal virtual {
        if (caller != owner) {
            _spendAllowance(owner, caller, shares);
        }

        // If _asset is ERC777, `transfer` can trigger a reentrancy AFTER the transfer happens through the
        // `tokensReceived` hook. On the other hand, the `tokensToSend` hook, that is triggered before the transfer,
        // calls the vault, which is assumed not malicious.
        //
        // Conclusion: we need to do the transfer after the burn so that any reentrancy would happen after the
        // shares are burned and after the assets are transferred, which is a valid state.
        _burn(owner, shares);
        SafeERC20.safeTransfer(_asset, receiver, assets);

        emit Withdraw(caller, receiver, owner, assets, shares);
    }

    function _decimalsOffset() internal view virtual returns (uint8) {
        return 0;
    }
}

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

pragma solidity ^0.8.20;

import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import {IERC20Metadata} from "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol";
import {ERC20Upgradeable} from "../ERC20Upgradeable.sol";
import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
import {IERC4626} from "@openzeppelin/contracts/interfaces/IERC4626.sol";
import {Math} from "@openzeppelin/contracts/utils/math/Math.sol";
import {Initializable} from "../../../proxy/utils/Initializable.sol";

/**
 * @dev Implementation of the ERC4626 "Tokenized Vault Standard" as defined in
 * https://eips.ethereum.org/EIPS/eip-4626[EIP-4626].
 *
 * This extension allows the minting and burning of "shares" (represented using the ERC20 inheritance) in exchange for
 * underlying "assets" through standardized {deposit}, {mint}, {redeem} and {burn} workflows. This contract extends
 * the ERC20 standard. Any additional extensions included along it would affect the "shares" token represented by this
 * contract and not the "assets" token which is an independent contract.
 *
 * [CAUTION]
 * ====
 * In empty (or nearly empty) ERC-4626 vaults, deposits are at high risk of being stolen through frontrunning
 * with a "donation" to the vault that inflates the price of a share. This is variously known as a donation or inflation
 * attack and is essentially a problem of slippage. Vault deployers can protect against this attack by making an initial
 * deposit of a non-trivial amount of the asset, such that price manipulation becomes infeasible. Withdrawals may
 * similarly be affected by slippage. Users can protect against this attack as well as unexpected slippage in general by
 * verifying the amount received is as expected, using a wrapper that performs these checks such as
 * https://github.com/fei-protocol/ERC4626#erc4626router-and-base[ERC4626Router].
 *
 * Since v4.9, this implementation uses virtual assets and shares to mitigate that risk. The `_decimalsOffset()`
 * corresponds to an offset in the decimal representation between the underlying asset's decimals and the vault
 * decimals. This offset also determines the rate of virtual shares to virtual assets in the vault, which itself
 * determines the initial exchange rate. While not fully preventing the attack, analysis shows that the default offset
 * (0) makes it non-profitable, as a result of the value being captured by the virtual shares (out of the attacker's
 * donation) matching the attacker's expected gains. With a larger offset, the attack becomes orders of magnitude more
 * expensive than it is profitable. More details about the underlying math can be found
 * xref:erc4626.adoc#inflation-attack[here].
 *
 * The drawback of this approach is that the virtual shares do capture (a very small) part of the value being accrued
 * to the vault. Also, if the vault experiences losses, the users try to exit the vault, the virtual shares and assets
 * will cause the first user to exit to experience reduced losses in detriment to the last users that will experience
 * bigger losses. Developers willing to revert back to the pre-v4.9 behavior just need to override the
 * `_convertToShares` and `_convertToAssets` functions.
 *
 * To learn more, check out our xref:ROOT:erc4626.adoc[ERC-4626 guide].
 * ====
 */
abstract contract ERC4626Upgradeable is Initializable, ERC20Upgradeable, IERC4626 {
    using Math for uint256;

    /// @custom:storage-location erc7201:openzeppelin.storage.ERC4626
    struct ERC4626Storage {
        IERC20 _asset;
        uint8 _underlyingDecimals;
    }

    // keccak256(abi.encode(uint256(keccak256("openzeppelin.storage.ERC4626")) - 1)) & ~bytes32(uint256(0xff))
    bytes32 private constant ERC4626StorageLocation = 0x0773e532dfede91f04b12a73d3d2acd361424f41f76b4fb79f090161e36b4e00;

    function _getERC4626Storage() private pure returns (ERC4626Storage storage $) {
        assembly {
            $.slot := ERC4626StorageLocation
        }
    }

    /**
     * @dev Attempted to deposit more assets than the max amount for `receiver`.
     */
    error ERC4626ExceededMaxDeposit(address receiver, uint256 assets, uint256 max);

    /**
     * @dev Attempted to mint more shares than the max amount for `receiver`.
     */
    error ERC4626ExceededMaxMint(address receiver, uint256 shares, uint256 max);

    /**
     * @dev Attempted to withdraw more assets than the max amount for `receiver`.
     */
    error ERC4626ExceededMaxWithdraw(address owner, uint256 assets, uint256 max);

    /**
     * @dev Attempted to redeem more shares than the max amount for `receiver`.
     */
    error ERC4626ExceededMaxRedeem(address owner, uint256 shares, uint256 max);

    /**
     * @dev Set the underlying asset contract. This must be an ERC20-compatible contract (ERC20 or ERC777).
     */
    function __ERC4626_init(IERC20 asset_) internal onlyInitializing {
        __ERC4626_init_unchained(asset_);
    }

    function __ERC4626_init_unchained(IERC20 asset_) internal onlyInitializing {
        ERC4626Storage storage $ = _getERC4626Storage();
        (bool success, uint8 assetDecimals) = _tryGetAssetDecimals(asset_);
        $._underlyingDecimals = success ? assetDecimals : 18;
        $._asset = asset_;
    }

    /**
     * @dev Attempts to fetch the asset decimals. A return value of false indicates that the attempt failed in some way.
     */
    function _tryGetAssetDecimals(IERC20 asset_) private view returns (bool, uint8) {
        (bool success, bytes memory encodedDecimals) = address(asset_).staticcall(
            abi.encodeCall(IERC20Metadata.decimals, ())
        );
        if (success && encodedDecimals.length >= 32) {
            uint256 returnedDecimals = abi.decode(encodedDecimals, (uint256));
            if (returnedDecimals <= type(uint8).max) {
                return (true, uint8(returnedDecimals));
            }
        }
        return (false, 0);
    }

    /**
     * @dev Decimals are computed by adding the decimal offset on top of the underlying asset's decimals. This
     * "original" value is cached during construction of the vault contract. If this read operation fails (e.g., the
     * asset has not been created yet), a default of 18 is used to represent the underlying asset's decimals.
     *
     * See {IERC20Metadata-decimals}.
     */
    function decimals() public view virtual override(IERC20Metadata, ERC20Upgradeable) returns (uint8) {
        ERC4626Storage storage $ = _getERC4626Storage();
        return $._underlyingDecimals + _decimalsOffset();
    }

    /** @dev See {IERC4626-asset}. */
    function asset() public view virtual returns (address) {
        ERC4626Storage storage $ = _getERC4626Storage();
        return address($._asset);
    }

    /** @dev See {IERC4626-totalAssets}. */
    function totalAssets() public view virtual returns (uint256) {
        ERC4626Storage storage $ = _getERC4626Storage();
        return $._asset.balanceOf(address(this));
    }

    /** @dev See {IERC4626-convertToShares}. */
    function convertToShares(uint256 assets) public view virtual returns (uint256) {
        return _convertToShares(assets, Math.Rounding.Floor);
    }

    /** @dev See {IERC4626-convertToAssets}. */
    function convertToAssets(uint256 shares) public view virtual returns (uint256) {
        return _convertToAssets(shares, Math.Rounding.Floor);
    }

    /** @dev See {IERC4626-maxDeposit}. */
    function maxDeposit(address) public view virtual returns (uint256) {
        return type(uint256).max;
    }

    /** @dev See {IERC4626-maxMint}. */
    function maxMint(address) public view virtual returns (uint256) {
        return type(uint256).max;
    }

    /** @dev See {IERC4626-maxWithdraw}. */
    function maxWithdraw(address owner) public view virtual returns (uint256) {
        return _convertToAssets(balanceOf(owner), Math.Rounding.Floor);
    }

    /** @dev See {IERC4626-maxRedeem}. */
    function maxRedeem(address owner) public view virtual returns (uint256) {
        return balanceOf(owner);
    }

    /** @dev See {IERC4626-previewDeposit}. */
    function previewDeposit(uint256 assets) public view virtual returns (uint256) {
        return _convertToShares(assets, Math.Rounding.Floor);
    }

    /** @dev See {IERC4626-previewMint}. */
    function previewMint(uint256 shares) public view virtual returns (uint256) {
        return _convertToAssets(shares, Math.Rounding.Ceil);
    }

    /** @dev See {IERC4626-previewWithdraw}. */
    function previewWithdraw(uint256 assets) public view virtual returns (uint256) {
        return _convertToShares(assets, Math.Rounding.Ceil);
    }

    /** @dev See {IERC4626-previewRedeem}. */
    function previewRedeem(uint256 shares) public view virtual returns (uint256) {
        return _convertToAssets(shares, Math.Rounding.Floor);
    }

    /** @dev See {IERC4626-deposit}. */
    function deposit(uint256 assets, address receiver) public virtual returns (uint256) {
        uint256 maxAssets = maxDeposit(receiver);
        if (assets > maxAssets) {
            revert ERC4626ExceededMaxDeposit(receiver, assets, maxAssets);
        }

        uint256 shares = previewDeposit(assets);
        _deposit(_msgSender(), receiver, assets, shares);

        return shares;
    }

    /** @dev See {IERC4626-mint}.
     *
     * As opposed to {deposit}, minting is allowed even if the vault is in a state where the price of a share is zero.
     * In this case, the shares will be minted without requiring any assets to be deposited.
     */
    function mint(uint256 shares, address receiver) public virtual returns (uint256) {
        uint256 maxShares = maxMint(receiver);
        if (shares > maxShares) {
            revert ERC4626ExceededMaxMint(receiver, shares, maxShares);
        }

        uint256 assets = previewMint(shares);
        _deposit(_msgSender(), receiver, assets, shares);

        return assets;
    }

    /** @dev See {IERC4626-withdraw}. */
    function withdraw(uint256 assets, address receiver, address owner) public virtual returns (uint256) {
        uint256 maxAssets = maxWithdraw(owner);
        if (assets > maxAssets) {
            revert ERC4626ExceededMaxWithdraw(owner, assets, maxAssets);
        }

        uint256 shares = previewWithdraw(assets);
        _withdraw(_msgSender(), receiver, owner, assets, shares);

        return shares;
    }

    /** @dev See {IERC4626-redeem}. */
    function redeem(uint256 shares, address receiver, address owner) public virtual returns (uint256) {
        uint256 maxShares = maxRedeem(owner);
        if (shares > maxShares) {
            revert ERC4626ExceededMaxRedeem(owner, shares, maxShares);
        }

        uint256 assets = previewRedeem(shares);
        _withdraw(_msgSender(), receiver, owner, assets, shares);

        return assets;
    }

    /**
     * @dev Internal conversion function (from assets to shares) with support for rounding direction.
     */
    function _convertToShares(uint256 assets, Math.Rounding rounding) internal view virtual returns (uint256) {
        return assets.mulDiv(totalSupply() + 10 ** _decimalsOffset(), totalAssets() + 1, rounding);
    }

    /**
     * @dev Internal conversion function (from shares to assets) with support for rounding direction.
     */
    function _convertToAssets(uint256 shares, Math.Rounding rounding) internal view virtual returns (uint256) {
        return shares.mulDiv(totalAssets() + 1, totalSupply() + 10 ** _decimalsOffset(), rounding);
    }

    /**
     * @dev Deposit/mint common workflow.
     */
    function _deposit(address caller, address receiver, uint256 assets, uint256 shares) internal virtual {
        ERC4626Storage storage $ = _getERC4626Storage();
        // If _asset is ERC777, `transferFrom` can trigger a reentrancy BEFORE the transfer happens through the
        // `tokensToSend` hook. On the other hand, the `tokenReceived` hook, that is triggered after the transfer,
        // calls the vault, which is assumed not malicious.
        //
        // Conclusion: we need to do the transfer before we mint so that any reentrancy would happen before the
        // assets are transferred and before the shares are minted, which is a valid state.
        // slither-disable-next-line reentrancy-no-eth
        SafeERC20.safeTransferFrom($._asset, caller, address(this), assets);
        _mint(receiver, shares);

        emit Deposit(caller, receiver, assets, shares);
    }

    /**
     * @dev Withdraw/redeem common workflow.
     */
    function _withdraw(
        address caller,
        address receiver,
        address owner,
        uint256 assets,
        uint256 shares
    ) internal virtual {
        ERC4626Storage storage $ = _getERC4626Storage();
        if (caller != owner) {
            _spendAllowance(owner, caller, shares);
        }

        // If _asset is ERC777, `transfer` can trigger a reentrancy AFTER the transfer happens through the
        // `tokensReceived` hook. On the other hand, the `tokensToSend` hook, that is triggered before the transfer,
        // calls the vault, which is assumed not malicious.
        //
        // Conclusion: we need to do the transfer after the burn so that any reentrancy would happen after the
        // shares are burned and after the assets are transferred, which is a valid state.
        _burn(owner, shares);
        SafeERC20.safeTransfer($._asset, receiver, assets);

        emit Withdraw(caller, receiver, owner, assets, shares);
    }

    function _decimalsOffset() internal view virtual returns (uint8) {
        return 0;
    }
}

// SPDX-License-Identifier: BUSL-1.1
pragma solidity 0.8.26;

/// @title Errors in Ipor Fusion
library Errors {
    /// @notice Error when wrong address is used
    error WrongAddress();
    /// @notice Error when wrong value is used
    error WrongValue();
    /// @notice Error when wrong decimals are used
    error WrongDecimals();
    /// @notice Error when wrong array length is used
    error WrongArrayLength();
    /// @notice Error when wrong caller is used
    error WrongCaller(address caller);
    /// @notice Error when wrong quote currency is used
    error UnsupportedQuoteCurrencyFromOracle();
    /// @notice Error when unsupported price oracle middleware is used
    error UnsupportedPriceOracleMiddleware();
}

// SPDX-License-Identifier: BUSL-1.1
pragma solidity 0.8.26;

import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";

/// @title FeeAccount
/// @notice Account contract that holds collected fees before distribution
/// @dev Each FeeAccount is dedicated to either management or performance fees
/// @dev Uses SafeERC20 for secure token operations
contract FeeAccount {
    using SafeERC20 for IERC20;

    /// @notice Error thrown when approval is attempted by non-fee manager address
    /// @dev Ensures only the designated fee manager can set token approvals
    error OnlyFeeManagerCanApprove();

    /// @notice The address of the FeeManager contract that controls this account
    /// @dev Set during construction and cannot be changed
    /// @dev This address has exclusive rights to manage token approvals
    address public immutable FEE_MANAGER;

    /// @notice Creates a new FeeAccount instance
    /// @dev Sets the immutable fee manager address
    /// @param feeManager_ Address of the FeeManager contract that will control this account
    /// @custom:security The fee manager address cannot be changed after deployment
    constructor(address feeManager_) {
        FEE_MANAGER = feeManager_;
    }

    /// @notice Approves the fee manager to spend the maximum amount of vault tokens
    /// @dev Uses force approve to handle tokens that require approval to be set to 0 first
    /// @param plasmaVault_ Address of the ERC20 vault token to approve
    /// @custom:access Only callable by the FEE_MANAGER address
    /// @custom:security Uses SafeERC20 for safe token operations
    function approveMaxForFeeManager(address plasmaVault_) external {
        if (msg.sender != FEE_MANAGER) {
            revert OnlyFeeManagerCanApprove();
        }

        IERC20(plasmaVault_).forceApprove(FEE_MANAGER, type(uint256).max);
    }
}

// SPDX-License-Identifier: BUSL-1.1
pragma solidity 0.8.26;

import {AccessManagedUpgradeable} from "../access/AccessManagedUpgradeable.sol";
import {IERC4626} from "@openzeppelin/contracts/interfaces/IERC4626.sol";
import {Math} from "@openzeppelin/contracts/utils/math/Math.sol";
import {FeeAccount} from "./FeeAccount.sol";
import {PlasmaVaultGovernance} from "../../vaults/PlasmaVaultGovernance.sol";
import {RecipientFee} from "./FeeManagerFactory.sol";
import {FeeManagerStorageLib, FeeRecipientDataStorage} from "./FeeManagerStorageLib.sol";
import {ContextClient} from "../context/ContextClient.sol";

/// @notice Struct containing initialization data for the fee manager
/// @param initialAuthority Address of the initial authority
/// @param plasmaVault Address of the plasma vault
/// @param iporDaoManagementFee Management fee percentage for the DAO (in percentage with 2 decimals, example 10000 is 100%, 100 is 1%)
/// @param iporDaoPerformanceFee Performance fee percentage for the DAO (in percentage with 2 decimals, example 10000 is 100%, 100 is 1%)
/// @param iporDaoFeeRecipientAddress Address of the DAO fee recipient
/// @param recipientManagementFees Array of recipient management fees
/// @param recipientPerformanceFees Array of recipient performance fees
struct FeeManagerInitData {
    address initialAuthority;
    address plasmaVault;
    uint256 iporDaoManagementFee;
    uint256 iporDaoPerformanceFee;
    address iporDaoFeeRecipientAddress;
    RecipientFee[] recipientManagementFees;
    RecipientFee[] recipientPerformanceFees;
}

/// @notice Struct containing data for a fee recipients
/// @param recipientFees Mapping of recipient addresses to their respective fee values
/// @param recipientAddresses Array of recipient addresses
struct FeeRecipientData {
    mapping(address recipient => uint256 feeValue) recipientFees;
    address[] recipientAddresses;
}

/// @notice Enum representing the type of fee
enum FeeType {
    MANAGEMENT,
    PERFORMANCE
}

/// @title FeeManager
/// @notice Manages the fees for the IporFusion protocol, including management and performance fees.
/// Total performance fee percentage is the sum of all recipients performance fees + DAO performance fee, represented in percentage with 2 decimals, example 10000 is 100%, 100 is 1%
/// Total management fee percentage is the sum of all recipients management fees + DAO management fee, represented in percentage with 2 decimals, example 10000 is 100%, 100 is 1%
/// @dev Inherits from AccessManaged for access control.
contract FeeManager is AccessManagedUpgradeable, ContextClient {
    event HarvestManagementFee(address receiver, uint256 amount);
    event HarvestPerformanceFee(address receiver, uint256 amount);
    event PerformanceFeeUpdated(uint256 totalFee, address[] recipients, uint256[] fees);
    event ManagementFeeUpdated(uint256 totalFee, address[] recipients, uint256[] fees);

    /// @notice Thrown when trying to call a function before initialization
    error NotInitialized();

    /// @notice Thrown when trying to initialize an already initialized contract
    error AlreadyInitialized();

    /// @notice Thrown when trying to set an invalid (zero) address as a fee recipient
    error InvalidFeeRecipientAddress();

    /// @notice Thrown when trying to set an invalid authority
    error InvalidAuthority();

    uint64 private constant INITIALIZED_VERSION = 10;

    /// @notice Address of the plasma vault contract
    address public immutable PLASMA_VAULT;

    /// @notice Account where performance fees are collected before distribution to recipients and DAO
    address public immutable PERFORMANCE_FEE_ACCOUNT;

    /// @notice Account where management fees are collected before distribution to recipients and DAO
    address public immutable MANAGEMENT_FEE_ACCOUNT;

    /// @notice Management fee percentage for IPOR DAO (10000 = 100%, 100 = 1%)
    uint256 public immutable IPOR_DAO_MANAGEMENT_FEE;

    /// @notice Performance fee percentage for IPOR DAO (10000 = 100%, 100 = 1%)
    uint256 public immutable IPOR_DAO_PERFORMANCE_FEE;

    modifier onlyInitialized() {
        if (_getInitializedVersion() != INITIALIZED_VERSION) {
            revert NotInitialized();
        }
        _;
    }

    constructor(FeeManagerInitData memory initData_) initializer {
        if (initData_.initialAuthority == address(0)) revert InvalidAuthority();

        super.__AccessManaged_init_unchained(initData_.initialAuthority);
        PLASMA_VAULT = initData_.plasmaVault;

        PERFORMANCE_FEE_ACCOUNT = address(new FeeAccount(address(this)));
        MANAGEMENT_FEE_ACCOUNT = address(new FeeAccount(address(this)));

        IPOR_DAO_MANAGEMENT_FEE = initData_.iporDaoManagementFee;
        IPOR_DAO_PERFORMANCE_FEE = initData_.iporDaoPerformanceFee;

        FeeManagerStorageLib.setIporDaoFeeRecipientAddress(initData_.iporDaoFeeRecipientAddress);

        uint256 totalManagementFee = IPOR_DAO_MANAGEMENT_FEE;
        uint256 totalPerformanceFee = IPOR_DAO_PERFORMANCE_FEE;

        uint256 recipientManagementFeesLength = initData_.recipientManagementFees.length;
        uint256 recipientPerformanceFeesLength = initData_.recipientPerformanceFees.length;

        if (recipientManagementFeesLength > 0) {
            address[] memory managementFeeRecipientAddresses = new address[](recipientManagementFeesLength);

            for (uint256 i; i < recipientManagementFeesLength; i++) {
                managementFeeRecipientAddresses[i] = initData_.recipientManagementFees[i].recipient;
                totalManagementFee += initData_.recipientManagementFees[i].feeValue;
                FeeManagerStorageLib.setManagementFeeRecipientFee(
                    initData_.recipientManagementFees[i].recipient,
                    initData_.recipientManagementFees[i].feeValue
                );
            }
            FeeManagerStorageLib.setManagementFeeRecipientAddresses(managementFeeRecipientAddresses);
        }

        if (recipientPerformanceFeesLength > 0) {
            address[] memory performanceFeeRecipientAddresses = new address[](recipientPerformanceFeesLength);

            for (uint256 i; i < recipientPerformanceFeesLength; i++) {
                performanceFeeRecipientAddresses[i] = initData_.recipientPerformanceFees[i].recipient;
                totalPerformanceFee += initData_.recipientPerformanceFees[i].feeValue;
                FeeManagerStorageLib.setPerformanceFeeRecipientFee(
                    initData_.recipientPerformanceFees[i].recipient,
                    initData_.recipientPerformanceFees[i].feeValue
                );
            }
            FeeManagerStorageLib.setPerformanceFeeRecipientAddresses(performanceFeeRecipientAddresses);
        }

        /// @dev Plasma Vault fees are the sum of all recipients fees + DAO fee, respectively for performance and management fees.
        /// @dev Values stored in FeeManager have to be equal to the values stored in PlasmaVault
        FeeManagerStorageLib.setPlasmaVaultTotalPerformanceFee(totalPerformanceFee);
        FeeManagerStorageLib.setPlasmaVaultTotalManagementFee(totalManagementFee);
    }

    /// @notice Initializes the FeeManager contract by setting up fee account approvals
    /// @dev Can only be called once due to reinitializer modifier
    /// @dev Sets maximum approval for both performance and management fee accounts to interact with plasma vault
    /// @dev This is required for the fee accounts to transfer tokens to recipients during fee distribution
    /// @custom:access Can only be called once during initialization
    /// @custom:error AlreadyInitialized if called after initialization
    function initialize() external reinitializer(INITIALIZED_VERSION) {
        FeeAccount(PERFORMANCE_FEE_ACCOUNT).approveMaxForFeeManager(PLASMA_VAULT);
        FeeAccount(MANAGEMENT_FEE_ACCOUNT).approveMaxForFeeManager(PLASMA_VAULT);
    }

    /// @notice Harvests both management and performance fees
    /// @dev Can be called by any address once initialized
    /// @dev This is a convenience function that calls harvestManagementFee() and harvestPerformanceFee()
    /// @custom:access Public after initialization
    function harvestAllFees() external onlyInitialized {
        harvestManagementFee();
        harvestPerformanceFee();
    }

    /// @notice Harvests the management fee and distributes it to recipients
    /// @dev Can be called by any address once initialized
    /// @dev Distributes fees proportionally based on configured fee percentages
    /// @dev First transfers the DAO portion, then distributes remaining to other recipients
    /// @custom:access Public after initialization
    function harvestManagementFee() public onlyInitialized {
        if (FeeManagerStorageLib.getIporDaoFeeRecipientAddress() == address(0)) {
            revert InvalidFeeRecipientAddress();
        }

        uint256 totalManagementFee = FeeManagerStorageLib.getPlasmaVaultTotalManagementFee();

        if (totalManagementFee == 0) {
            /// @dev If the management fee is 0, no fees are collected
            return;
        }

        uint256 managementFeeBalance = IERC4626(PLASMA_VAULT).balanceOf(MANAGEMENT_FEE_ACCOUNT);

        if (managementFeeBalance == 0) {
            /// @dev If the balance is 0, no fees are collected
            return;
        }

        uint256 remainingBalance = _transferDaoFee(
            MANAGEMENT_FEE_ACCOUNT,
            managementFeeBalance,
            totalManagementFee,
            IPOR_DAO_MANAGEMENT_FEE,
            FeeType.MANAGEMENT
        );

        if (remainingBalance == 0) {
            return;
        }

        address[] memory feeRecipientAddresses = FeeManagerStorageLib.getManagementFeeRecipientAddresses();

        uint256 feeRecipientAddressesLength = feeRecipientAddresses.length;

        for (uint256 i; i < feeRecipientAddressesLength && remainingBalance > 0; i++) {
            remainingBalance = _transferRecipientFee(
                feeRecipientAddresses[i],
                remainingBalance,
                managementFeeBalance,
                FeeManagerStorageLib.getManagementFeeRecipientFee(feeRecipientAddresses[i]),
                totalManagementFee,
                MANAGEMENT_FEE_ACCOUNT,
                FeeType.MANAGEMENT
            );
        }
    }

    /// @notice Harvests the performance fee and distributes it to recipients
    /// @dev Can be called by any address once initialized
    /// @dev Distributes fees proportionally based on configured fee percentages
    /// @dev First transfers the DAO portion, then distributes remaining to other recipients
    /// @custom:access Public after initialization
    function harvestPerformanceFee() public onlyInitialized {
        if (FeeManagerStorageLib.getIporDaoFeeRecipientAddress() == address(0)) {
            revert InvalidFeeRecipientAddress();
        }

        uint256 totalPerformanceFee = FeeManagerStorageLib.getPlasmaVaultTotalPerformanceFee();

        if (totalPerformanceFee == 0) {
            /// @dev If the performance fee is 0, no fees are collected
            return;
        }

        uint256 performanceFeeBalance = IERC4626(PLASMA_VAULT).balanceOf(PERFORMANCE_FEE_ACCOUNT);

        if (performanceFeeBalance == 0) {
            /// @dev If the balance is 0, no fees are collected
            return;
        }

        uint256 remainingBalance = _transferDaoFee(
            PERFORMANCE_FEE_ACCOUNT,
            performanceFeeBalance,
            totalPerformanceFee,
            IPOR_DAO_PERFORMANCE_FEE,
            FeeType.PERFORMANCE
        );

        if (remainingBalance == 0) {
            return;
        }

        address[] memory feeRecipientAddresses = FeeManagerStorageLib.getPerformanceFeeRecipientAddresses();

        uint256 feeRecipientAddressesLength = feeRecipientAddresses.length;

        for (uint256 i; i < feeRecipientAddressesLength && remainingBalance > 0; i++) {
            remainingBalance = _transferRecipientFee(
                feeRecipientAddresses[i],
                remainingBalance,
                performanceFeeBalance,
                FeeManagerStorageLib.getPerformanceFeeRecipientFee(feeRecipientAddresses[i]),
                totalPerformanceFee,
                PERFORMANCE_FEE_ACCOUNT,
                FeeType.PERFORMANCE
            );
        }
    }

    /// @notice Updates management fees for all recipients
    /// @dev Only callable by ATOMIST_ROLE (role id: 100)
    /// @dev Harvests existing management fees before updating
    /// @dev Total management fee will be the sum of all recipient fees + DAO fee
    /// @param recipientFees Array of recipient fees containing address and new fee value
    /// @custom:access Restricted to ATOMIST_ROLE
    function updateManagementFee(RecipientFee[] calldata recipientFees) external restricted {
        harvestManagementFee();
        _updateFees(
            recipientFees,
            FeeManagerStorageLib._managementFeeRecipientDataStorage(),
            IPOR_DAO_MANAGEMENT_FEE,
            MANAGEMENT_FEE_ACCOUNT,
            FeeType.MANAGEMENT
        );
    }

    /// @notice Updates performance fees for all recipients
    /// @dev Only callable by ATOMIST_ROLE (role id: 100)
    /// @dev Harvests existing performance fees before updating
    /// @dev Total performance fee will be the sum of all recipient fees + DAO fee
    /// @param recipientFees Array of recipient fees containing address and new fee value
    /// @custom:access Restricted to ATOMIST_ROLE
    function updatePerformanceFee(RecipientFee[] calldata recipientFees) external restricted {
        harvestPerformanceFee();
        _updateFees(
            recipientFees,
            FeeManagerStorageLib._performanceFeeRecipientDataStorage(),
            IPOR_DAO_PERFORMANCE_FEE,
            PERFORMANCE_FEE_ACCOUNT,
            FeeType.PERFORMANCE
        );
    }

    /// @notice Sets the IPOR DAO fee recipient address
    /// @dev Only callable by IPOR_DAO_ROLE (role id: 4)
    /// @dev The DAO fee recipient receives both management and performance fees allocated to the DAO
    /// @param iporDaoFeeRecipientAddress_ The address to set as the DAO fee recipient
    /// @custom:access Restricted to IPOR_DAO_ROLE
    function setIporDaoFeeRecipientAddress(address iporDaoFeeRecipientAddress_) external restricted {
        if (iporDaoFeeRecipientAddress_ == address(0)) {
            revert InvalidFeeRecipientAddress();
        }
        FeeManagerStorageLib.setIporDaoFeeRecipientAddress(iporDaoFeeRecipientAddress_);
    }

    /// @notice Internal function to completely replace existing fee recipients with new ones
    /// @dev This function will remove all existing recipients and their fees before setting up the new ones
    /// @param recipientFees Array of recipient fees containing address and new fee value
    /// @param feeData Storage reference to the fee recipient data
    /// @param daoFee The DAO fee percentage to include in total
    /// @param feeAccount The fee account address
    /// @param feeType The type of fee (MANAGEMENT or PERFORMANCE)
    function _updateFees(
        RecipientFee[] calldata recipientFees,
        FeeRecipientDataStorage storage feeData,
        uint256 daoFee,
        address feeAccount,
        FeeType feeType
    ) internal {
        uint256 totalFee = daoFee;

        address[] memory oldRecipients = feeData.recipientAddresses;

        uint256 oldRecipientsLength = oldRecipients.length;

        for (uint256 i; i < oldRecipientsLength; i++) {
            delete feeData.recipientFees[oldRecipients[i]];
        }

        delete feeData.recipientAddresses;

        address[] memory newRecipients = new address[](recipientFees.length);
        uint256[] memory newFees = new uint256[](recipientFees.length);

        uint256 recipientFeesLength = recipientFees.length;

        for (uint256 i; i < recipientFeesLength; i++) {
            if (recipientFees[i].recipient == address(0)) {
                revert InvalidFeeRecipientAddress();
            }

            newRecipients[i] = recipientFees[i].recipient;
            newFees[i] = recipientFees[i].feeValue;

            feeData.recipientFees[recipientFees[i].recipient] = recipientFees[i].feeValue;
            totalFee += recipientFees[i].feeValue;
        }

        feeData.recipientAddresses = newRecipients;

        if (feeType == FeeType.MANAGEMENT) {
            PlasmaVaultGovernance(PLASMA_VAULT).configureManagementFee(feeAccount, totalFee);
            FeeManagerStorageLib.setPlasmaVaultTotalManagementFee(totalFee);
            emit ManagementFeeUpdated(totalFee, newRecipients, newFees);
        } else {
            PlasmaVaultGovernance(PLASMA_VAULT).configurePerformanceFee(feeAccount, totalFee);
            FeeManagerStorageLib.setPlasmaVaultTotalPerformanceFee(totalFee);
            emit PerformanceFeeUpdated(totalFee, newRecipients, newFees);
        }
    }

    /// @notice Gets all management fee recipients with their fee values
    /// @dev View function accessible by anyone
    /// @return Array of RecipientFee structs containing recipient addresses and their fee values
    /// @custom:access Public view
    function getManagementFeeRecipients() external view returns (RecipientFee[] memory) {
        address[] memory recipients = FeeManagerStorageLib.getManagementFeeRecipientAddresses();
        uint256 length = recipients.length;

        RecipientFee[] memory recipientFees = new RecipientFee[](length);

        for (uint256 i; i < length; i++) {
            recipientFees[i] = RecipientFee({
                recipient: recipients[i],
                feeValue: FeeManagerStorageLib.getManagementFeeRecipientFee(recipients[i])
            });
        }

        return recipientFees;
    }

    /// @notice Gets all performance fee recipients with their fee values
    /// @dev View function accessible by anyone
    /// @return Array of RecipientFee structs containing recipient addresses and their fee values
    /// @custom:access Public view
    function getPerformanceFeeRecipients() external view returns (RecipientFee[] memory) {
        address[] memory recipients = FeeManagerStorageLib.getPerformanceFeeRecipientAddresses();
        uint256 length = recipients.length;
        RecipientFee[] memory recipientFees = new RecipientFee[](length);

        for (uint256 i; i < length; i++) {
            recipientFees[i] = RecipientFee({
                recipient: recipients[i],
                feeValue: FeeManagerStorageLib.getPerformanceFeeRecipientFee(recipients[i])
            });
        }

        return recipientFees;
    }

    /// @notice Gets the total management fee percentage
    /// @dev View function accessible by anyone
    /// @return Total management fee percentage with 2 decimals (10000 = 100%, 100 = 1%)
    /// @custom:access Public view
    function getTotalManagementFee() external view returns (uint256) {
        return FeeManagerStorageLib.getPlasmaVaultTotalManagementFee();
    }

    /// @notice Gets the total performance fee percentage
    /// @dev View function accessible by anyone
    /// @return Total performance fee percentage with 2 decimals (10000 = 100%, 100 = 1%)
    /// @custom:access Public view
    function getTotalPerformanceFee() external view returns (uint256) {
        return FeeManagerStorageLib.getPlasmaVaultTotalPerformanceFee();
    }

    /// @notice Gets the IPOR DAO fee recipient address
    /// @dev View function accessible by anyone
    /// @return The current DAO fee recipient address
    /// @custom:access Public view
    function getIporDaoFeeRecipientAddress() external view returns (address) {
        return FeeManagerStorageLib.getIporDaoFeeRecipientAddress();
    }

    /// @notice Internal function to transfer fees to the DAO
    /// @param feeAccount_ The address of the fee account
    /// @param feeBalance_ The balance of the fee account
    /// @param totalFee_ The total fee percentage
    /// @param daoFee_ The DAO fee percentage
    /// @param feeType_ The type of fee (PERFORMANCE or MANAGEMENT)
    /// @return The remaining balance after transferring fees to the DAO
    function _transferDaoFee(
        address feeAccount_,
        uint256 feeBalance_,
        uint256 totalFee_,
        uint256 daoFee_,
        FeeType feeType_
    ) internal returns (uint256) {
        uint256 decimals = IERC4626(PLASMA_VAULT).decimals();
        uint256 numberOfDecimals = 10 ** decimals;

        uint256 percentToTransferToDao_ = (daoFee_ * numberOfDecimals) / totalFee_;
        uint256 transferAmountToDao_ = Math.mulDiv(feeBalance_, percentToTransferToDao_, numberOfDecimals);

        if (transferAmountToDao_ > 0) {
            IERC4626(PLASMA_VAULT).transferFrom(
                feeAccount_,
                FeeManagerStorageLib.getIporDaoFeeRecipientAddress(),
                transferAmountToDao_
            );
            _emitHarvestEvent(FeeManagerStorageLib.getIporDaoFeeRecipientAddress(), transferAmountToDao_, feeType_);
        }

        return feeBalance_ > transferAmountToDao_ ? feeBalance_ - transferAmountToDao_ : 0;
    }

    /// @notice Internal function to emit harvest events
    /// @param recipient_ The address of the fee recipient
    /// @param amount_ The amount of fee to be harvested
    /// @param feeType_ The type of fee (PERFORMANCE or MANAGEMENT)
    function _emitHarvestEvent(address recipient_, uint256 amount_, FeeType feeType_) internal {
        if (feeType_ == FeeType.PERFORMANCE) {
            emit HarvestPerformanceFee(recipient_, amount_);
        } else {
            emit HarvestManagementFee(recipient_, amount_);
        }
    }

    /// @notice Internal function to handle fee transfer to a recipient
    /// @param recipient_ The address of the fee recipient
    /// @param remainingBalance_ Current remaining balance to distribute
    /// @param totalFeeBalance_ Total fee balance being distributed
    /// @param recipientFeeValue_ The fee value for this specific recipient
    /// @param totalFeePercentage_ Total fee percentage (management or performance)
    /// @param feeAccount_ The fee account to transfer from
    /// @param feeType_ The type of fee ("MANAGEMENT" or "PERFORMANCE")
    /// @return The new remaining balance after transfer
    function _transferRecipientFee(
        address recipient_,
        uint256 remainingBalance_,
        uint256 totalFeeBalance_,
        uint256 recipientFeeValue_,
        uint256 totalFeePercentage_,
        address feeAccount_,
        FeeType feeType_
    ) internal returns (uint256) {
        uint256 decimals = IERC4626(PLASMA_VAULT).decimals();
        uint256 numberOfDecimals = 10 ** decimals;

        uint256 recipientPercentage = (recipientFeeValue_ * numberOfDecimals) / totalFeePercentage_;
        uint256 recipientShare = Math.mulDiv(totalFeeBalance_, recipientPercentage, numberOfDecimals);

        if (recipientShare > 0) {
            if (remainingBalance_ < recipientShare) {
                recipientShare = remainingBalance_;
            }

            remainingBalance_ -= recipientShare;

            if (recipientShare > 0) {
                IERC4626(PLASMA_VAULT).transferFrom(feeAccount_, recipient_, recipientShare);
                _emitHarvestEvent(recipient_, recipientShare, feeType_);
            }
        }

        return remainingBalance_;
    }

    /// @notice Internal function to get the message sender from context
    /// @return The address of the message sender
    function _msgSender() internal view override returns (address) {
        return _getSenderFromContext();
    }
}

// SPDX-License-Identifier: BUSL-1.1
pragma solidity 0.8.26;

import {FeeManager, FeeManagerInitData} from "./FeeManager.sol";

/// @notice Struct containing fee configuration for a single recipient
/// @dev All fee values are stored with 2 decimal precision
/// @param recipient The address that will receive the fees
/// @param feeValue Fee percentage allocated to this recipient (10000 = 100%, 100 = 1%)
struct RecipientFee {
    address recipient;
    uint256 feeValue;
}

/// @notice Configuration parameters for initializing a new fee management system
/// @dev Used to set up initial fee structure and recipients for a plasma vault
struct FeeConfig {
    /// @notice Address of the factory contract deploying the fee manager
    address feeFactory;
    /// @notice Base management fee allocated to the IPOR DAO
    /// @dev Percentage with 2 decimal precision (10000 = 100%, 100 = 1%)
    uint256 iporDaoManagementFee;
    /// @notice Base performance fee allocated to the IPOR DAO
    /// @dev Percentage with 2 decimal precision (10000 = 100%, 100 = 1%)
    uint256 iporDaoPerformanceFee;
    /// @notice Address that receives the IPOR DAO's portion of fees
    /// @dev Must be non-zero address
    address iporDaoFeeRecipientAddress;
    /// @notice List of additional management fee recipients and their allocations
    /// @dev Total of all management fees (including DAO) must not exceed 100%
    RecipientFee[] recipientManagementFees;
    /// @notice List of additional performance fee recipients and their allocations
    /// @dev Total of all performance fees (including DAO) must not exceed 100%
    RecipientFee[] recipientPerformanceFees;
}

/// @notice Data structure containing deployed fee manager details
/// @dev Returned after successful deployment of a new fee manager
struct FeeManagerData {
    /// @notice Address of the deployed fee manager contract
    address feeManager;
    /// @notice Address of the associated plasma vault
    address plasmaVault;
    /// @notice Account that collects performance fees before distribution
    address performanceFeeAccount;
    /// @notice Account that collects management fees before distribution
    address managementFeeAccount;
    /// @notice Total management fee percentage (sum of all recipients including DAO)
    /// @dev Stored with 2 decimal precision (10000 = 100%, 100 = 1%)
    uint256 managementFee;
    /// @notice Total performance fee percentage (sum of all recipients including DAO)
    /// @dev Stored with 2 decimal precision (10000 = 100%, 100 = 1%)
    uint256 performanceFee;
}

/// @title FeeManagerFactory
/// @notice Factory contract for deploying and initializing FeeManager instances
/// @dev Creates standardized fee management systems for plasma vaults
contract FeeManagerFactory {
    /// @notice Deploys a new FeeManager contract with the specified configuration
    /// @dev Creates and initializes a new FeeManager with associated fee accounts
    /// @param initData_ Initialization parameters for the fee manager
    /// @return Data structure containing addresses and fee information of the deployed system
    /// @custom:security Validates fee recipient addresses and fee percentages during deployment
    function deployFeeManager(FeeManagerInitData memory initData_) external returns (FeeManagerData memory) {
        FeeManager feeManager = new FeeManager(initData_);

        return
            FeeManagerData({
                feeManager: address(feeManager),
                plasmaVault: feeManager.PLASMA_VAULT(),
                performanceFeeAccount: feeManager.PERFORMANCE_FEE_ACCOUNT(),
                managementFeeAccount: feeManager.MANAGEMENT_FEE_ACCOUNT(),
                managementFee: feeManager.getTotalManagementFee(),
                performanceFee: feeManager.getTotalPerformanceFee()
            });
    }
}

// SPDX-License-Identifier: BUSL-1.1
pragma solidity 0.8.26;

error FeeManagerStorageLibZeroAddress();

/// @notice Storage structure for DAO fee recipient data
/// @dev Stores the address that receives IPOR DAO fees
struct DaoFeeRecipientDataStorage {
    address iporDaoFeeRecipientAddress;
}

// Add new event with just the new recipient
event IporDaoFeeRecipientAddressChanged(address indexed newRecipient);

/// @notice Storage structure for total performance fee in plasma vault
/// @dev Value stored with 2 decimal precision (10000 = 100%)
struct PlasmaVaultTotalPerformanceFeeStorage {
    uint256 value;
}

/// @notice Storage structure for total management fee in plasma vault
/// @dev Value stored with 2 decimal precision (10000 = 100%)
struct PlasmaVaultTotalManagementFeeStorage {
    uint256 value;
}

/// @notice Storage structure for fee recipient data
/// @dev Maps recipient addresses to their fee allocations and maintains list of recipients
struct FeeRecipientDataStorage {
    mapping(address recipient => uint256 feeValue) recipientFees;
    address[] recipientAddresses;
}

/// @title Fee Manager Storage Library
/// @notice Library for managing fee-related storage in the IPOR Protocol's plasma vault system
/// @dev Implements diamond storage pattern for fee management including performance, management, and DAO fees
library FeeManagerStorageLib {
    /// @dev keccak256(abi.encode(uint256(keccak256("io.ipor.fee.manager.dao.fee.recipient.data.storage")) - 1)) & ~bytes32(uint256(0xff));
    bytes32 private constant DAO_FEE_RECIPIENT_DATA_SLOT =
        0xaf522f71ce1f2b5702c38f667fa2366c184e3c6dd86ab049ad3b02fec741fd00;

    /// @dev keccak256(abi.encode(uint256(keccak256("io.ipor.fee.manager.total.performance.fee.storage")) - 1)) & ~bytes32(uint256(0xff));
    bytes32 private constant TOTAL_PERFORMANCE_FEE_SLOT =
        0x91a7fd667a02d876183d5e3c0caf915fa5c0b6847afae1b6a2261f7bce984500;

    /// @dev keccak256(abi.encode(uint256(keccak256("io.ipor.fee.manager.total.management.fee.storage")) - 1)) & ~bytes32(uint256(0xff));
    bytes32 private constant TOTAL_MANAGEMENT_FEE_SLOT =
        0xcf56f35f42e69dcdff0b7b1f2e356cc5f92476bed919f8df0cdbf41f78aa1f00;

    /// @dev keccak256(abi.encode(uint256(keccak256("io.ipor.fee.manager.management.fee.recipient.data.storage")) - 1)) & ~bytes32(uint256(0xff));
    bytes32 private constant MANAGEMENT_FEE_RECIPIENT_DATA_SLOT =
        0xf1a2374333eb639fe6654c1bd32856f942f1f785e32d72be0c2e035f2e0f8000;

    /// @dev keccak256(abi.encode(uint256(keccak256("io.ipor.fee.manager.performance.fee.recipient.data.storage")) - 1)) & ~bytes32(uint256(0xff));
    bytes32 private constant PERFORMANCE_FEE_RECIPIENT_DATA_SLOT =
        0xc456e86573d79f7b5b60c9eb824345c471d5390facece9407699845c141b2d00;

    /// @notice Retrieves management fee recipient data storage
    /// @dev Uses assembly to access diamond storage pattern slot
    /// @return $ Storage pointer to FeeRecipientDataStorage
    function _managementFeeRecipientDataStorage() internal pure returns (FeeRecipientDataStorage storage $) {
        assembly {
            $.slot := MANAGEMENT_FEE_RECIPIENT_DATA_SLOT
        }
    }

    /// @notice Retrieves performance fee recipient data storage
    /// @dev Uses assembly to access diamond storage pattern slot
    /// @return $ Storage pointer to FeeRecipientDataStorage
    function _performanceFeeRecipientDataStorage() internal pure returns (FeeRecipientDataStorage storage $) {
        assembly {
            $.slot := PERFORMANCE_FEE_RECIPIENT_DATA_SLOT
        }
    }

    /// @notice Gets the total performance fee percentage for the plasma vault
    /// @return Total performance fee percentage with 2 decimals (10000 = 100%, 100 = 1%)
    function getPlasmaVaultTotalPerformanceFee() internal view returns (uint256) {
        return _totalPerformanceFeeStorage().value;
    }

    /// @notice Sets the total performance fee percentage for the plasma vault
    /// @dev Updates the total performance fee that will be distributed among recipients
    /// @param fee_ Total performance fee percentage with 2 decimals (10000 = 100%, 100 = 1%)
    function setPlasmaVaultTotalPerformanceFee(uint256 fee_) internal {
        _totalPerformanceFeeStorage().value = fee_;
    }

    /// @notice Gets the total management fee percentage for the plasma vault
    /// @return Total management fee percentage with 2 decimals (10000 = 100%, 100 = 1%)
    function getPlasmaVaultTotalManagementFee() internal view returns (uint256) {
        return _totalManagementFeeStorage().value;
    }

    /// @notice Sets the total management fee percentage for the plasma vault
    /// @param fee_ Total management fee percentage with 2 decimals (10000 = 100%, 100 = 1%)
    function setPlasmaVaultTotalManagementFee(uint256 fee_) internal {
        _totalManagementFeeStorage().value = fee_;
    }

    /// @notice Gets the fee value for a specific management fee recipient
    /// @param recipient_ The address of the recipient
    /// @return The fee value for the recipient
    function getManagementFeeRecipientFee(address recipient_) internal view returns (uint256) {
        return _managementFeeRecipientDataStorage().recipientFees[recipient_];
    }

    /// @notice Sets the fee value for a specific management fee recipient
    /// @dev Updates individual recipient's share of the total management fee
    /// @param recipient_ The address of the recipient
    /// @param feeValue_ The fee value to set, representing recipient's share of total fee
    function setManagementFeeRecipientFee(address recipient_, uint256 feeValue_) internal {
        _managementFeeRecipientDataStorage().recipientFees[recipient_] = feeValue_;
    }

    /// @notice Gets all management fee recipient addresses
    /// @return Array of recipient addresses
    function getManagementFeeRecipientAddresses() internal view returns (address[] memory) {
        return _managementFeeRecipientDataStorage().recipientAddresses;
    }

    /// @notice Sets all management fee recipient addresses
    /// @dev Overwrites the entire array of management fee recipients
    /// @param addresses_ Array of recipient addresses to set
    /// @dev Important: This replaces all existing recipients
    function setManagementFeeRecipientAddresses(address[] memory addresses_) internal {
        _managementFeeRecipientDataStorage().recipientAddresses = addresses_;
    }

    /// @notice Gets the fee value for a specific performance fee recipient
    /// @param recipient_ The address of the recipient
    /// @return The fee value for the recipient
    function getPerformanceFeeRecipientFee(address recipient_) internal view returns (uint256) {
        return _performanceFeeRecipientDataStorage().recipientFees[recipient_];
    }

    /// @notice Sets the fee value for a specific performance fee recipient
    /// @param recipient_ The address of the recipient
    /// @param feeValue_ The fee value to set
    function setPerformanceFeeRecipientFee(address recipient_, uint256 feeValue_) internal {
        _performanceFeeRecipientDataStorage().recipientFees[recipient_] = feeValue_;
    }

    /// @notice Gets all performance fee recipient addresses
    /// @return Array of recipient addresses
    function getPerformanceFeeRecipientAddresses() internal view returns (address[] memory) {
        return _performanceFeeRecipientDataStorage().recipientAddresses;
    }

    /// @notice Sets all performance fee recipient addresses
    /// @param addresses_ Array of recipient addresses to set
    function setPerformanceFeeRecipientAddresses(address[] memory addresses_) internal {
        _performanceFeeRecipientDataStorage().recipientAddresses = addresses_;
    }

    /// @notice Gets the IPOR DAO fee recipient address
    /// @return The address of the IPOR DAO fee recipient
    function getIporDaoFeeRecipientAddress() internal view returns (address) {
        return _daoFeeRecipientDataStorage().iporDaoFeeRecipientAddress;
    }

    /// @notice Sets the IPOR DAO fee recipient address
    /// @dev Updates the address that receives DAO fees and emits an event
    /// @param recipientAddress_ The address to set as the IPOR DAO fee recipient
    /// @dev Emits IporDaoFeeRecipientAddressChanged event
    function setIporDaoFeeRecipientAddress(address recipientAddress_) internal {
        _daoFeeRecipientDataStorage().iporDaoFeeRecipientAddress = recipientAddress_;
        emit IporDaoFeeRecipientAddressChanged(recipientAddress_);
    }

    function _daoFeeRecipientDataStorage() private pure returns (DaoFeeRecipientDataStorage storage $) {
        assembly {
            $.slot := DAO_FEE_RECIPIENT_DATA_SLOT
        }
    }

    function _totalPerformanceFeeStorage() private pure returns (PlasmaVaultTotalPerformanceFeeStorage storage $) {
        assembly {
            $.slot := TOTAL_PERFORMANCE_FEE_SLOT
        }
    }

    function _totalManagementFeeStorage() private pure returns (PlasmaVaultTotalManagementFeeStorage storage $) {
        assembly {
            $.slot := TOTAL_MANAGEMENT_FEE_SLOT
        }
    }
}

// SPDX-License-Identifier: BUSL-1.1
pragma solidity 0.8.26;

/// @title Fuses storage library responsible for managing storage fuses in the Plasma Vault
library FuseStorageLib {
    /**
     * @dev Storage slot for managing supported fuses in the Plasma Vault
     * @notice Maps fuse addresses to their index in the fuses array for tracking supported fuses
     *
     * Calculation:
     * keccak256(abi.encode(uint256(keccak256("io.ipor.CfgFuses")) - 1)) & ~bytes32(uint256(0xff))
     *
     * Purpose:
     * - Tracks which fuses are supported by the vault
     * - Enables efficient fuse validation
     * - Maps fuse addresses to their array indices
     * - Core component of fuse management system
     *
     * Storage Layout:
     * - Points to Fuses struct containing:
     *   - value: mapping(address fuse => uint256 index)
     *     - Zero index indicates unsupported fuse
     *     - Non-zero index (index + 1) indicates supported fuse
     *
     * Usage Pattern:
     * - Checked during fuse operations via isFuseSupported()
     * - Updated when adding/removing fuses
     * - Used for fuse validation in vault operations
     * - Maintains synchronization with fuses array
     *
     * Integration Points:
     * - FusesLib.isFuseSupported: Validates fuse status
     * - FusesLib.addFuse: Updates supported fuses
     * - FusesLib.removeFuse: Removes fuse support
     * - PlasmaVault: References for operation validation
     *
     * Security Considerations:
     * - Only modifiable through governance
     * - Critical for controlling vault integrations
     * - Must maintain consistency with fuses array
     * - Key component of vault security
     */
    bytes32 private constant CFG_FUSES = 0x48932b860eb451ad240d4fe2b46522e5a0ac079d201fe50d4e0be078c75b5400;

    /**
     * @dev Storage slot for storing the array of supported fuses in the Plasma Vault
     * @notice Maintains ordered list of all supported fuse addresses
     *
     * Calculation:
     * keccak256(abi.encode(uint256(keccak256("io.ipor.CfgFusesArray")) - 1)) & ~bytes32(uint256(0xff))
     *
     * Purpose:
     * - Stores complete list of supported fuses
     * - Enables iteration over all supported fuses
     * - Maintains order of fuse addition
     * - Provides efficient fuse removal mechanism
     *
     * Storage Layout:
     * - Points to FusesArray struct containing:
     *   - value: address[] array of fuse addresses
     *     - Each element is a supported fuse contract address
     *     - Array index corresponds to (mapping index - 1) in CFG_FUSES
     *
     * Usage Pattern:
     * - Referenced when listing all supported fuses
     * - Updated during fuse addition/removal
     * - Used for fuse enumeration
     * - Maintains parallel structure with CFG_FUSES mapping
     *
     * Integration Points:
     * - FusesLib.getFusesArray: Retrieves complete fuse list
     * - FusesLib.addFuse: Appends new fuses
     * - FusesLib.removeFuse: Manages array updates
     * - Governance: References for fuse management
     *
     * Security Considerations:
     * - Must stay synchronized with CFG_FUSES mapping
     * - Array operations must handle index updates correctly
     * - Critical for fuse system integrity
     * - Requires careful management during removals
     */
    bytes32 private constant CFG_FUSES_ARRAY = 0xad43e358bd6e59a5a0c80f6bf25fa771408af4d80f621cdc680c8dfbf607ab00;

    /**
     * @dev Storage slot for managing Uniswap V3 NFT position token IDs in the Plasma Vault
     * @notice Tracks and manages Uniswap V3 LP positions held by the vault
     *
     * Calculation:
     * keccak256(abi.encode(uint256(keccak256("io.ipor.UniswapV3TokenIds")) - 1)) & ~bytes32(uint256(0xff))
     *
     * Purpose:
     * - Tracks all Uniswap V3 NFT positions owned by the vault
     * - Enables efficient position management and lookup
     * - Supports liquidity provision operations
     * - Facilitates position value calculations
     *
     * Storage Layout:
     * - Points to UniswapV3TokenIds struct containing:
     *   - tokenIds: uint256[] array of Uniswap V3 NFT position IDs
     *   - indexes: mapping(uint256 tokenId => uint256 index) for position lookup
     *     - Maps each token ID to its index in the tokenIds array
     *     - Zero index indicates non-existent position
     *
     * Usage Pattern:
     * - Updated when creating new Uniswap V3 positions
     * - Referenced during position management
     * - Used for position value calculations
     * - Maintains efficient position tracking
     *
     * Integration Points:
     * - UniswapV3NewPositionFuse: Position creation and management
     * - PositionValue: NFT position valuation
     * - Balance calculation systems
     * - Withdrawal and rebalancing operations
     *
     * Security Considerations:
     * - Must accurately track all vault positions
     * - Critical for proper liquidity management
     * - Requires careful index management
     * - Essential for position ownership verification
     */
    bytes32 private constant UNISWAP_V3_TOKEN_IDS = 0x3651659bd419f7c37743f3e14a337c9f9d1cfc4d650d91508f44d1acbe960f00;

    /**
     * @dev Storage slot for managing Ramses V2 NFT position token IDs in the Plasma Vault
     * @notice Tracks and manages Ramses V2 LP positions held by the vault
     *
     * Calculation:
     * keccak256(abi.encode(uint256(keccak256("io.ipor.RamsesV2TokenIds")) - 1)) & ~bytes32(uint256(0xff))
     *
     * Purpose:
     * - Tracks all Ramses V2 NFT positions owned by the vault
     * - Enables efficient position management and lookup
     * - Supports concentrated liquidity position tracking
     * - Mirrors Uniswap V3-style position management for Arbitrum
     *
     * Storage Layout:
     * - Points to RamsesV2TokenIds struct containing:
     *   - tokenIds: uint256[] array of Ramses V2 NFT position IDs
     *   - indexes: mapping(uint256 tokenId => uint256 index) for position lookup
     *     - Maps each token ID to its index in the tokenIds array
     *     - Zero index indicates non-existent position
     *
     * Usage Pattern:
     * - Updated when creating new Ramses V2 positions
     * - Referenced during position management
     * - Used for position value calculations
     * - Maintains efficient position tracking on Arbitrum
     *
     * Integration Points:
     * - Ramses V2 position management fuses
     * - Position value calculation systems
     * - Balance tracking mechanisms
     * - Arbitrum-specific liquidity operations
     *
     * Security Considerations:
     * - Must accurately track all vault positions
     * - Critical for Arbitrum liquidity management
     * - Requires careful index management
     * - Essential for position ownership verification
     * - Parallel structure to Uniswap V3 position tracking
     */
    bytes32 private constant RAMSES_V2_TOKEN_IDS = 0x1a3831a406f27d4d5d820158b29ce95a1e8e840bf416921917aa388e2461b700;

    /// @custom:storage-location erc7201:io.ipor.CfgFuses
    struct Fuses {
        /// @dev fuse address => If index = 0 - is not granted, otherwise - granted
        mapping(address fuse => uint256 index) value;
    }

    /// @custom:storage-location erc7201:io.ipor.CfgFusesArray
    struct FusesArray {
        /// @dev value is a fuse address
        address[] value;
    }

    /// @custom:storage-location erc7201:io.ipor.UniswapV3TokenIds
    struct UniswapV3TokenIds {
        uint256[] tokenIds;
        mapping(uint256 tokenId => uint256 index) indexes;
    }

    /// @custom:storage-location erc7201:io.ipor.RamsesV2TokenIds
    struct RamsesV2TokenIds {
        uint256[] tokenIds;
        mapping(uint256 tokenId => uint256 index) indexes;
    }

    /// @notice Gets the fuses storage pointer
    function getFuses() internal pure returns (Fuses storage fuses) {
        assembly {
            fuses.slot := CFG_FUSES
        }
    }

    /// @notice Gets the fuses array storage pointer
    function getFusesArray() internal pure returns (FusesArray storage fusesArray) {
        assembly {
            fusesArray.slot := CFG_FUSES_ARRAY
        }
    }

    /// @notice Gets the UniswapV3TokenIds storage pointer
    function getUniswapV3TokenIds() internal pure returns (UniswapV3TokenIds storage uniswapV3TokenIds) {
        assembly {
            uniswapV3TokenIds.slot := UNISWAP_V3_TOKEN_IDS
        }
    }
    /// @notice Gets the UniswapV3TokenIds storage pointer
    function getRamsesV2TokenIds() internal pure returns (RamsesV2TokenIds storage ramsesV2TokenIds) {
        assembly {
            ramsesV2TokenIds.slot := RAMSES_V2_TOKEN_IDS
        }
    }
}

// SPDX-License-Identifier: BUSL-1.1
pragma solidity 0.8.26;

import {Address} from "@openzeppelin/contracts/utils/Address.sol";
import {IFuseCommon} from "../fuses/IFuseCommon.sol";
import {FuseStorageLib} from "./FuseStorageLib.sol";
import {PlasmaVaultStorageLib} from "./PlasmaVaultStorageLib.sol";
/**
 * @title Fuses Library - Core Component for Plasma Vault's Fuse Management System
 * @notice Library managing the lifecycle and configuration of fuses - specialized contracts that enable
 * the Plasma Vault to interact with external DeFi protocols
 * @dev This library is a critical component that:
 * 1. Manages the addition and removal of fuses to the vault system
 * 2. Handles balance fuse associations with specific markets
 * 3. Provides validation and access functions for fuse operations
 * 4. Maintains the integrity of fuse-market relationships
 *
 * Key Components:
 * - Fuse Management: Adding/removing supported fuses
 * - Balance Fuse Control: Market-specific balance tracking
 * - Validation Functions: Fuse support verification
 * - Storage Integration: Uses FuseStorageLib for persistent storage
 *
 * Integration Points:
 * - Used by PlasmaVault.execute() to validate fuse operations
 * - Used by PlasmaVaultGovernance.sol for fuse configuration
 * - Interacts with FuseStorageLib for storage management
 * - Coordinates with PlasmaVaultStorageLib for market data
 *
 * Security Considerations:
 * - Enforces strict validation of fuse addresses
 * - Prevents duplicate fuse registrations
 * - Ensures proper market-fuse relationships
 * - Manages balance fuse removal conditions
 * - Critical for vault's protocol integration security
 *
 * @custom:security-contact security@ipor.io
 */
library FusesLib {
    using Address for address;

    event FuseAdded(address fuse);
    event FuseRemoved(address fuse);
    event BalanceFuseAdded(uint256 marketId, address fuse);
    event BalanceFuseRemoved(uint256 marketId, address fuse);

    error FuseAlreadyExists();
    error FuseDoesNotExist();
    error FuseUnsupported(address fuse);
    error BalanceFuseAlreadyExists(uint256 marketId, address fuse);
    error BalanceFuseDoesNotExist(uint256 marketId, address fuse);
    error BalanceFuseNotReadyToRemove(uint256 marketId, address fuse, uint256 currentBalance);
    error BalanceFuseMarketIdMismatch(uint256 marketId, address fuse);
    /**
     * @notice Validates if a fuse contract is registered and supported by the Plasma Vault
     * @dev Checks the FuseStorageLib mapping to verify fuse registration status
     * - A non-zero value in the mapping indicates the fuse is supported
     * - The value represents (index + 1) in the fusesArray
     * - Used by PlasmaVault.execute() to validate fuse operations
     * - Critical for security as it prevents unauthorized protocol integrations
     *
     * Integration Context:
     * - Called before any fuse operation in PlasmaVault.execute()
     * - Used by PlasmaVaultGovernance for fuse management
     * - Part of the vault's protocol integration security layer
     *
     * @param fuse_ The address of the fuse contract to check
     * @return bool Returns true if the fuse is supported, false otherwise
     *
     * Security Notes:
     * - Zero address returns false
     * - Only fuses added through governance can return true
     * - Non-existent fuses return false
     */
    function isFuseSupported(address fuse_) internal view returns (bool) {
        return FuseStorageLib.getFuses().value[fuse_] != 0;
    }

    /**
     * @notice Validates if a fuse is configured as the balance fuse for a specific market
     * @dev Checks the PlasmaVaultStorageLib mapping to verify balance fuse assignment
     * - Each market can have only one balance fuse at a time
     * - Balance fuses are responsible for tracking market-specific asset balances
     * - Used for market balance validation and updates
     *
     * Integration Context:
     * - Used during market balance updates in PlasmaVault._updateMarketsBalances()
     * - Referenced during balance fuse configuration in PlasmaVaultGovernance
     * - Critical for asset distribution protection system
     *
     * Market Balance System:
     * - Balance fuses track protocol-specific positions (e.g., Compound, Aave positions)
     * - Provides standardized balance reporting across different protocols
     * - Essential for maintaining accurate vault accounting
     *
     * @param marketId_ The unique identifier of the market to check
     * @param fuse_ The address of the balance fuse contract to verify
     * @return bool Returns true if the fuse is the designated balance fuse for the market
     *
     * Security Notes:
     * - Returns false for non-existent market-fuse pairs
     * - Only one balance fuse can be active per market
     * - Critical for preventing unauthorized balance reporting
     */
    function isBalanceFuseSupported(uint256 marketId_, address fuse_) internal view returns (bool) {
        return PlasmaVaultStorageLib.getBalanceFuses().fuseAddresses[marketId_] == fuse_;
    }

    /**
     * @notice Retrieves the designated balance fuse contract address for a specific market
     * @dev Provides direct access to the balance fuse mapping in PlasmaVaultStorageLib
     * - Returns zero address if no balance fuse is configured for the market
     * - Each market can have only one active balance fuse at a time
     *
     * Integration Context:
     * - Used by PlasmaVault._updateMarketsBalances() for balance tracking
     * - Called during market balance validation and updates
     * - Referenced by AssetDistributionProtectionLib for limit checks
     *
     * Use Cases:
     * - Balance calculation during vault operations
     * - Market position valuation
     * - Asset distribution protection checks
     * - Protocol-specific balance queries
     *
     * @param marketId_ The unique identifier of the market
     * @return address The address of the balance fuse contract for the market
     *         Returns address(0) if no balance fuse is configured
     *
     * Related Components:
     * - CompoundV3BalanceFuse
     * - AaveV3BalanceFuse
     * - Other protocol-specific balance fuses
     */
    function getBalanceFuse(uint256 marketId_) internal view returns (address) {
        return PlasmaVaultStorageLib.getBalanceFuses().fuseAddresses[marketId_];
    }

    /**
     * @notice Retrieves the complete array of supported fuse contracts in the Plasma Vault
     * @dev Provides direct access to the fuses array from FuseStorageLib
     * - Array maintains order of fuse addition
     * - Used for fuse enumeration and management
     * - Critical for vault configuration and auditing
     *
     * Storage Pattern:
     * - Array indices correspond to (mapping value - 1) in FuseStorageLib.Fuses
     * - Maintains parallel structure with fuse mapping
     * - No duplicates allowed
     *
     * Integration Context:
     * - Used by PlasmaVaultGovernance for fuse management
     * - Referenced during vault configuration
     * - Used for fuse system auditing and verification
     * - Supports protocol integration management
     *
     * Use Cases:
     * - Fuse system configuration validation
     * - Protocol integration auditing
     * - Governance operations
     * - System state inspection
     *
     * @return address[] Array of all supported fuse contract addresses
     *
     * Related Functions:
     * - addFuse(): Appends to this array
     * - removeFuse(): Maintains array ordering
     * - getFuseArrayIndex(): Maps addresses to indices
     */
    function getFusesArray() internal view returns (address[] memory) {
        return FuseStorageLib.getFusesArray().value;
    }

    /**
     * @notice Retrieves the storage index for a given fuse contract
     * @dev Maps fuse addresses to their position in the fuses array
     * - Returns the value from FuseStorageLib.Fuses mapping
     * - Return value is (array index + 1) to distinguish from unsupported fuses
     * - Zero return value indicates fuse is not supported
     *
     * Storage Pattern:
     * - Mapping value = array index + 1
     * - Example: value 1 means index 0 in fusesArray
     * - Zero value means fuse not supported
     *
     * Integration Context:
     * - Used during fuse removal operations
     * - Supports array maintenance in removeFuse()
     * - Helps maintain storage consistency
     *
     * Use Cases:
     * - Fuse removal operations
     * - Storage validation
     * - Fuse support verification
     * - Array index lookups
     *
     * @param fuse_ The address of the fuse contract to look up
     * @return uint256 The storage index value (array index + 1) of the fuse
     *         Returns 0 if fuse is not supported
     *
     * Related Functions:
     * - addFuse(): Sets this index
     * - removeFuse(): Uses this for array maintenance
     * - getFusesArray(): Contains fuses at these indices
     */
    function getFuseArrayIndex(address fuse_) internal view returns (uint256) {
        return FuseStorageLib.getFuses().value[fuse_];
    }

    /**
     * @notice Registers a new fuse contract in the Plasma Vault's supported fuses list
     * @dev Manages the addition of fuses to both mapping and array storage
     * - Updates FuseStorageLib.Fuses mapping
     * - Appends to FuseStorageLib.FusesArray
     * - Maintains storage consistency between mapping and array
     *
     * Storage Updates:
     * 1. Checks for existing fuse to prevent duplicates
     * 2. Assigns new index (length + 1) in mapping
     * 3. Appends fuse address to array
     * 4. Emits FuseAdded event
     *
     * Integration Context:
     * - Called by PlasmaVaultGovernance.addFuses()
     * - Part of vault's protocol integration system
     * - Used during initial vault setup and protocol expansion
     *
     * Error Conditions:
     * - Reverts with FuseAlreadyExists if fuse is already registered
     * - Zero address handling done at governance level
     *
     * @param fuse_ The address of the fuse contract to add
     * @custom:events Emits FuseAdded when successful
     *
     * Security Considerations:
     * - Only callable through governance
     * - Critical for protocol integration security
     * - Must maintain storage consistency
     * - Affects vault's supported protocol list
     *
     * Gas Considerations:
     * - One SSTORE for mapping update
     * - One SSTORE for array push
     * - Event emission
     */
    function addFuse(address fuse_) internal {
        FuseStorageLib.Fuses storage fuses = FuseStorageLib.getFuses();

        uint256 keyIndexValue = fuses.value[fuse_];

        if (keyIndexValue != 0) {
            revert FuseAlreadyExists();
        }

        uint256 newLastFuseId = FuseStorageLib.getFusesArray().value.length + 1;

        /// @dev for balance fuses, value is a index + 1 in the fusesArray
        fuses.value[fuse_] = newLastFuseId;

        FuseStorageLib.getFusesArray().value.push(fuse_);

        emit FuseAdded(fuse_);
    }

    /**
     * @notice Removes a fuse contract from the Plasma Vault's supported fuses list
     * @dev Manages removal while maintaining storage consistency using swap-and-pop pattern
     * - Updates both FuseStorageLib.Fuses mapping and FusesArray
     * - Uses efficient swap-and-pop for array maintenance
     *
     * Storage Updates:
     * 1. Verifies fuse exists and gets its index
     * 2. Moves last array element to removed fuse's position
     * 3. Updates mapping for moved element
     * 4. Clears removed fuse's mapping entry
     * 5. Pops last array element
     * 6. Emits FuseRemoved event
     *
     * Integration Context:
     * - Called by PlasmaVaultGovernance.removeFuses()
     * - Part of protocol integration management
     * - Used during vault maintenance and protocol removal
     *
     * Error Conditions:
     * - Reverts with FuseDoesNotExist if fuse not found
     * - Zero address handling done at governance level
     *
     * @param fuse_ The address of the fuse contract to remove
     * @custom:events Emits FuseRemoved when successful
     *
     * Security Considerations:
     * - Only callable through governance
     * - Must maintain mapping-array consistency
     * - Critical for protocol integration security
     * - Affects vault's supported protocol list
     *
     * Gas Optimization:
     * - Uses swap-and-pop instead of shifting array
     * - Minimizes storage operations
     * - Three SSTORE operations:
     *   1. Update moved element's mapping
     *   2. Clear removed fuse's mapping
     *   3. Pop array
     */
    function removeFuse(address fuse_) internal {
        FuseStorageLib.Fuses storage fuses = FuseStorageLib.getFuses();

        uint256 indexToRemove = fuses.value[fuse_];

        if (indexToRemove == 0) {
            revert FuseDoesNotExist();
        }

        address lastKeyInArray = FuseStorageLib.getFusesArray().value[FuseStorageLib.getFusesArray().value.length - 1];

        fuses.value[lastKeyInArray] = indexToRemove;

        fuses.value[fuse_] = 0;

        /// @dev balanceFuses mapping contains values as index + 1
        FuseStorageLib.getFusesArray().value[indexToRemove - 1] = lastKeyInArray;

        FuseStorageLib.getFusesArray().value.pop();

        emit FuseRemoved(fuse_);
    }

    /**
     * @notice Associates a balance tracking fuse with a specific market in the Plasma Vault
     * @dev Manages market-specific balance fuse assignments and maintains market tracking data structures
     * - Updates both fuse mapping and market tracking arrays
     * - Maintains O(1) lookup capabilities through index mapping
     *
     * Storage Updates:
     * 1. Validates no duplicate fuse assignment
     * 2. Updates fuseAddresses mapping with new fuse
     * 3. Adds market to tracking array
     * 4. Updates index mapping for O(1) lookup
     * 5. Emits BalanceFuseAdded event
     *
     * Storage Pattern:
     * - balanceFuses.indexes[marketId_] stores (array index + 1)
     * - Example: value 1 means index 0 in marketIds array
     * - Matches pattern used in FuseStorageLib.Fuses mapping
     * - Allows distinguishing between non-existent (0) and first position (1)
     *
     * Integration Context:
     * - Called by PlasmaVaultGovernance.addBalanceFuse()
     * - Part of market setup and configuration
     * - Integrates with PlasmaVaultStorageLib.BalanceFuses
     * - Supports multi-market balance tracking system
     *
     * Market Tracking:
     * - Maintains ordered list of active markets
     * - Enables efficient market iteration
     * - Supports O(1) market existence checks
     * - Critical for balance update operations
     *
     * Error Conditions:
     * - Reverts with BalanceFuseAlreadyExists if:
     *   - Market already has this balance fuse
     *   - Prevents duplicate assignments
     *
     * @param marketId_ The unique identifier of the market
     * @param fuse_ The address of the balance fuse contract
     * @custom:events Emits BalanceFuseAdded when successful
     *
     * Security Considerations:
     * - Only callable through governance
     * - Must maintain array-mapping consistency
     * - Critical for market balance tracking
     * - Affects asset distribution protection
     * - Requires proper fuse validation
     *
     * Integration Points:
     * - PlasmaVault._updateMarketsBalances: Uses registered fuses
     * - AssetDistributionProtectionLib: Market balance checks
     * - Balance Fuses: Protocol-specific balance tracking
     * - Market Operations: Balance validation and updates
     */
    function addBalanceFuse(uint256 marketId_, address fuse_) internal {
        address currentFuse = PlasmaVaultStorageLib.getBalanceFuses().fuseAddresses[marketId_];

        if (currentFuse == fuse_) {
            revert BalanceFuseAlreadyExists(marketId_, fuse_);
        }

        if (marketId_ != IFuseCommon(fuse_).MARKET_ID()) {
            revert BalanceFuseMarketIdMismatch(marketId_, fuse_);
        }

        _updateBalanceFuseStructWhenAdding(marketId_, fuse_);

        emit BalanceFuseAdded(marketId_, fuse_);
    }

    /**
     * @notice Removes a balance tracking fuse from a specific market in the Plasma Vault
     * @dev Manages safe removal of market-fuse associations and updates market tracking data structures
     * - Uses swap-and-pop pattern for efficient array maintenance
     * - Maintains O(1) lookup capabilities through index mapping
     *
     * Storage Updates:
     * 1. Validates correct fuse-market association
     * 2. Verifies balance is below dust threshold via delegatecall
     * 3. Clears fuseAddresses mapping entry
     * 4. Updates marketIds array using swap-and-pop
     * 5. Updates indexes mapping for moved market
     * 6. Emits BalanceFuseRemoved event
     *
     * Storage Pattern:
     * - balanceFuses.indexes[marketId_] stores (array index + 1)
     * - Example: value 1 means index 0 in marketIds array
     * - Matches pattern used in FuseStorageLib.Fuses mapping
     * - Allows distinguishing between non-existent (0) and first position (1)
     *
     * Integration Context:
     * - Called by PlasmaVaultGovernance.removeBalanceFuse()
     * - Part of market decommissioning process
     * - Integrates with PlasmaVaultStorageLib.BalanceFuses
     * - Coordinates with balance fuse contracts
     *
     * Market Tracking:
     * - Maintains integrity of active markets list
     * - Updates market indexes after removal
     * - Preserves O(1) lookup capability
     * - Ensures proper market list maintenance
     *
     * Balance Validation:
     * - Uses delegatecall to check current balance
     * - Compares against dust threshold based on decimals
     * - Prevents removal of active positions
     * - Dust threshold scales with token precision
     *
     * Error Conditions:
     * - Reverts with BalanceFuseDoesNotExist if:
     *   - Fuse not assigned to market
     *   - Wrong fuse-market pair provided
     * - Reverts with BalanceFuseNotReadyToRemove if:
     *   - Balance exceeds dust threshold
     *   - Active positions exist
     *
     * @param marketId_ The unique identifier of the market
     * @param fuse_ The address of the balance fuse contract to remove
     * @custom:events Emits BalanceFuseRemoved when successful
     *
     * Security Considerations:
     * - Only callable through governance
     * - Must maintain array-mapping consistency
     * - Requires safe delegatecall handling
     * - Critical for market decommissioning
     * - Protects against premature removal
     *
     * Integration Points:
     * - PlasmaVault._updateMarketsBalances: Affected by removals
     * - Balance Fuses: Balance validation
     * - Asset Protection: Market tracking updates
     * - Market Operations: State consistency
     *
     * Gas Optimization:
     * - Uses swap-and-pop for array maintenance
     * - Minimizes storage operations
     * - Efficient market list updates
     * - Optimized for minimal gas usage
     */
    function removeBalanceFuse(uint256 marketId_, address fuse_) internal {
        address currentBalanceFuse = PlasmaVaultStorageLib.getBalanceFuses().fuseAddresses[marketId_];

        if (marketId_ != IFuseCommon(fuse_).MARKET_ID()) {
            revert BalanceFuseMarketIdMismatch(marketId_, fuse_);
        }

        if (currentBalanceFuse != fuse_) {
            revert BalanceFuseDoesNotExist(marketId_, fuse_);
        }

        uint256 wadBalanceAmountInUSD = abi.decode(
            currentBalanceFuse.functionDelegateCall(abi.encodeWithSignature("balanceOf()")),
            (uint256)
        );

        if (wadBalanceAmountInUSD > _calculateAllowedDustInBalanceFuse()) {
            revert BalanceFuseNotReadyToRemove(marketId_, fuse_, wadBalanceAmountInUSD);
        }

        _updateBalanceFuseStructWhenRemoving(marketId_);

        emit BalanceFuseRemoved(marketId_, fuse_);
    }

    /**
     * @notice Retrieves the list of all active markets with registered balance fuses
     * @dev Provides direct access to the ordered array of active market IDs from BalanceFuses storage
     * - Returns the complete marketIds array without modifications
     * - Order of markets matches their registration sequence
     *
     * Storage Access:
     * - Reads from PlasmaVaultStorageLib.BalanceFuses.marketIds
     * - No storage modifications
     * - O(1) operation for array access
     * - Returns reference to complete array
     *
     * Integration Context:
     * - Used by PlasmaVault._updateMarketsBalances for iteration
     * - Referenced during multi-market operations
     * - Supports balance update coordination
     * - Essential for market state management
     *
     * Use Cases:
     * - Market balance updates
     * - Asset distribution checks
     * - Market state validation
     * - Protocol-wide operations
     *
     * Array Properties:
     * - Maintained by addBalanceFuse/removeBalanceFuse
     * - No duplicates allowed
     * - Order may change during removals (swap-and-pop)
     * - Empty array possible if no active markets
     *
     * @return uint256[] Array of active market IDs with registered balance fuses
     *
     * Integration Points:
     * - Balance Update System: Market iteration
     * - Asset Protection: Market validation
     * - Governance: Market monitoring
     * - Protocol Operations: State checks
     *
     * Performance Notes:
     * - Constant gas cost for array access
     * - No array copying - returns storage reference
     * - Efficient for bulk market operations
     * - Suitable for view function calls
     */
    function getActiveMarketsInBalanceFuses() internal view returns (uint256[] memory) {
        return PlasmaVaultStorageLib.getBalanceFuses().marketIds;
    }

    function _calculateAllowedDustInBalanceFuse() private view returns (uint256) {
        return 10 ** (PlasmaVaultStorageLib.getERC4626Storage().underlyingDecimals / 2);
    }

    function _updateBalanceFuseStructWhenAdding(uint256 marketId_, address fuse_) private {
        PlasmaVaultStorageLib.BalanceFuses storage balanceFuses = PlasmaVaultStorageLib.getBalanceFuses();

        uint256 newMarketIdIndexValue = balanceFuses.marketIds.length + 1;

        balanceFuses.fuseAddresses[marketId_] = fuse_;
        balanceFuses.marketIds.push(marketId_);
        balanceFuses.indexes[marketId_] = newMarketIdIndexValue;
    }
    function _updateBalanceFuseStructWhenRemoving(uint256 marketId_) private {
        PlasmaVaultStorageLib.BalanceFuses storage balanceFuses = PlasmaVaultStorageLib.getBalanceFuses();

        delete balanceFuses.fuseAddresses[marketId_];

        uint256 indexValue = balanceFuses.indexes[marketId_];
        uint256 marketIdsLength = balanceFuses.marketIds.length;

        if (indexValue != marketIdsLength) {
            balanceFuses.marketIds[indexValue - 1] = balanceFuses.marketIds[marketIdsLength - 1];
            balanceFuses.indexes[balanceFuses.marketIds[marketIdsLength - 1]] = indexValue;
        }
        balanceFuses.marketIds.pop();

        delete balanceFuses.indexes[marketId_];
    }
}

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.0.0) (access/manager/IAccessManaged.sol)

pragma solidity ^0.8.20;

interface IAccessManaged {
    /**
     * @dev Authority that manages this contract was updated.
     */
    event AuthorityUpdated(address authority);

    error AccessManagedUnauthorized(address caller);
    error AccessManagedRequiredDelay(address caller, uint32 delay);
    error AccessManagedInvalidAuthority(address authority);

    /**
     * @dev Returns the current authority.
     */
    function authority() external view returns (address);

    /**
     * @dev Transfers control to a new authority. The caller must be the current authority.
     */
    function setAuthority(address) external;

    /**
     * @dev Returns true only in the context of a delayed restricted call, at the moment that the scheduled operation is
     * being consumed. Prevents denial of service for delayed restricted calls in the case that the contract performs
     * attacker controlled calls.
     */
    function isConsumingScheduledOp() external view returns (bytes4);
}

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.0.0) (access/manager/IAccessManager.sol)

pragma solidity ^0.8.20;

import {IAccessManaged} from "./IAccessManaged.sol";
import {Time} from "../../utils/types/Time.sol";

interface IAccessManager {
    /**
     * @dev A delayed operation was scheduled.
     */
    event OperationScheduled(
        bytes32 indexed operationId,
        uint32 indexed nonce,
        uint48 schedule,
        address caller,
        address target,
        bytes data
    );

    /**
     * @dev A scheduled operation was executed.
     */
    event OperationExecuted(bytes32 indexed operationId, uint32 indexed nonce);

    /**
     * @dev A scheduled operation was canceled.
     */
    event OperationCanceled(bytes32 indexed operationId, uint32 indexed nonce);

    /**
     * @dev Informational labelling for a roleId.
     */
    event RoleLabel(uint64 indexed roleId, string label);

    /**
     * @dev Emitted when `account` is granted `roleId`.
     *
     * NOTE: The meaning of the `since` argument depends on the `newMember` argument.
     * If the role is granted to a new member, the `since` argument indicates when the account becomes a member of the role,
     * otherwise it indicates the execution delay for this account and roleId is updated.
     */
    event RoleGranted(uint64 indexed roleId, address indexed account, uint32 delay, uint48 since, bool newMember);

    /**
     * @dev Emitted when `account` membership or `roleId` is revoked. Unlike granting, revoking is instantaneous.
     */
    event RoleRevoked(uint64 indexed roleId, address indexed account);

    /**
     * @dev Role acting as admin over a given `roleId` is updated.
     */
    event RoleAdminChanged(uint64 indexed roleId, uint64 indexed admin);

    /**
     * @dev Role acting as guardian over a given `roleId` is updated.
     */
    event RoleGuardianChanged(uint64 indexed roleId, uint64 indexed guardian);

    /**
     * @dev Grant delay for a given `roleId` will be updated to `delay` when `since` is reached.
     */
    event RoleGrantDelayChanged(uint64 indexed roleId, uint32 delay, uint48 since);

    /**
     * @dev Target mode is updated (true = closed, false = open).
     */
    event TargetClosed(address indexed target, bool closed);

    /**
     * @dev Role required to invoke `selector` on `target` is updated to `roleId`.
     */
    event TargetFunctionRoleUpdated(address indexed target, bytes4 selector, uint64 indexed roleId);

    /**
     * @dev Admin delay for a given `target` will be updated to `delay` when `since` is reached.
     */
    event TargetAdminDelayUpdated(address indexed target, uint32 delay, uint48 since);

    error AccessManagerAlreadyScheduled(bytes32 operationId);
    error AccessManagerNotScheduled(bytes32 operationId);
    error AccessManagerNotReady(bytes32 operationId);
    error AccessManagerExpired(bytes32 operationId);
    error AccessManagerLockedAccount(address account);
    error AccessManagerLockedRole(uint64 roleId);
    error AccessManagerBadConfirmation();
    error AccessManagerUnauthorizedAccount(address msgsender, uint64 roleId);
    error AccessManagerUnauthorizedCall(address caller, address target, bytes4 selector);
    error AccessManagerUnauthorizedConsume(address target);
    error AccessManagerUnauthorizedCancel(address msgsender, address caller, address target, bytes4 selector);
    error AccessManagerInvalidInitialAdmin(address initialAdmin);

    /**
     * @dev Check if an address (`caller`) is authorised to call a given function on a given contract directly (with
     * no restriction). Additionally, it returns the delay needed to perform the call indirectly through the {schedule}
     * & {execute} workflow.
     *
     * This function is usually called by the targeted contract to control immediate execution of restricted functions.
     * Therefore we only return true if the call can be performed without any delay. If the call is subject to a
     * previously set delay (not zero), then the function should return false and the caller should schedule the operation
     * for future execution.
     *
     * If `immediate` is true, the delay can be disregarded and the operation can be immediately executed, otherwise
     * the operation can be executed if and only if delay is greater than 0.
     *
     * NOTE: The IAuthority interface does not include the `uint32` delay. This is an extension of that interface that
     * is backward compatible. Some contracts may thus ignore the second return argument. In that case they will fail
     * to identify the indirect workflow, and will consider calls that require a delay to be forbidden.
     *
     * NOTE: This function does not report the permissions of this manager itself. These are defined by the
     * {_canCallSelf} function instead.
     */
    function canCall(
        address caller,
        address target,
        bytes4 selector
    ) external view returns (bool allowed, uint32 delay);

    /**
     * @dev Expiration delay for scheduled proposals. Defaults to 1 week.
     *
     * IMPORTANT: Avoid overriding the expiration with 0. Otherwise every contract proposal will be expired immediately,
     * disabling any scheduling usage.
     */
    function expiration() external view returns (uint32);

    /**
     * @dev Minimum setback for all delay updates, with the exception of execution delays. It
     * can be increased without setback (and reset via {revokeRole} in the case event of an
     * accidental increase). Defaults to 5 days.
     */
    function minSetback() external view returns (uint32);

    /**
     * @dev Get whether the contract is closed disabling any access. Otherwise role permissions are applied.
     */
    function isTargetClosed(address target) external view returns (bool);

    /**
     * @dev Get the role required to call a function.
     */
    function getTargetFunctionRole(address target, bytes4 selector) external view returns (uint64);

    /**
     * @dev Get the admin delay for a target contract. Changes to contract configuration are subject to this delay.
     */
    function getTargetAdminDelay(address target) external view returns (uint32);

    /**
     * @dev Get the id of the role that acts as an admin for the given role.
     *
     * The admin permission is required to grant the role, revoke the role and update the execution delay to execute
     * an operation that is restricted to this role.
     */
    function getRoleAdmin(uint64 roleId) external view returns (uint64);

    /**
     * @dev Get the role that acts as a guardian for a given role.
     *
     * The guardian permission allows canceling operations that have been scheduled under the role.
     */
    function getRoleGuardian(uint64 roleId) external view returns (uint64);

    /**
     * @dev Get the role current grant delay.
     *
     * Its value may change at any point without an event emitted following a call to {setGrantDelay}.
     * Changes to this value, including effect timepoint are notified in advance by the {RoleGrantDelayChanged} event.
     */
    function getRoleGrantDelay(uint64 roleId) external view returns (uint32);

    /**
     * @dev Get the access details for a given account for a given role. These details include the timepoint at which
     * membership becomes active, and the delay applied to all operation by this user that requires this permission
     * level.
     *
     * Returns:
     * [0] Timestamp at which the account membership becomes valid. 0 means role is not granted.
     * [1] Current execution delay for the account.
     * [2] Pending execution delay for the account.
     * [3] Timestamp at which the pending execution delay will become active. 0 means no delay update is scheduled.
     */
    function getAccess(uint64 roleId, address account) external view returns (uint48, uint32, uint32, uint48);

    /**
     * @dev Check if a given account currently has the permission level corresponding to a given role. Note that this
     * permission might be associated with an execution delay. {getAccess} can provide more details.
     */
    function hasRole(uint64 roleId, address account) external view returns (bool, uint32);

    /**
     * @dev Give a label to a role, for improved role discoverability by UIs.
     *
     * Requirements:
     *
     * - the caller must be a global admin
     *
     * Emits a {RoleLabel} event.
     */
    function labelRole(uint64 roleId, string calldata label) external;

    /**
     * @dev Add `account` to `roleId`, or change its execution delay.
     *
     * This gives the account the authorization to call any function that is restricted to this role. An optional
     * execution delay (in seconds) can be set. If that delay is non 0, the user is required to schedule any operation
     * that is restricted to members of this role. The user will only be able to execute the operation after the delay has
     * passed, before it has expired. During this period, admin and guardians can cancel the operation (see {cancel}).
     *
     * If the account has already been granted this role, the execution delay will be updated. This update is not
     * immediate and follows the delay rules. For example, if a user currently has a delay of 3 hours, and this is
     * called to reduce that delay to 1 hour, the new delay will take some time to take effect, enforcing that any
     * operation executed in the 3 hours that follows this update was indeed scheduled before this update.
     *
     * Requirements:
     *
     * - the caller must be an admin for the role (see {getRoleAdmin})
     * - granted role must not be the `PUBLIC_ROLE`
     *
     * Emits a {RoleGranted} event.
     */
    function grantRole(uint64 roleId, address account, uint32 executionDelay) external;

    /**
     * @dev Remove an account from a role, with immediate effect. If the account does not have the role, this call has
     * no effect.
     *
     * Requirements:
     *
     * - the caller must be an admin for the role (see {getRoleAdmin})
     * - revoked role must not be the `PUBLIC_ROLE`
     *
     * Emits a {RoleRevoked} event if the account had the role.
     */
    function revokeRole(uint64 roleId, address account) external;

    /**
     * @dev Renounce role permissions for the calling account with immediate effect. If the sender is not in
     * the role this call has no effect.
     *
     * Requirements:
     *
     * - the caller must be `callerConfirmation`.
     *
     * Emits a {RoleRevoked} event if the account had the role.
     */
    function renounceRole(uint64 roleId, address callerConfirmation) external;

    /**
     * @dev Change admin role for a given role.
     *
     * Requirements:
     *
     * - the caller must be a global admin
     *
     * Emits a {RoleAdminChanged} event
     */
    function setRoleAdmin(uint64 roleId, uint64 admin) external;

    /**
     * @dev Change guardian role for a given role.
     *
     * Requirements:
     *
     * - the caller must be a global admin
     *
     * Emits a {RoleGuardianChanged} event
     */
    function setRoleGuardian(uint64 roleId, uint64 guardian) external;

    /**
     * @dev Update the delay for granting a `roleId`.
     *
     * Requirements:
     *
     * - the caller must be a global admin
     *
     * Emits a {RoleGrantDelayChanged} event.
     */
    function setGrantDelay(uint64 roleId, uint32 newDelay) external;

    /**
     * @dev Set the role required to call functions identified by the `selectors` in the `target` contract.
     *
     * Requirements:
     *
     * - the caller must be a global admin
     *
     * Emits a {TargetFunctionRoleUpdated} event per selector.
     */
    function setTargetFunctionRole(address target, bytes4[] calldata selectors, uint64 roleId) external;

    /**
     * @dev Set the delay for changing the configuration of a given target contract.
     *
     * Requirements:
     *
     * - the caller must be a global admin
     *
     * Emits a {TargetAdminDelayUpdated} event.
     */
    function setTargetAdminDelay(address target, uint32 newDelay) external;

    /**
     * @dev Set the closed flag for a contract.
     *
     * Requirements:
     *
     * - the caller must be a global admin
     *
     * Emits a {TargetClosed} event.
     */
    function setTargetClosed(address target, bool closed) external;

    /**
     * @dev Return the timepoint at which a scheduled operation will be ready for execution. This returns 0 if the
     * operation is not yet scheduled, has expired, was executed, or was canceled.
     */
    function getSchedule(bytes32 id) external view returns (uint48);

    /**
     * @dev Return the nonce for the latest scheduled operation with a given id. Returns 0 if the operation has never
     * been scheduled.
     */
    function getNonce(bytes32 id) external view returns (uint32);

    /**
     * @dev Schedule a delayed operation for future execution, and return the operation identifier. It is possible to
     * choose the timestamp at which the operation becomes executable as long as it satisfies the execution delays
     * required for the caller. The special value zero will automatically set the earliest possible time.
     *
     * Returns the `operationId` that was scheduled. Since this value is a hash of the parameters, it can reoccur when
     * the same parameters are used; if this is relevant, the returned `nonce` can be used to uniquely identify this
     * scheduled operation from other occurrences of the same `operationId` in invocations of {execute} and {cancel}.
     *
     * Emits a {OperationScheduled} event.
     *
     * NOTE: It is not possible to concurrently schedule more than one operation with the same `target` and `data`. If
     * this is necessary, a random byte can be appended to `data` to act as a salt that will be ignored by the target
     * contract if it is using standard Solidity ABI encoding.
     */
    function schedule(address target, bytes calldata data, uint48 when) external returns (bytes32, uint32);

    /**
     * @dev Execute a function that is delay restricted, provided it was properly scheduled beforehand, or the
     * execution delay is 0.
     *
     * Returns the nonce that identifies the previously scheduled operation that is executed, or 0 if the
     * operation wasn't previously scheduled (if the caller doesn't have an execution delay).
     *
     * Emits an {OperationExecuted} event only if the call was scheduled and delayed.
     */
    function execute(address target, bytes calldata data) external payable returns (uint32);

    /**
     * @dev Cancel a scheduled (delayed) operation. Returns the nonce that identifies the previously scheduled
     * operation that is cancelled.
     *
     * Requirements:
     *
     * - the caller must be the proposer, a guardian of the targeted function, or a global admin
     *
     * Emits a {OperationCanceled} event.
     */
    function cancel(address caller, address target, bytes calldata data) external returns (uint32);

    /**
     * @dev Consume a scheduled operation targeting the caller. If such an operation exists, mark it as consumed
     * (emit an {OperationExecuted} event and clean the state). Otherwise, throw an error.
     *
     * This is useful for contract that want to enforce that calls targeting them were scheduled on the manager,
     * with all the verifications that it implies.
     *
     * Emit a {OperationExecuted} event.
     */
    function consumeScheduledOp(address caller, bytes calldata data) external;

    /**
     * @dev Hashing function for delayed operations.
     */
    function hashOperation(address caller, address target, bytes calldata data) external view returns (bytes32);

    /**
     * @dev Changes the authority of a target managed by this manager instance.
     *
     * Requirements:
     *
     * - the caller must be a global admin
     */
    function updateAuthority(address target, address newAuthority) external;
}

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.0.0) (access/manager/IAuthority.sol)

pragma solidity ^0.8.20;

/**
 * @dev Standard interface for permissioning originally defined in Dappsys.
 */
interface IAuthority {
    /**
     * @dev Returns true if the caller can invoke on a target the function identified by a function selector.
     */
    function canCall(address caller, address target, bytes4 selector) external view returns (bool allowed);
}

// SPDX-License-Identifier: BUSL-1.1
pragma solidity 0.8.26;

/**
 * @title IContextClient
 * @notice Interface for contracts that need to manage sender context in vault operations
 * @dev This interface defines the core functionality for context management in the vault system
 *
 * The context system allows for:
 * - Temporary impersonation of transaction senders
 * - Secure execution of operations with delegated permissions
 * - Clean context management with setup and cleanup
 *
 * Security considerations:
 * - Only authorized contracts should be allowed to set/clear context
 * - Context should never be nested (one context at a time)
 * - Context must always be cleared after use
 * - Proper access control should be implemented by contracts using this interface
 */
interface IContextClient {
    /**
     * @notice Sets up a new context with the specified sender address
     * @param sender_ The address to be set as the context sender
     * @dev Requirements:
     * - Must be called by an authorized contract
     * - No active context should exist when setting up new context
     * - Emits ContextSet event on successful setup
     * @custom:security Should implement access control to prevent unauthorized context manipulation
     */
    function setupContext(address sender_) external;

    /**
     * @notice Clears the current active context
     * @dev Requirements:
     * - Must be called by an authorized contract
     * - An active context must exist
     * - Emits ContextCleared event on successful cleanup
     * @custom:security Should always be called after context operations are complete
     */
    function clearContext() external;

    /**
     * @notice Emitted when a new context is successfully set
     * @param sender_ The address that was set as the context sender
     * @dev This event should be monitored for context tracking and auditing
     */
    event ContextSet(address indexed sender_);

    /**
     * @notice Emitted when an active context is cleared
     * @param sender_ The address that was removed from the context
     * @dev This event should be monitored to ensure proper context cleanup
     */
    event ContextCleared(address indexed sender_);

    /**
     * @notice Expected errors that may be thrown by implementations
     * @dev Implementations should define these errors:
     * - ContextAlreadySet(): When attempting to set context while one is active
     * - ContextNotSet(): When attempting to clear or access non-existent context
     * - UnauthorizedSender(): When unauthorized address attempts to modify context
     */
}

// 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/IERC20Metadata.sol)

pragma solidity ^0.8.20;

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

/**
 * @dev Interface for the optional metadata functions from the ERC20 standard.
 */
interface IERC20Metadata is IERC20 {
    /**
     * @dev Returns the name of the token.
     */
    function name() external view returns (string memory);

    /**
     * @dev Returns the symbol of the token.
     */
    function symbol() external view returns (string memory);

    /**
     * @dev Returns the decimals places of the token.
     */
    function decimals() external view returns (uint8);
}

// 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) (interfaces/IERC4626.sol)

pragma solidity ^0.8.20;

import {IERC20} from "../token/ERC20/IERC20.sol";
import {IERC20Metadata} from "../token/ERC20/extensions/IERC20Metadata.sol";

/**
 * @dev Interface of the ERC4626 "Tokenized Vault Standard", as defined in
 * https://eips.ethereum.org/EIPS/eip-4626[ERC-4626].
 */
interface IERC4626 is IERC20, IERC20Metadata {
    event Deposit(address indexed sender, address indexed owner, uint256 assets, uint256 shares);

    event Withdraw(
        address indexed sender,
        address indexed receiver,
        address indexed owner,
        uint256 assets,
        uint256 shares
    );

    /**
     * @dev Returns the address of the underlying token used for the Vault for accounting, depositing, and withdrawing.
     *
     * - MUST be an ERC-20 token contract.
     * - MUST NOT revert.
     */
    function asset() external view returns (address assetTokenAddress);

    /**
     * @dev Returns the total amount of the underlying asset that is “managed” by Vault.
     *
     * - SHOULD include any compounding that occurs from yield.
     * - MUST be inclusive of any fees that are charged against assets in the Vault.
     * - MUST NOT revert.
     */
    function totalAssets() external view returns (uint256 totalManagedAssets);

    /**
     * @dev Returns the amount of shares that the Vault would exchange for the amount of assets provided, in an ideal
     * scenario where all the conditions are met.
     *
     * - MUST NOT be inclusive of any fees that are charged against assets in the Vault.
     * - MUST NOT show any variations depending on the caller.
     * - MUST NOT reflect slippage or other on-chain conditions, when performing the actual exchange.
     * - MUST NOT revert.
     *
     * NOTE: This calculation MAY NOT reflect the “per-user” price-per-share, and instead should reflect the
     * “average-user’s” price-per-share, meaning what the average user should expect to see when exchanging to and
     * from.
     */
    function convertToShares(uint256 assets) external view returns (uint256 shares);

    /**
     * @dev Returns the amount of assets that the Vault would exchange for the amount of shares provided, in an ideal
     * scenario where all the conditions are met.
     *
     * - MUST NOT be inclusive of any fees that are charged against assets in the Vault.
     * - MUST NOT show any variations depending on the caller.
     * - MUST NOT reflect slippage or other on-chain conditions, when performing the actual exchange.
     * - MUST NOT revert.
     *
     * NOTE: This calculation MAY NOT reflect the “per-user” price-per-share, and instead should reflect the
     * “average-user’s” price-per-share, meaning what the average user should expect to see when exchanging to and
     * from.
     */
    function convertToAssets(uint256 shares) external view returns (uint256 assets);

    /**
     * @dev Returns the maximum amount of the underlying asset that can be deposited into the Vault for the receiver,
     * through a deposit call.
     *
     * - MUST return a limited value if receiver is subject to some deposit limit.
     * - MUST return 2 ** 256 - 1 if there is no limit on the maximum amount of assets that may be deposited.
     * - MUST NOT revert.
     */
    function maxDeposit(address receiver) external view returns (uint256 maxAssets);

    /**
     * @dev Allows an on-chain or off-chain user to simulate the effects of their deposit at the current block, given
     * current on-chain conditions.
     *
     * - MUST return as close to and no more than the exact amount of Vault shares that would be minted in a deposit
     *   call in the same transaction. I.e. deposit should return the same or more shares as previewDeposit if called
     *   in the same transaction.
     * - MUST NOT account for deposit limits like those returned from maxDeposit and should always act as though the
     *   deposit would be accepted, regardless if the user has enough tokens approved, etc.
     * - MUST be inclusive of deposit fees. Integrators should be aware of the existence of deposit fees.
     * - MUST NOT revert.
     *
     * NOTE: any unfavorable discrepancy between convertToShares and previewDeposit SHOULD be considered slippage in
     * share price or some other type of condition, meaning the depositor will lose assets by depositing.
     */
    function previewDeposit(uint256 assets) external view returns (uint256 shares);

    /**
     * @dev Mints shares Vault shares to receiver by depositing exactly amount of underlying tokens.
     *
     * - MUST emit the Deposit event.
     * - MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the
     *   deposit execution, and are accounted for during deposit.
     * - MUST revert if all of assets cannot be deposited (due to deposit limit being reached, slippage, the user not
     *   approving enough underlying tokens to the Vault contract, etc).
     *
     * NOTE: most implementations will require pre-approval of the Vault with the Vault’s underlying asset token.
     */
    function deposit(uint256 assets, address receiver) external returns (uint256 shares);

    /**
     * @dev Returns the maximum amount of the Vault shares that can be minted for the receiver, through a mint call.
     * - MUST return a limited value if receiver is subject to some mint limit.
     * - MUST return 2 ** 256 - 1 if there is no limit on the maximum amount of shares that may be minted.
     * - MUST NOT revert.
     */
    function maxMint(address receiver) external view returns (uint256 maxShares);

    /**
     * @dev Allows an on-chain or off-chain user to simulate the effects of their mint at the current block, given
     * current on-chain conditions.
     *
     * - MUST return as close to and no fewer than the exact amount of assets that would be deposited in a mint call
     *   in the same transaction. I.e. mint should return the same or fewer assets as previewMint if called in the
     *   same transaction.
     * - MUST NOT account for mint limits like those returned from maxMint and should always act as though the mint
     *   would be accepted, regardless if the user has enough tokens approved, etc.
     * - MUST be inclusive of deposit fees. Integrators should be aware of the existence of deposit fees.
     * - MUST NOT revert.
     *
     * NOTE: any unfavorable discrepancy between convertToAssets and previewMint SHOULD be considered slippage in
     * share price or some other type of condition, meaning the depositor will lose assets by minting.
     */
    function previewMint(uint256 shares) external view returns (uint256 assets);

    /**
     * @dev Mints exactly shares Vault shares to receiver by depositing amount of underlying tokens.
     *
     * - MUST emit the Deposit event.
     * - MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the mint
     *   execution, and are accounted for during mint.
     * - MUST revert if all of shares cannot be minted (due to deposit limit being reached, slippage, the user not
     *   approving enough underlying tokens to the Vault contract, etc).
     *
     * NOTE: most implementations will require pre-approval of the Vault with the Vault’s underlying asset token.
     */
    function mint(uint256 shares, address receiver) external returns (uint256 assets);

    /**
     * @dev Returns the maximum amount of the underlying asset that can be withdrawn from the owner balance in the
     * Vault, through a withdraw call.
     *
     * - MUST return a limited value if owner is subject to some withdrawal limit or timelock.
     * - MUST NOT revert.
     */
    function maxWithdraw(address owner) external view returns (uint256 maxAssets);

    /**
     * @dev Allows an on-chain or off-chain user to simulate the effects of their withdrawal at the current block,
     * given current on-chain conditions.
     *
     * - MUST return as close to and no fewer than the exact amount of Vault shares that would be burned in a withdraw
     *   call in the same transaction. I.e. withdraw should return the same or fewer shares as previewWithdraw if
     *   called
     *   in the same transaction.
     * - MUST NOT account for withdrawal limits like those returned from maxWithdraw and should always act as though
     *   the withdrawal would be accepted, regardless if the user has enough shares, etc.
     * - MUST be inclusive of withdrawal fees. Integrators should be aware of the existence of withdrawal fees.
     * - MUST NOT revert.
     *
     * NOTE: any unfavorable discrepancy between convertToShares and previewWithdraw SHOULD be considered slippage in
     * share price or some other type of condition, meaning the depositor will lose assets by depositing.
     */
    function previewWithdraw(uint256 assets) external view returns (uint256 shares);

    /**
     * @dev Burns shares from owner and sends exactly assets of underlying tokens to receiver.
     *
     * - MUST emit the Withdraw event.
     * - MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the
     *   withdraw execution, and are accounted for during withdraw.
     * - MUST revert if all of assets cannot be withdrawn (due to withdrawal limit being reached, slippage, the owner
     *   not having enough shares, etc).
     *
     * Note that some implementations will require pre-requesting to the Vault before a withdrawal may be performed.
     * Those methods should be performed separately.
     */
    function withdraw(uint256 assets, address receiver, address owner) external returns (uint256 shares);

    /**
     * @dev Returns the maximum amount of Vault shares that can be redeemed from the owner balance in the Vault,
     * through a redeem call.
     *
     * - MUST return a limited value if owner is subject to some withdrawal limit or timelock.
     * - MUST return balanceOf(owner) if owner is not subject to any withdrawal limit or timelock.
     * - MUST NOT revert.
     */
    function maxRedeem(address owner) external view returns (uint256 maxShares);

    /**
     * @dev Allows an on-chain or off-chain user to simulate the effects of their redeemption at the current block,
     * given current on-chain conditions.
     *
     * - MUST return as close to and no more than the exact amount of assets that would be withdrawn in a redeem call
     *   in the same transaction. I.e. redeem should return the same or more assets as previewRedeem if called in the
     *   same transaction.
     * - MUST NOT account for redemption limits like those returned from maxRedeem and should always act as though the
     *   redemption would be accepted, regardless if the user has enough shares, etc.
     * - MUST be inclusive of withdrawal fees. Integrators should be aware of the existence of withdrawal fees.
     * - MUST NOT revert.
     *
     * NOTE: any unfavorable discrepancy between convertToAssets and previewRedeem SHOULD be considered slippage in
     * share price or some other type of condition, meaning the depositor will lose assets by redeeming.
     */
    function previewRedeem(uint256 shares) external view returns (uint256 assets);

    /**
     * @dev Burns exactly shares from owner and sends assets of underlying tokens to receiver.
     *
     * - MUST emit the Withdraw event.
     * - MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the
     *   redeem execution, and are accounted for during redeem.
     * - MUST revert if all of shares cannot be redeemed (due to withdrawal limit being reached, slippage, the owner
     *   not having enough shares, etc).
     *
     * NOTE: some implementations will require pre-requesting to the Vault before a withdrawal may be performed.
     * Those methods should be performed separately.
     */
    function redeem(uint256 shares, address receiver, address owner) external returns (uint256 assets);
}