Nik Erzetič I Trustless Insurance Market Using FDC Web2 Connectivity I Flare I ETHGlobal Prague

[Music] Hello everyone and welcome to the Flare Builder online workshops uh session number eight trustless insurance market using FDC web2 connectivity um is the name of this workshop. So basically what we'll be doing in today's workshop is we'll take a look at a simple insurance agency uh built on flare using FDC uh and in this weather agency will basically be collecting weather data from a p public API to resolve policies. Uh my name is Nick. I'm a dev rail here at Flare and um I hope you enjoy this workshop. So uh before we uh start the workshop uh let me just tell you that there will be uh a time slot for Q&A at the end.

Uh so please uh do write your questions uh in the chat. uh but I'll probably answer them uh at uh in the last 15 minutes of this workshop. Uh there will also be a quiz at the end um where and if you if you complete the quiz you will be eligible to win a full suit of flare merch. So stay tuned for that. Um but without further ado, let's get on with it.

So first of all, let's look at uh what data uh we'll be accessing. So we'll be using open weather which is a public facing API. you do have to register to use it but otherwise it is free. Um the only caveat is that you need to provide a um an API key with your requests uh which you get when you register here. Um so first of all let's look at what the basic idea of this weather agency is.

We will be writing a smart contract which will basically facilitate the whole exchange. Um but other than that um the agency will run truly through user input or through user actions and no actions on our side. Um there will be two agents involved in this scenario. The first we call the policy holder. Uh and this is the one the the agent that wants to ensure uh their assets or something.

Um the the second uh agent is the insurer and they are the one that are willing to take on the risk uh in exchange for a premium. So the way things will work is that the policy holder will first create a policy uh where they will specify a premium that they are willing to pay uh and the coverage that they accept expect in return. Um they will also specify uh for what time interval uh the policy is in effect and also a loss criterion that determines if the policy if the coverage should be paid out to them or not. And this in this case the loss criterion will be whether a minimum temperature has been reached for a certain day. Um so once the policy holder creates a policy, it is up to an insurer to uh calculate their risks um and take on a policy.

If they decide to accept the policy or claim it, they need to deposit the uh the coverage to the smart contract where the policy was created and they get paid the premium immediately and then the policy uh the policy coverage remains. with the smart contract until the policy is resolved. So there are three ways a policy is resolved. First of all, if the policy has not been claimed even uh and its expiration timestamp is reached uh the policy is retired and the premium is paid back to the policy holder. Now if the policy has been claimed then there are two scenarios how uh it can be resolved.

The first way it can be resolved is that each expiration time step is reached without a proof being provided that a loss has occurred. In that case, the coverage is refounded to the insurer. But if a provy proof is provided to the policy that the loss has occurred in this case that the meanment temperature has been reached then the policy coverage is paid to the policy holder. Now who is responsible for providing the proof? Well, no one is I mean no one is uh compelled to do it, but it is in the interest of the party that would receive the funds to resolve the policy.

So in the case of a loss, the policy holder would be the one to bring the proof and resolve the policy that way. Um and in the case that no loss has occurred, it is in the best interest of the the insurer that they uh expire the policy. Um so so that they can get their funds back. Um in this sense is truly decentralized because I mean all in all anyone can do it. a random person would be able to resolve a policy.

They just wouldn't get anything out of it. But um the fact of the matter is that this way of doing things is decentralized. Um so let me just get a sip of water. Um yeah. So let's now take a look at the API for open weather and more specifically uh the current weather and forecast.

So we will be using the flare data connector to get this data. The fair data connector allows us to uh access arbitrary web two data and bring that onchain. Um there are just there are basically three things that we need to provide uh to the FDC hub uh or to the FDC protocol so that it can um collect the data for us. The first uh the first uh piece of the the first piece of data that we need to provide is the URL of an of an uh of a public API that basically returns a JSON format formatted data to us. So in this case the URL that we will be uh providing is this one where we will replace the latitude and uh longitude with the appropriate uh values and I will show which ones in a second but they are not that important to be honest.

Um, we will also need to give them our API uh key. Um, and this one we get with a free account if we just go um somewhere somewhere on here. Uh, but I won't show them so that we avoid getting spam on my account. Um and we will also be providing units uh being metric um just because uh to make sure we're on the same page. So yeah, this we'll modify this URL and get back a JSON that looks somewhat something like this.

Um, a word about the JSON API at the station type. The only real limitation or the two real limitations on what it can do uh right now is that the API must be public or we must be able to provide a key the way we do here. um there can't be uh an intricate intricate protection around the API. That's the first constraint. And the second is that it has to return a JSON with the data in it.

So, as long as we can get the JSON object back, we're basically good to go. Um, so yeah, let's take a quick look at the uh JSON response that we get from the open weather API. We get the latitude and longitude of the closest weather station to the coordinates that we provided. And this will be important because in order to uh specify the policies in a way that we can uh that we can compare the coordinates. We will need to create a policy containing the coordinates of the closest weather station to the location that we are interested in.

