STBL_PT1_Issuer

{{
  "language": "Solidity",
  "sources": {
    "contracts/Assets/PT1/STBL_PT1_Issuer.sol": {
      "content": "// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@openzeppelin/contracts-upgradeable/metatx/ERC2771ContextUpgradeable.sol";
import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
import "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";

import "@openzeppelin/contracts/token/ERC20/IERC20.sol";

import "../../interfaces/ISTBL_Register.sol";
import "../../interfaces/ISTBL_Core.sol";
import "../../interfaces/ISTBL_YLD.sol";

import "./interfaces/ISTBL_PT1_AssetIssuer.sol";
import "./interfaces/ISTBL_PT1_AssetVault.sol";
import "./interfaces/ISTBL_PT1_AssetYieldDistributor.sol";
import "./interfaces/ISTBL_PT1_AssetOracle.sol";

import "../../lib/STBL_Structs.sol";
import "../../lib/STBL_AssetDefinitionLib.sol";
import "../../lib/STBL_MetadataLib.sol";
import "../../lib/STBL_Errors.sol";
import "../../lib/STBL_Errors.sol";
import "../../lib/STBL_DecimalConverter.sol";

import "./lib/STBL_OracleLib.sol";
import "./lib/STBL_PT1_Asset_Errors.sol";

/**
 * @title STBL_PT1_Issuer
 * @notice Protocol Type 1 asset issuer contract that manages deposits and withdrawals for tokenized real-world assets
 * @dev Implements the iSTBL_PT1_AssetIssuer interface with UUPS upgradeable pattern and ERC2771 meta-transaction support
 * @dev This contract serves as the primary interface for users to deposit assets and receive yield-bearing NFTs
 * @author STBL Protocol
 * @custom:security-contact security@stbl.xyz
 */
contract STBL_PT1_Issuer is
    Initializable,
    iSTBL_PT1_AssetIssuer,
    ERC2771ContextUpgradeable,
    UUPSUpgradeable
{
    using STBL_AssetDefinitionLib for AssetDefinition;
    using STBL_OracleLib for iSTBL_PT1_AssetOracle;
    using STBL_MetadataLib for YLD_Metadata;
    using DecimalConverter for uint256;

    /** @notice Role identifier for contract upgrade authorization */
    bytes32 public constant UPGRADER_ROLE = keccak256("UPGRADER_ROLE");

    /** @notice Current implementation version number for tracking upgrades */
    uint256 private _version;

    /** @notice Registry contract interface providing access to all system components and configuration */
    iSTBL_Register private registry;

    /** @notice Unique identifier for the specific asset type managed by this issuer instance */
    uint256 private assetID;

    /**
     * @dev Storage gap reserved for future state variables in upgradeable contracts
     * @notice This gap ensures storage layout compatibility when adding new state variables in future versions
     */
    uint256[64] private __gap;

    /**
     * @notice Ensures the asset is properly configured and active before allowing operations
     * @dev Validates that the asset definition exists in the registry and is marked as active
     * @custom:reverts STBL_Asset_NotInitialized if the asset is not properly initialized or has been deactivated
     */
    modifier isSetupDone() {
        AssetDefinition memory AssetData = registry.fetchAssetData(assetID);
        if (!AssetData.isActive()) revert STBL_Asset_NotInitialized(assetID);
        _;
    }

    /**
     * @notice Contract constructor that initializes the ERC2771Context with a null trusted forwarder
     * @dev The trusted forwarder will be configured during the initialize() call via the registry
     * @custom:oz-upgrades-unsafe-allow constructor
     */
    constructor() ERC2771ContextUpgradeable(address(0)) {}

    /**
     * @notice Initializes the issuer contract with asset configuration and access controls
     * @dev Sets up UUPS upgradeability, access control roles, and links to the protocol registry
     * @dev This function can only be called once during proxy deployment
     * @param _id The unique asset identifier this issuer will manage
     * @param _registry Address of the STBL protocol registry contract
     * @custom:security Only the deployer receives initial admin and upgrader roles
     */
    function initialize(uint256 _id, address _registry) public initializer {
        __UUPSUpgradeable_init();

        registry = iSTBL_Register(_registry);
        assetID = _id;
    }

    /**
     * @notice Authorizes contract upgrades to new implementation addresses
     * @dev Implements UUPS upgrade authorization pattern with role-based access control
     * @dev Automatically increments version number on successful upgrades
     * @param newImplementation Address of the new contract implementation to upgrade to
     * @custom:security Requires UPGRADER_ROLE which is managed by the protocol registry
     */
    function _authorizeUpgrade(address newImplementation) internal override {
        if (!registry.hasRole(UPGRADER_ROLE, _msgSender()))
            revert STBL_UnauthorizedCaller();
        _version = _version + 1;
        emit ContractUpgraded(newImplementation);
    }

    /**
     * @notice Returns the current contract implementation version
     * @dev Useful for tracking which version of the contract is currently deployed
     * @return The version number, incremented with each upgrade
     */
    function version() external view returns (uint256) {
        return _version;
    }

    /**
     * @notice Deposits real-world assets and mints a yield-bearing NFT to the caller
     * @dev Wrapper function that calls iDeposit with the message sender as the recipient
     * @param assetValue Amount of assets to deposit, specified in the asset's native decimal precision
     * @return nftID The unique identifier of the minted NFT that represents ownership of the deposited assets
     */
    function deposit(uint256 assetValue) external returns (uint256) {
        return iDeposit(assetValue, _msgSender());
    }

    /**
     * @notice Deposits real-world assets and mints a yield-bearing NFT to a specified sender
     * @dev Wrapper function that calls iDeposit with a custom sender address
     * @param assetValue Amount of assets to deposit, specified in the asset's native decimal precision
     * @param _sender The address that will receive the ownership NFT
     * @return nftID The unique identifier of the minted NFT that represents ownership of the deposited assets
     */
    function deposit(
        uint256 assetValue,
        address _sender
    ) external returns (uint256) {
        return iDeposit(assetValue, _sender);
    }

    /**
     * @notice Withdraws deposited assets by burning the caller's yield-bearing NFT
     * @dev Wrapper function that calls iWithdraw with the message sender as the owner
     * @param _tokenID The unique identifier of the NFT to burn in exchange for withdrawing the underlying assets
     */
    function withdraw(uint256 _tokenID) external {
        iWithdraw(_tokenID, _msgSender());
    }

    /**
     * @notice Withdraws deposited assets by burning a specified sender's yield-bearing NFT
     * @dev Wrapper function that calls iWithdraw with a custom sender address
     * @param _tokenID The unique identifier of the NFT to burn in exchange for withdrawing the underlying assets
     * @param _sender The address of the account withdrawing assets
     */
    function withdraw(uint256 _tokenID, address _sender) external {
        iWithdraw(_tokenID, _sender);
    }

    /**
     * @notice Deposits real-world assets and mints a yield-bearing NFT representing ownership
     * @dev Orchestrates the full deposit flow: validation, metadata generation, vault deposit, NFT minting, and staking setup
     * @dev The deposited assets are transferred to the asset vault and an NFT is minted to represent ownership and yield rights
     * @param assetValue Amount of assets to deposit, specified in the asset's native decimal precision
     * @param sender The address of the account depositing assets and receiving the ownership NFT
     * @return nftID The unique identifier of the minted NFT that represents ownership of the deposited assets
     * @custom:requirements
     * - Asset must be properly initialized and active in the registry
     * - Deposit amount must be greater than zero
     * - Caller must have sufficient asset token balance
     * - Caller must have approved this contract to transfer the specified amount
     * @custom:effects
     * - Transfers asset tokens from caller to the protocol vault
     * - Mints an NFT to the caller representing ownership and yield rights
     * - Enables staking for the NFT in the yield distribution system
     * - Records deposit metadata including fees, timestamps, and valuations
     * @custom:emits depositAsset Event containing caller address, NFT ID, and complete metadata
     */
    function iDeposit(
        uint256 assetValue,
        address sender
    ) internal isSetupDone returns (uint256) {
        if (assetValue == 0)
            revert STBL_Asset_InvalidDepositAmount(assetID, assetValue);
        AssetDefinition memory AssetData = registry.fetchAssetData(assetID);

        YLD_Metadata memory MetaData = generateMetaData(assetValue);

        iSTBL_PT1_AssetVault(AssetData.vault).depositERC20(sender, MetaData);

        uint256 nftID = iSTBL_Core(registry.fetchCore()).put(sender, MetaData);

        iSTBL_PT1_AssetYieldDistributor(AssetData.rewardDistributor)
            .enableStaking(
                nftID,
                MetaData.stableValueNet + MetaData.haircutAmount
            );

        emit depositAsset(sender, nftID, MetaData);

        return nftID;
    }

    /**
     * @notice Withdraws deposited assets by burning the corresponding yield-bearing NFT
     * @dev Handles the complete withdrawal process: validation, reward claiming, asset transfer, staking cleanup, and NFT burning
     * @dev Claims any accumulated yield rewards before transferring the original deposited assets back to the user
     * @param _tokenID The unique identifier of the NFT to burn in exchange for withdrawing the underlying assets
     * @param _sender The address of the account withdrawing assets and receiving the ownership NFT
     * @custom:requirements
     * - Asset must be properly initialized and active in the registry
     * - Caller must be the current owner of the specified NFT
     * - NFT must belong to this specific asset type
     * - NFT must not be marked as disabled in the system
     * - The minimum lock duration must have elapsed since the original deposit
     * @custom:effects
     * - Claims any pending yield rewards for the NFT holder
     * - Transfers the underlying assets from vault back to the caller
     * - Disables staking for the NFT in the yield distribution system
     * - Burns the NFT, removing it from circulation permanently
     * @custom:reverts STBL_Asset_InvalidAsset if NFT doesn't belong to this asset or caller is not the owner
     * @custom:reverts STBL_YLDDisabled if the NFT has been marked as disabled by the protocol
     * @custom:reverts STBL_Asset_WithdrawDurationNotReached if attempting withdrawal before the minimum lock period expires
     * @custom:emits withdrawAsset Event containing caller address, NFT ID, and metadata at time of withdrawal
     */
    function iWithdraw(uint256 _tokenID, address _sender) internal isSetupDone {
        AssetDefinition memory AssetData = registry.fetchAssetData(assetID);

        YLD_Metadata memory MetaData = iSTBL_YLD(registry.fetchYLDToken())
            .getNFTData(_tokenID);

        /** Check for Valid Asset ID */
        if (MetaData.assetID != assetID)
            revert STBL_Asset_InvalidAsset(MetaData.assetID);

        /** Check for Owner of NFT */
        if (iSTBL_YLD(registry.fetchYLDToken()).ownerOf(_tokenID) != _sender)
            revert STBL_Asset_IncorrectOwner(_tokenID, _sender);

        /** Check if NFT is disabled */
        if (MetaData.isDisabled) revert STBL_YLDDisabled(_tokenID);

        /** Checks withdraw should happen post duration has passed */
        if (
            (MetaData.depositTimestamp + MetaData.Fees.yieldDuration) >
            block.timestamp
        ) revert STBL_Asset_WithdrawDurationNotReached(assetID, _tokenID);

        iSTBL_PT1_AssetYieldDistributor(AssetData.rewardDistributor).claim(
            _tokenID
        );

        iSTBL_PT1_AssetVault(AssetData.vault).withdrawERC20(_sender, MetaData);

        iSTBL_PT1_AssetYieldDistributor(AssetData.rewardDistributor)
            .disableStaking(
                _tokenID,
                MetaData.stableValueNet + MetaData.haircutAmount
            );

        iSTBL_Core(registry.fetchCore()).exit(
            assetID,
            _sender,
            _tokenID,
            MetaData.stableValueNet
        );

        emit withdrawAsset(_sender, _tokenID, MetaData);
    }

    /**
     * @notice Generates comprehensive metadata for a new asset deposit including fee calculations and valuations
     * @dev Creates a complete YLD_Metadata structure capturing all deposit parameters, fee snapshots, and USD valuations at deposit time
     * @dev This metadata is permanently stored with the NFT and used throughout the asset's lifecycle for calculations and withdrawals
     * @param assetValue The amount of assets being deposited, specified in the asset's native decimal precision
     * @return MetaData A fully populated YLD_Metadata structure containing:
     *   - Asset identification and deposit timestamp
     *   - Normalized asset value in 18-decimal format
     *   - Snapshot of all fee parameters at deposit time
     *   - USD gross valuation from oracle pricing
     *   - Calculated fee amounts in both asset and USD terms
     *   - Net USD value after all fee deductions
     * @custom:calculations
     * - Normalizes asset value from native decimals to standardized 18-decimal format
     * - Queries asset oracle for current USD pricing information
     * - Calculates deposit fees, withdrawal fees, haircut amounts, and insurance fees
     * - Computes final net stable value that determines yield generation basis
     */
    function generateMetaData(
        uint256 assetValue
    ) internal view returns (YLD_Metadata memory MetaData) {
        AssetDefinition memory AssetData = registry.fetchAssetData(assetID);

        MetaData.assetID = assetID;
        MetaData.assetValue = assetValue.normalizeToDecimals18(
            DecimalConverter.getTokenDecimals(AssetData.token)
        );
        MetaData.depositTimestamp = block.timestamp;
        MetaData.isDisabled = false;

        /** Snapshot of values */
        MetaData.Fees.depositFee = AssetData.depositFees;
        MetaData.Fees.withdrawFee = AssetData.withdrawFees;
        MetaData.Fees.hairCut = AssetData.cut;
        MetaData.Fees.insuranceFee = AssetData.insuranceFees;
        MetaData.Fees.duration = AssetData.duration;
        MetaData.Fees.yieldDuration = AssetData.yieldDuration;

        /** Determine USD Gross Value */
        MetaData.stableValueGross = iSTBL_PT1_AssetOracle(AssetData.oracle)
            .fetchForwardPrice(MetaData.assetValue);

        /** Fees Priced in Stable Value */
        MetaData = MetaData.calculateDepositFees();

        MetaData.haircutAmountAssetValue = iSTBL_PT1_AssetOracle(
            AssetData.oracle
        ).fetchInversePrice(MetaData.haircutAmount);

        /** Determine USD Net Value (USP Minted) */
        MetaData.stableValueNet = (MetaData.stableValueGross -
            (MetaData.depositfeeAmount +
                MetaData.haircutAmount +
                MetaData.insurancefeeAmount));

        return MetaData;
    }

    /**
     * @notice Retrieves the trusted forwarder address for ERC2771 meta-transaction support
     * @dev Delegates to the registry to get the current trusted forwarder configuration
     * @dev The trusted forwarder enables gasless transactions by allowing approved relayers to submit transactions on behalf of users
     * @return The address of the currently configured trusted forwarder contract
     */
    function trustedForwarder() public view virtual override returns (address) {
        return registry.trustedForwarder();
    }

    /**
     * @notice Retrieves the asset ID managed by this vault instance
     * @dev Returns the unique identifier for the asset type this vault handles
     * @return The asset ID associated with this vault
     */
    function fetchAssetID() external view returns (uint256) {
        return assetID;
    }

    /**
     * @notice Retrieves the protocol registry contract address
     * @dev Returns the registry contract that provides system configuration and access control
     * @return The address of the protocol registry contract
     */
    function fetchRegistry() external view returns (address) {
        return address(registry);
    }

    /**
     * @notice Resolves message sender in the context of potential meta-transactions
     * @dev Overrides both Context and ERC2771Context to handle inheritance conflicts
     * @dev Returns the actual transaction originator when using meta-transactions via trusted forwarder
     * @return The address of the actual message sender, accounting for meta-transaction forwarding
     */
    function _msgSender()
        internal
        view
        override(ERC2771ContextUpgradeable)
        returns (address)
    {
        return ERC2771ContextUpgradeable._msgSender();
    }

    /**
     * @notice Resolves message data in the context of potential meta-transactions
     * @dev Overrides both Context and ERC2771Context to handle inheritance conflicts
     * @dev Returns the actual transaction calldata when using meta-transactions via trusted forwarder
     * @return The actual transaction calldata, accounting for meta-transaction forwarding
     */
    function _msgData()
        internal
        view
        override(ERC2771ContextUpgradeable)
        returns (bytes calldata)
    {
        return ERC2771ContextUpgradeable._msgData();
    }

    /**
     * @notice Returns the context suffix length for ERC2771 meta-transaction support
     * @dev Overrides both Context and ERC2771Context to handle inheritance conflicts
     * @dev Used internally by ERC2771Context to properly decode meta-transaction data
     * @return The length of the context suffix appended to meta-transaction calldata
     */
    function _contextSuffixLength()
        internal
        view
        override(ERC2771ContextUpgradeable)
        returns (uint256)
    {
        return ERC2771ContextUpgradeable._contextSuffixLength();
    }
}
"
    },
    "node_modules/@openzeppelin/contracts-upgradeable/metatx/ERC2771ContextUpgradeable.sol": {
      "content": "// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.4.0) (metatx/ERC2771Context.sol)

pragma solidity ^0.8.20;

import {ContextUpgradeable} from "../utils/ContextUpgradeable.sol";
import {Initializable} from "../proxy/utils/Initializable.sol";

/**
 * @dev Context variant with ERC-2771 support.
 *
 * WARNING: Avoid using this pattern in contracts that rely in a specific calldata length as they'll
 * be affected by any forwarder whose `msg.data` is suffixed with the `from` address according to the ERC-2771
 * specification adding the address size in bytes (20) to the calldata size. An example of an unexpected
 * behavior could be an unintended fallback (or another function) invocation while trying to invoke the `receive`
 * function only accessible if `msg.data.length == 0`.
 *
 * WARNING: The usage of `delegatecall` in this contract is dangerous and may result in context corruption.
 * Any forwarded request to this contract triggering a `delegatecall` to itself will result in an invalid {_msgSender}
 * recovery.
 */
abstract contract ERC2771ContextUpgradeable is Initializable, ContextUpgradeable {
    /// @custom:oz-upgrades-unsafe-allow state-variable-immutable
    address private immutable _trustedForwarder;

    /**
     * @dev Initializes the contract with a trusted forwarder, which will be able to
     * invoke functions on this contract on behalf of other accounts.
     *
     * NOTE: The trusted forwarder can be replaced by overriding {trustedForwarder}.
     */
    /// @custom:oz-upgrades-unsafe-allow constructor
    constructor(address trustedForwarder_) {
        _trustedForwarder = trustedForwarder_;
    }

    /**
     * @dev Returns the address of the trusted forwarder.
     */
    function trustedForwarder() public view virtual returns (address) {
        return _trustedForwarder;
    }

    /**
     * @dev Indicates whether any particular address is the trusted forwarder.
     */
    function isTrustedForwarder(address forwarder) public view virtual returns (bool) {
        return forwarder == trustedForwarder();
    }

    /**
     * @dev Override for `msg.sender`. Defaults to the original `msg.sender` whenever
     * a call is not performed by the trusted forwarder or the calldata length is less than
     * 20 bytes (an address length).
     */
    function _msgSender() internal view virtual override returns (address) {
        uint256 calldataLength = msg.data.length;
        uint256 contextSuffixLength = _contextSuffixLength();
        if (calldataLength >= contextSuffixLength && isTrustedForwarder(msg.sender)) {
            unchecked {
                return address(bytes20(msg.data[calldataLength - contextSuffixLength:]));
            }
        } else {
            return super._msgSender();
        }
    }

    /**
     * @dev Override for `msg.data`. Defaults to the original `msg.data` whenever
     * a call is not performed by the trusted forwarder or the calldata length is less than
     * 20 bytes (an address length).
     */
    function _msgData() internal view virtual override returns (bytes calldata) {
        uint256 calldataLength = msg.data.length;
        uint256 contextSuffixLength = _contextSuffixLength();
        if (calldataLength >= contextSuffixLength && isTrustedForwarder(msg.sender)) {
            unchecked {
                return msg.data[:calldataLength - contextSuffixLength];
            }
        } else {
            return super._msgData();
        }
    }

    /**
     * @dev ERC-2771 specifies the context as being a single address (20 bytes).
     */
    function _contextSuffixLength() internal view virtual override returns (uint256) {
        return 20;
    }
}
"
    },
    "node_modules/@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol": {
      "content": "// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.3.0) (proxy/utils/Initializable.sol)

pragma solidity ^0.8.20;

/**
 * @dev This is a base contract to aid in writing upgradeable contracts, or any kind of contract that will be deployed
 * behind a proxy. Since proxied contracts do not make use of a constructor, it's common to move constructor logic to an
 * external initializer function, usually called `initialize`. It then becomes necessary to protect this initializer
 * function so it can only be called once. The {initializer} modifier provided by this contract will have this effect.
 *
 * The initialization functions use a version number. Once a version number is used, it is consumed and cannot be
 * reused. This mechanism prevents re-execution of each "step" but allows the creation of new initialization steps in
 * case an upgrade adds a module that needs to be initialized.
 *
 * For example:
 *
 * [.hljs-theme-light.nopadding]
 * ```solidity
 * contract MyToken is ERC20Upgradeable {
 *     function initialize() initializer public {
 *         __ERC20_init("MyToken", "MTK");
 *     }
 * }
 *
 * contract MyTokenV2 is MyToken, ERC20PermitUpgradeable {
 *     function initializeV2() reinitializer(2) public {
 *         __ERC20Permit_init("MyToken");
 *     }
 * }
 * ```
 *
 * TIP: To avoid leaving the proxy in an uninitialized state, the initializer function should be called as early as
 * possible by providing the encoded function call as the `_data` argument to {ERC1967Proxy-constructor}.
 *
 * CAUTION: When used with inheritance, manual care must be taken to not invoke a parent initializer twice, or to ensure
 * that all initializers are idempotent. This is not verified automatically as constructors are by Solidity.
 *
 * [CAUTION]
 * ====
 * Avoid leaving a contract uninitialized.
 *
 * An uninitialized contract can be taken over by an attacker. This applies to both a proxy and its implementation
 * contract, which may impact the proxy. To prevent the implementation contract from being used, you should invoke
 * the {_disableInitializers} function in the constructor to automatically lock it when it is deployed:
 *
 * [.hljs-theme-light.nopadding]
 * ```
 * /// @custom:oz-upgrades-unsafe-allow constructor
 * constructor() {
 *     _disableInitializers();
 * }
 * ```
 * ====
 */
abstract contract Initializable {
    /**
     * @dev Storage of the initializable contract.
     *
     * It's implemented on a custom ERC-7201 namespace to reduce the risk of storage collisions
     * when using with upgradeable contracts.
     *
     * @custom:storage-location erc7201:openzeppelin.storage.Initializable
     */
    struct InitializableStorage {
        /**
         * @dev Indicates that the contract has been initialized.
         */
        uint64 _initialized;
        /**
         * @dev Indicates that the contract is in the process of being initialized.
         */
        bool _initializing;
    }

    // keccak256(abi.encode(uint256(keccak256("openzeppelin.storage.Initializable")) - 1)) & ~bytes32(uint256(0xff))
    bytes32 private constant INITIALIZABLE_STORAGE = 0xf0c57e16840df040f15088dc2f81fe391c3923bec73e23a9662efc9c229c6a00;

    /**
     * @dev The contract is already initialized.
     */
    error InvalidInitialization();

    /**
     * @dev The contract is not initializing.
     */
    error NotInitializing();

    /**
     * @dev Triggered when the contract has been initialized or reinitialized.
     */
    event Initialized(uint64 version);

    /**
     * @dev A modifier that defines a protected initializer function that can be invoked at most once. In its scope,
     * `onlyInitializing` functions can be used to initialize parent contracts.
     *
     * Similar to `reinitializer(1)`, except that in the context of a constructor an `initializer` may be invoked any
     * number of times. This behavior in the constructor can be useful during testing and is not expected to be used in
     * production.
     *
     * Emits an {Initialized} event.
     */
    modifier initializer() {
        // solhint-disable-next-line var-name-mixedcase
        InitializableStorage storage $ = _getInitializableStorage();

        // Cache values to avoid duplicated sloads
        bool isTopLevelCall = !$._initializing;
        uint64 initialized = $._initialized;

        // Allowed calls:
        // - initialSetup: the contract is not in the initializing state and no previous version was
        //                 initialized
        // - construction: the contract is initialized at version 1 (no reinitialization) and the
        //                 current contract is just being deployed
        bool initialSetup = initialized == 0 && isTopLevelCall;
        bool construction = initialized == 1 && address(this).code.length == 0;

        if (!initialSetup && !construction) {
            revert InvalidInitialization();
        }
        $._initialized = 1;
        if (isTopLevelCall) {
            $._initializing = true;
        }
        _;
        if (isTopLevelCall) {
            $._initializing = false;
            emit Initialized(1);
        }
    }

    /**
     * @dev A modifier that defines a protected reinitializer function that can be invoked at most once, and only if the
     * contract hasn't been initialized to a greater version before. In its scope, `onlyInitializing` functions can be
     * used to initialize parent contracts.
     *
     * A reinitializer may be used after the original initialization step. This is essential to configure modules that
     * are added through upgrades and that require initialization.
     *
     * When `version` is 1, this modifier is similar to `initializer`, except that functions marked with `reinitializer`
     * cannot be nested. If one is invoked in the context of another, execution will revert.
     *
     * Note that versions can jump in increments greater than 1; this implies that if multiple reinitializers coexist in
     * a contract, executing them in the right order is up to the developer or operator.
     *
     * WARNING: Setting the version to 2**64 - 1 will prevent any future reinitialization.
     *
     * Emits an {Initialized} event.
     */
    modifier reinitializer(uint64 version) {
        // solhint-disable-next-line var-name-mixedcase
        InitializableStorage storage $ = _getInitializableStorage();

        if ($._initializing || $._initialized >= version) {
            revert InvalidInitialization();
        }
        $._initialized = version;
        $._initializing = true;
        _;
        $._initializing = false;
        emit Initialized(version);
    }

    /**
     * @dev Modifier to protect an initialization function so that it can only be invoked by functions with the
     * {initializer} and {reinitializer} modifiers, directly or indirectly.
     */
    modifier onlyInitializing() {
        _checkInitializing();
        _;
    }

    /**
     * @dev Reverts if the contract is not in an initializing state. See {onlyInitializing}.
     */
    function _checkInitializing() internal view virtual {
        if (!_isInitializing()) {
            revert NotInitializing();
        }
    }

    /**
     * @dev Locks the contract, preventing any future reinitialization. This cannot be part of an initializer call.
     * Calling this in the constructor of a contract will prevent that contract from being initialized or reinitialized
     * to any version. It is recommended to use this to lock implementation contracts that are designed to be called
     * through proxies.
     *
     * Emits an {Initialized} event the first time it is successfully executed.
     */
    function _disableInitializers() internal virtual {
        // solhint-disable-next-line var-name-mixedcase
        InitializableStorage storage $ = _getInitializableStorage();

        if ($._initializing) {
            revert InvalidInitialization();
        }
        if ($._initialized != type(uint64).max) {
            $._initialized = type(uint64).max;
            emit Initialized(type(uint64).max);
        }
    }

    /**
     * @dev Returns the highest version that has been initialized. See {reinitializer}.
     */
    function _getInitializedVersion() internal view returns (uint64) {
        return _getInitializableStorage()._initialized;
    }

    /**
     * @dev Returns `true` if the contract is currently initializing. See {onlyInitializing}.
     */
    function _isInitializing() internal view returns (bool) {
        return _getInitializableStorage()._initializing;
    }

    /**
     * @dev Pointer to storage slot. Allows integrators to override it with a custom storage location.
     *
     * NOTE: Consider following the ERC-7201 formula to derive storage locations.
     */
    function _initializableStorageSlot() internal pure virtual returns (bytes32) {
        return INITIALIZABLE_STORAGE;
    }

    /**
     * @dev Returns a pointer to the storage namespace.
     */
    // solhint-disable-next-line var-name-mixedcase
    function _getInitializableStorage() private pure returns (InitializableStorage storage $) {
        bytes32 slot = _initializableStorageSlot();
        assembly {
            $.slot := slot
        }
    }
}
"
    },
    "node_modules/@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol": {
      "content": "// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.3.0) (proxy/utils/UUPSUpgradeable.sol)

pragma solidity ^0.8.22;

import {IERC1822Proxiable} from "@openzeppelin/contracts/interfaces/draft-IERC1822.sol";
import {ERC1967Utils} from "@openzeppelin/contracts/proxy/ERC1967/ERC1967Utils.sol";
import {Initializable} from "./Initializable.sol";

/**
 * @dev An upgradeability mechanism designed for UUPS proxies. The functions included here can perform an upgrade of an
 * {ERC1967Proxy}, when this contract is set as the implementation behind such a proxy.
 *
 * A security mechanism ensures that an upgrade does not turn off upgradeability accidentally, although this risk is
 * reinstated if the upgrade retains upgradeability but removes the security mechanism, e.g. by replacing
 * `UUPSUpgradeable` with a custom implementation of upgrades.
 *
 * The {_authorizeUpgrade} function must be overridden to include access restriction to the upgrade mechanism.
 */
abstract contract UUPSUpgradeable is Initializable, IERC1822Proxiable {
    /// @custom:oz-upgrades-unsafe-allow state-variable-immutable
    address private immutable __self = address(this);

    /**
     * @dev The version of the upgrade interface of the contract. If this getter is missing, both `upgradeTo(address)`
     * and `upgradeToAndCall(address,bytes)` are present, and `upgradeTo` must be used if no function should be called,
     * while `upgradeToAndCall` will invoke the `receive` function if the second argument is the empty byte string.
     * If the getter returns `"5.0.0"`, only `upgradeToAndCall(address,bytes)` is present, and the second argument must
     * be the empty byte string if no function should be called, making it impossible to invoke the `receive` function
     * during an upgrade.
     */
    string public constant UPGRADE_INTERFACE_VERSION = "5.0.0";

    /**
     * @dev The call is from an unauthorized context.
     */
    error UUPSUnauthorizedCallContext();

    /**
     * @dev The storage `slot` is unsupported as a UUID.
     */
    error UUPSUnsupportedProxiableUUID(bytes32 slot);

    /**
     * @dev Check that the execution is being performed through a delegatecall call and that the execution context is
     * a proxy contract with an implementation (as defined in ERC-1967) pointing to self. This should only be the case
     * for UUPS and transparent proxies that are using the current contract as their implementation. Execution of a
     * function through ERC-1167 minimal proxies (clones) would not normally pass this test, but is not guaranteed to
     * fail.
     */
    modifier onlyProxy() {
        _checkProxy();
        _;
    }

    /**
     * @dev Check that the execution is not being performed through a delegate call. This allows a function to be
     * callable on the implementing contract but not through proxies.
     */
    modifier notDelegated() {
        _checkNotDelegated();
        _;
    }

    function __UUPSUpgradeable_init() internal onlyInitializing {
    }

    function __UUPSUpgradeable_init_unchained() internal onlyInitializing {
    }
    /**
     * @dev Implementation of the ERC-1822 {proxiableUUID} function. This returns the storage slot used by the
     * implementation. It is used to validate the implementation's compatibility when performing an upgrade.
     *
     * IMPORTANT: A proxy pointing at a proxiable contract should not be considered proxiable itself, because this risks
     * bricking a proxy that upgrades to it, by delegating to itself until out of gas. Thus it is critical that this
     * function revert if invoked through a proxy. This is guaranteed by the `notDelegated` modifier.
     */
    function proxiableUUID() external view virtual notDelegated returns (bytes32) {
        return ERC1967Utils.IMPLEMENTATION_SLOT;
    }

    /**
     * @dev Upgrade the implementation of the proxy to `newImplementation`, and subsequently execute the function call
     * encoded in `data`.
     *
     * Calls {_authorizeUpgrade}.
     *
     * Emits an {Upgraded} event.
     *
     * @custom:oz-upgrades-unsafe-allow-reachable delegatecall
     */
    function upgradeToAndCall(address newImplementation, bytes memory data) public payable virtual onlyProxy {
        _authorizeUpgrade(newImplementation);
        _upgradeToAndCallUUPS(newImplementation, data);
    }

    /**
     * @dev Reverts if the execution is not performed via delegatecall or the execution
     * context is not of a proxy with an ERC-1967 compliant implementation pointing to self.
     */
    function _checkProxy() internal view virtual {
        if (
            address(this) == __self || // Must be called through delegatecall
            ERC1967Utils.getImplementation() != __self // Must be called through an active proxy
        ) {
            revert UUPSUnauthorizedCallContext();
        }
    }

    /**
     * @dev Reverts if the execution is performed via delegatecall.
     * See {notDelegated}.
     */
    function _checkNotDelegated() internal view virtual {
        if (address(this) != __self) {
            // Must not be called through delegatecall
            revert UUPSUnauthorizedCallContext();
        }
    }

    /**
     * @dev Function that should revert when `msg.sender` is not authorized to upgrade the contract. Called by
     * {upgradeToAndCall}.
     *
     * Normally, this function will use an xref:access.adoc[access control] modifier such as {Ownable-onlyOwner}.
     *
     * ```solidity
     * function _authorizeUpgrade(address) internal onlyOwner {}
     * ```
     */
    function _authorizeUpgrade(address newImplementation) internal virtual;

    /**
     * @dev Performs an implementation upgrade with a security check for UUPS proxies, and additional setup call.
     *
     * As a security check, {proxiableUUID} is invoked in the new implementation, and the return value
     * is expected to be the implementation slot in ERC-1967.
     *
     * Emits an {IERC1967-Upgraded} event.
     */
    function _upgradeToAndCallUUPS(address newImplementation, bytes memory data) private {
        try IERC1822Proxiable(newImplementation).proxiableUUID() returns (bytes32 slot) {
            if (slot != ERC1967Utils.IMPLEMENTATION_SLOT) {
                revert UUPSUnsupportedProxiableUUID(slot);
            }
            ERC1967Utils.upgradeToAndCall(newImplementation, data);
        } catch {
            // The implementation is not UUPS
            revert ERC1967Utils.ERC1967InvalidImplementation(newImplementation);
        }
    }
}
"
    },
    "node_modules/@openzeppelin/contracts/token/ERC20/IERC20.sol": {
      "content": "// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.4.0) (token/ERC20/IERC20.sol)

pragma solidity >=0.4.16;

/**
 * @dev Interface of the ERC-20 standard as defined in the ERC.
 */
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);
}
"
    },
    "contracts/interfaces/ISTBL_Register.sol": {
      "content": "// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@openzeppelin/contracts/access/IAccessControl.sol";
import "../lib/STBL_Structs.sol";

/** @title STBL Register Interface
 * @notice Interface for managing asset registrations and configurations in the STBL protocol
 * @dev Inherits from OpenZeppelin's IAccessControl for role-based access control
 */
interface iSTBL_Register is IAccessControl {
    /** @notice Emitted when the Core contract address is updated
     * @param _Core The new Core contract address
     */
    event CoreUpdateEvent(address _Core);

    /** @notice Emitted when the treasury address is updated
     * @param _treasury The new treasury address
     */
    event TreasuryUpdateEvent(address _treasury);

    /** @notice Emitted when a new asset is added to the registry
     * @param _id The ID of the added asset
     * @param _Assetdata The asset definition data
     */
    event AddAssetEvent(uint256 indexed _id, AssetDefinition _Assetdata);

    /** @notice Emitted when an asset is setup with contract addresses and configuration
     * @param _id The ID of the setup asset
     * @param _Assetdata The complete asset definition containing all configuration parameters including
     * contract addresses, fee structures, limits, and durations
     */
    event SetupAssetEvent(uint256 indexed _id, AssetDefinition _Assetdata);

    /** @notice Emitted when an asset's cut percentage is updated
     * @param _id The ID of the asset
     * @param _cut The new cut percentage value
     */
    event CutUpdateEvent(uint256 indexed _id, uint256 _cut);

    /** @notice Emitted when an asset's limit is updated
     * @param _id The ID of the asset
     * @param _limit The new limit value
     */
    event LimitUpdateEvent(uint256 indexed _id, uint256 _limit);

    /** @notice Emitted when an asset's fees are updated
     * @param _id The ID of the asset
     * @param _depositFee The new deposit fee value in basis points
     * @param _withdrawFee The new withdrawal fee value in basis points
     * @param _insuranceFee The new insurance fee value in basis points
     * @param _yieldFees The new yield fee value in basis points
     */
    event FeeUpdateEvent(
        uint256 indexed _id,
        uint256 _depositFee,
        uint256 _withdrawFee,
        uint256 _insuranceFee,
        uint256 _yieldFees
    );

    /** @notice Emitted when an asset's duration parameters are updated
     * @param _id The ID of the asset
     * @param _duration The new main duration value in seconds
     * @param _yieldDuration The new yield duration value in seconds
     */
    event durationUpdateEvent(
        uint256 indexed _id,
        uint256 _duration,
        uint256 _yieldDuration
    );

    /** @notice Emitted when an additional buffer for an asset is updated
     * @param _id The ID of the asset
     * @param _data Additional buffer data stored as bytes
     */
    event AdditionalBufferUpdateEvent(uint256 indexed _id, bytes _data);

    /** @notice Emitted when an asset's oracle address is updated
     * @param _id The ID of the asset
     * @param _oracle The new oracle address for price feeds
     */
    event OracleUpdateEvent(uint256 indexed _id, address _oracle);

    /** @notice Emitted when an asset's state is updated
     * @param _id The ID of the asset
     * @param _state The new state of the asset (enum AssetStatus)
     */
    event AssetStateUpdateEvent(uint256 indexed _id, AssetStatus _state);

    /** @notice Event emitted when asset deposits are incremented
     * @param assetId The ID of the asset
     * @param amount The amount incremented
     */
    event AssetDepositIncrementEvent(uint256 indexed assetId, uint256 amount);

    /** @notice Event emitted when asset deposits are decremented
     * @param assetId The ID of the asset
     * @param amount The amount decremented
     */
    event AssetDepositDecrementEvent(uint256 indexed assetId, uint256 amount);

    /** @notice Event emitted when a trusted forwarder is updated
     * @param previousForwarder The address of the previous trusted forwarder
     * @param newForwarder The address of the new trusted forwarder
     * @dev Indicates a change in the trusted forwarder for meta-transactions
     */
    event TrustedForwarderUpdated(
        address indexed previousForwarder,
        address indexed newForwarder
    );

    /**
     * @notice Emitted when the contract implementation is upgraded
     * @dev Triggered during an upgrade of the contract to a new implementation
     * @param newImplementation Address of the new implementation contract
     */
    event ContractUpgraded(address newImplementation);

    /** @notice Sets the Core contract address
     * @dev Only callable by admin role
     * @param _Core The new Core contract address
     */
    function setCore(address _Core) external;

    /** @notice Sets the treasury address
     * @dev Only callable by admin role
     * @param _treasury The new treasury address
     */
    function setTreasury(address _treasury) external;

    /** @notice Adds a new asset to the registry
     * @dev Only callable by admin role
     * @param _name The name of the asset
     * @param _desc Description of the asset
     * @param _type Asset type identifier
     * @param _aggType Aggregation type flag
     * @return The asset ID of the newly added asset
     */
    function addAsset(
        string memory _name,
        string memory _desc,
        uint8 _type,
        bool _aggType
    ) external returns (uint256);

    /** @notice Sets up an asset with contract addresses and configuration parameters
     * @dev Only callable by admin role and allows setting all key parameters for an asset
     * @param _id The unique identifier of the asset to configure
     * @param _contractAddr The primary token contract address for the asset
     * @param _issuanceAddr Address responsible for issuing the asset tokens
     * @param _distAddr Address of the reward distribution contract
     * @param _vaultAddr Address of the asset's vault contract
     * @param _oracle Address of the price oracle for the asset
     * @param _cut Percentage cut applied to the asset's transactions
     * @param _limit Maximum value/cap for the asset
     * @param _depositFee Fee charged for depositing the asset (in basis points)
     * @param _withdrawFee Fee charged for withdrawing the asset (in basis points)
     * @param _yieldFee Fee applied to yield generation (in basis points)
     * @param _insuranceFee Insurance fee applied (in basis points)
     * @param _duration Main duration parameter for protocol operations (in seconds)
     * @param _yieldDuration Duration specifically for yield calculations (in seconds)
     * @param _additionalBytes Additional configuration data stored as bytes
     * @custom:error Pi_SetupAlreadyDone if the asset has already been set up
     * @custom:error Pi_InvalidAssetSetup if the asset ID is invalid
     * @custom:error Pi_InvalidFeePercentage if any fee exceeds 100% (10000 basis points)
     * @custom:event SetupAssetEvent emitted when the asset is successfully set up
     */
    function setupAsset(
        uint256 _id,
        address _contractAddr,
        address _issuanceAddr,
        address _distAddr,
        address _vaultAddr,
        address _oracle,
        uint256 _cut,
        uint256 _limit,
        uint256 _depositFee,
        uint256 _withdrawFee,
        uint256 _yieldFee,
        uint256 _insuranceFee,
        uint256 _duration,
        uint256 _yieldDuration,
        bytes memory _additionalBytes
    ) external;

    /** @notice Sets the cut percentage for an asset
     * @dev Only callable by admin role
     * @param _id The ID of the asset
     * @param _cut The new cut percentage
     */
    function setCut(uint256 _id, uint256 _cut) external;

    /** @notice Sets the limit for an asset
     * @dev Only callable by admin role
     * @param _id The ID of the asset
     * @param _limit The new limit value
     */
    function setLimit(uint256 _id, uint256 _limit) external;

    /** @notice Sets the fee structure for an asset
     * @dev Only callable by admin role, all fees are in basis points (10000 = 100%)
     * @param _id The ID of the asset
     * @param _depositFee The new deposit fee percentage in basis points
     * @param _withdrawFee The new withdrawal fee percentage in basis points
     * @param _yieldFee The new yield fee percentage in basis points
     * @param _insuranceFee The new insurance fee percentage in basis points
     * @custom:error Pi_InvalidFeePercentage if any fee exceeds 100% (10000 basis points)
     */
    function setFees(
        uint256 _id,
        uint256 _depositFee,
        uint256 _withdrawFee,
        uint256 _yieldFee,
        uint256 _insuranceFee
    ) external;

    /** @notice Sets the duration parameters for a specific asset
     * @dev Only callable by admin role
     * @param _id The ID of the asset to update durations for
     * @param _duration The main duration parameter for the asset's operations, measured in seconds
     * @param _yieldduration The duration parameter specifically for yield calculations, measured in seconds
     */
    function setDurations(
        uint256 _id,
        uint256 _duration,
        uint256 _yieldduration
    ) external;

    /** @notice Sets additional buffer data for an asset
     * @dev Only callable by admin role
     * @param _id The ID of the asset
     * @param _data Additional buffer data to store as bytes
     */
    function setAdditionalBuffer(uint256 _id, bytes memory _data) external;

    /** @notice Sets the oracle address for an asset
     * @dev Only callable by admin role
     * @param _id The ID of the asset
     * @param _oracle The new oracle address
     */
    function setOracle(uint256 _id, address _oracle) external;

    /** @notice Disables an asset in the registry
     * @dev Only callable by admin role
     * @param _id Asset ID to disable
     */
    function disableAsset(uint256 _id) external;

    /** @notice Enables a previously disabled asset
     * @dev Only callable by admin role
     * @param _id Asset ID to enable
     */
    function enableAsset(uint256 _id) external;

    /** @notice Increments the total deposits for a specific asset
     * @dev Only callable by admin or authorized contracts
     * @param _id The ID of the asset to increment deposits for
     * @param _amount The amount to increment deposits by
     */
    function incrementAssetDeposits(uint256 _id, uint256 _amount) external;

    /** @notice Decrements the total deposits for a specific asset
     * @dev Only callable by Core contract
     * @param _id The ID of the asset to decrement deposits for
     * @param _amount The amount to decrement deposits by
     */
    function decrementAssetDeposits(uint256 _id, uint256 _amount) external;

    /** @notice Updates the trusted forwarder address for meta-transactions
     * @dev Only callable by admin role, updates the address used for ERC2771 meta-transactions
     * @param _newForwarder The new trusted forwarder address to be used
     * @custom:event Emits TrustedForwarderUpdated with previous and new forwarder addresses
     */
    function updateTrustedForwarder(address _newForwarder) external;

    /** @notice Retrieves the complete data for a specific asset
     * @param _id Asset ID to query
     * @return The AssetDefinition struct containing all asset data
     */
    function fetchAssetData(
        uint256 _id
    ) external view returns (AssetDefinition memory);

    /** @notice Retrieves specific element of asset data based on flag
     * @dev Flag values: 0=name, 1=description, 2=contractType, 3=isAggregated, 4=isDisabled,
     *                   5=isSetup, 6=cut, 7=limit, 8=token, 9=issuer, 10=rewardDistributor, 11=vault
     * @param _id The ID of the asset to fetch from
     * @param _flag The flag indicating which element to fetch
     * @return The requested element value encoded as bytes
     */
    function fetchAssetElement(
        uint256 _id,
        uint8 _flag
    ) external view returns (bytes memory);

    /** @notice Fetches the USST-Pegged token contract address used in the system
     * @dev This represents the main stablecoin contract address
     * @return The contract address of the USD-Pegged token
     */
    function fetchUSSTToken() external view returns (address);

    /** @notice Fetches the USD-Interest token contract address used in the system
     * @dev This represents the interest-bearing stablecoin contract address
     * @return The contract address of the USD-Interest token
     */
    function fetchYLDToken() external view returns (address);

    /** @notice Retrieves the Core contract address
     * @return The address of the Core contract
     */
    function fetchCore() external view returns (address);

    /** @notice Retrieves the treasury address
     * @return The address of the treasury contract
     */
    function fetchTreasury() external view returns (address);

    /** @notice Retrieves the current counter value
     * @dev The counter tracks the total number of assets added to the registry
     * @return The current counter value
     */
    function fetchCounter() external view returns (uint256);

    /** @notice Retrieves the total deposit amount for a specific asset
     * @param _assetID The ID of the asset to query
     * @return The total amount deposited for the specified asset
     */
    function fetchDeposits(uint256 _assetID) external view returns (uint256);

    /** @notice Checks if adding a deposit amount would exceed the asset's deposit limit
     * @param _assetID The ID of the asset to check deposit limit for
     * @param _amount The amount proposed to be deposited
     * @return True if the deposit limit would be exceeded, false otherwise
     */
    function isDepositLimitReached(
        uint256 _assetID,
        uint256 _amount
    ) external view returns (bool);

    /** @notice Returns the address of the trusted forwarder for meta-transactions
     * @dev Used by ERC2771Context to validate meta-transaction relayers
     * @return The address of the current trusted forwarder
     */
    function trustedForwarder() external view returns (address);
}
"
    },
    "contracts/interfaces/ISTBL_Core.sol": {
      "content": "// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "../lib/STBL_Structs.sol";

/**
 * @title STBL Core Interface
 * @notice Interface for core functionality of the STBL Protocol
 * @dev Defines the main entry and exit points for assets in the protocol
 */
interface iSTBL_Core {
    /**
     * @notice Emitted when an asset is deposited into the protocol
     * @param _id The asset identifier
     * @param _to Address receiving the minted token
     * @param _metadata Metadata associated with the YLD token
     * @param _tokenID ID of the minted token
     */
    event putEvent(
        uint256 indexed _id,
        address indexed _to,
        YLD_Metadata _metadata,
        uint256 _tokenID
    );

    /**
     * @notice Emitted when an asset is withdrawn from the protocol
     * @param _id The asset identifier
     * @param _to Address receiving the withdrawn assets
     * @param _value The value of the withdrawn assets
     * @param _tokenID ID of the burned token
     */
    event exitEvent(
        uint256 indexed _id,
        address indexed _to,
        uint256 _value,
        uint256 _tokenID
    );

    /**
     * @notice Event emitted when a trusted forwarder is updated
     * @param previousForwarder The address of the previous trusted forwarder
     * @param newForwarder The address of the new trusted forwarder
     * @dev Indicates a change in the trusted forwarder for meta-transactions
     */
    event TrustedForwarderUpdated(
        address indexed previousForwarder,
        address indexed newForwarder
    );

    /**
     * @notice Emitted when the contract implementation is upgraded
     * @dev Triggered during an upgrade of the contract to a new implementation
     * @param newImplementation Address of the new implementation contract
     */
    event ContractUpgraded(address newImplementation);

    /**
     * @notice Method to update trusted forwarder
     * @param _newForwarder Address of the new trusted forwarder
     * @dev Only callable by admin
     */
    function updateTrustedForwarder(address _newForwarder) external;

    /**
     * @notice Issues X and Y tokens for a given asset
     * @dev Only callable by the asset issuer
     * @param _to Address to receive the tokens
     * @param _metadata Metadata associated with the YLD Token
     * @return nftID The ID of the minted Y token (NFT)
     */
    function put(
        address _to,
        YLD_Metadata memory _metadata
    ) external returns (uint256);

    /**
     * @notice Withdraws assets from the protocol
     * @param _assetID The identifier of the asset being withdrawn
     * @param _from Address that owns the token being burned
     * @param _tokenID ID of the token to burn
     * @param _value The amount of X tokens to burn during redemption
     */
    function exit(
        uint256 _assetID,
        address _from,
        uint256 _tokenID,
        uint256 _value
    ) external;

    /**
     * @notice Retrieves the USP token address
     * @return The address of the USP token contract
     */
    function fetchUSPToken() external view returns (address);

    /**
     * @notice Retrieves the USI token address
     * @return The address of the USI token contract
     */
    function fetchUSIToken() external view returns (address);

    /**
     * @notice Retrieves the registry address
     * @return The address of the registry contract
     */
    function fetchRegistry() external view returns (address);
}
"
    },
    "contracts/interfaces/ISTBL_YLD.sol": {
      "content": "// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@openzeppelin/contracts/access/IAccessControl.sol";
import "@openzeppelin/contracts/token/ERC721/IERC721.sol";

import "../lib/STBL_Structs.sol";

/**
 * @title iSTBL_YLD Interface
 * @notice Interface for the STBL YLD contract that manages yield-generating NFT tokens with lifecycle controls
 * @dev Extends IAccessControl and IERC721 to provide role-based permissions and standard NFT functionality
 * @author STBL Protocol Team
 */
interface iSTBL_YLD is IAccessControl, IERC721 {
    /**
     * @notice Emitted when the trusted forwarder address is updated
     * @param previousForwarder Address of the previous trusted forwarder
     * @param newForwarder Address of the new trusted forwarder
     * @dev Used for meta-transaction support and gasless transactions
     */
    event TrustedForwarderUpdated(
        address indexed previousForwarder,
        address indexed newForwarder
    );

    /**
     * @notice Emitted when an NFT is disabled
     * @param _id Token ID of the disabled NFT
     * @dev Disabled NFTs cannot be transferred or used until re-enabled
     */
    event NFTDisabled(uint256 indexed _id);

    /**
     * @notice Emitted when a disabled NFT is re-enabled
     * @param _id Token ID of the enabled NFT
     * @dev Re-enabled NFTs restore full functionality including transfers
     */
    event NFTEnabled(uint256 indexed _id);

    /**
     * @notice Emitted when a new NFT is minted
     * @param _addr Recipient address of the minted NFT
     * @param _id Token ID of the newly minted NFT
     * @param _nftMetadata Complete metadata structure for the NFT
     * @dev Contains all relevant data for the newly created yield-bearing token
     */
    event MintEvent(
        address indexed _addr,
        uint256 indexed _id,
        YLD_Metadata _nftMetadata
    );

    /**
     * @notice Emitted when an NFT is permanently burned
     * @param _from Address that previously owned the burned NFT
     * @param _id Token ID of the burned NFT
     * @dev Burning permanently removes the token from circulation
     */
    event BurnEvent(address indexed _from, uint256 indexed _id);

    /**
     * @notice Emitted when the contract implementation is upgraded
     * @dev Triggered during an upgrade of the contract to a new implementation
     * @param newImplementation Address of the new implementation contract
     */
    event ContractUpgraded(address newImplementation);

    /**
     * @notice Updates the base URI for token metadata
     * @dev Changes the base URI used for constructing token metadata URLs
     * @dev Only callable by addresses with DEFAULT_ADMIN_ROLE
     * @param _uri The new base URI to set for token metadata
     */
    function setBaseURI(string memory _uri) external;

    /**
     * @notice Pauses all contract functionality
     * @dev Only callable by PAUSER_ROLE. Prevents transfers, minting, and burning
     * @custom:security Emergency function to halt all operations
     */
    function pause() external;

    /**
     * @notice Resumes all contract functionality
     * @dev Only callable by PAUSER_ROLE. Restores normal operations after pause
     * @custom:security Should only be called after emergency conditions are resolved
     */
    function unpause() external;

    /**
     * @notice Retrieves complete metadata for a specific NFT
     * @param _tokenID Token ID to query metadata for
     * @return YLD_Metadata struct containing all token data
     * @dev Reverts with NonexistentToken if tokenID does not exist
     * @custom:view-function Pure read operation with no state changes
     */
    function getNFTData(
        uint256 _tokenID
    ) external view returns (YLD_Metadata memory);

    /**
     * @notice Creates a new NFT with specified metadata
     * @param _to Recipient address for the new NFT
     * @param _metadata Complete metadata structure for the NFT
     * @return Token ID of the newly minted NFT
     * @dev Only callable by MINTER_ROLE. Increments total supply
     * @custom:security Validates recipient address and metadata integrity
     */
    function mint(
        address _to,
        YLD_Metadata memory _metadata
    ) external returns (uint256);

    /**
     * @notice Permanently destroys an existing NFT
     * @param _from Current owner address of the NFT
     * @param _id Token ID to burn
     * @dev Only callable by BURNER_ROLE. Decrements total supply
     * @custom:security Validates ownership and token existence before burning
     */
    function burn(address _from, uint256 _id) external;

    /**
     * @notice Disables an N