Part 1 – Etherisc Blog

Part 1 – Etherisc Blog

In this article, we will go through all the steps of creating your very first product on top of GIF. So put your fingers on the keyboard and let’s get moving.

First of all, what is GIF? The acronym stands for “Generic Insurance Framework”. Its main goal is to provide a simple and clean interface to build decentralized insurance products. Core contracts are aimed to be deployed on-chain.

A product contract acts as a client and utilizes generic methods which are important parts of every policy lifecycle. From this point of view, a product’s business logic could be defined in a single smart contract and all the hard work is delegated to GIF.

Some insurance terminology

Before we start, let’s define some insurance specific terminology.

• An insurance company is a legal body which is qualified in accepting risks against a premium. In most countries, insurance companies need a license. The insurance company is not necessarily the entity which runs the technical process; it can also be outsourced to a service provider. Most of the other functions in the value chain can also be taken by other parties (e.g. distribution, claims management etc.). The only function which cannot be delegated is the actual transfer of the risk.
• An application is a formal request of the customer for an insurance policy. It is a signal from customer to the insurance company: “I ask for insurance cover”.
• The application is then checked by the insurance company and either accepted or declined. The process of accepting an application is called underwriting, and the person who performs this action is an “underwriter”. By underwriting, the insurance company commits itself to transfer the risk from the customer to the insurance company. This fact is documented in a contract. This contract is called policy. A contract is binding for both parties: The customer is committed to paying the premium and the insurance company is committed to covering a loss in case an insured event occurs.
• If an insured event occurs, the customer will typically file a claim — a step which can be omitted in case of parametric insurance where a data-driven oracle will take the responsibility to file the claim automatically.
• The claim is then checked by the insurance company and if the insurance company decides that the claim is justified then a payout is triggered (e.g. the insurance company will deny the claim if the premium has not been paid). Again, in a parametric case, the insurance company can delegate the decision to a rule-based engine or to an external independent oracle.
• Payouts can be done in one or more parts.

GIF provides generic functions for this lifecycle and a generic workflow which controls the sequence of states. In the next section, we will describe these functions and how they work in detail. Every function can be assigned to a role, which can be defined by the product designer. Typical roles are e.g. underwriter, claims manager, application manager, bookkeeper but of course the product designer is not limited to these.

Generic Lifecycle Functions

Here is the list of magic methods available for every product:

• _register (each product needs to be registered in order to get access to the GIF functionality)
• _newApplication (to put application data into the storage)
• _underwrite (to underwite an application and create a new policy)
• _decline (to decline an application)
• _newClaim (to create a new claim for policy)
• _confirmClaim (to confirm a claim and create a payout object)
• _declineClaim (to decline a claim)
• _payout (to confirm an off-chain payout)
• _request (to request data or action from the oracle)
• _createRole (to create roles for actors)
• _addRoleToAccount (to assign roles to actors)

Underscore is used here to highlight that the names of these methods are internal and you can override them in your product.

The idea

In this case, we will build an insurance product for an electronic store. This store sells screens for laptops.

Let’s assume that a screen is unrepairable. If it’s broken (and of course only if it is an insurance case), a payout should be equal to the price of the screen.

The pricing model is very simple. Let’s assume that a policy premium should be 10% of the laptop screen price.

A policy expiration period is 1 year.

Thу following actors will take part in the process: an application manager, an underwriter, a claims manager and a bookkeeper.

Here are the steps of the product life cycle:

• The customer applies for a policy.
• The application manager creates an application for the policy on behalf of the customer.
• The underwriter underwrites or declines the application.
• If the application is underwritten, a new policy is issued.
• If something wrong happens with the laptop screen, the customer can create a claim.
• The claims manager confirms or declines this claim.
• If the claim is confirmed, a new payout is created.
• Then, the bookkeeper should pay to the customer and confirm that the payout has been executed.
• After the expiration period ends, the policy should be expired.

Setting up the environment

Create two directories: “gif” for platform smart contracts and “product”.

mkdir -p gif product

Prerequisites:

