Introduction

In occasion of the Reflector challenge, aimed at displaying different use cases for the oracle’s decentralized price feeds in soroban smart contracts, at xycloo Labs decided to participate building Soroban Insurance.

This turned out to be a very interesting concept with a pretty solid use case: Soroban Insurance is a protocol that allows any user to purchase an insurance policy that protects against the possibility that a certain asset moves by a certain percentage or quantity with respect to another during a predefined period of time.

Reflector is Soroban’s first oracle protocol, providing decentralized price fees to soroban defi applications.

In this article we will dig into the protocol’s utility and functioning, as well as exploring the smart contract’s dynamics. You can find here the link to the protocol’s whitepaper.

Contracts

Different Pool Contracts can be deployed from a Factory Contract (not integrated yet - pools have to be deployed autonomously for now) and initialized with their factory parameters:

• The two assets the policies will follow: the volatile one and the base, like for example XLM against USDC.
• The triggering condition against which the buyer of the insurance is covered, also called volatility. If this condition verifies, a refund will be disbursed (like for example if XLM moves by more than 20% with respect to USDC).
• The contract periods, which define how long a policy could be valid.
• The multiplier, useful to let the pool initializer adjust the calculation of the insurance benefit (the amount that the covered individual receives in case the condition he protected against was met).
• The address of the Reflector Contract (the oracle) that will provide the price feed for the asset pair (more specifically the price of the volatile asset with respect to the base asset). The contract verifies that the covered condition is met based on the oracle response.
• The currency asset for the contract, that is the asset used to perform all operations in the pool (like to enroll in policies or receive reimbursements).

Liquidity Pools

Each Soroban Insurance contract (except for the factory) can be defined as a liquidity pool as we have two different kind of actors:

• On the one side we have the insured parties, or policyholders. An example of insurance could be: if XLM moves by more than 20% with respect to USDC in period t, the contract is going to refund the policyholder. The insured parties pay a fee or premium (p) to the contract for purchasing the insurance policy. But they’re also using the liquidity of the contract as, in case the claim event is resolved, the liquidity of the contract is used to refund them.
• On the other side there are the liquidity providers (LPs) that deposit funds in the pool for the current period (more on periods later) and earn the fees paid by the policy owners in the form of insurance premiums, but at the same time they take on the risk of losing their liquidity in case some policy owners need to be refunded.

Insurance-Contract Periods

To guarantee the integrity of the contract, each pool is divided into regular periods or intervals, the duration of which is defined by the pool initiator upon initialization. If for example the periods are set for 30 days, it means that from the initialization, every 30 days a new period will start (and the old one will finish). Each entry of the pool is tied to a specific period, except for the pool factory parameters (like the asset pair, the volatility etc.).

For example, if someone has provided 1000 XLM of liquidity in period 1, that liquidity will be stored as solely for this interval. The same can be said for the rewards earned from the pool fees or the insurance policies taken out . When that epoch finishes, everything starts all over again: everything that is related to the previous period is stored as bound to that epoch, and their value for the new one is set to zero.

Supply Side: Liquidity and Fee Rewards

We already covered the logic behind liquidity provision and fee-rewards: LPs deposit their liquidity that is locked to cover possible insurance benefits, while they split between each other the premiums paid (the fees paid for buying the insurance policies).

Let’s dig a bit deeper on how this mechanism actually works: upon liquidity deposit in a pool, liquidity provider shares (LP shares) are minted following Equation 1 (look at the whitepaper) and assigned to the provider. The equation states that the newly minted shares to LP i for period t will be equal to the deposited amount multiplied for the total supply of LP shares for that period up to the moment of the new deposit, and divided by the total liquidity in the contract for period t up to the new deposit expressed in the contract’s currency asset.

As everything else, LP shares are linked to a specific period. This liquidity (the principal) is locked and cannot be withdrawn during the period it was deposited, in order to avoid a fleet of liquidity in case a certain condition that would pay out an insurance benefit (and therefore decrease the pool liquidity) is about to be met.

Each liquidity provider will be able to remove its principal only when the period he performed the deposit in will be finished. This operation will be performed by burning their liquidity provider shares and receiving back the corresponding principal according to Equation 2 in the whitepaper. The equation states that the principal withdrawn by LP i for period t will be equal to the burnt shares multiplied by the total liquidity in the contract for period t up to the new withdrawal, divided by the total supply of LP shares for that period up to the moment of the new withdrawal

The insurance fees are instead immediately assigned to each liquidity provider upon insurance purchase based on their liquidity provider shares, and can be claimed or withdrawn by them at any moment (it is also possible for example to reinvest them in the pool immediately to compound the interest). Rewards for the liquidity provided are in fact specific for each period. The logic behind is that rewards have to be tied directly to the liquidity upon which they were generated. When the old period finishes, the rewards matured can still be withdrawn by the liquidity provided by specifying the period they were matured in.

