Merge pull request #27 from euler-xyz/cantina-docs-fixes

Cantina docs fixes

src/EVault/Dispatch.sol

@@ -60,6 +60,9 @@ abstract contract Dispatch is
         address governance;
     }
 
+    /// @notice EVault's constructor
+    /// @dev It is highly recommended to deploy fresh modules for every new EVault deployment. Particular care must
+    /// also be taken to ensure the modules are deployed with the exact same values of the `Integrations` struct.
     constructor(Integrations memory integrations, DeployedModules memory modules) Base(integrations) {
         MODULE_INITIALIZE = AddressUtils.checkContract(modules.initialize);
         MODULE_TOKEN = AddressUtils.checkContract(modules.token);

src/EVault/IEVault.sol

@@ -245,6 +245,8 @@ interface IBorrowing {
     /// @return shares Amount of shares burned
     /// @return debt Amount of debt removed in assets
     /// @dev Equivalent to withdrawing and repaying, but no assets are needed to be present in the vault
+    /// @dev Contrary to a regular `repay`, if account is unhealthy, the repay amount must bring the account back to
+    /// health, or the operation will revert during account status check
     function repayWithShares(uint256 amount, address receiver) external returns (uint256 shares, uint256 debt);
 
     /// @notice Take over debt from another account
@@ -285,9 +287,11 @@ interface ILiquidation {
     /// @param violator Address that may be in collateral violation
     /// @param collateral Collateral which is to be seized
     /// @param repayAssets The amount of underlying debt to be transferred from violator to sender, in asset units (use
-    /// max uint256 to repay the maximum possible amount).
+    /// max uint256 to repay the maximum possible amount). Meant as slippage check together with `minYieldBalance`
     /// @param minYieldBalance The minimum acceptable amount of collateral to be transferred from violator to sender, in
-    /// collateral balance units (shares for vaults)
+    /// collateral balance units (shares for vaults).  Meant as slippage check together with `repayAssets`
+    /// @dev If `repayAssets` is set to max uint256 it is assumed the caller will perform their own slippage checks to
+    /// make sure they are not taking on too much debt. This option is mainly meant for smart contract liquidators
     function liquidate(address violator, address collateral, uint256 repayAssets, uint256 minYieldBalance) external;
 }
 
@@ -382,7 +386,7 @@ interface IGovernance {
     function protocolConfigAddress() external view returns (address);
 
     /// @notice Retrieves the protocol fee share
-    /// @return A percentage share of fees accrued belonging to the protocol. In wad scale (1e18)
+    /// @return A percentage share of fees accrued belonging to the protocol, in 1e4 scale
     function protocolFeeShare() external view returns (uint256);
 
     /// @notice Retrieves the address which will receive protocol's fees
@@ -432,6 +436,9 @@ interface IGovernance {
 
     /// @notice Retrieves the maximum liquidation discount
     /// @return The maximum liquidation discount in 1e4 scale
+    /// @dev The default value, which is zero, is deliberately bad, as it means there would be no incentive to liquidate
+    /// unhealthy users. The vault creator must take care to properly select the limit, given the underlying and
+    /// collaterals used.
     function maxLiquidationDiscount() external view returns (uint16);
 
     /// @notice Retrieves liquidation cool-off time, which must elapse after successful account status check before
@@ -499,6 +506,8 @@ interface IGovernance {
 
     /// @notice Set a new interest rate model contract
     /// @param newModel The new IRM address
+    /// @dev If the new model reverts, perhaps due to governor error, the vault will silently use a zero interest
+    /// rate. Governor should make sure the new interest rates are computed as expected.
     function setInterestRateModel(address newModel) external;
 
     /// @notice Set a new hook target and a new bitmap indicating which operations should call the hook target.

src/EVault/modules/RiskManager.sol

@@ -109,6 +109,8 @@ abstract contract RiskManagerModule is IRiskManager, LiquidityUtils {
             // Borrows are rounded down, because total assets could increase during repays.
             // This could happen when repaid user debt is rounded up to assets and used to increase cash,
             // while totalBorrows would be adjusted by only the exact debt, less than the increase in cash.
+            // If multiple accounts need to repay while the supply cap is exceeded they should do so in
+            // separate batches.
             uint256 supply = vaultCache.cash.toUint() + vaultCache.totalBorrows.toAssetsDown().toUint();
 
             if (supply > vaultCache.supplyCap && supply > prevSupply) revert E_SupplyCapExceeded();

src/EVault/shared/AssetTransfers.sol

@@ -20,15 +20,16 @@ abstract contract AssetTransfers is Base {
         vaultStorage.cash = vaultCache.cash = vaultCache.cash + amount;
     }
 
-    /// @dev If the `CFG_EVC_COMPATIBLE_ASSET` flag is set, the function will protect users from mistakenly sending
-    /// funds to the EVC sub-accounts. Functions that push tokens out (`withdraw`, `redeem`, `borrow`) accept a
-    /// `receiver` argument. If the user sets one of their sub-accounts (not the owner) as the receiver, funds would be
-    /// lost because a regular asset doesn't support the EVC's sub-accounts. The private key to a sub-account (not the
-    /// owner) is not known, so the user would not be able to move the funds out. The function will make a best effort
-    /// to prevent this by checking if the receiver of the token is recognized by EVC as a non-owner sub-account. In
-    /// other words, if there is an account registered in EVC as the owner for the intended receiver, the transfer will
-    /// be prevented. However, there is no guarantee that EVC will have the owner registered. If the asset itself is
-    /// compatible with EVC, it is safe to not set the flag and send the asset to a non-owner sub-account.
+    /// @dev If the `CFG_EVC_COMPATIBLE_ASSET` flag is not set (default), the function will protect users from
+    /// mistakenly sending funds to the EVC sub-accounts. Functions that push tokens out (`withdraw`, `redeem`,
+    /// `borrow`) accept a `receiver` argument. If the user sets one of their sub-accounts (not the owner) as the
+    /// receiver, funds would be lost because a regular asset doesn't support the EVC's sub-accounts. The private key to
+    /// a sub-account (not the owner) is not known, so the user would not be able to move the funds out. The function
+    /// will make a best effort to prevent this by checking if the receiver of the token is recognized by EVC as a
+    /// non-owner sub-account. In other words, if there is an account registered in EVC as the owner for the intended
+    /// receiver, the transfer will be prevented. However, there is no guarantee that EVC will have the owner
+    /// registered. If the asset itself is compatible with EVC, it is safe to set the flag and send the asset to a
+    /// non-owner sub-account.
     function pushAssets(VaultCache memory vaultCache, address to, Assets amount) internal virtual {
         if (
             to == address(0)

src/EVault/shared/LiquidityUtils.sol

@@ -30,9 +30,9 @@ abstract contract LiquidityUtils is BorrowUtils, LTVUtils {
         liabilityValue = getLiabilityValue(vaultCache, account, vaultStorage.users[account].getOwed(), liquidation);
     }
 
-    // Check that the value of the collateral, adjusted for borrowing LTV, is equal or greater than the liability value.
-    // Since this function uses bid/ask prices, it should only be used within the account status check, and not
-    // for determining whether an account can be liquidated (which uses mid-point prices).
+    // Check that there is no liability, or the value of the collateral, adjusted for borrowing LTV, is greater than the
+    // liability value. Since this function uses bid/ask prices, it should only be used within the account status check,
+    // and not for determining whether an account can be liquidated (which uses mid-point prices).
     function checkLiquidity(VaultCache memory vaultCache, address account, address[] memory collaterals)
         internal
         view

src/Synths/EulerSavingsRate.sol

@@ -84,12 +84,12 @@ contract EulerSavingsRate is EVCUtil, ERC4626 {
         return super.mint(shares, receiver);
     }
 
-    /// @notice Withdraws a certain amount of assets to the vault.
+    /// @notice Withdraws a certain amount of assets from the vault.
     /// @dev Overwritten to update the accrued interest and update _totalAssets.
     /// @param assets The amount of assets to withdraw.
-    /// @param receiver The recipient of the shares.
-    /// @param owner The account from which the assets are withdrawn
-    /// @return The amount of shares minted.
+    /// @param receiver The recipient of the assets.
+    /// @param owner The holder of shares to burn.
+    /// @return The amount of shares burned.
     function withdraw(uint256 assets, address receiver, address owner) public override nonReentrant returns (uint256) {
         // Move interest to totalAssets
         updateInterestAndReturnESRSlotCache();

src/Synths/IRMSynth.sol

@@ -43,15 +43,15 @@ contract IRMSynth is IIRM {
 
     event InterestUpdated(uint256 rate);
 
-    constructor(address synth_, address referenceAsset_, address oracle_, uint256 targetQuoute_) {
+    constructor(address synth_, address referenceAsset_, address oracle_, uint256 targetQuote_) {
         if (synth_ == address(0) || referenceAsset_ == address(0) || oracle_ == address(0)) {
             revert E_ZeroAddress();
         }
 
         synth = synth_;
         referenceAsset = referenceAsset_;
         oracle = IPriceOracle(oracle_);
-        targetQuote = targetQuoute_;
+        targetQuote = targetQuote_;
         quoteAmount = 10 ** IERC20(synth_).decimals();
 
         // Refusing to proceed with worthless asset
@@ -101,7 +101,7 @@ contract IRMSynth is IIRM {
             // If the quote is less than the target, increase the rate
             rate = rate * ADJUST_FACTOR / ADJUST_ONE;
         } else {
-            // If the quote is greater than the target, decrease the rate
+            // If the quote is greater than or equal to the target, decrease the rate
             rate = rate * ADJUST_ONE / ADJUST_FACTOR;
         }