You should have Node.js installed on your machine. The Node.js version should be >= 8.12.0 and the npm version should be >= 6.4.1. To test your contracts, we recommend the use of a smart contract development environment like truffle.

Then, clone the GIF repository. It’s worth mentioning that GIF contracts will be deployed to the mainnet and testnets soon (at the moment, we are working hard to create a sandbox for products) and contract addresses will be provided. Right now, GIF sandbox is under development and you need to deploy core contracts by yourself.

git clone https://github.com/etherisc/GIF
cd git
npm install
npm run bootstrap

Now deploy contracts to Ganache. You have 3 options on how to run it:

1. Download, install, and run the Ganache desktop version

2. If you prefer Docker, run:

npm run dev:services:run

3. Or install ganache-cli

npm install -g ganache-cli
ganache-cli

Now Ganache should start listening to localhost:8545 and we are ready to deploy contracts.

npm run migrate

Check deployed contract addresses, run:

npm run networks

Coding

Now we are ready to build a product. Get back to the “product” directory and run these commands.

npm init -y
npm install truffle
./node_modules/.bin/truffle init

This will bootstrap the Truffle project. Now install the “gif” package from the npm. Create a new file “EStoreInsurance.sol” in the contracts directory.

pragma solidity ^0.5.0;

import "@etherisc/gif/contract/Product.sol";

contract EStoreInsurance is Product 
}

First of all, we import the Product contract from the GIF package and inherit from it. From now if we deploy this contract, our product will become a client for GIF contracts. Look at these magic constants: NAME and POLICY_FLOW. NAME is a name for your product. The only restriction here is that it should fit 32-bytes length. The POLICY_FLOW constant should be defined to choose the core contract which will represent the policy lifecycle for this product. Right now, we have only such contract — “PolicyFlowDefault”.

In the constructor, we call the Product’s constructor and pass the address of ProductService to it (you should have it after GIF core contracts deployment). The Product’s constructor will call the “register” function and your product contract will be proposed as a product (and it should be approved by the administrator before this product starts to accept new applications).

The Product contract also provides roles management functionality to your contracts. We define “applicationManager”, “underwriter”, “claimsManager” and “bookkeeper” roles and assign them to the deployer account for the sake of simplicity.

Now let’s define objects required for risk definition.

struct Risk 

mapping(bytes32 => Risk) public risks;

The risk contains brand, model, and year fields.

Here is the function to calculate a premium:

function calculatePremium(uint256 _price) view returns (uint256 _premium) 

This function could be used to provide quotas to applicants.

Now we can define a function which will be used to apply for a policy

function applyForPolicy(
bytes32 _brand,
bytes32 _model,
uint256 _year,
bytes32 _serialNumber,
uint256 _price,
uint256 _premium,
bytes32 _currency,
bytes32 _customerExternalId
) external onlyWithRole("applicationManager") 

As well as all other functions for actors.

function underwriteApplication(uint256 _applicationId) external onlyWithRole("underwriter") 

function declineApplication(uint256 _applicationId) external onlyWithRole("underwriter") 

function createClaim(uint256 _policyId) external onlyWithRole("applicationManager") 

function confirmClaim(uint256 _applicationId, uint256 _claimId) external onlyWithRole("claimsManager") 

function confirmPayout(uint256 _claimId, uint256 _amount) external
onlyWithRole("bookkeeper") 

Don’t forget to define events for your product.

event LogRequestUnderwriter(uint256 applicationId);
event LogApplicationUnderwritten(uint256 applicationId, uint256 policyId);
event LogApplicationDeclined(uint256 applicationId);
event LogRequestClaimsManager(uint256 policyId, uint256 claimId);
event LogClaimDeclined(uint256 claimId);
event LogRequestPayout(uint256 payoutId);
event LogPayout(uint256 claimId, uint256 amount);

Congratulations!) You have just built your first insurance product!

In the next post, we will dive into the high-level architecture of GIF smart contracts from a bird’s eye view. You will see how the just defined functions play together, how we handle payments for premiums and payouts and how we handle data protection for customer data.

Stay tuned!

Published at Tue, 14 May 2019 13:05:58 +0000