Simulation Outputs

Data produced by the simulation engine

The simulation engine runs different scenarios and generates a rich log for introspection and data analysis.

Here is an example of data generated by a simulation.

The results are published in different folders:

• results: Aerial view data -> a couple of aggregated CSV files: metrics.csv and policies.csv.

• states: Intermediate level data -> one CSV file per scenario, retracing the evolution of each scenario step by step.

• agents: Highest resolution data -> detailed logs per agent retracing their journeys and behaviours.

• reserves: One CSV file per scenario tracking the vault reserves at each step.

• trades: One CSV file per scenario tracking the trades performed by the protocol at each step.

The following sections will detail what you can expect to find in each of these folders.

Results

This folder is the first place to browse to get aggregated data about all scenarios and policies.

summary.csv

The file summary.csv summarizes all the outcomes in one line per scenario. You can use it to calculate averages, look at min/max, or 95% percentiles of each metric. It's the first place to look at to measure the financial consequences of our inputs, model our risk, and establish directional effects.

Columns in the file:

• scenario_id: Identifier of the scenario, to zoom further into it, one can browse to the states folder and find its full log, or the results folder and find some analytic charts.

• btc_return_ eth_return_: summary statistics about BTC and ETH price in the scenario's price trajectory

• reserve_start reserve_min reserve_max reserve_end: Starting, end, min and max values of the reserve during the scenario, expressed as percentages of the initial vault amount.

• vault_overdraft, vault_overdraft_alert: did the vault go under at any point in time, and by how much.

• pnl, pnl_start_to_end: profit & loss calculated 2 different ways, these 2 values should always be the same.

• disbursed, lent, repaid, open_fees, claim_fees, claim_fees_in, claim_fees_out, interests, interests_in, interests_out, penalties, losses, open_fees_plus_interests, claim_fees_plus_penalties: Totals accumulated in the Protocol Vault class, expressed as percentages of the initial vault amount. for claim fees and interests, in means that the total is charged and already recovered; vs out meaning the amount is charged but still outstanding.

• bought, bought_at_fc, sold: amounts traded during the simulation, bought_at_fc means it was exchanged against stable at foreclosure.

• collateral_reserve: value in usd of the collateral held at the end of the scenario.

• trading_income: profit and loss accrued by the balance sheet strategy.

• pnl_check: equals amount_owed + cash_flow

• promised2reserve_: capital efficiency stats.

