@venusprotocol/isolated-pools 1.0.0-dev.6 → 1.0.0-dev.8

package/contracts/BaseJumpRateModelV2.sol

@@ -8,8 +8,9 @@ import { BLOCKS_PER_YEAR, EXP_SCALE, MANTISSA_ONE } from "./lib/constants.sol";
 
 /**
  * @title Logic for Compound's JumpRateModel Contract V2.
- * @author Compound (modified by Dharma Labs, refactored by Arr00)
- * @notice Version 2 modifies Version 1 by enabling updateable parameters.
+ * @author Compound (modified by Dharma Labs, Arr00 and Venus)
+ * @notice An interest rate model with a steep increase after a certain utilization threshold called **kink** is reached.
+ * The parameters of this interest rate model can be adjusted by the owner. Version 2 modifies Version 1 by enabling updateable parameters.
  */
 abstract contract BaseJumpRateModelV2 is InterestRateModel {
     /**
@@ -134,7 +135,7 @@ abstract contract BaseJumpRateModelV2 is InterestRateModel {
         uint256 reserves,
         uint256 badDebt
     ) public pure returns (uint256) {
-        // Utilization rate is 0 when there are no borrows
+        // Utilization rate is 0 when there are no borrows and badDebt
         if ((borrows + badDebt) == 0) {
             return 0;
         }

package/contracts/Comptroller.sol

@@ -14,7 +14,27 @@ import { MaxLoopsLimitHelper } from "./MaxLoopsLimitHelper.sol";
 import { ensureNonzeroAddress } from "./lib/validators.sol";
 
 /**
- * @title Comptroller Contract
+ * @title Comptroller
+ * @author Venus
+ * @notice The Comptroller is designed to provide checks for all minting, redeeming, transferring, borrowing, lending, repaying, liquidating,
+ * and seizing done by the `vToken` contract. Each pool has one `Comptroller` checking these interactions across markets. When a user interacts
+ * with a given market by one of these main actions, a call is made to a corresponding hook in the associated `Comptroller`, which either allows
+ * or reverts the transaction. These hooks also update supply and borrow rewards as they are called. The comptroller holds the logic for assessing
+ * liquidity snapshots of an account via the collateral factor and liquidation threshold. This check determines the collateral needed for a borrow,
+ * as well as how much of a borrow may be liquidated. A user may borrow a portion of their collateral with the maximum amount determined by the
+ * markets collateral factor. However, if their borrowed amount exceeds an amount calculated using the market’s corresponding liquidation threshold,
+ * the borrow is eligible for liquidation.
+ *
+ * The `Comptroller` also includes two functions `liquidateAccount()` and `healAccount()`, which are meant to handle accounts that do not exceed
+ * the `minLiquidatableCollateral` for the `Comptroller`:
+ *
+ * - `healAccount()`: This function is called to seize all of a given user’s collateral, requiring the `msg.sender` repay a certain percentage
+ * of the debt calculated by `collateral/(borrows*liquidationIncentive)`. The function can only be called if the calculated percentage does not exceed
+ * 100%, because otherwise no `badDebt` would be created and `liquidateAccount()` should be used instead. The difference in the actual amount of debt
+ * and debt paid off is recorded as `badDebt` for each market, which can then be auctioned off for the risk reserves of the associated pool.
+ * - `liquidateAccount()`: This function can only be called if the collateral seized will cover all borrows of an account, as well as the liquidation
+ * incentive. Otherwise, the pool will incur bad debt, in which case the function `healAccount()` should be used instead. This function skips the logic
+ * verifying that the repay amount does not exceed the close factor.
  */
 contract Comptroller is
     Ownable2StepUpgradeable,
@@ -161,10 +181,6 @@ contract Comptroller is
     function enterMarkets(address[] memory vTokens) external override returns (uint256[] memory) {
         uint256 len = vTokens.length;
 
-        uint256 accountAssetsLen = accountAssets[msg.sender].length;
-
-        _ensureMaxLoops(accountAssetsLen + len);
-
         uint256[] memory results = new uint256[](len);
         for (uint256 i; i < len; ++i) {
             VToken vToken = VToken(vTokens[i]);
@@ -337,9 +353,6 @@ contract Comptroller is
     ) external override {
         _checkActionPauseState(vToken, Action.BORROW);
 
-        //Update the prices of tokens
-        updatePrices(borrower);
-
         if (!markets[vToken].isListed) {
             revert MarketNotListed(address(vToken));
         }
@@ -347,11 +360,14 @@ contract Comptroller is
         if (!markets[vToken].accountMembership[borrower]) {
             // only vTokens may call borrowAllowed if borrower not in market
             _checkSenderIs(vToken);
-            _ensureMaxLoops(accountAssets[msg.sender].length + 1);
+
             // attempt to add borrower to the market or revert
             _addToMarket(VToken(msg.sender), borrower);
         }
 
+        // Update the prices of tokens
+        updatePrices(borrower);
+
         if (oracle.getUnderlyingPrice(vToken) == 0) {
             revert PriceError(address(vToken));
         }
@@ -445,7 +461,7 @@ contract Comptroller is
         // Action.SEIZE on it
         _checkActionPauseState(vTokenBorrowed, Action.LIQUIDATE);
 
-        //Update the prices of tokens
+        // Update the prices of tokens
         updatePrices(borrower);
 
         if (!markets[vTokenBorrowed].isListed) {
@@ -1313,7 +1329,7 @@ contract Comptroller is
             return;
         }
 
-        //Update the prices of tokens
+        // Update the prices of tokens
         updatePrices(redeemer);
 
         /* Otherwise, perform a hypothetical liquidity check to guard against shortfall */

package/contracts/ComptrollerInterface.sol

@@ -6,6 +6,11 @@ import { ResilientOracleInterface } from "@venusprotocol/oracle/contracts/interf
 import { VToken } from "./VToken.sol";
 import { RewardsDistributor } from "./Rewards/RewardsDistributor.sol";
 
+/**
+ * @title ComptrollerInterface
+ * @author Venus
+ * @notice Interface implemented by the `Comptroller` contract.
+ */
 interface ComptrollerInterface {
     /*** Assets You Are In ***/
 
@@ -70,6 +75,11 @@ interface ComptrollerInterface {
     function getAllMarkets() external view returns (VToken[] memory);
 }
 
+/**
+ * @title ComptrollerViewInterface
+ * @author Venus
+ * @notice Interface implemented by the `Comptroller` contract, including only some util view functions.
+ */
 interface ComptrollerViewInterface {
     function markets(address) external view returns (bool, uint256);
 

package/contracts/ComptrollerStorage.sol

@@ -6,6 +6,11 @@ import { ResilientOracleInterface } from "@venusprotocol/oracle/contracts/interf
 import { VToken } from "./VToken.sol";
 import { RewardsDistributor } from "./Rewards/RewardsDistributor.sol";
 
+/**
+ * @title ComptrollerStorage
+ * @author Venus
+ * @notice Storage layout for the `Comptroller` contract.
+ */
 contract ComptrollerStorage {
     struct LiquidationOrder {
         VToken vTokenCollateral;

package/contracts/ErrorReporter.sol

@@ -1,6 +1,11 @@
 // SPDX-License-Identifier: BSD-3-Clause
 pragma solidity 0.8.13;
 
+/**
+ * @title TokenErrorReporter
+ * @author Venus
+ * @notice Errors that can be thrown by the `VToken` contract.
+ */
 contract TokenErrorReporter {
     uint256 public constant NO_ERROR = 0; // support legacy return codes
 

package/contracts/Lens/PoolLens.sol

@@ -12,6 +12,19 @@ import { PoolRegistryInterface } from "../Pool/PoolRegistryInterface.sol";
 import { PoolRegistry } from "../Pool/PoolRegistry.sol";
 import { RewardsDistributor } from "../Rewards/RewardsDistributor.sol";
 
+/**
+ * @title PoolLens
+ * @author Venus
+ * @notice The `PoolLens` contract is designed to retrieve important information for each registered pool. A list of essential information
+ * for all pools within the lending protocol can be acquired through the function `getAllPools()`. Additionally, the following records can be
+ * looked up for specific pools and markets:
+- the vToken balance of a given user;
+- the pool data (oracle address, associated vToken, liquidation incentive, etc) of a pool via its associated comptroller address;
+- the vToken address in a pool for a given asset;
+- a list of all pools that support an asset;
+- the underlying asset price of a vToken;
+- the metadata (exchange/borrow/supply rate, total supply, collateral factor, etc) of any vToken.
+ */
 contract PoolLens is ExponentialNoError {
     /**
      * @dev Struct for PoolDetails.

package/contracts/MaxLoopsLimitHelper.sol

@@ -1,6 +1,11 @@
 // SPDX-License-Identifier: BSD-3-Clause
 pragma solidity 0.8.13;
 
+/**
+ * @title MaxLoopsLimitHelper
+ * @author Venus
+ * @notice Abstract contract used to avoid collection with too many items that would generate gas errors and DoS.
+ */
 abstract contract MaxLoopsLimitHelper {
     // Limit for the loops to avoid the DOS
     uint256 public maxLoopsLimit;

package/contracts/Pool/PoolRegistry.sol

@@ -24,7 +24,25 @@ import { ensureNonzeroAddress } from "../lib/validators.sol";
 
 /**
  * @title PoolRegistry
- * @notice PoolRegistry is a registry for Venus interest rate pools.
+ * @author Venus
+ * @notice The Isolated Pools architecture centers around the `PoolRegistry` contract. The `PoolRegistry` maintains a directory of isolated lending
+ * pools and can perform actions like creating and registering new pools, adding new markets to existing pools, setting and updating the pool's required
+ * metadata, and providing the getter methods to get information on the pools.
+ *
+ * Isolated lending has three main components: PoolRegistry, pools, and markets. The PoolRegistry is responsible for managing pools.
+ * It can create new pools, update pool metadata and manage markets within pools. PoolRegistry contains getter methods to get the details of
+ * any existing pool like `getVTokenForAsset` and `getPoolsSupportedByAsset`. It also contains methods for updating pool metadata (`updatePoolMetadata`)
+ * and setting pool name (`setPoolName`).
+ *
+ * The directory of pools is managed through two mappings: `_poolByComptroller` which is a hashmap with the comptroller address as the key and `VenusPool` as
+ * the value and `_poolsByID` which is an array of comptroller addresses. Individual pools can be accessed by calling `getPoolByComptroller` with the pool's
+ * comptroller address. `_poolsByID` is used to iterate through all of the pools.
+ *
+ * PoolRegistry also contains a map of asset addresses called `_supportedPools` that maps to an array of assets suppored by each pool. This array of pools by
+ * asset is retrieved by calling `getPoolsSupportedByAsset`.
+ *
+ * PoolRegistry registers new isolated pools in the directory with the `createRegistryPool` method. Isolated pools are composed of independent markets with
+ * specific assets and custom risk management configurations according to their markets.
  */
 contract PoolRegistry is Ownable2StepUpgradeable, AccessControlledV8, PoolRegistryInterface {
     using SafeERC20Upgradeable for IERC20Upgradeable;

package/contracts/Pool/PoolRegistryInterface.sol

@@ -1,9 +1,14 @@
 // SPDX-License-Identifier: BSD-3-Clause
 pragma solidity 0.8.13;
 
+/**
+ * @title PoolRegistryInterface
+ * @author Venus
+ * @notice Interface implemented by `PoolRegistry`.
+ */
 interface PoolRegistryInterface {
     /**
-     * @dev Struct for a Venus interest rate pool.
+     * @notice Struct for a Venus interest rate pool.
      */
     struct VenusPool {
         string name;
@@ -14,7 +19,7 @@ interface PoolRegistryInterface {
     }
 
     /**
-     * @dev Struct for a Venus interest rate pool metadata.
+     * @notice Struct for a Venus interest rate pool metadata.
      */
     struct VenusPoolMetaData {
         string category;
@@ -22,18 +27,18 @@ interface PoolRegistryInterface {
         string description;
     }
 
-    /*** get All Pools in PoolRegistry ***/
+    /// @notice Get all pools in PoolRegistry
     function getAllPools() external view returns (VenusPool[] memory);
 
-    /*** get a Pool by comptrollerAddress ***/
+    /// @notice Get a pool by comptroller address
     function getPoolByComptroller(address comptroller) external view returns (VenusPool memory);
 
-    /*** get VToken in the Pool for an Asset ***/
+    /// @notice Get the address of the VToken contract in the Pool where the underlying token is the provided asset
     function getVTokenForAsset(address comptroller, address asset) external view returns (address);
 
-    /*** get Pools supported by Asset ***/
+    /// @notice Get the addresss of the Pools supported that include a market for the provided asset
     function getPoolsSupportedByAsset(address asset) external view returns (address[] memory);
 
-    /*** get metadata of a Pool by comptroller ***/
+    /// @notice Get the metadata of a Pool by comptroller address
     function getVenusPoolMetadata(address comptroller) external view returns (VenusPoolMetaData memory);
 }

package/contracts/Rewards/RewardsDistributor.sol

@@ -11,6 +11,21 @@ import { VToken } from "../VToken.sol";
 import { Comptroller } from "../Comptroller.sol";
 import { MaxLoopsLimitHelper } from "../MaxLoopsLimitHelper.sol";
 
+/**
+ * @title `RewardsDistributor`
+ * @author Venus
+ * @notice Contract used to configure, track and distribute rewards to users based on their actions (borrows and supplies) in the protocol.
+ * Users can receive additional rewards through a `RewardsDistributor`. Each `RewardsDistributor` proxy is initialized with a specific reward
+ * token and `Comptroller`, which can then distribute the reward token to users that supply or borrow in the associated pool.
+ * Authorized users can set the reward token borrow and supply speeds for each market in the pool. This sets a fixed amount of reward
+ * token to be released each block for borrowers and suppliers, which is distributed based on a user’s percentage of the borrows or supplies
+ * respectively. The owner can also set up reward distributions to contributor addresses (distinct from suppliers and borrowers) by setting
+ * their contributor reward token speed, which similarly allocates a fixed amount of reward token per block.
+ *
+ * The owner has the ability to transfer any amount of reward tokens held by the contract to any other address. Rewards are not distributed
+ * automatically and must be claimed by a user calling `claimRewardToken()`. Users should be aware that it is up to the owner and other centralized
+ * entities to ensure that the `RewardsDistributor` holds enough tokens to distribute the accumulated rewards of users and contributors.
+ */
 contract RewardsDistributor is ExponentialNoError, Ownable2StepUpgradeable, AccessControlledV8, MaxLoopsLimitHelper {
     using SafeERC20Upgradeable for IERC20Upgradeable;
 

package/contracts/RiskFund/IProtocolShareReserve.sol

@@ -1,6 +1,11 @@
 // SPDX-License-Identifier: BSD-3-Clause
 pragma solidity 0.8.13;
 
+/**
+ * @title IProtocolShareReserve
+ * @author Venus
+ * @notice Interface implemented by `ProtocolShareReserve`.
+ */
 interface IProtocolShareReserve {
     function updateAssetsState(address comptroller, address asset) external;
 }

package/contracts/RiskFund/IRiskFund.sol

@@ -1,6 +1,11 @@
 // SPDX-License-Identifier: BSD-3-Clause
 pragma solidity 0.8.13;
 
+/**
+ * @title IRiskFund
+ * @author Venus
+ * @notice Interface implemented by `RiskFund`.
+ */
 interface IRiskFund {
     function swapPoolsAssets(
         address[] calldata markets,

package/contracts/RiskFund/ProtocolShareReserve.sol

@@ -11,6 +11,11 @@ import { ReserveHelpers } from "./ReserveHelpers.sol";
 import { IRiskFund } from "./IRiskFund.sol";
 import { ensureNonzeroAddress } from "../lib/validators.sol";
 
+/**
+ * @title ProtocolShareReserve
+ * @author Venus
+ * @notice Contract used to store and distribute the reserves generated in the markets.
+ */
 contract ProtocolShareReserve is Ownable2StepUpgradeable, ExponentialNoError, ReserveHelpers, IProtocolShareReserve {
     using SafeERC20Upgradeable for IERC20Upgradeable;
 

package/contracts/RiskFund/ReserveHelpers.sol

@@ -8,6 +8,11 @@ import { ensureNonzeroAddress } from "../lib/validators.sol";
 import { ComptrollerInterface } from "../ComptrollerInterface.sol";
 import { PoolRegistryInterface } from "../Pool/PoolRegistryInterface.sol";
 
+/**
+ * @title ReserveHelpers
+ * @author Venus
+ * @notice Contract with basic features to track/hold different assets for different Comptrollers.
+ */
 contract ReserveHelpers {
     using SafeERC20Upgradeable for IERC20Upgradeable;
 

package/contracts/RiskFund/RiskFund.sol

@@ -19,6 +19,9 @@ import { MaxLoopsLimitHelper } from "../MaxLoopsLimitHelper.sol";
 import { ensureNonzeroAddress } from "../lib/validators.sol";
 
 /**
+ * @title ReserveHelpers
+ * @author Venus
+ * @notice Contract with basic features to track/hold different assets for different Comptrollers.
  * @dev This contract does not support BNB.
  */
 contract RiskFund is

package/contracts/Shortfall/IShortfall.sol

@@ -1,6 +1,11 @@
 // SPDX-License-Identifier: BSD-3-Clause
 pragma solidity 0.8.13;
 
+/**
+ * @title IShortfall
+ * @author Venus
+ * @notice Interface implemented by `Shortfall`.
+ */
 interface IShortfall {
     function convertibleBaseAsset() external returns (address);
 }

package/contracts/Shortfall/Shortfall.sol

@@ -17,6 +17,16 @@ import { PoolRegistryInterface } from "../Pool/PoolRegistryInterface.sol";
 import { ensureNonzeroAddress } from "../lib/validators.sol";
 import { EXP_SCALE } from "../lib/constants.sol";
 
+/**
+ * @title Shortfall
+ * @author Venus
+ * @notice Shortfall is an auction contract designed to auction off the `convertibleBaseAsset` accumulated in `RiskFund`. The `convertibleBaseAsset`
+ * is auctioned in exchange for users paying off the pool's bad debt. An auction can be started by anyone once a pool's bad debt has reached a minimum value.
+ * This value is set and can be changed by the authorized accounts. If the pool’s bad debt exceeds the risk fund plus a 10% incentive, then the auction winner
+ * is determined by who will pay off the largest percentage of the pool's bad debt. The auction winner then exchanges for the entire risk fund. Otherwise,
+ * if the risk fund covers the pool's bad debt plus the 10% incentive, then the auction winner is determined by who will take the smallest percentage of the
+ * risk fund in exchange for paying off all the pool's bad debt.
+ */
 contract Shortfall is Ownable2StepUpgradeable, AccessControlledV8, ReentrancyGuardUpgradeable, IShortfall {
     using SafeERC20Upgradeable for IERC20Upgradeable;
 
@@ -225,7 +235,6 @@ contract Shortfall is Ownable2StepUpgradeable, AccessControlledV8, ReentrancyGua
      * @notice Close an auction
      * @param comptroller Comptroller address of the pool
      * @custom:event Emits AuctionClosed event on successful close
-     * @custom:event Errors if auctions are paused
      */
     function closeAuction(address comptroller) external nonReentrant {
         Auction storage auction = auctions[comptroller];
@@ -290,7 +299,6 @@ contract Shortfall is Ownable2StepUpgradeable, AccessControlledV8, ReentrancyGua
      * @notice Restart an auction
      * @param comptroller Address of the pool
      * @custom:event Emits AuctionRestarted event on successful restart
-     * @custom:event Errors if auctions are paused
      */
     function restartAuction(address comptroller) external {
         Auction storage auction = auctions[comptroller];

package/contracts/VToken.sol

@@ -15,8 +15,30 @@ import { IProtocolShareReserve } from "./RiskFund/IProtocolShareReserve.sol";
 import { ensureNonzeroAddress } from "./lib/validators.sol";
 
 /**
- * @title Venus VToken Contract
- * @author Venus Dev Team
+ * @title VToken
+ * @author Venus
+ * @notice Each asset that is supported by a pool is integrated through an instance of the `VToken` contract. As outlined in the protocol overview,
+ * each isolated pool creates its own `vToken` corresponding to an asset. Within a given pool, each included `vToken` is referred to as a market of
+ * the pool. The main actions a user regularly interacts with in a market are:
+
+- mint/redeem of vTokens;
+- transfer of vTokens;
+- borrow/repay a loan on an underlying asset;
+- liquidate a borrow or liquidate/heal an account.
+
+ * A user supplies the underlying asset to a pool by minting `vTokens`, where the corresponding `vToken` amount is determined by the `exchangeRate`.
+ * The `exchangeRate` will change over time, dependent on a number of factors, some of which accrue interest. Additionally, once users have minted
+ * `vToken` in a pool, they can borrow any asset in the isolated pool by using their `vToken` as collateral. In order to borrow an asset or use a `vToken`
+ * as collateral, the user must be entered into each corresponding market (else, the `vToken` will not be considered collateral for a borrow). Note that
+ * a user may borrow up to a portion of their collateral determined by the market’s collateral factor. However, if their borrowed amount exceeds an amount
+ * calculated using the market’s corresponding liquidation threshold, the borrow is eligible for liquidation. When a user repays a borrow, they must also
+ * pay off interest accrued on the borrow.
+ * 
+ * The Venus protocol includes unique mechanisms for healing an account and liquidating an account. These actions are performed in the `Comptroller`
+ * and consider all borrows and collateral for which a given account is entered within a market. These functions may only be called on an account with a
+ * total collateral amount that is no larger than a universal `minLiquidatableCollateral` value, which is used for all markets within a `Comptroller`.
+ * Both functions settle all of an account’s borrows, but `healAccount()` may add `badDebt` to a vToken. For more detail, see the description of
+ * `healAccount()` and `liquidateAccount()` in the `Comptroller` summary section below.
  */
 contract VToken is
     Ownable2StepUpgradeable,

package/contracts/VTokenInterfaces.sol

@@ -7,6 +7,11 @@ import { ResilientOracleInterface } from "@venusprotocol/oracle/contracts/interf
 import { ComptrollerInterface } from "./ComptrollerInterface.sol";
 import { InterestRateModel } from "./InterestRateModel.sol";
 
+/**
+ * @title VTokenStorage
+ * @author Venus
+ * @notice Storage layout used by the `VToken` contract
+ */
 // solhint-disable-next-line max-states-count
 contract VTokenStorage {
     /**
@@ -130,6 +135,11 @@ contract VTokenStorage {
     uint256[50] private __gap;
 }
 
+/**
+ * @title VTokenInterface
+ * @author Venus
+ * @notice Interface implemented by the `VToken` contract
+ */
 abstract contract VTokenInterface is VTokenStorage {
     struct RiskManagementInit {
         address shortfall;

package/contracts/WhitePaperInterestRateModel.sol

@@ -90,7 +90,7 @@ contract WhitePaperInterestRateModel is InterestRateModel {
         uint256 reserves,
         uint256 badDebt
     ) public pure returns (uint256) {
-        // Utilization rate is 0 when there are no borrows
+        // Utilization rate is 0 when there are no borrows and badDebt
         if ((borrows + badDebt) == 0) {
             return 0;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venusprotocol/isolated-pools",
-  "version": "1.0.0-dev.6",
+  "version": "1.0.0-dev.8",
   "description": "",
   "files": [
     "artifacts",