@ensuro/core 2.0.0-beta8 → 2.0.0-beta9

package/contracts/PolicyPool.sol

@@ -8,7 +8,6 @@ import {ERC721Upgradeable} from "@openzeppelin/contracts-upgradeable/token/ERC72
 import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
 import {IAccessManager} from "./interfaces/IAccessManager.sol";
 import {PausableUpgradeable} from "@openzeppelin/contracts-upgradeable/security/PausableUpgradeable.sol";
-import {EnumerableSet} from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
 import {IPremiumsAccount} from "./interfaces/IPremiumsAccount.sol";
 import {IPolicyPool} from "./interfaces/IPolicyPool.sol";
 import {IRiskModule} from "./interfaces/IRiskModule.sol";
@@ -16,21 +15,22 @@ import {IPolicyPoolComponent} from "./interfaces/IPolicyPoolComponent.sol";
 import {IEToken} from "./interfaces/IEToken.sol";
 import {IPolicyHolder} from "./interfaces/IPolicyHolder.sol";
 import {Policy} from "./Policy.sol";
-import {WadRayMath} from "./WadRayMath.sol";
+import {WadRayMath} from "./dependencies/WadRayMath.sol";
 
 /**
  * @title Ensuro PolicyPool contract
  * @dev This is the main contract of the protocol, it stores the eTokens (liquidity pools) and has the operations
- *      to interact with them. This is also the contract that receives and sends the underlying asset.
+ *      to interact with them. This is also the contract that receives and sends the underlying asset (currency).
  *      Also this contract keeps track of accumulated premiums in different stages:
  *      - activePurePremiums
  *      - wonPurePremiums (surplus)
  *      - borrowedActivePP (deficit borrowed from activePurePremiums)
+ *      This contract also implements the ERC721 standard, because it mints and NFT for each policy created. The
+ *      property of the NFT represents the one that will receive the payout.
  * @custom:security-contact security@ensuro.co
  * @author Ensuro
  */
 contract PolicyPool is IPolicyPool, PausableUpgradeable, UUPSUpgradeable, ERC721Upgradeable {
-  using EnumerableSet for EnumerableSet.AddressSet;
   using WadRayMath for uint256;
   using Policy for Policy.PolicyData;
   using SafeERC20 for IERC20Metadata;
@@ -40,13 +40,26 @@ contract PolicyPool is IPolicyPool, PausableUpgradeable, UUPSUpgradeable, ERC721
   bytes32 public constant LEVEL2_ROLE = keccak256("LEVEL2_ROLE");
   bytes32 public constant LEVEL3_ROLE = keccak256("LEVEL3_ROLE");
 
+  /**
+   * @dev {AccessManager} that handles the access permissions for the PolicyPool and its components.
+   */
   /// @custom:oz-upgrades-unsafe-allow state-variable-immutable
   IAccessManager internal immutable _access;
+
+  /**
+   * @dev {ERC20} token used in PolicyPool as currency. Usually it will be a stablecoin such as USDC.
+   */
   /// @custom:oz-upgrades-unsafe-allow state-variable-immutable
   IERC20Metadata internal immutable _currency;
 
+  /**
+   * @dev Address of Ensuro's treasury that receives the protocol fees.
+   */
   address internal _treasury; // address of Ensuro treasury
 
+  /**
+   * @dev This enum tracks the different status that a component ({PremiumsAccount}, {EToken} or {RiskModule} can have.
+   */
   enum ComponentStatus {
     /**
      * @dev inactive status = 0 means the component doesn't exists - All operations rejected
@@ -73,6 +86,10 @@ contract PolicyPool is IPolicyPool, PausableUpgradeable, UUPSUpgradeable, ERC721
     suspended
   }
 
+  /**
+   * @dev Enum of the different kind of top level components that can be plugged into the pool. Each one corresponds
+   * with the {EToken}, {RiskModule} and {PremiumsAccount} respectively.
+   */
   enum ComponentKind {
     unknown,
     eToken,
@@ -80,6 +97,10 @@ contract PolicyPool is IPolicyPool, PausableUpgradeable, UUPSUpgradeable, ERC721
     premiumsAccount
   }
 
+  /**
+   * @dev Struct to keep the state and type of the components installed. The `kind` never changes. The `status`
+   * initially is `active` and can be changes with {PolicyPool-changeComponentStatus} and {PolicyPool-removeComponent}.
+   */
   struct Component {
     ComponentStatus status;
     ComponentKind kind;
@@ -87,7 +108,6 @@ contract PolicyPool is IPolicyPool, PausableUpgradeable, UUPSUpgradeable, ERC721
 
   /**
    * @dev Mapping of installed components (see {EToken}, {RiskModule}, {PremiumsAccount}) in the PolicyPool.
-   * For each one it keep an state {ComponentStatus}.
    */
   mapping(IPolicyPoolComponent => Component) private _components;
 
@@ -100,17 +120,27 @@ contract PolicyPool is IPolicyPool, PausableUpgradeable, UUPSUpgradeable, ERC721
   /**
    * @dev Event emitted every time a new policy is added to the pool. Contains all the data about the policy that is
    * later required for doing operations with the policy like resolution or expiration.
+   *
+   * @param riskModule The risk module that created the policy
+   * @param policy The {Policy-PolicyData} struct with all the immutable fields of the policy.
    */
   event NewPolicy(IRiskModule indexed riskModule, Policy.PolicyData policy);
 
   /**
    * @dev Event emitted every time a policy is removed from the pool. If the policy expired, the `payout` is 0,
    * otherwise is the amount transferred to the policyholder.
+   *
+   * @param riskModule The risk module where that created the policy initially.
+   * @param policyId The unique id of the policy
+   * @param payout The payout that has been paid to the policy holder. 0 when the policy expired.
    */
   event PolicyResolved(IRiskModule indexed riskModule, uint256 indexed policyId, uint256 payout);
 
   /**
    * @dev Event emitted when the treasury changes
+   *
+   * @param action The type of governance action (just setTreasury in this contract for now)
+   * @param value  The address of the new treasury
    */
   event ComponentChanged(IAccessManager.GovernanceActions indexed action, address value);
 
@@ -127,22 +157,42 @@ contract PolicyPool is IPolicyPool, PausableUpgradeable, UUPSUpgradeable, ERC721
     ComponentStatus newStatus
   );
 
+  /**
+   * @dev Modifier that checks the caller has a given role
+   */
   modifier onlyRole(bytes32 role) {
-    _access.checkRole(role, msg.sender);
+    _access.checkRole(role, _msgSender());
     _;
   }
 
+  /**
+   * @dev Modifier that checks the caller has any of the given rolea
+   */
   modifier onlyRole2(bytes32 role1, bytes32 role2) {
-    _access.checkRole2(role1, role2, msg.sender);
+    _access.checkRole2(role1, role2, _msgSender());
     _;
   }
 
+  /**
+   * @dev Instantiates a Policy Pool. Sets immutable fields.
+   *
+   * @param access_ The address of the {AccessManager} that manages the access permissions for the pool governance
+   * operations.
+   * @param currency_ The {ERC20} token that's used as a currency in the protocol. Usually a stablecoin such as USDC.
+   */
   /// @custom:oz-upgrades-unsafe-allow constructor
   constructor(IAccessManager access_, IERC20Metadata currency_) {
     _access = access_;
     _currency = currency_;
   }
 
+  /**
+   * @dev Initializes a Policy Pool
+   *
+   * @param name_ The name of the ERC721 token.
+   * @param symbol_ The symbol of the ERC721 token.
+   * @param treasury_ The address of the treasury that will receive the protocol fees.
+   */
   function initialize(
     string memory name_,
     string memory symbol_,
@@ -162,10 +212,23 @@ contract PolicyPool is IPolicyPool, PausableUpgradeable, UUPSUpgradeable, ERC721
   // solhint-disable-next-line no-empty-blocks
   function _authorizeUpgrade(address) internal override onlyRole2(GUARDIAN_ROLE, LEVEL1_ROLE) {}
 
+  /**
+   * @dev Pauses the contract. When the contract is paused, several operations are rejected: deposits, withdrawals, new
+   * policies, policy resolution and expiration, nft transfers.
+   *
+   * Requirements:
+   * - Must be executed by a user with the {GUARDIAN_ROLE}.
+   */
   function pause() public onlyRole(GUARDIAN_ROLE) {
     _pause();
   }
 
+  /**
+   * @dev Unpauses the contract. All the operations disabled when the contract was paused are re-enabled.
+   *
+   * Requirements:
+   * - Must be called by a user with either the {GUARDIAN_ROLE} or a {LEVEL1_ROLE}.
+   */
   function unpause() public onlyRole2(GUARDIAN_ROLE, LEVEL1_ROLE) {
     _unpause();
   }
@@ -178,15 +241,42 @@ contract PolicyPool is IPolicyPool, PausableUpgradeable, UUPSUpgradeable, ERC721
     return _currency;
   }
 
+  /**
+   * @dev Changes the address of the treasury, the one that receives the protocol fees.
+   *
+   * Requirements:
+   * - Must be called by a user with the {LEVEL1_ROLE}.
+   *
+   * Events:
+   * - Emits {ComponentChanged} with action = setTreasury and the address of the new treasury.
+   */
   function setTreasury(address treasury_) external onlyRole(LEVEL1_ROLE) {
     _treasury = treasury_;
     emit ComponentChanged(IAccessManager.GovernanceActions.setTreasury, _treasury);
   }
 
+  /**
+   * @dev Returns the address of the treasury, the one that receives the protocol fees.
+   */
   function treasury() external view override returns (address) {
     return _treasury;
   }
 
+  /**
+   * @dev Adds a new component (either an {EToken}, {RiskModule} or {PremiumsAccount}) to the protocol. The component
+   * status will be `active`.
+   *
+   * Requirements:
+   * - Must be called by a user with the {LEVEL1_ROLE}
+   * - The component wasn't added before.
+   *
+   * Events:
+   * - Emits {ComponentStatusChanged} with status active.
+   *
+   * @param component The address of component contract. Must be an {EToken}, {RiskModule} or {PremiumsAccount} linked
+   * to this specific {PolicyPool} and matching the `kind` specified in the next paramter.
+   * @param kind The type of component to be added.
+   */
   function addComponent(IPolicyPoolComponent component, ComponentKind kind)
     external
     onlyRole(LEVEL1_ROLE)
@@ -211,6 +301,19 @@ contract PolicyPool is IPolicyPool, PausableUpgradeable, UUPSUpgradeable, ERC721
     emit ComponentStatusChanged(component, kind, ComponentStatus.active);
   }
 
+  /**
+   * @dev Removes a component from the protocol. The component needs to be in `deprecated` status before doing this
+   * operation.
+   *
+   * Requirements:
+   * - Must be called by a user with the {LEVEL1_ROLE}
+   * - The component status is `deprecated`.
+   *
+   * Events:
+   * - Emits {ComponentStatusChanged} with status inactive.
+   *
+   * @param component The address of component contract. Must be a component added before.
+   */
   function removeComponent(IPolicyPoolComponent component) external onlyRole(LEVEL1_ROLE) {
     Component storage comp = _components[component];
     require(comp.status == ComponentStatus.deprecated, "Component not deprecated");
@@ -240,6 +343,19 @@ contract PolicyPool is IPolicyPool, PausableUpgradeable, UUPSUpgradeable, ERC721
     delete _components[component];
   }
 
+  /**
+   * @dev Changes the status of a component.
+   *
+   * Requirements:
+   * - Must be called by a user with the {LEVEL1_ROLE} if the new status is `active` or `deprecated`.
+   * - Must be called by a user with the {GUARDIAN_ROLE} if the new status is `suspended`.
+   *
+   * Events:
+   * - Emits {ComponentStatusChanged} with the new status.
+   *
+   * @param component The address of component contract. Must be a component added before.
+   * @param newStatus The new status, must be either `active`, `deprecated` or `suspended`.
+   */
   function changeComponentStatus(IPolicyPoolComponent component, ComponentStatus newStatus)
     external
     onlyRole2(GUARDIAN_ROLE, LEVEL1_ROLE)
@@ -247,15 +363,21 @@ contract PolicyPool is IPolicyPool, PausableUpgradeable, UUPSUpgradeable, ERC721
     Component storage comp = _components[component];
     require(comp.status != ComponentStatus.inactive, "Component not found");
     require(
-      (newStatus == ComponentStatus.active && _access.hasRole(LEVEL1_ROLE, msg.sender)) ||
-        (newStatus == ComponentStatus.suspended && _access.hasRole(GUARDIAN_ROLE, msg.sender)) ||
-        (newStatus == ComponentStatus.deprecated && _access.hasRole(LEVEL1_ROLE, msg.sender)),
+      (newStatus == ComponentStatus.active && _access.hasRole(LEVEL1_ROLE, _msgSender())) ||
+        (newStatus == ComponentStatus.suspended && _access.hasRole(GUARDIAN_ROLE, _msgSender())) ||
+        (newStatus == ComponentStatus.deprecated && _access.hasRole(LEVEL1_ROLE, _msgSender())),
       "Only GUARDIAN can suspend / Only LEVEL1 can activate/deprecate"
     );
     comp.status = newStatus;
     emit ComponentStatusChanged(component, comp.kind, newStatus);
   }
 
