From b9b8a7756896a9e8018fb66161690c22943199ad Mon Sep 17 00:00:00 2001 From: eagle Date: Thu, 16 Jan 2025 20:03:28 +0530 Subject: [PATCH] feat: add code comments to asset pool interface contract --- src/interfaces/IAssetPool.sol | 277 +++++++++++++++++++++++++++++++++- 1 file changed, 274 insertions(+), 3 deletions(-) diff --git a/src/interfaces/IAssetPool.sol b/src/interfaces/IAssetPool.sol index cd095e9..b794961 100644 --- a/src/interfaces/IAssetPool.sol +++ b/src/interfaces/IAssetPool.sol @@ -8,25 +8,110 @@ import {IXToken} from "./IXToken.sol"; import {ILPRegistry} from "./ILPRegistry.sol"; import {IAssetOracle} from "./IAssetOracle.sol"; +/** + * @title IAssetPool + * @notice Interface for the AssetPool contract which manages a decentralized pool of assets + * @dev Handles deposits, minting, redemptions, and LP rebalancing operations + */ interface IAssetPool { + /** + * @notice Enum representing the current state of the pool's operational cycle + * @param ACTIVE Normal operation state where users can deposit and withdraw + * @param REBALANCING State during which LPs adjust their reserve positions + */ enum CycleState { - ACTIVE, // Normal operation - REBALANCING // LPs rebalancing reserves + ACTIVE, + REBALANCING } // -------------------------------------------------------------------------------- // EVENTS // -------------------------------------------------------------------------------- + + /** + * @notice Emitted when a user requests to deposit reserve tokens + * @param user Address of the user making the deposit + * @param amount Amount of reserve tokens being deposited + * @param cycleIndex Current operational cycle index + */ event DepositRequested(address indexed user, uint256 amount, uint256 indexed cycleIndex); + + /** + * @notice Emitted when a user cancels their deposit request + * @param user Address of the user canceling the deposit + * @param amount Amount of reserve tokens being returned + * @param cycleIndex Current operational cycle index + */ event DepositCancelled(address indexed user, uint256 amount, uint256 indexed cycleIndex); + + /** + * @notice Emitted when a user claims their minted asset tokens + * @param user Address of the user claiming assets + * @param amount Amount of asset tokens claimed + * @param cycleIndex Cycle index when the claim was processed + */ event AssetClaimed(address indexed user, uint256 amount, uint256 indexed cycleIndex); + + /** + * @notice Emitted when a user requests to burn their asset tokens + * @param user Address of the user requesting the burn + * @param xTokenAmount Amount of asset tokens to be burned + * @param cycleIndex Current operational cycle index + */ event BurnRequested(address indexed user, uint256 xTokenAmount, uint256 indexed cycleIndex); + + /** + * @notice Emitted when a user cancels their burn request + * @param user Address of the user canceling the burn + * @param amount Amount of asset tokens being returned + * @param cycleIndex Current operational cycle index + */ event BurnCancelled(address indexed user, uint256 amount, uint256 indexed cycleIndex); + + /** + * @notice Emitted when a user withdraws reserve tokens after burning + * @param user Address of the user withdrawing reserves + * @param amount Amount of reserve tokens withdrawn + * @param cycleIndex Cycle index when the withdrawal was processed + */ event ReserveWithdrawn(address indexed user, uint256 amount, uint256 indexed cycleIndex); + + /** + * @notice Emitted when an LP completes their rebalancing action + * @param lp Address of the LP performing the rebalance + * @param rebalancePrice Price at which the rebalance occurred + * @param amount Amount of tokens involved in the rebalance + * @param isDeposit True if LP is depositing, false if withdrawing + * @param cycleIndex Current operational cycle index + */ event Rebalanced(address indexed lp, uint256 rebalancePrice, uint256 amount, bool isDeposit, uint256 indexed cycleIndex); + + /** + * @notice Emitted when a new operational cycle begins + * @param cycleIndex Index of the new cycle + * @param timestamp Block timestamp when the cycle started + */ event CycleStarted(uint256 indexed cycleIndex, uint256 timestamp); + + /** + * @notice Emitted when the cycle duration is updated + * @param newCycleTime New duration for operational cycles + */ event CycleTimeUpdated(uint256 newCycleTime); + + /** + * @notice Emitted when the rebalance period duration is updated + * @param newRebalanceTime New duration for rebalancing periods + */ event RebalanceTimeUpdated(uint256 newRebalanceTime); + + /** + * @notice Emitted when a rebalance period is initiated + * @param cycleIndex Current operational cycle index + * @param assetPrice Current price of the asset + * @param netReserveDelta Net change in reserves required + * @param rebalanceAmount Total amount to be rebalanced + */ event RebalanceInitiated( uint256 indexed cycleIndex, uint256 assetPrice, @@ -37,47 +122,129 @@ interface IAssetPool { // -------------------------------------------------------------------------------- // ERRORS // -------------------------------------------------------------------------------- + + /// @notice Thrown when an invalid amount is provided for an operation error InvalidAmount(); + /// @notice Thrown when a user has insufficient balance for an operation error InsufficientBalance(); + /// @notice Thrown when a non-LP address attempts to perform LP actions error NotLP(); + /// @notice Thrown when an action is attempted in an invalid cycle state error InvalidCycleState(); + /// @notice Thrown when an LP attempts to rebalance multiple times in a cycle error AlreadyRebalanced(); + /// @notice Thrown when a rebalance action is attempted after the window has closed error RebalancingExpired(); + /// @notice Thrown when a zero address is provided for a critical parameter error ZeroAddress(); + /// @notice Thrown when attempting to claim with no pending claims error NothingToClaim(); + /// @notice Thrown when attempting to cancel with no pending requests error NothingToCancel(); + /// @notice Thrown when user has a pending mint or burn request error MintOrBurnPending(); + /// @notice Thrown when attempting operations during an active cycle error CycleInProgress(); + /// @notice Thrown when an LP has insufficient liquidity for an operation error InsufficientLPLiquidity(); + /// @notice Thrown when rebalance parameters don't match requirements error RebalanceMismatch(); // -------------------------------------------------------------------------------- // USER ACTIONS // -------------------------------------------------------------------------------- + + /** + * @notice Allows users to deposit reserve tokens into the pool + * @param amount Amount of reserve tokens to deposit + */ function depositReserve(uint256 amount) external; + + /** + * @notice Allows users to cancel their pending deposit request + */ function cancelDeposit() external; + + /** + * @notice Mints asset tokens for a user based on their processed deposit + * @param user Address of the user to mint assets for + */ function mintAsset(address user) external; + + /** + * @notice Burns asset tokens and creates a redemption request + * @param assetAmount Amount of asset tokens to burn + */ function burnAsset(uint256 assetAmount) external; + + /** + * @notice Allows users to cancel their pending burn request + */ function cancelBurn() external; + + /** + * @notice Allows users to withdraw reserve tokens after burning assets + * @param user Address of the user to process withdrawal for + */ function withdrawReserve(address user) external; // -------------------------------------------------------------------------------- // LP ACTIONS // -------------------------------------------------------------------------------- + + /** + * @notice Initiates the rebalancing period for LPs + */ function initiateRebalance() external; + + /** + * @notice Allows LPs to perform their rebalancing actions + * @param lp Address of the LP performing the rebalance + * @param rebalancePrice Price at which the rebalance is executed + * @param amount Amount of tokens involved in the rebalance + * @param isDeposit True if depositing, false if withdrawing + */ function rebalancePool(address lp, uint256 rebalancePrice, uint256 amount, bool isDeposit) external; // -------------------------------------------------------------------------------- // GOVERNANCE ACTIONS // -------------------------------------------------------------------------------- + + /** + * @notice Updates the duration of operational cycles + * @param newCycleTime New cycle duration in seconds + */ function updateCycleTime(uint256 newCycleTime) external; + + /** + * @notice Updates the duration of rebalancing periods + * @param newRebalanceTime New rebalance period duration in seconds + */ function updateRebalanceTime(uint256 newRebalanceTime) external; + + /** + * @notice Pauses all pool operations + */ function pausePool() external; + + /** + * @notice Resumes all pool operations + */ function unpausePool() external; // -------------------------------------------------------------------------------- // VIEW FUNCTIONS // -------------------------------------------------------------------------------- + + /** + * @notice Returns general information about the pool's state + * @return _xTokenSupply Total supply of asset tokens + * @return _cycleState Current state of the pool + * @return _cycleIndex Current operational cycle index + * @return _nextRebalanceStartDate Start time of next rebalance + * @return _nextRebalanceEndDate End time of next rebalance + * @return _assetPrice Current price of the asset + */ function getGeneralInfo() external view returns ( uint256 _xTokenSupply, CycleState _cycleState, @@ -87,6 +254,13 @@ interface IAssetPool { uint256 _assetPrice ); + /** + * @notice Returns LP-specific information about the pool + * @return _totalDepositRequests Total pending deposits + * @return _totalRedemptionRequests Total pending redemptions + * @return _netReserveDelta Net change in reserves + * @return _rebalanceAmount Amount to be rebalanced + */ function getLPInfo() external view returns ( uint256 _totalDepositRequests, uint256 _totalRedemptionRequests, @@ -97,31 +271,128 @@ interface IAssetPool { // -------------------------------------------------------------------------------- // STATE GETTERS // -------------------------------------------------------------------------------- + + /** + * @notice Returns the reserve token contract + */ function reserveToken() external view returns (IERC20); + + /** + * @notice Returns the asset token contract + */ function assetToken() external view returns (IXToken); + + /** + * @notice Returns the LP registry contract + */ function lpRegistry() external view returns (ILPRegistry); + + /** + * @notice Returns the asset oracle contract + */ function assetOracle() external view returns (IAssetOracle); + /** + * @notice Returns the current cycle index + */ function cycleIndex() external view returns (uint256); + + /** + * @notice Returns the current cycle state + */ function cycleState() external view returns (CycleState); + + /** + * @notice Returns the start time of the next rebalance + */ function nextRebalanceStartDate() external view returns (uint256); + + /** + * @notice Returns the end time of the next rebalance + */ function nextRebalanceEndDate() external view returns (uint256); + + /** + * @notice Returns the duration of operational cycles + */ function cycleTime() external view returns (uint256); + + /** + * @notice Returns the duration of rebalance periods + */ function rebalanceTime() external view returns (uint256); + /** + * @notice Returns the total balance of reserve tokens + */ function totalReserveBalance() external view returns (uint256); + + /** + * @notice Returns the new supply of reserve tokens after rebalance + */ function newReserveSupply() external view returns (uint256); + + /** + * @notice Returns the new supply of asset tokens after rebalance + */ function newAssetSupply() external view returns (uint256); + + /** + * @notice Returns the net change in reserves after rebalance + */ function netReserveDelta() external view returns (int256); + + /** + * @notice Returns the total amount to be rebalanced + */ function rebalanceAmount() external view returns (int256); + /** + * @notice Returns the number of LPs that have completed rebalancing + */ function rebalancedLPs() external view returns (uint256); + + /** + * @notice Checks if an LP has completed their rebalancing + * @param lp Address of the LP to check + */ function hasRebalanced(address lp) external view returns (bool); + /** + * @notice Returns total deposit requests for a specific cycle + * @param cycle Cycle index to query + */ function cycleTotalDepositRequests(uint256 cycle) external view returns (uint256); + + /** + * @notice Returns total redemption requests for a specific cycle + * @param cycle Cycle index to query + */ function cycleTotalRedemptionRequests(uint256 cycle) external view returns (uint256); + + /** + * @notice Returns deposit requests for a specific user in a cycle + * @param cycle Cycle index to query + * @param user Address of the user to query + */ function cycleDepositRequests(uint256 cycle, address user) external view returns (uint256); + + /** + * @notice Returns redemption requests for a specific user in a cycle + * @param cycle Cycle index to query + * @param user Address of the user to query + */ function cycleRedemptionRequests(uint256 cycle, address user) external view returns (uint256); + + /** + * @notice Returns the last cycle index a user interacted with + * @param user Address of the user to query + */ function lastActionCycle(address user) external view returns (uint256); + + /** + * @notice Returns the rebalance price for a specific cycle + * @param cycle Cycle index to query + */ function cycleRebalancePrice(uint256 cycle) external view returns (uint256); -} +} \ No newline at end of file