• protection_cost protection_value: Total protection costs paid by agents vs total value created for them by using our protection (0 for agents who didn't claim; +/- difference with liquidation path for the ones who claimed.)

• protection_value4money: equals protection_value / protection_cost

• bottom_cash_flow_: Bottom of the predicted cashflows; in other words, the maximum amount that would need to be disbursed by the vault if all open policies were to claim.

• uncovered_liquidations: Number of uncovered liquidations that occurred during the scenario

• policies_: Statistics about the policies of the scenario.

• trades_: Statistics about the trades of the scenario.

policies.csv

The file policies.csv is a concatenation of all the policies that were bought across all scenarios. Each row has a rich set of information, +100 columns, to establish statistics and study the different lifecycles of our policies from start to end. Note that this file is simply a concatenation of all the files from the policies folder, and can be pretty big to analyze as a spreadsheet.

The columns contain +100 features to describe all the details of the policy lifecycle:

• When and how it started;

• At each step protection (loan disbursement), the price action, the position's supply and borrow, the LTV levels, and the amount owed.

• How it ended, by expiry, foreclosure or user repayment, plus the final state right before and after it was closed.

For the descriptions of its columns, please refer to the policies folder section below.

The descriptions of its columns are as follow:

• scenario_id

• agent_id

• duration: in days

• open_fee: percentage of promised amount.

• open_fee_amount: actual amount paid in fees.

• interest_rate interest_rate_day interest_rate_second: Yearly, daily and per-second interest rates.

• ltv_protect: LTV at which we trigger protection.

• close_tolerance: Buffer percentage to foreclose the loan if the value of the position gets too close to the amount owed to us.

• liquidation_buffer: Percentage under the lending protocol liquidation threshold at which we will foreclose.

• promised: Promised amount

• num_disbursements: Number of planned disbursements.

• policy_type: OCL or EC.

• num_claims amount_claimed: Number and amount claimed.

• amount_owed: Amount owed after claim and interests accrued.

• started_at ltv_at_start supply_at_start borrowed_at_start supplied_stable_prct supplied_btc_prct supplied_eth_prct price_btc_at_start price_eth_at_start: When did the policy start and a description of the position and collateral prices then

• debug

• expired_at ltv_at_expiration supplied_at_expiration borrowed_at_expiration: Information at the expiration time.

• ended_at protection_value price_btc_at_end price_eth_at_end return_btc_at_end return_eth_at_end return_at_end ltv_at_end supplied_at_end borrowed_at_end: Information at the end of the policy. Note that this can be different between the information at expiry because foreclosure can happen in-between expiry and end information.

• amount_repaid: Amount recovered by the protocol through user repayment or foreclosure.

• still_owed: Amount lost by the protocol on this policy, including interests and fees (=amount_owed - amount_repaid)

• userrepaid: Did the user repay the Concrete protocol? True/False.

• autorepaid: Did we auto-repay ourselves while keeping the position open (happens when LTV is low enough)? True/False

• foreclosed: Did we foreclose the position?

• protected_at_1 ltv_at_protect_1 supplied_at_protect_1 borrowed_at_protect_1 return_btc_at_protect_1 return_eth_at_protect_1 return_at_protect_1: Information at first protection, before we posted collateral.

• claimed_at_1 amount_claimed_1 return_btc_at_claim_1 return_eth_at_claim_1 return_at_claim_1 ltv_at_claim_1 supplied_at_claim_1 borrowed_at_claim_1: Information at first claim, after we posted collateral.

• foreclosure_reason: exp; liq or val:

  • exp: because the policy expired

  • liq: because the liquidation threshold of the lending protocol was too close.

  • val: because the value of the position was too close to the amount owed to us.

• ltv_at_foreclose supplied_at_foreclose borrowed_at_foreclose value_at_foreclose: Information at foreclosure time.

• ltv_at_user_repay: ltv when the user repaid us.

• ltv_at_auto_repay: ltv when we auto-repaid ourselves.

States

This folder contains one CSV file per scenario, where each row represents one step in its progression.

The files come with the following columns:

• cursor: step number

• day: day being simulated. Note that the cursor will generally step one day at a time, but when daily returns are high we start moving intra-day.

• price_btc, price_eth

• vault_reserve: current vault balance

• vault_disbursed, vault_fees, vault_interests, vault_penalties, vault_losses, vault_income, vault_received: these are cumulative values as accounted by the vault every time it received or disbursed funds.

• vault_promised, vault_lent: these are also accounted by the vault but not cumulative values.

• vault_lent_to_promised_ratio: vault_promised / vault_lent

• vault_cash_flow: vault_received - vault_disbursed (cumulative)

• current_active_policies, current_claimed_policies, current_amount_owed, current_amount_promised, total_policies_opened, total_policies_promised, total_policies_claimed: these values come from aggregating the policies at each step; unlike the accounting of the vault, these are not cumulative.

• total_protection_cost, total_protection_value: these are cumulative values storing the amount charged for protection vs the value, or effect, of buying a policy vs not buying it. By comparing protected vs a hypothetical unprotected outcome.

• ltvs_covered_0, ltvs_covered_1, ltvs_covered_2, ltvs_covered_3, ltvs_covered_4: these 5 values describe the distribution of covered LTVs at each step (minimum; 25%; median; 75% and max)

• drop_list_btc_bottom, drop_list_eth_bottom: these are calculations of the lowest point in a cumulative cash flow by drop in collateral price chart. In other words, the maximum amount that would need to be disbursed by the vault if all open policies were to claim. (see this chart for clarification)

• drop_list_bottom: drop_list_btc_bottom + drop_list_eth_bottom

• traj_: the fields starting with traj_ are the ones coming from the price trajectory, including prices and interest rates.

Agents

A typical simulation will consist of 100 scenarios with 1000 agents each, thus 100k agents.

But storing 100k CSV files is unpractical, therefore, we only store here some samples, tagged into some pre-defined categories:

• unprotected, liquidated: for uncovered agents.

• protected, single-claim, multi-claim, losses: for covered agents.

• low_value, high_value: agents featuring the lowest or highest value for money ratio when they used our product.

• foreclosed_val, foreclosed_liq, foreclosed_exp: the codes val, liq and exp stand for the following foreclosure reasons:

  • val: because the value of the position (supply minus borrow) is too close to the owed amount.

  • liq: because the LTV is close to the lending protocol liquidation threshold.

  • exp: because the policy expired and the user didn't repay their loan.

When navigating to one of these folders, you can find a list of agent's logs - the file name is the scenario number followed by the agent number.

The CSV files detail everything in an agent's journey, with the following columns:

• agent_id

• cohort: S, M, L or W

• credit: Credit bucket (0, 1, 2, 3)

• day: day being simulated. Note that the cursor will generally step one day at a time, but when daily returns are high we start moving intra-day.

• event: the type of event being logged:

  • interests: this event will happen at every step and accrue borrowing and supply interests.

  • position: the agent started or changed their borrowing position.

  • supply_ltv: the agent supplied new collateral to target a new LTV.

  • supply_add: the agent supplied new collateral specified with exact amounts.

  • borrow_set: sets the agent's borrowing amounts to new values.

  • liquidate: the agent is being liquidated by the lending protocol.

  • new_policy: the agent bought a new policy.

  • protect: the agent is being protected by their policy.

  • claimed: happens after protect to reflect the changes in the agent's position.

  • repay: the agent is repaying their Concrete loan.

  • auto_repay: the loan is being autorepaid by the protocol.

  • foreclose: the loan is being foreclosed for one of the reasons specified by the codes val, liq or exp (see above)

  • policy_expired

  • end_policy: happens after any of the above events that close the policy.

  • debug: can come with any debugging information.

• price_btc price_eth

• supplied borrowed ltv supplied_ borrowed_: supply and borrow amounts, LTV and percentages by token.

• policy_active: True/False

• policy_amount_owed: Current amount owed to the protocol.

• total_policies total_claimed total_protection_cost total_protection_value: Cumulative stats about the agent's policies.

• event_details: specific information about the event that doesn't fit in the other columns, for example foreclose event will come with the reason here; new_policy will have all the details of the new policy here, etc.

Reserves

The CSV describes the balance sheet strategy actions at each step, how much was available by token; how much was deemed required to buy to service policies; and how much was calculated as good to sell. It also logs the transactions to buy or sell collateral applied by the balance sheet strategy.

Trades

The CSV describes all the trades performed, including the ones triggered by the balance sheet strategy, to protect positions, or to execute foreclosures.

Description of the columns:

• day: simulation step

• direction: 'buy' or 'sell'

• token: 'btc' or 'eth'

• amount: in token units.

• is_background_swap: True/False.

• price: in stable.

• slippage_rate: percentage

• slippage: actual cost of slippage in usd.

• usd: value of the trade in usd