+  /**
+   * @dev Returns the status of a component.
+   *
+   * @param component The address of the component
+   * @return The status of the component. See {ComponentStatus}
+   */
   function getComponentStatus(IPolicyPoolComponent component)
     external
     view
@@ -284,8 +406,8 @@ contract PolicyPool is IPolicyPool, PausableUpgradeable, UUPSUpgradeable, ERC721
 
   function deposit(IEToken eToken, uint256 amount) external override whenNotPaused {
     require(_etkStatus(eToken) == ComponentStatus.active, "eToken is not active");
-    _currency.safeTransferFrom(msg.sender, address(eToken), amount);
-    eToken.deposit(msg.sender, amount);
+    _currency.safeTransferFrom(_msgSender(), address(eToken), amount);
+    eToken.deposit(_msgSender(), amount);
   }
 
   function withdraw(IEToken eToken, uint256 amount)
@@ -299,7 +421,7 @@ contract PolicyPool is IPolicyPool, PausableUpgradeable, UUPSUpgradeable, ERC721
       etkStatus == ComponentStatus.active || etkStatus == ComponentStatus.deprecated,
       "eToken not found or withdraws not allowed"
     );
-    address provider = msg.sender;
+    address provider = _msgSender();
     return eToken.withdraw(provider, amount);
   }
 
