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

Information Per Vault

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

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.

Current relevant data recorded on Vstorage:

Vaults:

• published.vaultFactory
• published.vaultFactory.governance
  • "ChargingPeriod"
  • "Electorate"
  • "MinInitialDebt"
  • "RecordingPeriod"
  • "ReferencedUI"
  • "ShortfallInvitation"
• published.vaultFactory.managers
• published.vaultFactory.managers.manager0
• published.vaultFactory.managers.manager0.governance
  • "DebtLimit"
  • "InterestRate"
  • "LiquidationMargin"
  • "LiquidationPadding"
  • "LiquidationPenalty"
  • "MintFee"
• published.vaultFactory.managers.manager0.metrics
  • "liquidatingCollateral"
  • "liquidatingDebt"
  • "lockedQuote"
  • "numActiveVaults"
  • "numLiquidatingVaults"
  • "numLiquidationsAborted"
  • "numLiquidationsCompleted"
  • "retainedCollateral"
  • "totalCollateral"
  • "totalCollateralSold"
  • "totalDebt"
  • "totalOverageReceived"
  • "totalProceedsReceived"
  • "totalShortfallReceived"
• published.vaultFactory.managers.manager0.quotes
  • "quoteAmount”
• published.vaultFactory.managers.manager0.vaults
• published.vaultFactory.managers.manager0.vaults.vault0
  • "debtSnapshot"
  • "locked"
  • "vaultState"

Auctions

• published.auction
• published.auction.book0
  • "collateralAvailable":
  • "currentPriceLevel"
  • "remainingProceedsGoal"
  • "startCollateral"
  • "startPrice"
  • "startProceedsGoal"
• published.auction.governance
  • "AuctionStartDelay"
  • "ClockStep"
  • "DiscountStep"
  • "Electorate"
  • "LowestRate"
  • "PriceLockPeriod"
  • "StartFrequency"
  • "StartingRate"
• published.auction.schedule
  • "activeStartTime"
  • "nextDescendingStepTime"
  • "nextStartTime"

Unit tests

Context:

Considering that we intend to update the inter-protocol pkg source code to extend the data being published to the storage node for increased visibility of the vaults liquidation, auction and post auction distribution.
We plan to increase the test coverage in this regard to assure that our updates are behaving accordingly.

A more detailed description of the assignment and solution proposed can be found here

Open Questions:

1. Should we extend an existing test file, (e.g. inter-protocol/test/vaultFactory/test-vaultLiquidation.js), or create a new one?
2. In case of creating a new file, would it be beneficial for us to either build a file to export some support functions or extend an existing one, (e.g. vaultFactoryUtils.js), to avoid duplicating code.
   For example:

• setupBasics
• setupServices
• setClockAndAdvanceNTimes
• startAuctionClock
• bid
• ...

Current approach (WiP)

As an experiment to explore the liquidation visibility, without risking creating a conflict with a future merge, we create a new directory called liquidationVisibility that contain some of the tests created.

Work Plan:

• Establish scope of this task
• Establish success metrics and required test coverage
• Identify modules that will be updated