@etherisc/gif-next 0.0.2-eb7397c → 0.0.2-eb98db7-932

package/README.md

@@ -1,4 +1,44 @@
-# gif-next (Generic Insurance Framework next version)
+# GIF-Next (Generic Insurance Framework, next version)
+
+
+```mermaid
+  graph TD
+      IPoolComponent --> IComponent
+      IComponent --> IRegisterable
+      IComponent --> ITransferInterceptor
+      IRegistryService --> IService
+      IService-->IRegisterable
+      IService-->IVersionable
+      IRegisterable-->INftOwnable
+      INftOwnable-->IERC165
+```
+
+## Add OpenZeppelin V5 Dependencies
+
+```shell
+forge install openzeppelin-contracts-500=OpenZeppelin/openzeppelin-contracts@v5.0.0
+cd cd lib/openzeppelin-contracts-500
+git checkout tags/v5.0.0
+cd ../..
+```
+
+See `remappings.txt` to see how to work with different OpenZeppelin versions in parallel
+
+```
+cat remappings.txt 
+@openzeppelin5/contracts/=lib/openzeppelin-contracts-500/contracts/
+@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/
+@openzeppelin/contracts-upgradeable/=lib/openzeppelin-contracts-upgradeable/contracts/
+```
+
+
+## Submodules checkout
+
+This repository uses submodules. To checkout or update to the latest submodules, run the following command after updating to any revision (or checking out the repository)
+
+```shell
+git submodule update --recursive
+```
 
 ## Hardhat 
 
@@ -13,17 +53,65 @@ npm run test-with-gas
 npm run coverage
 ```
 
-### Deployment 
+### Docgen
+
+Produce `solidty-docgen` documentation using the command below.
+
+```shell
+hh docgen
+```
+
+The resulting markdown files are written to `docs`
+
+
+### Full protocol deployment 
 
+Install the dependencies before running the script below for the first time.
+
+```bash
+npm install
 ```
-hh run --network <networkname> scripts/deploy.ts
+
+The deploy script will deploy all required contracts and create a test instance with a test product and a test pool. 
+
+```bash
+# run deployment on a locally created ganache instance
+export SKIP_VERIFICATION=true
+hh run scripts/deploy_all.ts
 ```
 
-Networks:
-- hardhat (dynamically created network - https://hardhat.org/hardhat-network/docs/overview)
-- anvil (anvsil chain running in container next when using devcontainer)
-- mumbai (polygon testnet, requires WEB3_INFURA_PROJECT_ID)
-- mainnet (polygon mainnet, requires WEB3_INFURA_PROJECT_ID)
+```bash
+# set appropriate values vor env variables (see below)
+
+# run deployment on another network
+hh run --network <networkname> scripts/deploy_all.ts
+```
+
+Environment variables:
+
+- `SKIP_VERIFICATION` set to `true` to skip etherscan verification (required for ganacht and anvil)
+- `WEB3_INFURA_PROJECT_ID` set to infura project id (required for mumbai and mainnet)
+- `WALLET_MNEMONIC` the mnemonic of the wallet to use for deployment (required for mumbai and mainnet)
+- `ETHERSCAN_API_KEY` `POLYGONSCAN_API_KEY` the api key for etherscan/polygonscan (required for mumbai and mainnet)
+
+### Create a new instance
+
+Requires previous step to be completed. 
+
+```bash
+# set appropriate values vor env variables (see below)
+
+hh run --network <networkname> scripts/new_instance.ts
+```
+
+Currently an HD wallet is expected to be used for the deployment. The mnemonic of the wallet needs to be provided via the `WALLET_MNEMONIC` environment variable. 
+The instance owner will be the 11th address of the wallet.
+
+Environment variables:
+
+- `WEB3_INFURA_PROJECT_ID` set to infura project id (required for mumbai and mainnet)
+- `WALLET_MNEMONIC` the mnemonic of the wallet to use for deployment (required for mumbai and mainnet)
+- `REGISTRY_ADDRESS` the address of the registry that is already deployed and configured and has a valid master instance
 
 
 ### Console
@@ -48,6 +136,9 @@ https://hardhat.org/hardhat-runner/docs/guides/compile-contracts
 ```shell
 forge build
 
