Architecture

The Decentralized Insurance Protocol (DIP) enables the creation and management of decentralized insurance products. The protocol is designed to be flexible and extensible, allowing for the creation of a wide range of insurance products.

The protocol supports a multi-chain ecosystem to let users choose the chain that best fits their needs. The protocol is designed to be chain agnostic, allowing for the deployment of the protocol on any EVM compatible chain.

The Generalized Insurance Framework (GIF) is a set of smart contracts that implement the Decentralized Insurance Protocol (DIP). The main Goal of the GIF is to support its users in creating and managing decentralized insurance products as efficitiently and safe as possible.

GIF users should be able to focus on their use case specific business logic. GIF takes care of the use case independent heavy lifting like managing policies, claims, payouts, managing collateral in pools, etc.

The GIF itself is a highly modularized and flexible infrastructure that can be deployed to any EVM compatible chain. Most contracts of the GIF will already be deployed and are ready to be used by the users.

For each supported chain a chain specific GIF setup is deployed. To link all chains together a global registry is deployed on mainnet. This global registry then holds the links to all chain specific registries as shown in the diagram below.

The global registry is deployed on mainnet can be understood as the directory and entry point for the entire protocol ecosystem.

The global registry contains entries for all protocol relevant objects on mainnet and a chain registry entry for each supported chain in the ecosystem. At the same time the global registy plays the role of the mainnet chain registry.

On each chain supported by the protocol, a chain registry is deployed. A chain registry contains entries for all protocol relevant objects on that specific chain. These entries hold basic metadata for each registered object. Each registry entry is backed by an NFT that defines the ownership of the object.

The GIF setup on any specific chain always consists of a registry and staking modules, services and instances as shown in the diagram below.

Registries have already been introduced in the text above. As mentioned above, a registry is the central entry point for all protocol objects on a specific chain. Registries also serve as the trusted source for protocol object information and relationships between different objects.

Once the instance is created it can be used to deploy a set of components contracts that are required to implement the use case. The framework provides template contracts for products, distributions, oracles, and pools that need to be extended to implement the actual business logic.

The staking module is used to manage the DIP that are staked by users to either the protocol itself or to an instance that is registered as a staking target.

Services implement the generic insurance business logic of the protocol. They also manage the communication between components, instances, the registry, and the staking module.

Each service is associated with a specific GIF release and has a defined domain scope, such as "Registry" or "Policy". Services are stateless and operate solely on the state of the module contracts they are involved with. Additionally, service contracts may interact with other service contracts. It is important to note that all service contracts are designed to be upgradeable, allowing for bug fixes and minor enhancements.

Breaking changes in any service, instance or component template contract would imply the deployment of a new GIF release.

The registry maintains a complete and reliable record of all relevant protocol objects. The registry module plays a critical role in the overall architecture of the protocol, facilitating the seamless integration and interoperability of the different instances, components, services and staking.

By centralizing object information and their relationships, registries ensure consistency and integrity across the protocol ecosystem. They provide a reliable foundation for the decentralized insurance protocol, enabling efficient and secure management of insurance products.

Registries are non-upgradeable. Once deployed, the registry contracts remain unchanged to maintain the integrity of the protocol’s object ecosystem. In addition, registry entries are immutable and cannot be altered or deleted once they have been written to the registry. This ensures that the protocol’s object ecosystem remains consistent and reliable.

Protocol objects are stored in the registry in the form of registry objects. A registry object is a simple data structure that holds the following properties.

The table below lists the different object types that can be stored in the registry.

Except for the protocol object each object in the registry is linked to a parent object. Every object has its defined parent object. The only exception are stake objects which may either have the protocol object or an instance object as its parent object.

The diagram below shows the registry object hierarchy.

The global registry is the parent object for all chain registries. On Mainnet the global registry may also serve as a parent object for service, staking and instance objects on mainnet.

The registry module diagram below provides an overview of the registry related contracts of a GIF deployment.

Contracts and their responsibilities are outlined below.

Instances provide the central context to create and operate actual protection/insurance use cases. The recommendation is to create a new instance for each new use case.

The purpose of an instance is to manage all necessary aspects and components to implement a use case. An instance is responsible for the handling of the following aspects:

New instances can only be created through the instance service contract. To enforce this behaviour only the instance service is authorized to register instances with the registry through the registry service.

This process ensures that it is not possible to deploy and register malicious instances when using the framework. The process also ensures that the inital wiring and authorization of a newly created instance is done completely and correctly.

Instance creation is the responsibility of the InstanceService. New instances are created using the function createInstance(). This function creates a complete set of instance contracts via cloning the contracts of its "master instance". This "master instance" is part of the deployment of every GIF release.

The principal steps of the instance creation process are outlined below: g 1. A new InstanceAdmin contract with its AccessManagerCloneable contract is cloned from the master instance.

The instance owner is responsible for granting and revoking of the predefined component owner roles. The instance owner may also define additional use case specific roles. The instance owner can also extend the authorization to use case specific supporting contracts.