@@ -310,7 +432,7 @@ contract PolicyPool is IPolicyPool, PausableUpgradeable, UUPSUpgradeable, ERC721
     uint96 internalId
   ) external override whenNotPaused returns (uint256) {
     IRiskModule rm = policy.riskModule;
-    require(address(rm) == msg.sender, "Only the RM can create new policies");
+    require(address(rm) == _msgSender(), "Only the RM can create new policies");
     require(_rmStatus(rm) == ComponentStatus.active, "RM module not found or not active");
     policy.id = (uint256(uint160(address(rm))) << 96) + internalId;
     _policies[policy.id] = policy.hash();
@@ -332,10 +454,6 @@ contract PolicyPool is IPolicyPool, PausableUpgradeable, UUPSUpgradeable, ERC721
     return policy.id;
   }
 
-  function _balance() internal view returns (uint256) {
-    return _currency.balanceOf(address(this));
-  }
-
   function _validatePolicy(Policy.PolicyData memory policy) internal view {
     require(policy.id != 0 && policy.hash() == _policies[policy.id], "Policy not found");
   }
@@ -361,10 +479,17 @@ contract PolicyPool is IPolicyPool, PausableUpgradeable, UUPSUpgradeable, ERC721
     return _resolvePolicy(policy, customerWon ? policy.payout : 0, false);
   }
 
