@ensuro/core 2.0.0-beta1 → 2.0.0-beta11

package/README.md

@@ -1,3 +1,9 @@
+[![Tests](https://github.com/ensuro/ensuro/actions/workflows/tests.yaml/badge.svg)](https://github.com/ensuro/ensuro/actions/workflows/tests.yaml)
+[![cov](https://github.com/ensuro/ensuro/raw/main/badges/coverage.svg)](https://github.com/ensuro/ensuro/actions/workflows/tests.yaml)
+[![Build and Push Docker Image to Google Artifact Registry](https://github.com/ensuro/ensuro/actions/workflows/build-base-image.yaml/badge.svg)](https://github.com/ensuro/ensuro/actions/workflows/build-base-image.yaml)
+[![release](https://badgen.net/github/release/ensuro/ensuro)](https://github.com/ensuro/ensuro/releases)
+[![NPM Package](https://github.com/ensuro/ensuro/actions/workflows/npm.yaml/badge.svg)](https://www.npmjs.com/package/@ensuro/core)
+
 # Ensuro - Decentralized capital for insurance
 
 Ensuro is a decentralized protocol that manages the capital to support insurance products.
@@ -17,50 +23,66 @@ Each policy sold and active it's a _risk_ or potential loss, a random variable t
 
 <dl>
 <dt>PolicyPool</dt>
-<dd>This is the main contract that keeps track of active policies and manages the assets. It has the methods for LP to deposit/withdraw. The PolicyPool is connected to a set of eTokens and RiskModules.</dd>
-</dl>
-
-<dl>
-<dt>PolicyNFT</dt>
-<dd>This contract follows ERC721 standard to control the ownership of the policies (each policy is an NFT). Policies are minted by PolicyPool.</dd>
+<dd>
+PolicyPool is the protocol's main contract. It keeps track of active policies and receives spending allowances. It has methods for LP to deposit/withdraw, acting as a gateway. The PolicyPool is connected to a set of eTokens, Premiums Accounts, and RiskModules.
+This contract also follows the ERC721 standard, minting an NFT for each policy created. The owner of the NFT is who will receive the payout in case there's any.
+</dd>
 </dl>
 
 <dl>
-<dt>PolicyPoolConfig</dt>
-<dd>This contract holds some configurable components of the protocol such as treasury address and the installed risk modules. Also this module holds the access control permissions for the governance actions.</dd>
+<dt>AccessManager</dt>
+<dd>This contract the access control permissions for the governance actions.</dd>
 </dl>
 
 <dl>
 <dt>EToken</dt>
-<dd>This is a ERC20 compatible contract that represents the capital of each liquidity provider in a given pool. The valuation is one-to-one with the underlyng stablecoin. The view scr() returns the amount of capital that's locked backing up policies. For this capital locked, the pool receives an interest (scrInterestRate() / tokenInterestRate()) that is continously accrued in the balance of eToken holders.</dd>
+<dd>EToken is an ERC20-compatible contract that counts the capital of each liquidity provider in a given pool. The valuation is one-to-one with the underlying stablecoin. The view `scr()` returns the amount of capital that's locked backing up policies. For this capital locked, the pool receives an interest (see `scrInterestRate()` and `tokenInterestRate()`) that is continuously accrued in the balance of eToken holders.</dd>
 </dl>
 
 <dl>
 <dt>RiskModule</dt>
-<dd>This is a base contract that needs to be reimplemented with the specific logic related with custom policy parameters, validation of the received price and with different strategies for policy resolution (e.g. using oracles). This is the contract that must be called by a customer for creating a new policy that, after doing validations and storing parameters needed for resolution, will submit the new policy to the PolicyPool.</dd>
+<dd>This base contract allows risk partners and customers to interact with the protocol. It needs to be reimplemented for each different product, each time defining the proper policy parameters, price validation, and policy resolution strategy (e.g., using oracles). RiskModule must be called to create a new policy; after validating the price and storing parameters needed for resolution, RiskModule submits the policy to PolicyPool.</dd>
 </dl>
 
 <dl>
 <dt>PremiumsAccount</dt>
-<dd>The risk modules are grouped in *premiums accounts* that keep track of the pure premiums (active and earned) their policies. The responsability of these contracts is keeping track of the premiums and releasing the payouts. When premiums are exhausted (losses more than expected), they borrow money from the *eTokens* to cover the payouts. This money will be repaid when/if later the premiums account has surplus (losses less than expected).</dd>
+<dd>The risk modules are grouped in premiums accounts that keep track of their policies' pure premiums (active and earned). The responsibility of these contracts is to keep track of the premiums and release the payouts. When premiums are exhausted (losses more than expected), they borrow money from the eTokens to cover the payouts. This money will be repaid when/if later the premiums account has a surplus (losses less than expected).</dd>
+</dl>
+
+<dl>
+<dt>AssetManager</dt>
+<dd>Both _eTokens_ and _PremiumsAccounts_ are _reserves_ because they hold assets. It's possible to assign to each reserve an AssetManager. The AssetManager is a contract that operates in the reserve's context (through delegatecalls) and manages the assets by applying some strategy to invest in other DeFi protocols to generate additional returns.</dd>
 </dl>
 
 <dl>
 <dt>LPWhitelist</dt>
-<dd>This is an optional component. If present it controls which Liquidity Providers can deposit or transfer their <i>eTokens</i>.</dd>
+<dd>This is an optional component. If present it controls which Liquidity Providers can deposit or transfer their <i>eTokens</i>. Each eToken may be or not connected to a whitelist.</dd>
 </dl>
 
 <dl>
 <dt>Policy</dt>
-<dd>This is a library with the struct and the calculation of relevant attributes of a policy. It includes the logic around the distribution of the premium, calculation of SCR, shared coverage and other behaviour of the protocol.</dd>
+<dd>Policy is a library with the struct and the calculation of relevant attributes of a policy. It includes the logic around the premium distribution, SCR calculation, shared coverage, and other protocol behaviors.</dd>
 </dl>
 
 ## Governance
 
-The protocol uses three levels of access control, plus a guardian role. The roles are managed by the PolicyPoolConfig smart contract.
+The protocol uses three levels of access control, plus a guardian role. These roles can be assigned at protocol level or specifically for a component. The roles are managed by the AccessManager smart contract.
 
 More info about governance in https://docs.google.com/spreadsheets/d/1LqlogRn8AlnLq1rPTd5UT7CJI3uc31PdBaxj4pX3mtE/edit?usp=sharing
 
+## Upgradability
+
+Ensuro contracts are upgradeable, meaning the code can be changed after deployment. We implement this following the UUPS pattern (https://eips.ethereum.org/EIPS/eip-1822) where the contract used is a proxy that can be redirected to a different implementation.
+
+The main reason to do this is to be able to fix errors and to do minor changes in the protocol.
+
+We will never deploy upgrades to live contracts without prior notice to the users, mainly if it implies a change in the behavior. The permission for executing upgrades will be delegated to two different roles:
+
+- LEVEL1_ROLE: this will be delegated to a Timelock contract that will give enough time to the users to be notified of the imminent upgrade.
+- GUARDIAN_ROLE: this will used only for emergency situations to prevent hacks or fix vulnerabilities. It will be delegated to multisigs where one of the signers is a trusted third party.
+
+Have in mind the new versions of the contracts might or might not be covered by the same audit processes as the initial ones. Always check the details of the audit reports.
+
 ## Development
 
 For coding the smart contracts the approach we took was prototyping initially in Python (see folder `prototype`), and later we coded in Solidity. The tests run the same test case both on the Python prototype code and the Solidity code. To adapt the Solidity code that is called using [brownie](https://eth-brownie.readthedocs.io/en/stable/), we have some glue code implemented in `tests/wrappers.py`.