@venusprotocol/isolated-pools 1.0.0-dev.7 → 1.0.0-dev.9

package/README.md

@@ -12,20 +12,10 @@ The first generation of lending pools, including the Venus Core Pool, aggregate
 
 ### PoolRegistry
 
-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.
+The Isolated Pools architecture centers around the `PoolRegistry` contract. The `PoolRegistry` maintains a directory of isolated lending pools and can perform actions like 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.
 
 ![image](https://user-images.githubusercontent.com/47150934/236290058-6b14a499-7afe-46e4-bca6-d72e3db8a28e.png)
 
-### Factories
-
-There are three factory contracts:
-
-- JumpRateModelFactory
-- VTokenProxyFactory
-- WhiteRateInterestModelFactory
-
-These contracts are designed to deploy contracts when adding markets to a pool. In particular, the `JumpRateModelFactory` and `WhiteRateInterestModelFactory` deploy contracts for the rate model based on which was chosen for the market. The `VtokenProxyFactory` is used to generate a new `vToken` proxy for each market when it is added to a pool.
-
 ### Risk Fund
 
 The risk fund concerns three main contracts:

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 {
     /**

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,
@@ -714,7 +734,7 @@ contract Comptroller is
      * @notice Sets the closeFactor to use when liquidating borrows
      * @param newCloseFactorMantissa New close factor, scaled by 1e18
      * @custom:event Emits NewCloseFactor on success
-     * @custom:access Only Governance
+     * @custom:access Controlled by AccessControlManager
      */
     function setCloseFactor(uint256 newCloseFactorMantissa) external {
         _checkAccessAllowed("setCloseFactor(uint256)");

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

@@ -2,54 +2,44 @@
 pragma solidity 0.8.13;
 
 import { Ownable2StepUpgradeable } from "@openzeppelin/contracts-upgradeable/access/Ownable2StepUpgradeable.sol";
-import { IERC20Upgradeable } from "@openzeppelin/contracts-upgradeable/token/ERC20/IERC20Upgradeable.sol";
 import { SafeERC20Upgradeable } from "@openzeppelin/contracts-upgradeable/token/ERC20/utils/SafeERC20Upgradeable.sol";
-import { BeaconProxy } from "@openzeppelin/contracts/proxy/beacon/BeaconProxy.sol";
-import { IERC20Metadata } from "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol";
-import { ResilientOracleInterface } from "@venusprotocol/oracle/contracts/interfaces/OracleInterface.sol";
-import { AccessControlManager } from "@venusprotocol/governance-contracts/contracts/Governance/AccessControlManager.sol";
+import { IERC20Upgradeable } from "@openzeppelin/contracts-upgradeable/token/ERC20/IERC20Upgradeable.sol";
 import { AccessControlledV8 } from "@venusprotocol/governance-contracts/contracts/Governance/AccessControlledV8.sol";
 
 import { PoolRegistryInterface } from "./PoolRegistryInterface.sol";
 import { Comptroller } from "../Comptroller.sol";
-import { VTokenProxyFactory } from "../Factories/VTokenProxyFactory.sol";
-import { JumpRateModelFactory } from "../Factories/JumpRateModelFactory.sol";
-import { WhitePaperInterestRateModelFactory } from "../Factories/WhitePaperInterestRateModelFactory.sol";
-import { WhitePaperInterestRateModel } from "../WhitePaperInterestRateModel.sol";
 import { VToken } from "../VToken.sol";
-import { InterestRateModel } from "../InterestRateModel.sol";
-import { Shortfall } from "../Shortfall/Shortfall.sol";
-import { VTokenInterface } from "../VTokenInterfaces.sol";
 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;
 
-    enum InterestRateModels {
-        WhitePaper,
-        JumpRate
-    }
-
     struct AddMarketInput {
-        address comptroller;
-        address asset;
-        uint8 decimals;
-        string name;
-        string symbol;
-        InterestRateModels rateModel;
-        uint256 baseRatePerYear;
-        uint256 multiplierPerYear;
-        uint256 jumpMultiplierPerYear;
-        uint256 kink_;
+        VToken vToken;
         uint256 collateralFactor;
         uint256 liquidationThreshold;
-        uint256 reserveFactor;
-        AccessControlManager accessControlManager;
-        address beaconAddress;
         uint256 initialSupply;
         address vTokenReceiver;
         uint256 supplyCap;
@@ -58,31 +48,6 @@ contract PoolRegistry is Ownable2StepUpgradeable, AccessControlledV8, PoolRegist
 
     uint256 internal constant MAX_POOL_NAME_LENGTH = 100;
 
-    /**
-     * @notice VTokenProxyFactory contract address
-     */
-    VTokenProxyFactory public vTokenFactory;
-
-    /**
-     * @notice JumpRateModelFactory contract address
-     */
-    JumpRateModelFactory public jumpRateFactory;
-
-    /**
-     * @notice WhitePaperInterestRateModelFactory contract address
-     */
-    WhitePaperInterestRateModelFactory public whitePaperFactory;
-
-    /**
-     * @notice Shortfall contract address
-     */
-    Shortfall public shortfall;
-
-    /**
-     * @notice Shortfall contract address
-     */
-    address payable public protocolShareReserve;
-
     /**
      * @notice Maps pool's comptroller address to metadata.
      */
@@ -137,16 +102,6 @@ contract PoolRegistry is Ownable2StepUpgradeable, AccessControlledV8, PoolRegist
      */
     event MarketAdded(address indexed comptroller, address indexed vTokenAddress);
 
-    /**
-     * @notice Event emitted when shortfall contract address is changed
-     */
-    event NewShortfallContract(address indexed oldShortfall, address indexed newShortfall);
-
-    /**
-     * @notice Event emitted when protocol share reserve contract address is changed
-     */
-    event NewProtocolShareReserve(address indexed oldProtocolShareReserve, address indexed newProtocolShareReserve);
-
     /// @custom:oz-upgrades-unsafe-allow constructor
     constructor() {
         // Note that the contract is upgradeable. Use initialize() or reinitializers
@@ -156,163 +111,73 @@ contract PoolRegistry is Ownable2StepUpgradeable, AccessControlledV8, PoolRegist
 
     /**
      * @dev Initializes the deployer to owner
-     * @param vTokenFactory_ vToken factory address
-     * @param jumpRateFactory_ jump rate factory address
-     * @param whitePaperFactory_ white paper factory address
-     * @param protocolShareReserve_ protocol's shares reserve address
-     * @param shortfall_ Shortfall contract address
      * @param accessControlManager_ AccessControlManager contract address
-     * @custom:error ZeroAddressNotAllowed is thrown when shortfall contract address is zero
-     * @custom:error ZeroAddressNotAllowed is thrown when protocol share reserve address is zero
      */
-    function initialize(
-        VTokenProxyFactory vTokenFactory_,
-        JumpRateModelFactory jumpRateFactory_,
-        WhitePaperInterestRateModelFactory whitePaperFactory_,
-        Shortfall shortfall_,
-        address payable protocolShareReserve_,
-        address accessControlManager_
-    ) external initializer {
+    function initialize(address accessControlManager_) external initializer {
         __Ownable2Step_init();
         __AccessControlled_init_unchained(accessControlManager_);
-
-        vTokenFactory = vTokenFactory_;
-        jumpRateFactory = jumpRateFactory_;
-        whitePaperFactory = whitePaperFactory_;
-        _setShortfallContract(shortfall_);
-        _setProtocolShareReserve(protocolShareReserve_);
     }
 
     /**
-     * @notice Sets protocol share reserve contract address
-     * @param protocolShareReserve_ The address of the protocol share reserve contract
-     * @custom:error ZeroAddressNotAllowed is thrown when protocol share reserve address is zero
-     * @custom:access Only Governance
-     */
-    function setProtocolShareReserve(address payable protocolShareReserve_) external onlyOwner {
-        _setProtocolShareReserve(protocolShareReserve_);
-    }
-
-    /**
-     * @notice Sets shortfall contract address
-     * @param shortfall_ The address of the shortfall contract
-     * @custom:error ZeroAddressNotAllowed is thrown when shortfall contract address is zero
-     * @custom:access Only Governance
-     */
-    function setShortfallContract(Shortfall shortfall_) external onlyOwner {
-        _setShortfallContract(shortfall_);
-    }
-
-    /**
-     * @dev Deploys a new Venus pool and adds to the directory.
+     * @notice Adds a new Venus pool to the directory
+     * @dev Price oracle must be configured before adding a pool
      * @param name The name of the pool
-     * @param beaconAddress The upgradeable beacon contract address for Comptroller implementation
+     * @param comptroller Pool's Comptroller contract
      * @param closeFactor The pool's close factor (scaled by 1e18)
      * @param liquidationIncentive The pool's liquidation incentive (scaled by 1e18)
      * @param minLiquidatableCollateral Minimal collateral for regular (non-batch) liquidations flow
-     * @param priceOracle The pool's price oracle address
-     * @param maxLoopsLimit The maximum number of iterations the loops can perform
-     * @param accessControlManager AccessControlManager contract address
      * @return index The index of the registered Venus pool
-     * @return proxyAddress The the Comptroller proxy address
-     * @custom:error ZeroAddressNotAllowed is thrown when Comptroller beacon address is zero
+     * @custom:error ZeroAddressNotAllowed is thrown when Comptroller address is zero
      * @custom:error ZeroAddressNotAllowed is thrown when price oracle address is zero
      */
-    function createRegistryPool(
+    function addPool(
         string calldata name,
-        address beaconAddress,
+        Comptroller comptroller,
         uint256 closeFactor,
         uint256 liquidationIncentive,
-        uint256 minLiquidatableCollateral,
-        address priceOracle,
-        uint256 maxLoopsLimit,
-        address accessControlManager
-    ) external virtual returns (uint256 index, address proxyAddress) {
-        _checkAccessAllowed("createRegistryPool(string,address,uint256,uint256,uint256,address,uint256,address)");
+        uint256 minLiquidatableCollateral
+    ) external virtual returns (uint256 index) {
+        _checkAccessAllowed("addPool(string,address,uint256,uint256,uint256)");
         // Input validation
-        ensureNonzeroAddress(beaconAddress);
-        ensureNonzeroAddress(priceOracle);
-
-        BeaconProxy proxy = new BeaconProxy(
-            beaconAddress,
-            abi.encodeWithSelector(Comptroller.initialize.selector, maxLoopsLimit, accessControlManager)
-        );
+        ensureNonzeroAddress(address(comptroller));
+        ensureNonzeroAddress(address(comptroller.oracle()));
 
-        proxyAddress = address(proxy);
-        Comptroller comptrollerProxy = Comptroller(proxyAddress);
-
-        uint256 poolId = _registerPool(name, proxyAddress);
+        uint256 poolId = _registerPool(name, address(comptroller));
 
         // Set Venus pool parameters
-        comptrollerProxy.setCloseFactor(closeFactor);
-        comptrollerProxy.setLiquidationIncentive(liquidationIncentive);
-        comptrollerProxy.setMinLiquidatableCollateral(minLiquidatableCollateral);
-        comptrollerProxy.setPriceOracle(ResilientOracleInterface(priceOracle));
-
-        // Start transferring ownership to msg.sender
-        comptrollerProxy.transferOwnership(msg.sender);
+        comptroller.setCloseFactor(closeFactor);
+        comptroller.setLiquidationIncentive(liquidationIncentive);
+        comptroller.setMinLiquidatableCollateral(minLiquidatableCollateral);
 
-        return (poolId, proxyAddress);
+        return poolId;
     }
 
     /**
-     * @notice Add a market to an existing pool and then mint to provide initial supply.
-     * @param input The structure describing the parameters for adding a market to a pool.
-     * @custom:error ZeroAddressNotAllowed is thrown when Comptroller address is zero
-     * @custom:error ZeroAddressNotAllowed is thrown when asset address is zero
-     * @custom:error ZeroAddressNotAllowed is thrown when VToken beacon address is zero
+     * @notice Add a market to an existing pool and then mint to provide initial supply
+     * @param input The structure describing the parameters for adding a market to a pool
+     * @custom:error ZeroAddressNotAllowed is thrown when vToken address is zero
      * @custom:error ZeroAddressNotAllowed is thrown when vTokenReceiver address is zero
      */
     function addMarket(AddMarketInput memory input) external {
         _checkAccessAllowed("addMarket(AddMarketInput)");
-        ensureNonzeroAddress(input.comptroller);
-        ensureNonzeroAddress(input.asset);
-        ensureNonzeroAddress(input.beaconAddress);
+        ensureNonzeroAddress(address(input.vToken));
         ensureNonzeroAddress(input.vTokenReceiver);
+        require(input.initialSupply > 0, "PoolRegistry: initialSupply is zero");
+
+        VToken vToken = input.vToken;
+        address vTokenAddress = address(vToken);
+        address comptrollerAddress = address(vToken.comptroller());
+        Comptroller comptroller = Comptroller(comptrollerAddress);
+        address underlyingAddress = vToken.underlying();
+        IERC20Upgradeable underlying = IERC20Upgradeable(underlyingAddress);
 
+        require(_poolByComptroller[comptrollerAddress].creator != address(0), "PoolRegistry: Pool not registered");
         // solhint-disable-next-line reason-string
         require(
-            _vTokens[input.comptroller][input.asset] == address(0),
+            _vTokens[comptrollerAddress][underlyingAddress] == address(0),
             "PoolRegistry: Market already added for asset comptroller combination"
         );
 
-        require(input.initialSupply > 0, "PoolRegistry: initialSupply is zero");
-
-        InterestRateModel rate;
-        if (input.rateModel == InterestRateModels.JumpRate) {
-            rate = InterestRateModel(
-                jumpRateFactory.deploy(
-                    input.baseRatePerYear,
-                    input.multiplierPerYear,
-                    input.jumpMultiplierPerYear,
-                    input.kink_,
-                    input.accessControlManager
-                )
-            );
-        } else {
-            rate = InterestRateModel(whitePaperFactory.deploy(input.baseRatePerYear, input.multiplierPerYear));
-        }
-
-        Comptroller comptroller = Comptroller(input.comptroller);
-        uint256 underlyingDecimals = IERC20Metadata(input.asset).decimals();
-
-        VTokenProxyFactory.VTokenArgs memory initializeArgs = VTokenProxyFactory.VTokenArgs(
-            input.asset,
-            comptroller,
-            rate,
-            10**(underlyingDecimals + 18 - input.decimals),
-            input.name,
-            input.symbol,
-            input.decimals,
-            msg.sender,
-            input.accessControlManager,
-            VTokenInterface.RiskManagementInit(address(shortfall), protocolShareReserve),
-            input.beaconAddress,
-            input.reserveFactor
-        );
-
-        VToken vToken = vTokenFactory.deployVTokenProxy(initializeArgs);
-
         comptroller.supportMarket(vToken);
         comptroller.setCollateralFactor(vToken, input.collateralFactor, input.liquidationThreshold);
 
@@ -327,16 +192,15 @@ contract PoolRegistry is Ownable2StepUpgradeable, AccessControlledV8, PoolRegist
         comptroller.setMarketSupplyCaps(vTokens, newSupplyCaps);
         comptroller.setMarketBorrowCaps(vTokens, newBorrowCaps);
 
-        _vTokens[input.comptroller][input.asset] = address(vToken);
-        _supportedPools[input.asset].push(input.comptroller);
+        _vTokens[comptrollerAddress][underlyingAddress] = vTokenAddress;
+        _supportedPools[underlyingAddress].push(comptrollerAddress);
 
-        IERC20Upgradeable token = IERC20Upgradeable(input.asset);
-        uint256 amountToSupply = _transferIn(token, msg.sender, input.initialSupply);
-        token.approve(address(vToken), 0);
-        token.approve(address(vToken), amountToSupply);
+        uint256 amountToSupply = _transferIn(underlying, msg.sender, input.initialSupply);
+        underlying.approve(vTokenAddress, 0);
+        underlying.approve(vTokenAddress, amountToSupply);
         vToken.mintBehalf(input.vTokenReceiver, amountToSupply);
 
-        emit MarketAdded(address(comptroller), address(vToken));
+        emit MarketAdded(comptrollerAddress, vTokenAddress);
     }
 
     /**
@@ -439,20 +303,6 @@ contract PoolRegistry is Ownable2StepUpgradeable, AccessControlledV8, PoolRegist
         return balanceAfter - balanceBefore;
     }
 
-    function _setShortfallContract(Shortfall shortfall_) internal {
-        ensureNonzeroAddress(address(shortfall_));
-        address oldShortfall = address(shortfall);
-        shortfall = shortfall_;
-        emit NewShortfallContract(oldShortfall, address(shortfall_));
-    }
-
-    function _setProtocolShareReserve(address payable protocolShareReserve_) internal {
-        ensureNonzeroAddress(protocolShareReserve_);
-        address oldProtocolShareReserve = protocolShareReserve;
-        protocolShareReserve = protocolShareReserve_;
-        emit NewProtocolShareReserve(oldProtocolShareReserve, protocolShareReserve_);
-    }
-
     function _ensureValidName(string calldata name) internal pure {
         require(bytes(name).length <= MAX_POOL_NAME_LENGTH, "Pool's name is too large");
     }

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