Merge pull request #80 from euler-xyz/natspec

Natspec

src/EVault/DToken.sol

@@ -6,6 +6,9 @@ import {Errors} from "./shared/Errors.sol";
 import {Events} from "./shared/Events.sol";
 import {IERC20, IEVault} from "./IEVault.sol";
 
+/// @title DToken
+/// @author Euler Labs (https://www.eulerlabs.com/)
+/// @notice Contract implements read only ERC20 interface, and `Transfer` events, for EVault's debt
 contract DToken is IERC20, Errors, Events {
     address public immutable eVault;
 

src/EVault/Dispatch.sol

@@ -15,6 +15,9 @@ import {RiskManagerModule} from "./modules/RiskManager.sol";
 
 import "./shared/Constants.sol";
 
+/// @title Dispatch
+/// @author Euler Labs (https://www.eulerlabs.com/)
+/// @notice Contract which ties in the EVault modules and provides utilities for routing calls to modules and the EVC
 abstract contract Dispatch is
     Base,
     InitializeModule,
@@ -78,6 +81,9 @@ abstract contract Dispatch is
         }
     }
 
+    // External function which is only callable by the EVault itself. Its purpose is to be static called by `delegateToModuleView`
+    // which allows view functions to be implemented in modules, even though delegatecall cannot be directly used within
+    // view functions.
     function viewDelegate() external {
         if (msg.sender != address(this)) revert E_Unauthorized();
 

src/EVault/EVault.sol

@@ -4,17 +4,25 @@ pragma solidity ^0.8.0;
 
 import {Dispatch} from "./Dispatch.sol";
 
+/// @title EVault
+/// @author Euler Labs (https://www.eulerlabs.com/)
+/// @notice This contract implements an EVC enabled lending vault
+/// @dev The responsibility of this contract is call routing. Select functions are embedded, while most are delegated to the modules.
 contract EVault is Dispatch {
     constructor(Integrations memory integrations, DeployedModules memory modules) Dispatch(integrations, modules) {}
 
 
-    // ------------ Initialization -------------
+    ///////////////////////////////////////////////////////////////////////////////////////////////
+    //                                     INITIALIZATION                                        //
+    ///////////////////////////////////////////////////////////////////////////////////////////////
 
     function initialize(address proxyCreator) public virtual override use(MODULE_INITIALIZE) {}
 
 
 
-    // ----------------- Token -----------------
+    ///////////////////////////////////////////////////////////////////////////////////////////////
+    //                                         TOKEN                                             //
+    ///////////////////////////////////////////////////////////////////////////////////////////////
 
     function name() public view virtual override useView(MODULE_TOKEN) returns (string memory) {}
 
@@ -39,7 +47,9 @@ contract EVault is Dispatch {
 
 
 
-    // ----------------- Vault -----------------
+    ///////////////////////////////////////////////////////////////////////////////////////////////
+    //                                         VAULT                                             //
+    ///////////////////////////////////////////////////////////////////////////////////////////////
 
     function asset() public view virtual override returns (address) { return super.asset(); }
 
@@ -84,7 +94,9 @@ contract EVault is Dispatch {
 
 
 
-    // ----------------- Borrowing -----------------
+    ///////////////////////////////////////////////////////////////////////////////////////////////
+    //                                        BORROWING                                          //
+    ///////////////////////////////////////////////////////////////////////////////////////////////
 
     function totalBorrows() public view virtual override useView(MODULE_BORROWING) returns (uint256) {}
 
@@ -121,15 +133,19 @@ contract EVault is Dispatch {
 
 
 
-    // ----------------- Liquidation -----------------
+    ///////////////////////////////////////////////////////////////////////////////////////////////
+    //                                     LIQUIDATION                                           //
+    ///////////////////////////////////////////////////////////////////////////////////////////////
 
     function checkLiquidation(address liquidator, address violator, address collateral) public view virtual override useView(MODULE_LIQUIDATION) returns (uint256 maxRepay, uint256 maxYield) {}
 
     function liquidate(address violator, address collateral, uint256 repayAssets, uint256 minYieldBalance) public virtual override callThroughEVC use(MODULE_LIQUIDATION) {}
 
 
 
-    // ----------------- RiskManager -----------------
+    ///////////////////////////////////////////////////////////////////////////////////////////////
+    //                                    RISK MANAGEMENT                                        //
+    ///////////////////////////////////////////////////////////////////////////////////////////////
 
     function accountLiquidity(address account, bool liquidation) public view virtual override useView(MODULE_RISKMANAGER) returns (uint256 collateralValue, uint256 liabilityValue) {}
 
@@ -144,7 +160,9 @@ contract EVault is Dispatch {
 
 
 
-    // ----------------- Balance Forwarder -----------------
+    ///////////////////////////////////////////////////////////////////////////////////////////////
+    //                                   BALANCE TRACKING                                        //
+    ///////////////////////////////////////////////////////////////////////////////////////////////
 
     function balanceTrackerAddress() public view virtual override useView(MODULE_BALANCE_FORWARDER) returns (address) {}
 
@@ -157,7 +175,9 @@ contract EVault is Dispatch {
 
 
 
-    // ----------------- Governance -----------------
+    ///////////////////////////////////////////////////////////////////////////////////////////////
+    //                                     GOVERNANCE                                            //
+    ///////////////////////////////////////////////////////////////////////////////////////////////
 
     function governorAdmin() public view virtual override useView(MODULE_GOVERNANCE) returns (address) {}
 

src/EVault/IEVault.sol

@@ -6,12 +6,16 @@ import {IVault as IEVCVault} from "ethereum-vault-connector/interfaces/IVault.so
 
 // Full interface of EVault and all it's modules
 
+/// @title IInitialize
+/// @notice Interface of the initialization module of EVault
 interface IInitialize {
     /// @notice Initialization of the newly deployed proxy contract
     /// @param proxyCreator Account which created the proxy or should be the initial governor
     function initialize(address proxyCreator) external;
 }
 
+/// @title IERC20
+/// @notice Interface of the EVault's Initialize module
 interface IERC20 {
     /// @notice Vault share token (eToken) name, ie "Euler Vault: DAI"
     function name() external view returns (string memory);
@@ -50,13 +54,17 @@ interface IERC20 {
     function approve(address spender, uint256 amount) external returns (bool);
 }
 
+/// @title IToken
+/// @notice Interface of the EVault's Token module
 interface IToken is IERC20 {
     /// @notice Transfer the full eToken balance of an address to another
     /// @param from This address must've approved the to address
     /// @param to Recipient account
     function transferFromMax(address from, address to) external returns (bool);
 }
 
+/// @title IERC4626
+/// @notice Interface of an ERC4626 vault
 interface IERC4626 {
     /// @notice Vault underlying asset
     function asset() external view returns (address);
@@ -134,6 +142,8 @@ interface IERC4626 {
     function redeem(uint256 amount, address receiver, address owner) external returns (uint256);
 }
 
+/// @title IVault
+/// @notice Interface of the EVault's Vault module
 interface IVault is IERC4626 {
     /// @notice Balance of the fees accumulator, in eTokens
     function accumulatedFees() external view returns (uint256);
@@ -152,6 +162,8 @@ interface IVault is IERC4626 {
     function skim(uint256 amount, address receiver) external returns (uint256);
 }
 
+/// @title IBorrowing
+/// @notice Interface of the EVault's Borrowing module
 interface IBorrowing {
     /// @notice Sum of all outstanding debts, in underlying units (increases as interest is accrued)
     function totalBorrows() external view returns (uint256);
@@ -223,6 +235,8 @@ interface IBorrowing {
     function touch() external;
 }
 
+/// @title ILiquidation
+/// @notice Interface of the EVault's Liquidation module
 interface ILiquidation {
     /// @notice Checks to see if a liquidation would be profitable, without actually doing anything
     /// @param liquidator Address that will initiate the liquidation
@@ -243,6 +257,8 @@ interface ILiquidation {
     function liquidate(address violator, address collateral, uint256 repayAssets, uint256 minYieldBalance) external;
 }
 
+/// @title IRiskManager
+/// @notice Interface of the EVault's RiskManager module
 interface IRiskManager is IEVCVault {
     /// @notice Retrieve account's total liquidity
     /// @param account Account holding debt in this vault
@@ -280,6 +296,8 @@ interface IRiskManager is IEVCVault {
     function checkVaultStatus() external returns (bytes4);
 }
 
+/// @title IBalanceForwarder
+/// @notice Interface of the EVault's BalanceForwarder module
 interface IBalanceForwarder {
     /// @notice Retrieve the address of rewards contract, tracking changes in account's balances
     function balanceTrackerAddress() external view returns (address);
@@ -298,6 +316,8 @@ interface IBalanceForwarder {
     function disableBalanceForwarder() external;
 }
 
+/// @title IGovernance
+/// @notice Interface of the EVault's Governance module
 interface IGovernance {
     /// @notice Retrieves the address of the governor
     function governorAdmin() external view returns (address);
@@ -408,6 +428,8 @@ interface IGovernance {
     function setInterestFee(uint16 newFee) external;
 }
 
+/// @title IEVault
+/// @notice Interface of the EVault, an EVC enabled lending vault
 interface IEVault is
     IInitialize,
     IToken,

src/EVault/modules/BalanceForwarder.sol

@@ -5,6 +5,9 @@ pragma solidity ^0.8.0;
 import {IBalanceForwarder} from "../IEVault.sol";
 import {Base} from "../shared/Base.sol";
 
+/// @title BalanceForwarderModule
+/// @author Euler Labs (https://www.eulerlabs.com/)
+/// @notice An EVault module handling communication a with balance tracker contract.
 abstract contract BalanceForwarderModule is IBalanceForwarder, Base {
     /// @inheritdoc IBalanceForwarder
     function balanceTrackerAddress() public view virtual reentrantOK returns (address) {
@@ -13,15 +16,15 @@ abstract contract BalanceForwarderModule is IBalanceForwarder, Base {
 
     /// @inheritdoc IBalanceForwarder
     function balanceForwarderEnabled(address account) public view virtual reentrantOK returns (bool) {
-        return vaultStorage.users[account].getBalanceForwarderEnabled();
+        return vaultStorage.users[account].isBalanceForwarderEnabled();
     }
 
     /// @inheritdoc IBalanceForwarder
     function enableBalanceForwarder() public virtual reentrantOK {
         if (address(balanceTracker) == address(0)) revert E_BalanceForwarderUnsupported();
 
         address account = EVCAuthenticate();
-        bool wasBalanceForwarderEnabled = vaultStorage.users[account].getBalanceForwarderEnabled();
+        bool wasBalanceForwarderEnabled = vaultStorage.users[account].isBalanceForwarderEnabled();
 
         vaultStorage.users[account].setBalanceForwarder(true);
         balanceTracker.balanceTrackerHook(account, vaultStorage.users[account].getBalance().toUint(), false);
@@ -34,7 +37,7 @@ abstract contract BalanceForwarderModule is IBalanceForwarder, Base {
         if (address(balanceTracker) == address(0)) revert E_BalanceForwarderUnsupported();
 
         address account = EVCAuthenticate();
-        bool wasBalanceForwarderEnabled = vaultStorage.users[account].getBalanceForwarderEnabled();
+        bool wasBalanceForwarderEnabled = vaultStorage.users[account].isBalanceForwarderEnabled();
 
         vaultStorage.users[account].setBalanceForwarder(false);
         balanceTracker.balanceTrackerHook(account, 0, false);
@@ -43,6 +46,7 @@ abstract contract BalanceForwarderModule is IBalanceForwarder, Base {
     }
 }
 
+/// @dev Deployable module contract
 contract BalanceForwarder is BalanceForwarderModule {
     constructor(Integrations memory integrations) Base(integrations) {}
 }

src/EVault/modules/Borrowing.sol

@@ -17,6 +17,9 @@ interface IFlashLoan {
     function onFlashLoan(bytes memory data) external;
 }
 
+/// @title BorrowingModule
+/// @author Euler Labs (https://www.eulerlabs.com/)
+/// @notice An EVault module handling borrowing and repaying of vault assets
 abstract contract BorrowingModule is IBorrowing, Base, AssetTransfers, BalanceUtils, LiquidityUtils {
     using TypesLib for uint256;
     using SafeERC20Lib for IERC20;
@@ -226,6 +229,7 @@ abstract contract BorrowingModule is IBorrowing, Base, AssetTransfers, BalanceUt
     }
 }
 
+/// @dev Deployable module contract
 contract Borrowing is BorrowingModule {
     constructor(Integrations memory integrations) Base(integrations) {}
 }

src/EVault/modules/Governance.sol

@@ -12,6 +12,9 @@ import {ProxyUtils} from "../shared/lib/ProxyUtils.sol";
 
 import "../shared/types/Types.sol";
 
+/// @title GovernanceModule
+/// @author Euler Labs (https://www.eulerlabs.com/)
+/// @notice An EVault module handling governance, including configuration and fees
 abstract contract GovernanceModule is IGovernance, Base, BalanceUtils, BorrowUtils, LTVUtils {
     using TypesLib for uint16;
 
@@ -285,6 +288,7 @@ abstract contract GovernanceModule is IGovernance, Base, BalanceUtils, BorrowUti
     }
 }
 
+/// @dev Deployable module contract
 contract Governance is GovernanceModule {
     constructor(Integrations memory integrations) Base(integrations) {}
 }

src/EVault/modules/Initialize.sol

@@ -12,6 +12,9 @@ import {VaultCache} from "../shared/types/VaultCache.sol";
 import "../shared/Constants.sol";
 import "../shared/types/Types.sol";
 
+/// @title InitializeModule
+/// @author Euler Labs (https://www.eulerlabs.com/)
+/// @notice An EVault module implementing the initialization of the new vault contract
 abstract contract InitializeModule is IInitialize, Base, BorrowUtils {
     using TypesLib for uint16;
 
@@ -57,6 +60,7 @@ abstract contract InitializeModule is IInitialize, Base, BorrowUtils {
     }
 }
 
+/// @dev Deployable module contract
 contract Initialize is InitializeModule {
     constructor(Integrations memory integrations) Base(integrations) {}
 }

src/EVault/modules/Liquidation.sol

@@ -9,6 +9,9 @@ import {LiquidityUtils} from "../shared/LiquidityUtils.sol";
 
 import "../shared/types/Types.sol";
 
+/// @title LiquidationModule
+/// @author Euler Labs (https://www.eulerlabs.com/)
+/// @notice An EVault module handling liquidations of unhealthy accounts
 abstract contract LiquidationModule is ILiquidation, Base, BalanceUtils, LiquidityUtils {
     using TypesLib for uint256;
 
@@ -216,6 +219,7 @@ abstract contract LiquidationModule is ILiquidation, Base, BalanceUtils, Liquidi
     }
 }
 
+/// @dev Deployable module contract
 contract Liquidation is LiquidationModule {
     constructor(Integrations memory integrations) Base(integrations) {}
 }

src/EVault/modules/RiskManager.sol

@@ -8,6 +8,9 @@ import {LiquidityUtils} from "../shared/LiquidityUtils.sol";
 
 import "../shared/types/Types.sol";
 
+/// @title RiskManagerModule
+/// @author Euler Labs (https://www.eulerlabs.com/)
+/// @notice An EVault module handling risk management, including vault and account health checks
 abstract contract RiskManagerModule is IRiskManager, Base, LiquidityUtils {
     using TypesLib for uint256;
 
@@ -113,6 +116,7 @@ abstract contract RiskManagerModule is IRiskManager, Base, LiquidityUtils {
     }
 }
 
+/// @dev Deployable module contract
 contract RiskManager is RiskManagerModule {
     constructor(Integrations memory integrations) Base(integrations) {}
 }

src/EVault/modules/Token.sol

@@ -9,6 +9,9 @@ import {ProxyUtils} from "../shared/lib/ProxyUtils.sol";
 
 import "../shared/types/Types.sol";
 
+/// @title TokenModule
+/// @author Euler Labs (https://www.eulerlabs.com/)
+/// @notice An EVault module handling ERC20 behaviour of vault shares
 abstract contract TokenModule is IToken, Base, BalanceUtils {
     using TypesLib for uint256;
 
@@ -79,6 +82,7 @@ abstract contract TokenModule is IToken, Base, BalanceUtils {
     }
 }
 
+/// @dev Deployable module contract
 contract Token is TokenModule {
     constructor(Integrations memory integrations) Base(integrations) {}
 }

src/EVault/modules/Vault.sol

@@ -11,6 +11,9 @@ import {ProxyUtils} from "../shared/lib/ProxyUtils.sol";
 
 import "../shared/types/Types.sol";
 
+/// @title VaultModule
+/// @author Euler Labs (https://www.eulerlabs.com/)
+/// @notice An EVault module handling ERC4626 standard behaviour
 abstract contract VaultModule is IVault, Base, AssetTransfers, BalanceUtils {
     using TypesLib for uint256;
     using SafeERC20Lib for IERC20;
@@ -267,6 +270,7 @@ abstract contract VaultModule is IVault, Base, AssetTransfers, BalanceUtils {
     }
 }
 
+/// @dev Deployable module contract
 contract Vault is VaultModule {
     constructor(Integrations memory integrations) Base(integrations) {}
 }