Um then we get uh several things back like um like what count kind of weather it is for example here it is ID 83 clouds and this is contained in in another example uh that we've prepared but we won't be looking it this today. Um because what we'll be interested in is the current weather and specifically [Music] um where is it? Well, anyways, we will be interested in the minimum temperature. Um perhaps this one here is somewhat deprecated. Uh we'll look at a real example um in a little while.

Cool. So with that, let me first direct you to the Flare developer hub. So, uh you can find written guides for hardhead and foundry on this site. Uh although the weather insurance example is only uh available for hardhead as of yet. And now the second thing um the second site I want to show you is the flare hardhead starter.

Uh so this is the repository which contains the code for all these examples um including the weather uh insurance agency. So what I've done uh what I've done already is I've cloned uh the repository and then followed the instructions in the readme file. So I've run the yarn uh to install the dependencies. I've um I've created a EMV file and populated it with um insertion values. So I replace the private key with my private key.

Uh, and I've also added the um the API key for the open weather to my m uh file. Uh, and we will be reading the the value for the uh uh API key from the EMV file. Now um let's look at the contract for this example. We only need a sing uh single contract. Um in this case it is within the contracts weather insurance and mean temp agency dossole file.

Uh the second file is the one that I've mentioned uh that takes the ID of the weather um uh situation and basically decides whether a loss has occurred uh using that. Now, right at the top of the file, um we have a data transport object. Um this will come into play in a second. So, let's just skip that for now. Um and look at the main contract.

So the mean temp agency it has an array of registered policies and also a mapping uh from the ID of a policy to the address of the insurer. Um, we need this so we can pay back the coverage uh if a policy is expired without a proof of loss being provided. Um, but basically the main strct in this uh example is the policy. Um it has the address of the policy holder uh which is assigned automatically when policy holder creates the policy. Um then it contains the co coordinates which again need to be the coordinates of a um of the closest weather station.

Then there are the start and expiration timestamps. Um so which define the lifetime of a policy and then there is a the the minimum temp threshold which is the threshold value that if the if the temp the minimum temperature falls below this value that will constitute a loss. So this is the loss criteria. I've been uh I've mentioned at the start. Then there are the premium and coverage values um which we'll see how they are assigned in a second.

Um and then there's the policy status. The policy status is the enum which has three possible values. So when a policy is first created, it is unclaimed and um once uh a an insurance claims the policy, it becomes open and it remains open until it is settled. uh that is until until it is resolved, expired or retired and so then it becomes settled. Uh this is important so that we can um check whether check real quick whether a policy is even um worth uh examining uh or not because it will be It's it's a safety measure to ensure that only policies of the right status are accessed uh at certain steps.

And then there's the policy ID which is assigned automatically when a policy is created. Now here are a few events. they are omitted at the appropriate stages of the workflow and are self-descriptive. But now let's go through those stages u uh the stages I've described the stages at the start of the workshop. Um but yeah let's just go through them again.

So first of all, a policy needs to be created. Um the policy holder needs to specify the latitude and the longitude of the closest weather station. Then they must provide the start and expiration timestamps for the policy. They need to uh define what uh they consider a loss and uh what coverage they expect in return uh in case uh a loss occurs. Um you might be wondering where's the premium for the policy?

Well, the premium is defined by the uh value that they pay to the contract. So the first check we do is we check if any ether has been sent to the um to the pol to the contract and if the number is zero then we just revert because that's a policy no one would be willing to take. Um then we check the validity of the data of the timestamps. Um and if everything's uh if everything's fine, we create a new policy and assign the uh the message sender uh as the policy holder and declare the premium to be the value um that they sent with this transaction. uh and the ID is uh is taken to be the uh length of the uh array of of registered policies.

So um we just increase the ID of the current of the latest policy to one by one. Um and so we also add the policy to the list of registered policies. uh and then a policy created event is emitted. Cool. So that's the first step creating a policy.

The next one is uh claiming the policy. So an an insurer sees a policy that uh they find uh acceptable um and they uh perform a claim policy function call on this contract with the ID of the policy that they want to ensure. [Music] Um first of all um the policy has to be unclaimed as of yet. Then we check that a uh that the policy has not come into uh an effect yet. Uh because what we are trying to avoid here is the scenario where a policy would be seconds from expiration or something and someone would come in to sweep uh uh to basically sweep sweep out the premium without taking any risk at all.

Uh so that's why we do this. we only allow accepting uh policies before they come into effect. Uh and then we check that the insurer has paid uh the proper premium uh sorry the proper um the the proper coverage. Um and we are not bothered if the coverage is uh larger than expected. Um and we are not we we we aren't returning the value.

So it's up to the insurer to ensure that the value they pay equals to the coverage. Um but we could also uh implement a a refound method method here uh quite easily. Then we set the policy statement to open so that no one can claim it. Um we update uh the state uh we we update the state of the policy to open um and declare the uh sender of the transaction as uh the insurer for the policy. Um and only then do we pay the premium to the message sender and after that the event is also emitted.