+  function isActive(uint256 policyId) external view override returns (bool) {
+    return _policies[policyId] != bytes32(0);
+  }
+
   /**
    * @dev Internal function that handles the different alternative resolutions for a policy, with or without payout and
    * expiration.
    *
+   * Events:
+   * - Emits {PolicyResolved} with the payout
+   *
    * @param policy A policy created with {Policy-initialize}
    * @param payout The amount to paid to the policyholder
    * @param expired True for expiration resolution (`payout` must be 0)
@@ -376,7 +501,7 @@ contract PolicyPool is IPolicyPool, PausableUpgradeable, UUPSUpgradeable, ERC721
   ) internal {
     _validatePolicy(policy);
     IRiskModule rm = policy.riskModule;
-    require(expired || address(rm) == msg.sender, "Only the RM can resolve policies");
+    require(expired || address(rm) == _msgSender(), "Only the RM can resolve policies");
     require(payout == 0 || policy.expiration > block.timestamp, "Can't pay expired policy");
     ComponentStatus compStatus = _rmStatus(rm);
     require(
@@ -451,4 +576,12 @@ contract PolicyPool is IPolicyPool, PausableUpgradeable, UUPSUpgradeable, ERC721
       return;
     }
   }
+
+  function _beforeTokenTransfer(
+    address from,
+    address to,
+    uint256 tokenId
+  ) internal override whenNotPaused {
+    super._beforeTokenTransfer(from, to, tokenId);
+  }
 }

package/contracts/PolicyPoolComponent.sol

@@ -7,7 +7,7 @@ import {IPolicyPool} from "./interfaces/IPolicyPool.sol";
 import {IPolicyPoolComponent} from "./interfaces/IPolicyPoolComponent.sol";
 import {IAccessManager} from "./interfaces/IAccessManager.sol";
 import {PausableUpgradeable} from "@openzeppelin/contracts-upgradeable/security/PausableUpgradeable.sol";
-import {WadRayMath} from "./WadRayMath.sol";
+import {WadRayMath} from "./dependencies/WadRayMath.sol";
 
 /**
  * @title Base class for PolicyPool components
@@ -51,17 +51,17 @@ abstract contract PolicyPoolComponent is
   }
 
   modifier onlyComponentRole(bytes32 role) {
-    _policyPool.access().checkComponentRole(address(this), role, msg.sender, false);
+    _policyPool.access().checkComponentRole(address(this), role, _msgSender(), false);
     _;
   }
 
   modifier onlyGlobalOrComponentRole(bytes32 role) {
-    _policyPool.access().checkComponentRole(address(this), role, msg.sender, true);
+    _policyPool.access().checkComponentRole(address(this), role, _msgSender(), true);
     _;
   }
 
   modifier onlyGlobalOrComponentRole2(bytes32 role1, bytes32 role2) {
-    _policyPool.access().checkComponentRole2(address(this), role1, role2, msg.sender, true);
+    _policyPool.access().checkComponentRole2(address(this), role1, role2, _msgSender(), true);
     _;
   }
 
@@ -71,8 +71,8 @@ abstract contract PolicyPoolComponent is
     bytes32 role3
   ) {
     IAccessManager access = _policyPool.access();
-    if (!access.hasComponentRole(address(this), role1, msg.sender, true)) {
-      _policyPool.access().checkComponentRole2(address(this), role2, role3, msg.sender, true);
+    if (!access.hasComponentRole(address(this), role1, _msgSender(), true)) {
+      _policyPool.access().checkComponentRole2(address(this), role2, role3, _msgSender(), true);
     }
     _;
   }
@@ -117,22 +117,7 @@ abstract contract PolicyPoolComponent is
   }
 
   function hasPoolRole(bytes32 role) internal view returns (bool) {
-    return _policyPool.access().hasComponentRole(address(this), role, msg.sender, true);
-  }
-
-  function _isTweakRay(
-    uint256 oldValue,
-    uint256 newValue,
-    uint256 maxTweak
-  ) internal pure returns (bool) {
-    if (oldValue == newValue) return true;
-    if (oldValue == 0) return maxTweak >= WadRayMath.RAY;
-    if (newValue == 0) return false;
-    if (oldValue < newValue) {
-      return (newValue.rayDiv(oldValue) - WadRayMath.RAY) <= maxTweak;
-    } else {
-      return (WadRayMath.RAY - newValue.rayDiv(oldValue)) <= maxTweak;
-    }
+    return _policyPool.access().hasComponentRole(address(this), role, _msgSender(), true);
   }
 
   function _isTweakWad(