The instance owner only interacts with the Instance contract although the actual authorization is managed by the InstanceAdmin contract. The available instance functions for authorization management are listed in the table below.

When an instance is created it is automatically registered as a staking target with the staking module. It is then in the responsibility of the instance owner to define the staking parameters for the instance. For this purpose the instance provides the functions listed in the table below.

The instance module diagram below provides an overview of the instance related contracts.

Contracts and their responsibilities are outlined below.

Components are are always linked to a specific instance. The term "component" covers four distinct types of components that together implement the actual use case specific business logic of a concrete use case.

The diagram below shows the architecture of an exemplary "My Product" use case. TODO remove or update module packages in diagram

Moudle contracts and their responsibilities are outlined below.

Every component contract has its own wallet address. As mentioned above the default wallet address is the component contract address.

To increase flexibility for use case specific implementations the component owner may also define an external wallet address. For example a gnosis safe or a multisig wallet. In such cases it is the responsibility of the external wallet owner to maintain adequate allowances from the external wallet to the components token handling contract.

Every component contract has its own token handling contract that manages token transfers to and from the component contract.

Moving tokens form an account to the component wallet requires a corresponding allowance from that account to the token handling contract. Moving tokens from the component wallet to a receiving account also requires an allowance from the component wallet to the token handling contract.

To illustrate this setup consider a premium payment. To buy a policy, a policy holder first needs to create an approval for the token handling contract of the policy component over the premium amount. The buying transaction then calculates the associated fees, commissions, and net premium amount. The token handler of the product component then executes the transfer of the product fee to the product wallet, the transfers of the distribution fee and commission to the distribution wallet, and the transfer of the pool fee, the bundle fee and the net premium to the pool wallet.

In the case of a payout the token handler of the pool component transfers the payout amount from the pool wallet to the policy holder.

Other uses component token handlers include fee withdrawals for component owners, commission withdrawals and risk capital collection from investors.

The component diagram below provides the overview of the component contract hierarchy.

The table below provides additional contract specific information.

The product component forms the central part of a use case implementation. It is responsible for the management of risk, application, policy, claim, and payout business objects.

Via the services shown in the diagram below, the product component stores its business objects data with the instance module and interacts with the other components that jointly implement the use case.

The responsibilities of the services interacting with the product component are described in detail in the business processes section below.

Product owners and policy holders are the relevant stakeholder accounts for product components.

The distribution component manages the process of selling policies. This includes the management of distributors (brokers) and referral codes associated with distributors. A distribution component is always linked to a single product component and cannot be shared between multiple product components.

Via the services shown in the diagram below, the distribution component stores its business objects data with the instance module.

The responsibilities of the services interacting with the distribution component are described in detail in the business processes section below.

Distribution owners and distributors are the relevant stakeholder accounts for distribution components.

The oracle component manages the interactions of the product cluster with the "real" worls. An oracle component is always linked to a single product component and cannot be shared between multiple product components.

Via the services shown in the diagram below, the oracle component stores its business objects data with the instance module.

The responsibilities of the services interacting with the oracle component are described in detail in the business processes section below.

Oracles only have oracle owners as stakeholders. In contrast to the other component types, the oracle owner does not need to manage any framework relevant variable parameters.

The oracle owner is represented by the account that holds the oracle NFT. The initial owner is specified via the getInitialInfo() function of the oracle component.

The pool component manages the funds required to collateralize policies. A pool component is always linked to a single product component and cannot be shared between multiple product components.

Via the services shown in the diagram below, the pool component stores its business objects data with the instance module.

The responsibilities of the services interacting with the pool component are described in detail in the business processes section below.

Pool owners and bundle owners are the relevant stakeholder accounts for pool components.

The protocl currently provides two options for staking the DIP protocol token.

The first option is protocol staking where a DIP holder directly stakes DIP token to the protocol. The staker receives a reward in the form of DIP tokens to incentivize the participation in the protocol. In the future staking to the protocol will be required to actively participate in the governance of the protocol. The reward rate, locking period and reserves are managed by the DIF as the protocol owner.

The second option is instance staking where DIP tokens are staked to a specific instance. Instance staking is required to enable the operation of the instance in relation to the total value locked by that instance. The instance owner may decide to stake the required DIP tokens from its own funds or incentivice other DIP holders to stake to the instance. When an instance owner decides to invite the community to stake to the instance the instance owner is responsible for setting the reward rate, the locking period and providing the reward reserves. The instance owner also has the possibility to cap the total amount of DIP that can be staked to the instance in relation to the total locked value of the instance.

These two staking options are managed by the staking module and the staking service.

The staking module diagram below provides an overview of the registry related contracts of a GIF deployment.

Contracts and their responsibilities are outlined below.

Logging is one of the key feature of the framework and ensures the transparency and traceability of all business processes. As described below complete and accurate logs are crucial for compliance assurance, data integrity and accuracy, audit trail for accountability, and legal and forensic evidence.

