Fire insurance implementation

Overview

The fire insurance product is a very simple example implementation for a product on the GIF with very few parameters. The idea is to provide a minimal implementation that can be used as a starting point for other products.

The fire insurance can insure a house (identified by its object name and object value) with a certain value against fire. In case of a fire, the oracle will provide the product with the size of the damage done by the fire (S, M, L). Depending on the size of the damage, the product will pay out a certain amount of money

  • S - None,

  • M - 20% of the object value

  • L - 100% of the object value.

The fire insurence product consists of three components (contracts):

  • The FireProduct contract is the main contract that implements the product logic

  • The FireRiskpool contract is the risk pool contract that holds the funds

  • The FireOracle contract is the oracle contract that provides the product with data from the outside world (in this case the size of the damage done by a fire)

Interaction diagram

The following diagram shows the interaction between the different components of the fire insurance product and the GIF.

Static

FireProduct (contracts/fire/FireProduct.sol)

The FireProduct contract inherits from the GIF Product contract. It provides three main functions (and also some helper functions which we will not discuss here)

  • applyForPolicy

  • expirePolicy

  • oracleCallback

applyForPolicy

The applyForPolicy function takes objectName and objectValue as parameters and used them to create a new policy for the given object. It returns the processId (policy id) of the newly created policy as well as the requestId of the orcacle (which is required to provide oracle response).

The applyForPolicy function first calculates the premium for the policy based on the objectValue. Thereafter it calls newApplication on the Product contract to create a new _Application. The Application is a data structure that holds all the information about the policy (e.g. the premium, the object name (encoded in the data field), the sum insured, etc.).

Right after the application is created, the underwrite function is called to underwrite and create the Policy, transfer the premium from the customer to the riskpool and set the policy into state _active. The important part here is to note, that the policy is only active after underwrite has been called and the premium transfer was _successful. If the premium transfer fails, the Application will remain in state Applied and no Policy is created. A separate underwrite function could be used to underwrite the policy at a later point in time, but this is not implemented in the fire insurance product.

Finally the _request is called to trigger a fire observation request for the house on the fire oracle.

Its important to note that the applyForPolicy function is called by the customer and not by the underwriter.

expirePolicy

The expirePolicy function takes the processId (policy id) as parameter and expires that policy.

To do that, it just calls the expire function on the Product contract which sets the state of the Policy to _Expired. No claims and payouts are possible after a policy has expired.

The expirePolicy function must be called by the owner of the product.

oracleCallback

The oracleCallback function takes the requestId, processId and (oracle) response as parameters and is called by the oracle to provide the product with the size of the damage done by the fire. As the method also includes claim and payout handling it leads to a completely automated claim and payout process which is executed together with the oracle response.

The function decodes the size of the damage from the response and calls the internal _handleClaim function.

_handleClaim first calculates the payout amount based on the size of the damage and the sum insured.

If the payout amount is larger than zero, a new Claim is created by calling _newClaim immediately followed by a call to `_confirmClaim to confirm the claim (which allows the payout to be processed).

Then a new Payout is created by calling _newPayout from the Product contract. After that the payout amount is transferred from the riskpool to the customer by calling _processPayout from the Product contract. Finally the policy is expired and closed by calling the respectve methods on the base class.

The four sequential calls to create and confirm the claim as well as create and process the payout can be split into two separate transactions if the product required a more complex claim handling and payout process.

This function can only be called by the oracle.

FireRiskpool (contracts/fire/FireRiskpool.sol)

The FireRiskpool contract inherits from the GIF BasicRiskpool contract. The BasicRiskpool always collateralizes one application using exactly one bundle.

The riskpool must provide (next to some other parameters) the collateralization level, the collateral token and the cap for the total sum insured of the riskpool.

It must also implement the bundleMatchesApplication method which provides the logic to match an application with a bundle. In the case of the fire insurance product this matching is very simple and the product will allow for any bundle and application combination for simplicty.

FireOracle (contracts/fire/FireOracle.sol)

The FireOracle contract inherits from the GIF Oracle contract. The purpose of the oracle is to provide the product with data from the outside world (in this case the size of the damage done by a fire). It needs to send requests to outside systems and return their results.

In the case of the fire insurance product, the oracle will simulate a request to a fire observation service by storing the request id and accepting the result via a call to the respond function.

The main methods are

  • request

  • respond

request

Takes the requestId and data as parameters.

The data parameter contains an abi encoded string with the objectName. The mapping from objectName to requestId is stored internally for later use in the respond function.

respond

Takes the requestId and fireCategory as parameters.

The fireCategory is then abi encoded to create the result data which is send back to the product via a call to the respond function on the Oracle contract. This call triggers the oracleCallback function on the product which will then handle the claim and payout process.

← Fire insurance registration