Work Plan: Write Liquidation Auction Results to Vstorage

[Jorge-Lopes]

Problem Definition

Currently when there are liquidatable vaults present in one of the vaultManagers, it's collateral is deposited into the auctioneer and a dutch auction is run. The problem is that too little information is exposed to vstorage for running financial analysis and being transparent overall.

Desired data to be exposed on vstorage:

1. Which vaults got liquidated and added to an auction. For each vault

   1. Vault manager
   2. Collateral at time of liquidation
   3. Debt at time of liquidation
   4. Time of liquidation

2. Auction details. For each auction run:

   1. Auction start time
   2. Auction end time
   3. Auction identifier
   4. Starting state
      1. Collateral offered
      2. IST target
   5. Ending state
      1. Collateral sold
      2. Collateral remaining
      3. IST raised
      4. IST target remaining

3. Post-auction funds distribution:

   1. Collateral asset for liquidation penalty sent to Reserve
   2. Collateral asset returned to vault holders
   3. Debt returned to vault holders (only happens in certain circumstances)
   4. Shortfall value sent to Reserve

Open Questions

• Time of liquidation data point
  • we've traced that liquidations are scheduled to take place when auctions are starting. This means time of liquidation = auctioneer.schedule.activeStartTime but not sure to include this here since this will be the same for multiple vaults going into the same auction.
• Post Auction Details.
  • to us, Post Auction Details means that the auction is completed AND all unsold collateral along with raised IST is returned to the respective vault managers. We feel the need to make this clarification because the auctioneer itself does a distribution too. Which handles sending the unsold collateral and the raised Bid to depositors then send any uneven Bid to reserve, if any.
• Collateral returned to vault
  • do we need to expose collateral returned in per vault basis for every individual vault?
• Debt returned to vault
  • what exactly do we mean here?

Solution Analysis

During our analysis, below are what we've found:

Auction Details

Data	Path	Derived
Auction identifier	published.auctioneer.{bookID}	-
Auction start	published.auctioneer.schedule.activeStartTime	-
Collateral offered	published.auctioneer.{bookID}.startCollateral	-
IST Target	published.auctioneer.{bookID}.startProceedsGoal	-
Collateral remaining	published.auctioneer.{bookID}.collateralAvailable	-
Collateral sold	-	(Collateral offered) - (Collateral remaining)
IST target remaining	published.auctioneer.{bookID}. remainingProceedsGoal	-
IST raised	-	(IST target )- (IST target remaining)

Information Per Vault

Data	Path	Derived
Vault Manager	-	Correlate collateral sold in auction and accepted in Vault Manager
Collateral at time of liquidation	-	collateralAmount recorded on vaultData
Debt at time of liquidation	-	debtAmount recorded on vaultData
Time of liquidation	-	Auction start time

No data correlating individual vaults to liquidations can be found in vstorage. This raises a requirement which we have to put new data to vstorage. When going over vaultManager code, we've found this in liquidateVauıtls method

 const { totalDebt, totalCollateral, vaultData, liqSeat } =
        getLiquidatableVaults(
          zcf,
          {
            quote: lockedQuote,
            interest: compoundedInterest,
            margin: liqMargin,
          },
          prioritizedVaults,
          liquidatingVaults,
          debtBrand,
          collateralBrand,
        );

Where vaultData has the following type definition;

/**
   * @type {MapStore<
   *   Vault,
   *   { collateralAmount: Amount<'nat'>; debtAmount: Amount<'nat'> }
   * >}
   */

This means vaultData will have the exact amounts of collateral and debt going into the liquidation which is what we want and can expose this to vstorage.

Post Auction Details

Data	Path	Derived
Collateral sent to reserve	-	plan.collateralForReserve
Collateral returned to vault	-	-
Debt returned to vault	-	-
Shortfall sent to reserve	-	plan.shortfallToReserve

Currently vstorage does not have any data in it in the sense that we described above. See this comment.

However, we've located where this data is in the vaultManager;

for (const [vault, balances] of bestToWorst) {
            vaultsInPlan.push(vault);
            vaultsBalances.push({
              collateral: balances.collateralAmount,
              // if interest accrued during sale, the current debt will be higher
              presaleDebt: balances.debtAmount,
              currentDebt: vault.getCurrentDebt(),
            });
          }
          harden(vaultsInPlan);
          harden(vaultsBalances);

          const plan = calculateDistributionPlan({
            proceeds,
            totalDebt,
            totalCollateral,
            oraclePriceAtStart: oraclePriceAtStart.quoteAmount.value[0],
            vaultsBalances,
            penaltyRate,
          });
          return { plan, vaultsInPlan };

Notice that we know what vaults are reinstated or marked as liquidated along with their respective balances. A plan object is built progressively by iterating over these vaults. Which has the type definition;

/**
 * @typedef {{
 *   overage: Amount<'nat'>,
 *   shortfallToReserve: Amount<'nat'>,
 *   collateralForReserve: Amount<'nat'>,
 *   actualCollateralSold: Amount<'nat'>,
 *   collateralSold: Amount<'nat'>,
 *   collatRemaining: Amount<'nat'>,
 *   debtToBurn: Amount<'nat'>,
 *   mintedForReserve: Amount<'nat'>,
 *   mintedProceeds: Amount<'nat'>,
 *   phantomDebt: Amount<'nat'>,
 *   totalPenalty: Amount<'nat'>,
 *   transfersToVault: Array<[number, AmountKeywordRecord]>,
 *   vaultsToReinstate: Array<number>
 * }} DistributionPlan

This plan object satisfies our needs in Post Auction Details more than enough. We can cherry pick which ones to expose in vstorage.

[Jorge-Lopes]

Establish scope of this task

We'll use this section what to deliver exactly. We aim to clarify the work scope here.

Will Deliver

Make the necessary updates to what's written to vstorage. Work on on-chain code.

Might Deliver

• A library for off-chain programs to query what's going on in inter-protocol liquidations. This deliverable depends on these variables;
  • The logic we use to derive some of the data gets so complex that it's better to wrap it up in a separate library.
  • Agoric OpCo requests such a feature
• Upgrade the dashboard in analytics page. This deliverable depends on these variables;
  • Agoric OpCo requests this front-end work to be implemented by BytePitch.

[Jorge-Lopes]

Considerations:

• Should be careful when adding new nodes to vstorage from a resource consumption and performance standpoint.
• It's probably better to initiate the UX work for analytics page as that might end up affecting how we structure data when writing to vstorage.
• Handling possible implications of querying multiple paths and assure that data is consistent.
• Update contracts which updates that are currently being blocked by other constraints. For example the auctioneer contract.

[Jorge-Lopes]

Work Plan

• Establish scope of this task
• Establish success metrics and required test coverage
• Identify modules that will require an updated
  • map desired data with currently recorded data
  • analyse sdk components that are writing to the relevant nodes
  • identify missing attributes and from where can this data be recorded on vstorage
• Build test environment
• Update necessary agoric contracts
• Build querying library or/and update inter protocol liquidations dashboard
• Provide documentation and demo

[Jorge-Lopes]

agoric-sdk

Link to agoric-sdk fork: https://github.com/Jorge-Lopes/agoric-sdk-liquidation-visibility

[otoole-brendan]

Update: as clarified on call yesterday scope of this work is does not extend to adding liquidation results to info.inter.trade or alternative dashboard