Ensuro Samples

Samples for using Ensuro protocol from the command line. Also the JS code is simple enough to take it to your project to integrate with Ensuro.

Authentication

Defender Relay

This repository is ready to use OpenZeppelin Defender relays. Defender relays are a service that manages an Ethereum account for you, keeping the private address and offers an HTTP interface to send the transactions.

For using this setup, you need to define the following environment variables:

export RELAY_API_KEY=<defender-api-key>
export RELAY_API_SECRET=<defender-api-secret>

Private Key authentication

Alternativelly, you can create your own private key and define the address and the RPC endpoint with the following environment variables:

export WEB3_RPC_URL=<RPC-url-such-as-https://polygon-mumbai.g.alchemy.com/v2/apikey>
export ACCOUNT_PK=<private key of the address, starting with 0x>

See getSigner() in envsigner.js for other options.

Pre-requisite - Money

The authenticated account sending the transactions needs USDC (besides the gas, check https://mumbaifaucet.com/ if you need MATIC on Mumbai). Also, you need to approve the spending of that USDC by the Ensuro protocol, at least for the amount of the premium.

On testnet, we use this contract as currency for the protocol.

We provide useful commands to use our faucet to get test USDC and approve the spending.

export POOL_ADDRESS=0x77066b63c710B4fA352018E0D8Af0e5cC7243181 # Mumbai address of Ensuro Pool
./cli.js faucet
./cli.js approve --spender $POOL_ADDRESS  # Does infinite approval, or you can specify --approval-limit

SignedQuoteRiskModule

In this kind of RiskModule the creation of the policies can be done only providing a quote signed by an authorized account.

These quotes are generated by an HTTP API provided by Ensuro, that based on given policy parameters replies with a quote indicating the premium to charge, loss probability and other parameters.

Getting the quote

export QUOTE_API_KEY=<api-key-provided-by-ensuro>
export QUOTE_API_URL=<quote-api-url-provided-by-ensuro>
./cli.js quote-policy $QUOTE_API_URL \
         --payout 5000 \
         --expiration 2592000 \
         --json-data '{"foo": "bar", "payout_type": "proportional"}'
         --output-file signed-quote-policy-input.json

This will do a POST call to the API and get a signed quote for the given policy parameters. The --output-file option saves the output in a format that's ready for the next operation, the smart contract call that will create the policy.json

Policy Creation

With the quote fields stored in signed-quote-policy-input.json we can now call the blockchain to create the policy. Another pre-requisite is the calling account needs to have enough USDC to pay the premium and issued an spending approval to the pool.

In some setups, the SignedQuoteRiskModule also requires the policy creation transaction to be executed by an authorized account with the component role POLICY_CREATOR_ROLE. Usually we leave this open in testnet.

export RM_ADDRESS=<address-of-the-risk-module>
export CUSTOMER=<policy-holder-address>
./cli.js new-policy signed-quote-policy-input.json --output-file signed-quote-policy-output.json

Policy Resolution

After the policy was created and before the expiration, you can resolve the policy with a payout less or equal to the payout specified in creation.

To be able to execute this operation, the account needs to be authorized with the RESOLVER_ROLE.

To execute the Policy Resolution transaction, all the fields of the Policy struct are required as parameter. They are stored in the output file by the previous command.

./cli.js resolve-policy signed-quote-policy-output.json 3000

Webhooks for creation and resolution

You can also use webhooks to create and resolve policies. These will take care of creating the quote, in some cases batching several policies to save on gas, and finally create the policies on-chain.

A command is provided to create policies through a webhook:

export QUOTE_API_KEY=<api-key-provided-by-ensuro>
export WEBHOOK_URL=<webhook-url-provided-by-ensuro>
export SIGNATURE_PK=<your-pk-authorized-to-sign-webhook-calls>
# Alternatively you can use a pre-shared-key
# export SIGNATURE_PSK=<pre-shared-key-provided-by-ensuro>

./cli.js new-policy-webhook \
  --jsonData '{ "partnerPolicyId": "78fb131b-95f9-4d9d-bc20-f29ea1952612" }' \
  --payout 1000.5 \
  --expiration 3600 \
  --eip191SigningKey "$SIGNATURE_PK" \
  "$WEBHOOK_URL"

TrustfullRiskModule

With this kind of RiskModule, the creation and the resolution of the policy is done trusting authorized users.

The account (or relay account) must have the role PRICER_ROLE to create policies and RESOLVER_ROLE to resolve.

npm install
node cli.js new-policy 1234 sample-policy.json <customer-address>
node cli.js resolve-policy PolicyData-1234.json true

The <customer-address> is the address that will pay the premium and receive the payout. To be able to pay the premium, before the creation of the policy the customer needs to approve the spending of the currency to the pool address. (see https://medium.com/ethex-market/erc20-approve-allow-explained-88d6de921ce9) . This approval might be infinite if you don't want to issue an approval transaction before each policy, the pool anyway will only spend the amount indicated in the premium parameter.

Policy parameters

The policy parameters are sent in the JSON file (if using the CLI or as function parameters if using ensuro.js)

{
  "payout": 110.0,  // Amount of the payout in USD
  "premium": 12.0,  // Amount of the premium
  "lossProb": 0.08,  // Probability of payout - 0.08 == 8%
  "expiration": 3600  // Expiration as relative time, can also be send as absolute epoch timestamp
}

SignedQuoteRiskModule and TieredSignedQuoteRiskModule

For this module policies must be created by previously obtaining a valid signature from an offchain service.

See the ensuro docs for details on using this offchain service.

A sample signed quote is available in sample-signed-quote.json.

npm install
node cli.js new-policy sample-policy-signed-quote.json <customer-address> --rmType SignedQuoteRiskModule

FlightDelayRiskModule

In this module the policies are resolved automatically using a Chainlink oracle. When the policy is created, a job is scheduled in Chainlink to be run at expectedArribal + tolerance + 120 that will call FlightAware API to verify if the flight arrived on time or not.

Besides this scheduled job, you can force the resolution of the policy (uses the same oracle, but doesn't wait) with the resolve-fd-policy command or calling ensuro.resolveFlightDelayPolicy javascript function.

npm install
node cli.js new-policy 1234 sample-flight-delay-policy.json <customer-address>
node cli.js resolve-fd-policy 1234

Policy parameters

The policy parameters are sent in the JSON file (if using the CLI or as function parameters if using ensuro.js)

{
  "flight": "UAL488",  // Flight airline and number
  "departure": 1641481200,  // Filed departure date (this two parameters identify the flight)
  "expectedArrival": 1641486660,
  "tolerance": 7200,  // In seconds - if (actualArribal - expectedArrival) > tolerance ==> payout
  "payout": 110.0,  // Amount of the payout in USD
  "premium": 12.0,  // Amount of the premium
  "lossProb": 0.08,  // Probability of payout - 0.08 == 8%
}