@ensuro/core 2.0.0-beta8 → 2.0.0-beta9

package/contracts/TimeScaled.sol

@@ -2,7 +2,8 @@
 
 pragma solidity ^0.8.0;
 
-import {WadRayMath} from "./WadRayMath.sol";
+import {WadRayMath} from "./dependencies/WadRayMath.sol";
+import {SafeCast} from "@openzeppelin/contracts/utils/math/SafeCast.sol";
 
 /**
  * @title TimeScaled
@@ -12,13 +13,15 @@ import {WadRayMath} from "./WadRayMath.sol";
  */
 library TimeScaled {
   using WadRayMath for uint256;
+  using SafeCast for uint256;
 
-  uint256 internal constant SECONDS_PER_YEAR = 365 days;
-  uint128 public constant MIN_SCALE = 1e17; // 0.0000000001 == 1e-10 in ray
+  uint256 private constant SECONDS_PER_YEAR = 365 days;
+  uint112 private constant MIN_SCALE = 1e17; // 0.0000000001 == 1e-10 in ray
+  uint112 private constant RAY112 = 1e27;
 
   struct ScaledAmount {
-    uint128 scale;
-    uint96 amount;
+    uint112 scale;
+    uint112 amount;
     uint32 lastUpdate;
   }
 
@@ -27,7 +30,7 @@ library TimeScaled {
     if (scaledAmount.amount == 0) {
       scaledAmount.lastUpdate = uint32(block.timestamp);
     } else {
-      scaledAmount.scale = uint128(getScale(scaledAmount, interestRate));
+      scaledAmount.scale = getScale(scaledAmount, interestRate).toUint112();
       scaledAmount.lastUpdate = uint32(block.timestamp);
     }
   }
@@ -44,7 +47,7 @@ library TimeScaled {
     uint256 timeDifference = uint256(now_ - scaledAmount.lastUpdate);
     return
       uint256(scaledAmount.scale).rayMul(
-        ((interestRate.wadToRay() * timeDifference) / SECONDS_PER_YEAR) + WadRayMath.ray()
+        ((interestRate.wadToRay() * timeDifference) / SECONDS_PER_YEAR) + WadRayMath.RAY
       );
   }
 
@@ -61,7 +64,7 @@ library TimeScaled {
   }
 
   function init(ScaledAmount storage scaledAmount) internal {
-    scaledAmount.scale = uint128(WadRayMath.ray());
+    scaledAmount.scale = RAY112;
     scaledAmount.amount = 0;
     scaledAmount.lastUpdate = uint32(block.timestamp);
   }
@@ -89,7 +92,7 @@ library TimeScaled {
   ) internal returns (uint256) {
     updateScale(scaledAmount, interestRate);
     uint256 scaledAdd = scaleAmount(scaledAmount, amount);
-    scaledAmount.amount += uint96(scaledAdd);
+    scaledAmount.amount += scaledAdd.toUint96();
     return scaledAdd;
   }
 
@@ -100,10 +103,10 @@ library TimeScaled {
   ) internal returns (uint256) {
     updateScale(scaledAmount, interestRate);
     uint256 scaledSub = scaleAmount(scaledAmount, amount);
-    scaledAmount.amount -= uint96(scaledSub);
+    scaledAmount.amount -= scaledSub.toUint96();
     if (scaledAmount.amount == 0) {
       // Reset scale if amount == 0
-      scaledAmount.scale = uint128(WadRayMath.ray());
+      scaledAmount.scale = RAY112;
     }
     return scaledSub;
   }
@@ -115,9 +118,10 @@ library TimeScaled {
   ) internal {
     updateScale(scaledAmount, interestRate);
     uint256 newScaledAmount = uint256(int256(getScaledAmount(scaledAmount, interestRate)) + amount);
-    scaledAmount.scale = uint128(
-      newScaledAmount.wadToRay().rayDiv(uint256(scaledAmount.amount).wadToRay())
-    );
+    scaledAmount.scale = newScaledAmount
+      .wadToRay()
+      .rayDiv(uint256(scaledAmount.amount).wadToRay())
+      .toUint112();
     require(scaledAmount.scale >= MIN_SCALE, "Scale too small, can lead to rounding errors");
   }
 
@@ -127,7 +131,7 @@ library TimeScaled {
     returns (uint256)
   {
     uint256 ts = getScaledAmount(scaledAmount, interestRate);
-    uint256 minTs = uint256(scaledAmount.amount).wadToRay().rayMul(MIN_SCALE * 10).rayToWad();
+    uint256 minTs = uint256(scaledAmount.amount).wadToRay().rayMul(MIN_SCALE).rayToWad();
     if (ts > minTs) return ts - minTs;
     else return 0;
   }

package/contracts/TrustfulRiskModule.sol

@@ -63,9 +63,9 @@ contract TrustfulRiskModule is RiskModule {
     uint96 internalId
   ) external onlyComponentRole(PRICER_ROLE) returns (uint256) {
     address payer = onBehalfOf;
-    if (payer != msg.sender && _policyPool.currency().allowance(payer, msg.sender) < premium)
+    if (payer != _msgSender() && _policyPool.currency().allowance(payer, _msgSender()) < premium)
       /**
-       * The standard is the payer should be the msg.sender but usually, in this type of module,
+       * The standard is the payer should be the _msgSender() but usually, in this type of module,
        * the sender is an operative account managed by software, where the onBehalfOf is a more
        * secure account (hardware wallet) that does the cash movements.
        * This non standard behaviour allows for a more secure setup, where the sender never manages
@@ -75,7 +75,7 @@ contract TrustfulRiskModule is RiskModule {
        * Note that this allowance won't be spent, so it can be set as the maximum amount of a single
        * premium even for multiple policies.
        */
-      payer = msg.sender;
+      payer = _msgSender();
 
     return _newPolicy(payout, premium, lossProb, expiration, payer, onBehalfOf, internalId).id;
   }

package/contracts/dependencies/WadRayMath.sol

@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity ^0.8.0;
+
+/**
+ * @title WadRayMath library
+ * @author Aave
+ * @notice Provides functions to perform calculations with Wad and Ray units
+ * @dev Provides mul and div function for wads (decimal numbers with 18 digits of precision) and rays (decimal numbers
+ * with 27 digits of precision)
+ * @dev Operations are rounded. If a value is >=.5, will be rounded up, otherwise rounded down.
+ **/
+library WadRayMath {
+  // HALF_WAD and HALF_RAY expressed with extended notation as constant with operations are not supported in Yul assembly
+  uint256 internal constant WAD = 1e18;
+  uint256 internal constant HALF_WAD = 0.5e18;
+
+  uint256 internal constant RAY = 1e27;
+  uint256 internal constant HALF_RAY = 0.5e27;
+
+  uint256 internal constant WAD_RAY_RATIO = 1e9;
+
+  /**
+   * @dev Multiplies two wad, rounding half up to the nearest wad
+   * @dev assembly optimized for improved gas savings, see https://twitter.com/transmissions11/status/1451131036377571328
+   * @param a Wad
+   * @param b Wad
+   * @return c = a*b, in wad
+   **/
+  function wadMul(uint256 a, uint256 b) internal pure returns (uint256 c) {
+    // to avoid overflow, a <= (type(uint256).max - HALF_WAD) / b
+    assembly {
+      if iszero(or(iszero(b), iszero(gt(a, div(sub(not(0), HALF_WAD), b))))) {
+        revert(0, 0)
+      }
+
+      c := div(add(mul(a, b), HALF_WAD), WAD)
+    }
+  }
+
+  /**
+   * @dev Divides two wad, rounding half up to the nearest wad
+   * @dev assembly optimized for improved gas savings, see https://twitter.com/transmissions11/status/1451131036377571328
+   * @param a Wad
+   * @param b Wad
+   * @return c = a/b, in wad
+   **/
+  function wadDiv(uint256 a, uint256 b) internal pure returns (uint256 c) {
+    // to avoid overflow, a <= (type(uint256).max - halfB) / WAD
+    assembly {
+      if or(iszero(b), iszero(iszero(gt(a, div(sub(not(0), div(b, 2)), WAD))))) {
+        revert(0, 0)
+      }
+
+      c := div(add(mul(a, WAD), div(b, 2)), b)
+    }
+  }
+
+  /**
+   * @notice Multiplies two ray, rounding half up to the nearest ray
+   * @dev assembly optimized for improved gas savings, see https://twitter.com/transmissions11/status/1451131036377571328
+   * @param a Ray
+   * @param b Ray
+   * @return c = a raymul b
+   **/
+  function rayMul(uint256 a, uint256 b) internal pure returns (uint256 c) {
+    // to avoid overflow, a <= (type(uint256).max - HALF_RAY) / b
+    assembly {
+      if iszero(or(iszero(b), iszero(gt(a, div(sub(not(0), HALF_RAY), b))))) {
+        revert(0, 0)
+      }
+
+      c := div(add(mul(a, b), HALF_RAY), RAY)
+    }
+  }
+
+  /**
+   * @notice Divides two ray, rounding half up to the nearest ray
+   * @dev assembly optimized for improved gas savings, see https://twitter.com/transmissions11/status/1451131036377571328
+   * @param a Ray
+   * @param b Ray
+   * @return c = a raydiv b
+   **/
+  function rayDiv(uint256 a, uint256 b) internal pure returns (uint256 c) {
+    // to avoid overflow, a <= (type(uint256).max - halfB) / RAY
+    assembly {
+      if or(iszero(b), iszero(iszero(gt(a, div(sub(not(0), div(b, 2)), RAY))))) {
+        revert(0, 0)
+      }
+
+      c := div(add(mul(a, RAY), div(b, 2)), b)
+    }
+  }
+
+  /**
+   * @dev Casts ray down to wad
+   * @dev assembly optimized for improved gas savings, see https://twitter.com/transmissions11/status/1451131036377571328
+   * @param a Ray
+   * @return b = a converted to wad, rounded half up to the nearest wad
+   **/
+  function rayToWad(uint256 a) internal pure returns (uint256 b) {
+    assembly {
+      b := div(a, WAD_RAY_RATIO)
+      let remainder := mod(a, WAD_RAY_RATIO)
+      if iszero(lt(remainder, div(WAD_RAY_RATIO, 2))) {
+        b := add(b, 1)
+      }
+    }
+  }
+
+  /**
+   * @dev Converts wad up to ray
+   * @dev assembly optimized for improved gas savings, see https://twitter.com/transmissions11/status/1451131036377571328
+   * @param a Wad
+   * @return b = a converted in ray
+   **/
+  function wadToRay(uint256 a) internal pure returns (uint256 b) {
+    // to avoid overflow, b/WAD_RAY_RATIO == a
+    assembly {
+      b := mul(a, WAD_RAY_RATIO)
+
+      if iszero(eq(div(b, WAD_RAY_RATIO), a)) {
+        revert(0, 0)
+      }
+    }
+  }
+}

package/contracts/interfaces/IAccessManager.sol

@@ -9,18 +9,20 @@ import {IAccessControlUpgradeable} from "@openzeppelin/contracts-upgradeable/acc
  * @author Ensuro
  */
 interface IAccessManager is IAccessControlUpgradeable {
+  /**
+   * @dev Enum with the different governance actions supported in the protocol.
+   *      It's good to keep actions of the same component consecutive, parts of the code relay on that,
+   *      so we put some fillers in case new actions are added.
+   */
   enum GovernanceActions {
     none,
     setTreasury, // Changes PolicyPool treasury address
     setAssetManager, // Change in the asset manager strategy of a reserve
-    setInsolvencyHook, // Changes PolicyPool InsolvencyHook
-    setLPWhitelist, // Changes PolicyPool Liquidity Providers Whitelist
-    addRiskModule,
-    removeRiskModule,
     setAssetManagerForced, // Change in the asset manager strategy of a reserve, forced (deinvest failed)
-    cfgFiller2, // Reserve space for future PolicyPoolConfig actions
-    cfgFiller3, // Reserve space for future PolicyPoolConfig actions
-    cfgFiller4, // Reserve space for future PolicyPoolConfig actions
+    ppFiller1, // Reserve space for future PolicyPool or AccessManager actions
+    ppFiller2, // Reserve space for future PolicyPool or AccessManager actions
+    ppFiller3, // Reserve space for future PolicyPool or AccessManager actions
+    ppFiller4, // Reserve space for future PolicyPool or AccessManager actions
     // RiskModule Governance Actions
     setMoc,
     setJrCollRatio,
@@ -38,6 +40,7 @@ interface IAccessManager is IAccessControlUpgradeable {
     rmFiller3, // Reserve space for future RM actions
     rmFiller4, // Reserve space for future RM actions
     // EToken Governance Actions
+    setLPWhitelist, // Changes EToken Liquidity Providers Whitelist
     setLiquidityRequirement,
     setMinUtilizationRate,
     setMaxUtilizationRate,
@@ -46,21 +49,43 @@ interface IAccessManager is IAccessControlUpgradeable {
     etkFiller2, // Reserve space for future EToken actions
     etkFiller3, // Reserve space for future EToken actions
     etkFiller4, // Reserve space for future EToken actions
+    // PremiumsAccount Governance Actions
+    setDeficitRatio,
+    setDeficitRatioWithAdjustment,
+    paFiller1,
+    paFiller2,
+    paFiller3,
+    paFiller4,
     // AssetManager Governance Actions
     setLiquidityMin,
     setLiquidityMiddle,
     setLiquidityMax,
-    // AaveAssetManager Governance Actions
-    setClaimRewardsMin,
-    setReinvestRewardsMin,
-    setMaxSlippage,
-    setPriceOracle, // Changes exchange's PriceOracle
-    setSwapRouter, // Changes exchange's SwapRouter
+    amFiller1, // Reserve space for future Asset Manager actions
+    amFiller2, // Reserve space for future Asset Manager actions
+    amFiller3, // Reserve space for future Asset Manager actions
+    amFiller4, // Reserve space for future Asset Manager actions
     last
   }
 
+  /**
+   * @dev Gets a role identifier mixing the hash of the global role and the address of the component
+   *
+   * @param component The component where this role will apply
+   * @param role A role such as `keccak256("LEVEL1_ROLE")` that's global
+   * @return A new role, mixing (XOR) the component address and the role.
+   */
   function getComponentRole(address component, bytes32 role) external view returns (bytes32);
 
+  /**
+   * @dev Tells if a user has been granted a given role for a component
+   *
+   * @param component The component where this role will apply
+   * @param role A role such as `keccak256("LEVEL1_ROLE")` that's global
+   * @param account The user address for who we want to verify the permission
+   * @param alsoGlobal If true, it will return if the users has either the component role, or the role itself.
+   *                   If false, only the component role is accepted
+   * @return Whether the user has or not any of the roles
+   */
   function hasComponentRole(
     address component,
     bytes32 role,
@@ -68,14 +93,35 @@ interface IAccessManager is IAccessControlUpgradeable {
     bool alsoGlobal
   ) external view returns (bool);
 
+  /**
+   * @dev Checks if a user has been granted a given role and reverts if it doesn't
+   *
+   * @param role A role such as `keccak256("LEVEL1_ROLE")` that's global
+   * @param account The user address for who we want to verify the permission
+   */
   function checkRole(bytes32 role, address account) external view;
 
+  /**
+   * @dev Checks if a user has been granted any of the two roles specified and reverts if it doesn't
+   *
+   * @param role1 A role such as `keccak256("LEVEL1_ROLE")` that's global
+   * @param role2 Another role such as `keccak256("GUARDIAN_ROLE")` that's global
+   * @param account The user address for who we want to verify the permission
+   */
   function checkRole2(
     bytes32 role1,
     bytes32 role2,
     address account
   ) external view;
 
+  /**
+   * @dev Checks if a user has been granted a given component role and reverts if it doesn't
+   *
+   * @param role A role such as `keccak256("LEVEL1_ROLE")` that's global
+   * @param account The user address for who we want to verify the permission
+   * @param alsoGlobal If true, it will accept not only the component role, but also the (global) `role` itself.
+   *                   If false, only the component role is accepted
+   */
   function checkComponentRole(
     address component,
     bytes32 role,
@@ -83,6 +129,15 @@ interface IAccessManager is IAccessControlUpgradeable {
     bool alsoGlobal
   ) external view;
 
+  /**
+   * @dev Checks if a user has been granted any of the two component roles specified and reverts if it doesn't
+   *
+   * @param role1 A role such as `keccak256("LEVEL1_ROLE")` that's global
+   * @param role2 Another role such as `keccak256("GUARDIAN_ROLE")` that's global
+   * @param account The user address for who we want to verify the permission
+   * @param alsoGlobal If true, it will accept not only the component roles, but also the global ones.
+   *                   If false, only the component roles are accepted
+   */
   function checkComponentRole2(
     address component,
     bytes32 role1,

package/contracts/interfaces/IAssetManager.sol

@@ -3,20 +3,82 @@ pragma solidity ^0.8.0;
 
 /**
  * @title IAssetManager - Interface of the asset management strategy that's plugged into the reserves
+ * @dev The asset manager is a contract that's plugged and called with `delegatecall` (operates in the context of the
+ *      reserve - see {Reserve}). The asset manager contract applies a strategy to invest the reserve funds and
+ *      get additional yields.
  * @author Ensuro
  */
 interface IAssetManager {
+  /**
+   * @dev Event emitted when funds are removed from Reserve liquidity and invested in the investment strategy,
+   * @param amount The amount invested
+   */
   event MoneyInvested(uint256 amount);
+
+  /**
+   * @dev Event emitted when funds are deinvested from the investment strategy and returned to the reserve as liquid
+   * funds.
+   *
+   * @param amount The amount de-invested
+   */
   event MoneyDeinvested(uint256 amount);
+
+  /**
+   * @dev Event emitted when investment yields are accounted in the reserve
+   *
+   * @param earnings The amount of earnings generated since last record. It's positive in the case of earnings or
+   * negative when there are losses.
+   */
   event EarningsRecorded(int256 earnings);
 
+  /**
+   * @dev Function called when an asset manager is plugged into a reserve. Useful for initialization tasks
+   */
   function connect() external;
 
+  /**
+   * @dev Gives the opportunity to the asset manager to rebalance the funds between those that are kept liquid in the
+   * reserve balance and those that are invested. Called with delegatecall by the reserve from the external function
+   * rebalance (see {Reserve-rebalance}).
+   *
+   * Events:
+   * - Emits {MoneyInvested} or {MoneyDeinvested}
+   */
   function rebalance() external;
 
+  /**
+   * @dev Gives the opportunity to the asset manager to rebalance the funds between those that are kept liquid in the
+   * reserve balance and those that are invested. Called with delegatecall by the reserve from the external function
+   * rebalance (see {Reserve-rebalance}).
+   *
+   * Events:
+   * - Emits {MoneyInvested} or {MoneyDeinvested}
+   */
   function recordEarnings() external returns (int256);
 
-  function refillWallet(uint256 paymentAmount) external;
+  /**
+   * @dev Refills the reserve balance with enought money to do a payment. Called from the reserve when a payment needs
+   * to be made and there's no enought liquid balance (`currency().balanceOf(reserve) < paymentAmount`)
+   *
+   * Events:
+   * - Emits {MoneyDeinvested} with the amount transferred to the liquid balance.
+   *
+   * @param paymentAmount The total amount of the payment that needs to be made. If this function is called, it's
+   * because paymentAmount > balanceOf(reserve). The minimum amount that needs to be transferred to the reserve is
+   * `paymentAmount - balanceOf(reserve)`, but it can transfer more.
+   * @return Returns the actual amount transferred
+   */
+  function refillWallet(uint256 paymentAmount) external returns (uint256);
 
+  /**
+   * @dev Deinvests all the funds transfer all the assets to the liquid balance. Called from the reserve when the asset
+   * manager is unplugged.
+   *
+   * Events:
+   * - Emits {MoneyDeinvested} with the amount transferred to the liquid balance.
+   * - Emits {EarningsRecorded} with the amount of earnings since earnings were recorded last time.
+   *
+   * @return Returns the earnings or losses (negative) since last time earnings were recorded.
+   */
   function deinvestAll() external returns (int256);
 }

package/contracts/interfaces/IEToken.sol

@@ -9,6 +9,9 @@ import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
  * @author Ensuro
  */
 interface IEToken is IERC20 {
+  /**
+   * @dev Enum of the different parameters that are configurable in an EToken.
+   */
   enum Parameter {
     liquidityRequirement,
     minUtilizationRate,
@@ -84,7 +87,7 @@ interface IEToken is IERC20 {
    *
    * @param provider The address of the liquidity provider
    * @param amount The amount deposited.
-   * @return The actual balance of the provider (TODO)
+   * @return The actual balance of the provider
    */
   function deposit(address provider, uint256 amount) external returns (uint256);
 

package/contracts/interfaces/ILPWhitelist.sol

@@ -8,12 +8,29 @@ import {IEToken} from "./IEToken.sol";
  * @author Ensuro
  */
 interface ILPWhitelist {
+  /**
+   * @dev Indicates whether or not a liquidity provider can do a deposit in an eToken.
+   *
+   * @param etoken The eToken (see {EToken}) where the provider wants to deposit money.
+   * @param provider The address of the liquidity provider (user) that wants to deposit
+   * @param amount The amount of the deposit
+   * @return true if `provider` deposit is accepted, false if not
+   */
   function acceptsDeposit(
     IEToken etoken,
     address provider,
     uint256 amount
   ) external view returns (bool);
 
+  /**
+   * @dev Indicates whether or not the eTokens can be transferred from `providerFrom` to `providerTo`
+   *
+   * @param etoken The eToken (see {EToken}) that the LPs have the intention to transfer.
+   * @param providerFrom The current owner of the tokens
+   * @param providerTo The destination of the tokens if the transfer is accepted
+   * @param amount The amount of tokens to be transferred
+   * @return true if the transfer operation is accepted, false if not.
+   */
   function acceptsTransfer(
     IEToken etoken,
     address providerFrom,

package/contracts/interfaces/IPolicyPool.sol

@@ -100,6 +100,13 @@ interface IPolicyPool {
    */
   function expirePolicy(Policy.PolicyData calldata policy) external;
 
+  /**
+   * @dev Returns whether or not a policy is active
+   * @param policyId The id of the policy we are querying
+   * @return Returns true if a policy with that id was created and wasn't yet resolved or expired, or false otherwise.
+   */
+  function isActive(uint256 policyId) external view returns (bool);
+
   /**
    * @dev Deposits liquidity into an eToken. Forwards the call to {EToken-deposit}, after transferring the funds.
    * The user will receive etokens for the same amount deposited.

package/contracts/interfaces/IPolicyPoolComponent.sol

@@ -9,5 +9,8 @@ import {IPolicyPool} from "./IPolicyPool.sol";
  * @author Ensuro
  */
 interface IPolicyPoolComponent {
+  /**
+   * @dev Returns the address of the PolicyPool (see {PolicyPool}) where this component belongs.
+   */
   function policyPool() external view returns (IPolicyPool);
 }

package/contracts/interfaces/IRiskModule.sol

@@ -9,6 +9,9 @@ import {IPremiumsAccount} from "./IPremiumsAccount.sol";
  * @author Ensuro
  */
 interface IRiskModule {
+  /**
+   * @dev Enum with the different parameters of the risk module, used in {RiskModule-setParam}.
+   */
   enum Parameter {
     moc,
     jrCollRatio,
@@ -22,28 +25,85 @@ interface IRiskModule {
     maxDuration
   }
 
+  /**
+   * Struct of the parameters of the risk module that are used to calculate the different Policy fields (see
+   * {Policy-PolicyData}.
+   */
   struct Params {
+    /**
+     * @dev MoC (Margin of Conservativism) is a factor that multiplies the lossProb to increase or decrease the pure
+     * premium.
+     */
     uint256 moc;
+    /**
+     * @dev Junior Collateralization Ratio is the percentage of policy exposure (payout) that will be covered with the
+     * purePremium and the Junior EToken
+     */
     uint256 jrCollRatio;
+    /**
+     * @dev Collateralization Ratio is the percentage of policy exposure (payout) that will be covered by the
+     * purePremium and the Junior and Senior EToken. Usually is calculated as the relation between VAR99.5% and VAR100
+     * (full collateralization).
+     */
     uint256 collRatio;
+    /**
+     * @dev Ensuro PurePremium Fee is the percentage that will be multiplied by the pure premium to obtain the part of
+     * the Ensuro Fee that's proportional to the pure premium.
+     */
     uint256 ensuroPpFee;
+    /**
+     * @dev Ensuro Cost of Capital Fee is the percentage that will be multiplied by the cost of capital (CoC) to
+     * obtain the part of the Ensuro Fee that's proportional to the CoC.
+     */
     uint256 ensuroCocFee;
+    /**
+     * @dev Junior Return on Capital is the annualized interest rate that's charged for the capital locked in the Junior
+     * EToken.
+     */
     uint256 jrRoc;
+    /**
+     * @dev Senior Return on Capital is the annualized interest rate that's charged for the capital locked in the Senior
+     * EToken.
+     */
     uint256 srRoc;
   }
 
+  /**
+   * @dev A readable name of this risk module. Never changes.
+   */
   function name() external view returns (string memory);
 
+  /**
+   * @dev Returns different parameters of the risk module (see {Params})
+   */
   function params() external view returns (Params memory);
 
-  function maxPayoutPerPolicy() external view returns (uint256);
-
-  function exposureLimit() external view returns (uint256);
-
+  /**
+   * @dev Returns the maximum duration (in hours) of the policies of this risk module.
+   *      The `expiration` of the policies has to be `<= (block.timestamp + 3600 * maxDuration())`
+   */
   function maxDuration() external view returns (uint256);
 
+  /**
+   * @dev Returns the maximum payout accepted for new policies.
+   */
+  function maxPayoutPerPolicy() external view returns (uint256);
+
+  /**
+   * @dev Returns sum of the (maximum) payout of the active policies of this risk module, i.e. the maximum possible
+   * amount of money that's exposed for this risk module.
+   */
   function activeExposure() external view returns (uint256);
 
+  /**
+   * @dev Returns maximum exposure (sum of the (maximum) payout of the active policies) of this risk module.
+   * `activeExposure() <= exposureLimit()` always
+   */
+  function exposureLimit() external view returns (uint256);
+
+  /**
+   * @dev Returns the address of the partner that receives the partnerCommission
+   */
   function wallet() external view returns (address);
 
   /**
@@ -56,5 +116,8 @@ interface IRiskModule {
    */
   function releaseExposure(uint256 payout) external;
 
+  /**
+   * @dev Returns the {PremiumsAccount} where the premiums of this risk module are collected. Never changes.
+   */
   function premiumsAccount() external view returns (IPremiumsAccount);
 }