It is clear at this point that there’s a fundamental distinction at the contract level between the principal (the liquidity) and the LPs rewards derived from the paid insurance premiums. The former is locked and its value reflected by the LPs shares, and the latter are stored and accumulated as a separate entry. They can be removed at any time and, unless they’re withdrawn and reinvested, never counted as part of the liquidity. The main consequence of that separation is that if a claim event happens, the amount is taken and subtracted from the pool liquidity, while the rewards remain untouched.

A crucial point is that the amount of liquidity in the pool determines how much insurance policies can be bought for that pool for a certain period. In fact, in order to ensure that all the possible claims can be satisfied, Equation 3 in the whitepaper needs to be always satisfied. The equation states that the total liquidity in the pool for period t always has to be greater or equal to the sum of all the individual possible insurance benefits for a period t (the amount the policy beneficiaries could be reimbursed if the covered event verifies - more on that later).

This means that the liquidity in the pool always has to be greater than the total possible reimbursements, and that before conceding a policy, Equation 4 of the whitepaper (stating that the total liquidity in the pool for period t always has to be greater than the new total possible reimbursements after a new policy purchase) needs to be satisfied. Trying to acquire a new policy if the condition is not met will result in an error.

Demand Side: Insurance Policy Purchase

Now that we have focused on the supply side, let’s concentrate on the demand, that is the insured parties, or those subjects who purchase insurance policies. The general mechanism is that, if there’s enough liquidity per the period, the insurance buyer purchases the policy by choosing a premium to pay. In the case that the covered event verifies, an insurance benefit will be disbursed from the contract in favor of the buyer. Now let’s expand on that dynamic.

Insurance Benefits: relation to t

The insurance benefit (or claim amount), is the amount the policyholder receives if the triggering event verifies. It is closely tied to the concept of contract periods, and explaining that relation allows us to expand on the functioning of the same: when you take out an insurance policy and we’re for example halfway into the current period (on the 15th day of a 30 day period), the insurance is going to be valid only for 15 days, that is until the end of the current period.

This means that, if the predefined condition to pay out the insurance claim amount (always the same for the same pool) is for example that XLM moves by more than 20% with respect to USDC from the moment you subscribed the insurance, you have less probability that this condition will be satisfied with respect to someone that purchased the policy at the beginning of the period (as you have less days). That’s why the insurance benefits are directly dependent on the time the insurance was purchased with respect to the end of the current period: if an insurance policy was purchased very close to the end, in the case the event verifies it’s going to have a much higher benefit with respect to a contract that was taken out at the beginning.

Insurance Premiums and how Benefits are Calculated

Before explaining how the benefit is actually calculated, we need to understand how insurance premiums work: the premium is the amount that someone pays to activate the insurance policy. In Soroban Insurance you can choose how much to pay as premium (as long as there’s enough liquidity - see “Liquidity”) and based on that, the claim amount is going to be determined.

The higher the premium you’re willing to pay, the higher the benefit, which as already mentioned also depends on the time left until the end of the current period and the multiplier which is set upon pool initialization and is meant to let the initializer adjust the benefit size: this relation is shown in Equation 5 in the whitepaper. It states that the insurance benefit for certain policy holder i for a certain period t will be equal to the insurance premium, multiplied by the multiplier, divided by the difference between the duration of a pool period and the elapsed time of the current period.

Claiming the Insurance Benefit

When the beneficiary notices the triggering event of the insurance verifies, he can call the contract’s claim_rewards function that will verify with Reflector if the claim is consistent (by comparing the current price with respect to when the policy was purchased). If the condition is met, the claim amount will be paid out. In this version of the protocol, the benefit-rewards by the policyholders (but not the liquidity-provider fees, which can be withdrawn at any time as seen before) can only be claimed during the period associated with the insurance policy.

This means that if the policy is for “period 1”, the triggering condition verifies and the claim is enforced in the same period, the benefit will be paid out. Claiming it the period after (period 2) will result in an error. Another crucial aspect to note is that the claim has to be made when the price is such that the triggering condition is verified, as the check uses as reference the current price upon claim.

Conclusion

The source code of soroban insurance is public, and anyone can deploy a pool, or interact with the already deployed one on testnet (CBPUNMPSJF7IDJVLIWJIYKXF7XVZGD3F24N2XP6EZFOA2QTFSEK5ILUP). The codebase will continue to evolve and improve, starting from the implementation of the factory contract. Any updates on Soroban Insurance will be posted on our channels!