Compliance Assurance Depending on the use case this is a mandatory requirement to demonstrate how the operation of the product adheres to legal and regulatory standards by providing a clear, indisputable record of all transactions, modifications.

Data Integrity and Accuracy Complete logs also enable interested parties to ensure that all financial and operational data is accurate and unaltered. This is crucial to maintain the trust of external stakeholder trust.

Audit Trail for Accountability Complete and accurate logs serve as an audit trail that details who did what and when

Legal and Forensic Evidence In cases of disputes or litigation, logs can serve as evidence. Complete and accurate logging ensures that the evidence is credible and can be used in legal proceedings.

Autorization is a key concept in the GIF. Authorization is organized per supported chain and implemented in access admin contracts using role based access control. Role based access control involves roles, targets and functions level authorization.

Roles can be considered as lables or IDs that can be assigned (granted) to accounts or removed (revoked) from accounts. Accounts can either be externally owned accounts or contract accounts. The set of accounts that have a specific role is called the role members.

The term Targets is used for contracts for which function level authorization is managed by an access admin contract. That particular access admin contract is then called the authority of the target contract.

Function Level Authorization defines which fuctions of a target may be executed through which role. For each authorized function of a target the required role to access it is defined. Only a single role can be specified per function and only members of that role (both contracts and externally owned accounts) may then execute the function.

Access admin contracts manage explicit lists of named targets, roles and functions that are granted to these roles. It also provides view functions that allow to enumerate all available roles, current role members and all granted functions for every managed target.

The implementation of the access admin contract is based on OpenZeppelin’s AccessManagerUpgradeable and AccessManagedUpgradeable contracts.

The access admin contract extends the OpenZeppelin functionality by providing named roles, targets and functions and by providing the capability to enumerate all current role members and all granted functions for every managed target.

The access admin contract is the base contract for two specialized admin contracts. Per supported chain there is a registry admin contract and for each instance there is an instance admin contract.

The registry admin contract is the central contract that controls access to the registry, to staking as well as interactions between service contracts.

In the case of services the registry admin maintains access to service functions per major release in the sense that a service of a specific major release may only interact with services of the same major release.

For each instance an individual instance admin contract exits. This instance admin is used to manage authorizations for the interactions between the instance and all its linked components with all linked services.

Authorization for upgrading upgradeable contracts is a special case. Every upgradeable contract in GIF comes with its own proxy manager contract. Only this proxy manager contract may be used to upgrade an upgradeable contract. And only the owner of an upgradeable contract may execute an upgrade via this proxy manager contract.

The ownership of an GIF relevant upgradeable contract is defined via its NFT as recorded in the chain registry.

Upgradeability relies on OpenZeppelin’s TransparentUpgradeableProxy and ProxyAdmin contracts.

GIF releases follow semantic versioning, which includes major, minor, and patch releases. The major version number is incremented whenever there are breaking changes that could potentially disrupt existing functionality or compatibility.

For every major releases, a consistent set of upgradeable service contracts are deployed and registered with the registry. For non-breaking changes the existing service contracts are upgraded in place. The staking module is independently upgradeable and may be upgraded at any time. The registry module is non-upgradeable and is capable of serving multiple major releases simultaneously. Instance modules are non-upgradeable and directly linked to the service contracts of the same major release.

Adding a new major release is guarded by role based authorization including two roles, a GIF Admin role and the GIF Manager role.

The core deployment sets up the registry and the staking modules and includes all the wiring between the contracts needed for actual relese deployment. For each supported chain a core deployment is the required first step.

For the registry module deployments the contracts Registry, ChainNft, TokenRegistry, and RegistryAdmin are deployed and initialized. Where neceesary these contracts are linked to the registry admin contract that manages all authorization for both the registry and the staking module.

On mainnet the Regsitry contract is deployed and initialized with two entries, one for the protocol object and one for global registry. On any other chain the initial setup includes an additional entry for the chain registry.

The registry istelf deployes the ChainNFT contract that will hold NFT representations of all protocol relevant objects on this chain.

The TokenRegistry is deployed and initialized with the DIP token as staking token.

The RegistryAdmin contract is deployed intialized with the GIF Admin role and the GIF Manager role.

For the staking module deployment the contracts StakingReader, StakingStore, StakingManager and Staking are deployed and initialized. The staking contract is also registerd with the registry.

The release deployment is the second and final GIF deployment step to a specific chain. For each supported chain a release deployment is required. A release deployment to a new chain will only include the deployment of the latest major release. Initially this will be the GIF v3 release. In the future new major releases should be deployed on all chains that are actively supported by the protocol.

A release deployment consist of the deployment and authorization of a release specific and consistent set of service contracts. As the service authorization is restricted to other services of the same release, services are assigned release specific roles. Service authorization is managed by the registry admin contract and defines which service fuction may be called by which other service.

The process of a release deployment invlovles the GIF Admin and the GIF Manager roles. The GIF Admin role represents the principal owner of the protocol and GIF Manager role is the role that is authorized to deploy and register the service contracts with the release registry.