@ensuro/core 2.0.0-beta8 → 2.0.0

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

@@ -54,6 +54,23 @@ contract TrustfulRiskModule is RiskModule {
     );
   }
 
+  /**
+   * @dev Creates a new Policy
+   *
+   * Requirements:
+   * - The caller has been granted componentRole(PRICER_ROLE)
+   *
+   * Emits:
+   * - {PolicyPool.NewPolicy}
+   *
+   * @param payout The exposure (maximum payout) of the policy
+   * @param premium The premium that will be paid by the policyHolder
+   * @param lossProb The probability of having to pay the maximum payout (wad)
+   * @param expiration The expiration of the policy (timestamp)
+   * @param onBehalfOf The policy holder
+   * @param internalId An id that's unique within this module and it will be used to identify the policy
+   * @return Returns the id of the created policy
+   */
   function newPolicy(
     uint256 payout,
     uint256 premium,
@@ -62,10 +79,60 @@ contract TrustfulRiskModule is RiskModule {
     address onBehalfOf,
     uint96 internalId
   ) external onlyComponentRole(PRICER_ROLE) returns (uint256) {
-    address payer = onBehalfOf;
-    if (payer != msg.sender && _policyPool.currency().allowance(payer, msg.sender) < premium)
+    return
+      _newPolicy(
+        payout,
+        premium,
+        lossProb,
+        expiration,
+        _getPayer(onBehalfOf, premium),
+        onBehalfOf,
+        internalId
+      ).id;
+  }
+
+  /**
+   * @dev Creates a new Policy. Version that returns all the PolicyData struct, not just the id.
+   *
+   * Requirements:
+   * - The caller has been granted componentRole(PRICER_ROLE)
+   *
+   * Emits:
+   * - {PolicyPool.NewPolicy}
+   *
+   * @param payout The exposure (maximum payout) of the policy
+   * @param premium The premium that will be paid by the policyHolder
+   * @param lossProb The probability of having to pay the maximum payout (wad)
+   * @param expiration The expiration of the policy (timestamp)
+   * @param onBehalfOf The policy holder
+   * @param internalId An id that's unique within this module and it will be used to identify the policy
+   * @return createdPolicy Returns the id of the created policy
+   */
+  function newPolicyFull(
+    uint256 payout,
+    uint256 premium,
+    uint256 lossProb,
+    uint40 expiration,
+    address onBehalfOf,
+    uint96 internalId
+  ) external onlyComponentRole(PRICER_ROLE) returns (Policy.PolicyData memory createdPolicy) {
+    return
+      _newPolicy(
+        payout,
+        premium,
+        lossProb,
+        expiration,
+        _getPayer(onBehalfOf, premium),
+        onBehalfOf,
+        internalId
+      );
+  }
+
+  function _getPayer(address onBehalfOf, uint256 premium) internal view returns (address payer) {
+    payer = onBehalfOf;
+    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,11 +142,24 @@ 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;
-
-    return _newPolicy(payout, premium, lossProb, expiration, payer, onBehalfOf, internalId).id;
+      payer = _msgSender();
+    return payer;
   }
 
+  /**
+   * @dev Resolves a policy, if payout > 0, it pays to the policy holder.
+   *
+   * Requirements:
+   * - The caller has been granted componentRole(RESOLVER_ROLE)
+   * - payout <= policy.payout
+   * - block.timestamp >= policy.expiration
+   *
+   * Emits:
+   * - {PolicyPool.PolicyResolved}
+   *
+   * @param policy The policy previously created (from {NewPolicy} event)
+   * @param payout The payout to transfer to the policy holder
+   */
   function resolvePolicy(Policy.PolicyData calldata policy, uint256 payout)
     external
     onlyComponentRole(RESOLVER_ROLE)
@@ -88,6 +168,20 @@ contract TrustfulRiskModule is RiskModule {
     _policyPool.resolvePolicy(policy, payout);
   }
 
+  /**
+   * @dev Resolves a policy with full payout (policy.payout) if customerWon == true
+   *
+   * Requirements:
+   * - The caller has been granted componentRole(RESOLVER_ROLE)
+   * - block.timestamp >= policy.expiration
+   *
+   * Emits:
+   * - {PolicyPool.PolicyResolved}
+   *
+   * @param policy The policy previously created (from {NewPolicy} event)
+   * @param customerWon If true, policy.payout is transferred to the policy holder. If false, the policy is resolved
+   * without payout and can't be longer claimed.
+   */
   function resolvePolicyFullPayout(Policy.PolicyData calldata policy, bool customerWon)
     external
     onlyComponentRole(RESOLVER_ROLE)
@@ -95,4 +189,11 @@ contract TrustfulRiskModule is RiskModule {
   {
     _policyPool.resolvePolicyFullPayout(policy, customerWon);
   }
+
+  /**
+   * @dev This empty reserved space is put in place to allow future versions to add new
+   * variables without shifting down storage in the inheritance chain.
+   * See https://docs.openzeppelin.com/contracts/4.x/upgradeable#storage_gaps
+   */
+  uint256[50] private __gap;
 }

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

@@ -1,22 +1,89 @@
 // SPDX-License-Identifier: Apache-2.0
 pragma solidity ^0.8.0;
 
+import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
+
 /**
  * @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.
+ *
+ *      All implementations of this contract should use the Diamond Storage pattern to avoid overwriting the calling contract's state.
+ *      See https://eips.ethereum.org/EIPS/eip-2535#storage
  * @author Ensuro
  */
-interface IAssetManager {
+interface IAssetManager is IERC165 {
+  /**
+   * @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 enough money to do a payment. Called from the reserve when a payment needs
+   * to be made and there's no enough 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,24 @@ interface IPolicyPool {
    */
   function expirePolicy(Policy.PolicyData calldata policy) external;
 
+  /**
+   * @dev Returns whether a policy is active, i.e., it's still in the PolicyPool, not yet resolved or expired.
+   *      Be aware that a policy might be active but the `block.timestamp` might be after the expiration date, so it
+   *      can't be triggered with a payout.
+   *
+   * @param policyId The id of the policy queried
+   * @return Whether the policy is active or not
+   */
+  function isActive(uint256 policyId) external view returns (bool);
+
+  /**
+   * @dev Returns the stored hash of the policy. It's `bytes32(0)` is the policy isn't active.
+   *
+   * @param policyId The id of the policy queried
+   * @return Returns the hash of a given policy id
+   */
+  function getPolicyHash(uint256 policyId) external view returns (bytes32);
+
   /**
    * @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.
@@ -130,7 +148,7 @@ interface IPolicyPool {
    *
    * @param eToken The address of the eToken from where the user wants to withdraw liquidity
    * @param amount The amount to withdraw. If equal to type(uint256).max, means full withdrawal.
-   *               If the balance is not enought or can't be withdrawn (locked as SCR), it withdraws
+   *               If the balance is not enough or can't be withdrawn (locked as SCR), it withdraws
    *               as much as it can, but doesn't fails.
    * @return Returns the actual amount withdrawn.
    */