But here's an important point. We first update the status of the policy before um sending the premium to the insurer. We need to do this so that uh a malicious actor doesn't uh send multiple calls to the contract um and take out uh a larger premium that uh they actually want um are willing to pay. Uh so it's very important that the state is updated before any transfer of funds occurs. Now we are almost to the end of the policy's lifetime here.

Um the last thing to do is to resolve a policy. What we need to do here is so a policy resolution can be triggered by anyone but in practice this would be uh the the party that has uh has the most to gain. Um what they do or rather the the policy holder is the usually the one that would do this. Um because this method, this function specifically is designed to uh return the the the to pay the policy coverage in case of a loss. So what the what the the agent that triggers the uh policy resolution needs to do is provide an an I JSON API proof.

um which also contains uh data which the policy will uh compare and of course the id of the policy. Uh this is the uh proof strct of the J of the JSON API at station type. Um so what we do is first of all we check that the policy is actually still open. Um and then we verify the proof. This happens automatically on chain.

Um, all we have to do is to um is to get the JSON API verification contract uh or the auxiliary contract um sorry the JSON API verification contract and call it verify JSON API on the proof that was provided and that will uh verify the proof. Um once the proof is deemed valid, we decode the data that we've been sent to the to a data transport object. This is the one that I've skipped over earlier. So um let's talk about it now. A data transport object is just a strct that we would like our data to be encoded with.

Uh and I'll explain in a second how we can specify uh this to the um FDC protocol. I mean how we can specify how uh data should be encoded. But as you can see it um it contains certain fields uh that can be taken from the uh JSON at the open weather API but more on that in a second. So um we decode the data. We make sure that the time stamp of the current block is greater than the start time stamp of the policy which means that the policy has come uh in an effect into an effect.

Um and we also check that the policy has not yet expired and if it has we expired the policy. So um the the policy holder is not incentivized to call this uh function uh if a policy has already expired. Um, we also check the coordinates and this is why it's important that they match the coordinates of the closest weather station. uh because the longitude and latitude in the data transport object are exactly the ones from the JSON API which are the um coordinates of the closest weather station. And then lastly we check that the minimum uh temperature threshold has been um exceeded.

Uh and so that the loss has occurred and if a loss has occurred then we proclaim the policy is settled. We update the state of the policy in the registry. Um and again we only transfer the funds to the policy holder once we've updated the state. Um and in this case we pay the policy coverage to the policy holder because a loss has occurred. Now let's look at the other two options for uh a policy to reaches the end of its lifetime.

The first one that's already been used is expire policy. Um, this one makes sure that the policy is open, that the time stamp of the current block exceeds the expiration timestamp of the policy. And if that is true, the policy is uh uh proclaimed as settled. uh the state is updated and the policy coverage is refunded to the uh insurer and the last uh option is to retire an unclaimed policy. Um basically no one is incentivized or rather the policy holder is in incentivized to do this if the policy has expired.

So what is the criterion for that it status is still unclaimed and the current time time stamp is greater than the start timestamp of the policy. Um in and if these two conditions are true, the policy status is set to settled. Uh the state is updated and a premium the premium is refound funded to the policy holder. Um and again an event is emitted. We have a few auxiliary functions here.

Um the re the one that's really interesting to us is the AI signature hack. Um this function does basically nothing. Um it only takes a data transport object as a as a parameter. But that's actually the key and the reason why we have it here. Um you see I mentioned that we need to specify to the FDC how to encode the data that it retrieves from the um from the uh uh API from the website.

Um, and there's a another thing there's a step in between which I'll focus on in a second. But yeah, we basically need to specify how to encode the data it gets back and we do that by providing AI the AI signature of the object that we want to the FDC. And this function helps us to do that because in hard hat once we have compiled uh the project we can go to artifacts contracts weather insurance m agency.soul console and mint temp pages JSON. And here we can look for AI signature hack.

Um the uh this is one of the functions here. And if we look at its inputs, we can we can take this object here which corresponds to the data transport object and we can just copy and give this to the uh FDC as one of the uh parameters. Editor will know how to encode the data it gets back. Cool. So, let me get a sip of water.

Um, there's one more thing to talk about right now. Um and that is how can we after getting back back something like that how can we extract only the things that we're interested in and make them compatible with solidity um and basically transform them into the data transport port object form which is again um something like that. So how do we produce this transformation and the answer is we use uh a jq filter. So, let's go to the JQ Playground website and let let's paste in the um the example JSON. And what this allows us to do is to for example get uh latitude by doing something like that.

Um, of course, the thing the thing that I've given it is not actually a valid JSON, which is very cool. Um, let's try to copy this one and hope this one works better. Um, yeah. And as you can see um uh we got our latitude by just simply calling the that lat field. But uh there is a small problem here and that is that what we get back is a floating point number and solidity doesn't do with floating point numbers.

So what is the solution? Well, we multiply it by a large number and then we'll be made aware or we'll be aware that um we're operating with multiples of a number. Um and another thing that we'll also have to do [Music]