+# contract sizes
+forge build --sizes | grep Instance
+
 forge test
 
 # run single test case
@@ -60,7 +151,11 @@ forge test -vvvv --mt test_decimals
 # provide gas report for a single test
 forge test --mt test_decimals --gas-report
 
+# provide code coverage report
 forge coverage
+forge coverage --report lcov 
+
+
 ```
 
 Chisel session
@@ -119,9 +214,342 @@ uint256 lifetime =365*24*3600;
 uint256 policyNftId = ps.createApplicationForBundle(customer, bundleNftId, sumInsuredAmount, premiumAmount, lifetime);
 
 ```
+### Library Linking
+
+https://ethereum.stackexchange.com/questions/153411/does-foundry-support-dynamical-library-linking-in-solidity
 
+```toml
+# foundry.toml
+
+[profile.default]
+  # expected format(example below): libraries = ["<path>:<lib name>:<address>"]
+  libraries = ["src/libraries/MyLibrary.sol:MyLibrary:0x..."]
+```
 
 ### Documentation
 
 https://book.getfoundry.sh/reference/
 
+## Style Guide
+
+Solidity code is to be written according to the [Solidity Style Guide](https://docs.soliditylang.org/en/latest/style-guide.html).
+
+Documentation of the code should be written inline using [NatSpec](https://docs.soliditylang.org/en/latest/natspec-format.html).
+
+### Naming conventions
+
+Additionally, we use the following naming conventions:
+
+- Function arguments and return types: If using custom data types, make the name include the type by appending the Type to the argument name, e.g. `function getInfo(NftId bundleNftId)` instead of `function getInfo(NftId bundleId)`. Background: Custom data types are lost when using the ABI or Typescript binding classes (e.g. instead of `NftID` a `uint96` is used), so the type needs to be included in the name to make it clear what the argument is without having to look at the documentation or checking the solidity source code. 
+- When naming a field or an attribute `id` and the context is not clear, call it `nftId` instead so its clear what type if id it is as there will be multiple ids for different kind of objects. Example: if you the function has a bundle nft id and a policy nft id as arguments, call them `bundleNftId` and `policyNftId` instead of `id` and `policyId`. In case of doubt, be a bit more verbose for the sake of clarity. 
+- When naming things, remember that the code will likely be used in Javascript/Typescript as well, so avoid names that are reserved in Javascript/Typescript. A list of reserved words in Javascript can be found [here](https://www.w3schools.com/js/js_reserved.asp) and a list of reserved words in Typescript can be found [here](https://www.tektutorialshub.com/typescript/identifiers-keywords-in-typescript/). 
+
+### Automatic code formatting
+
+We use prettier and the solidity plugin to format the code automatically. 
+The plugin is configured to use the style guide mentioned above.
+To execute format checks run `npm run styleCheck`.
+To execute formatting run `npm run styleFix`.
+
+### Linting 
+
+We use solhint to lint the code.
+To execute linting run `npm run lint`.
+
+
+### Adding Brownie (Legacy)
+
+python3 is already installed
+
+```bash
+npm install -g ganache
+sudo apt update
+sudo apt install python3-pip
+pip install eth-brownie
+brownie pm install OpenZeppelin/openzeppelin-contracts@4.9.3
+brownie pm install OpenZeppelin/openzeppelin-contracts@5.0.0
+```
+
+```bash
+brownie compile --all
+brownie console
+```
+
+```python
+registry_owner = accounts[0]
+instance_owner = accounts[1]
+product_owner = accounts[2]
+
+# deploy libs and helper contracts
+nft_id_lib = NftIdLib.deploy({'from': registry_owner})
+ufixed_math_lib = UFixedMathLib.deploy({'from': registry_owner})
+test_fee = TestFee.deploy({'from': registry_owner})
+
+# deploy registry and a token
+registry = Registry.deploy({'from': registry_owner})
+nft = ChainNft.deploy(registry, {'from': registry_owner})
+registry.initialize(nft,  {'from': registry_owner})
+token = TestUsdc.deploy({'from': registry_owner})
+
+# deploy services
+component_owner_service = ComponentOwnerService.deploy(registry, {'from': registry_owner})
+product_service = ProductService.deploy(registry, {'from': registry_owner})
+
+# deploy an instance
+instance = Instance.deploy(registry, component_owner_service, product_service, {'from': instance_owner})
+
+# deploy product
+pool = TestPool.deploy(registry, instance, token, {'from': product_owner})
+policy_fee = test_fee.createFee(1, -1, 0)
+product = TestProduct.deploy(registry, instance, token, pool, policy_fee, {'from': product_owner})
+
+# grant roles
+pool_owner_role = instance.getRoleForName("PoolOwner")
+product_owner_role = instance.getRoleForName("ProductOwner")
+instance.grantRole(pool_owner_role, product_owner, {'from': instance_owner})
+instance.grantRole(product_owner_role, product_owner, {'from': instance_owner})
+
+# register objects
+instance.register()
+component_owner_service.register(pool, {'from': product_owner})
+component_owner_service.register(product, {'from': product_owner})
+
+instance_id = instance.getNftId()
+pool_id = pool.getNftId()
+product_id = product.getNftId()
+```
+
+## Objects
+
+### Registry
+
+Mandatory properties
+
+* One registry per chain
+* Global registry: the registry on mainnet
+* One entry per protocol object
+* Once registered object properties are immutable
+* Globally unique NFT minted per protocol object (chain id is embedded in NFT id)
+* Object ownership defined by NFT ownernship
+* Typed objects (instance, product, policy, ...)
+* Each object has parent object (only one exception: protocol object does not have parent object)
+* Parent object type is defined by type of child object
+
+Object properties (for smart contracts)
+* Objects that represent a smart contract record its contract address
+* With one exception (see next point) smart contract addresses refer to the address on the same chain as the registry
+* The global registry also holds entries for all the registries on different chains than mainnet, in these cases the addresses refer to the chains of these chain specific registries (this is the only case where registered addresses do not refer to the same chain)
+
+Optional properties
+
+* Objects can have names
+* Object names are unique per chain
+* Objects may define an intercepting property, in which case a predefined smart contract is involved in NFT transfers of the objects NFT (transfer may trigger actions, transfer may be blocked etc)
+* 
+
+Ownership property
+
+* Object ownership defined by ownership of NFT representing the object
+* Protocol
+  * Fixed/predefined owner (address without private key)
+* Registry
+  * Allows registration of token and services (per major release)
+  * May transfer ownership
+* Token
+  * Fixed/predefined owner (address without private key)
+  * TODO add whitelisting for token per major release
+* Service
+  * Allows upgrades of services as long as major version is same
+  * Until further notice the same entity as the registry owner
+  * May transfer ownership
+* Instance
+  * Granting/revoking of roles (both default + custom)
+  * Management of custom roles and targets
+  * May lock instance and/or components
+  * May transfer ownership
+* Component (Product, Pool, Distribution, Oracle)
+  * Register component
+  * Set component wallet (which receives fees, holds funds)
+  * May lock component
+  * May transfer ownership
+  * Additional use case specific features
+* Policy
+  * Represents policy holder
+  * Receive payouts (GIF default behaviour)
+  * May transfer ownership
+* Bundle
+  * Represents funds owner
+  * May withdraw funds not locked by active policies
+  * May transfer ownership
+* Distributor
+  * Receives commissions from sales (GIF default behaviour)
+  * May transfer ownership
+
+Intercepting property
+  * Service owner is indirectly owner of service manager contract
+
+* Instance
+  * intercepts transfer of instance owner (new owner needs access manager admin rights for custom roles and targets)
+  * intercepts transfer of components, to do what? check that new owner has necessary roles?
+* Product
+  * intercepts transfer of policies (use case specific: eg. limit/disallow transfers)
+* Pool:
+  * intercepts transfer of bundles (use case specific: eg. limit/disallow transfers)
+* Distribution
+  * intercepts transfer of distributors (bookkeeping: only one distributor per address allowed)
+* Oracle
+  * likely meaningless
+
+
+### Instance
+
+### Product
+
+### Payout Handling
+
+Pool specifies **retention level**.
+Retention level defines up to which percentage of the sum insured the pool is payout out using its own/current funds.
+Depending on the amount of a new payout the poolService decides to either execute the payout directly or to add the payout as a pending payout with a notification of the pool.
+
+The sequence below sketches the small payout flow (payout < retention amount)
+- retention level: 30%
+- sum insured: 1000
+- payout: 200
+
+```mermaid
+sequenceDiagram
+  participant customer
+  participant product
+  participant claimService
+  participant poolService
+  participant pool
+  product->>claimService: createPayout()
+  claimService ->> poolService: requestPayout()
+  poolService -->> pool: verifyPayout() *
+  poolService ->> poolService: processPayout()
+  poolService ->> customer: transfer token for payout
+  poolService ->> claimService: payoutExecuted()
+  poolService -->> customer: payoutExecutedCallback() **
+```
+
+*: if pool is configured to verify payouts before execution
+
+**: callback only if customer is contract (IPolicyHolder)
+
+The sequence below sketches the call flow for payouts larger than the retention amount
+- retention level: 30%
+- sum insured: 1000
+- payout: 500
+  * locally available: 300
+  * via policy (re-insurance): 200
+
+```mermaid
+sequenceDiagram 
+  participant customer
+  participant product
+  participant claimService
+  participant poolService
+  participant pool
+  pool ->> reinsuranceProduct: applyForPolicy()
+  product->>claimService: createPayout()
+  claimService ->> poolService: requestPayout()
+  poolService ->> pool: pendingPayoutAdded()
+  pool ->> pool: getReinsurancePolicy()
+  pool ->> reinsuranceProduct: claim()
+  reinsuranceProduct -->> reinsurancePool: createPayout
+  reinsurancePool ->> pool: transfer token for payout
+  reinsurancePool ->> pool: payoutExecutedCallback()
+  pool ->> poolService: processPendingPayout()
+  poolService ->> customer: transfer token for payout
+  poolService ->> claimService: payoutExecuted()
+```
+
+### Pool
+
+### Distribution
+
+### Oracle
+
+## Registry and Services
+
+### Principles
+
+- 1 service per object type and major version
+- registry service guards write access to registry
+- all other objects registered via registry service
+- root object for the complete tree is the protocol object
+- under the root object a single registry object is registered (= global registry/ethereum mainnet)
+
+
+### Service Responsibilities
+
+Registry Service
+
+- deployed and registered during bootstrapping of registry
+- used to register tokens and other services by registry owner
+- an object may only be registered by the service designated by the type of the object
+- to register an object the parent object needs already be registered
+- the type of the object to be registered needs to match a valid child type/parent type combination
+
+Instance Service
+
+- deploys master instance during its own bootstrapping (if allowed by contract size)
+- registered via registry service by registry owner
+- registeres master instance during its own registration by regsitry owner
+- deploys and registeres new instances (= instance factory) by instance owner (instance owner is a permissionless role, anybody may creates a new instance)
+- provides upgrade functionality to instance owners
+
+Product Service
+
+- registered via registry service by registry owner
+- registers products for registered instances via registry service by product owner (product owner role is permissend by the product's instance)
+- registers applications/policies for registered products via registry service
+
+Distribution Service
+
+- registered via registry service by registry owner
+- registers distribution components for registered products via registry service by distribution owner (distribution owner role is permissend by the product's instance)
+- registers distributors for registered distribution components via registry service
+
+## Contract Organisation
+
+now 
+
+contracts
+  components
+  instance
+  registry
+  shared
+  types
+
+
+contracts
+  component
+    pool
+      Pool.sol
+      PoolService.sol
+    oracle
+    distribution
+    product
+      Product.sol
+      ProductService.sol
+    Component.sol
+    ComponentService.sol
+  instance
+    Instance.sol
+    InstanceAccessManager.sol
+    InstanceReader.sol
+    InstanceService.sol
+    InstanceServiceManager.sol
+  registry
+    ChainNft.sol
+    Registry.sol
+    RegistryService.sol
+    RegistryServiceManager.sol
+  shared
+    Registerable.sol
+    RegisterableUpgradable.sol
+  type
+    NftId.sol
+    ObjectType.sol
+

package/artifacts/contracts/components/Component.sol/Component.dbg.json

@@ -1,4 +1,4 @@
 {
   "_format": "hh-sol-dbg-1",
-  "buildInfo": "../../../build-info/5d58518916abd285d6742c7724f5c203.json"
+  "buildInfo": "../../../build-info/d562d636257f2606676a5d6ce99e5205.json"
 }