feat(run-protocol): interest charging O(1) for all vaults in a manager

docs/threat_models/vaultFactory/vaultFactory.puml

@@ -41,8 +41,6 @@ node "Vat" {
         circle getDebtAmount
         circle getLiquidationSeat
         getLiquidationSeat -u-> LiquidationSeat
-        circle getLiquidationPromise
-        getLiquidationPromise -u-> LiquidationPromise
     }
 }
 Borrower -> makeLoanInvitation: open vault and transfer collateral

packages/run-protocol/README.md

@@ -0,0 +1,27 @@
+# RUN protocol
+
+## Overview
+
+RUN is a stable token that enables the core of the Agoric economy.
+
+By convention there is one well-known **VaultFactory**. By governance it creates a **VaultManager** for each type of asset that can serve as collateral to mint RUN.
+
+Anyone can make a **Vault** by putting up collateral with the appropriate VaultManager. Then
+they can request RUN that is backed by that collateral.
+
+In any vault, when the ratio of the debt to the collateral exceeds a governed threshold, it is
+deemed undercollateralized. If the result of a price check shows that a vault is
+undercollateralized, the VaultManager liquidates it.
+## Persistence
+
+The above states are robust to system restarts and upgrades. This is accomplished using the Agoric (Endo?) Collections API.
+
+## Debts
+
+Debts are denominated in µRUN. (1 million µRUN = 1 RUN)
+
+Each interest charging period (say daily) the actual debts in all vaults are affected. Materializing that across all vaults would be O(n) writes. Instead, to make charging interest O(1) we virtualize the debt that a vault owes to be a function of stable vault attributes and values that change in the vault manager when it charges interest. Specifically,
+- a compoundedInterest value on the manager that keeps track of interest accrual since its launch
+- a debtSnapshot on the vault by which one can calculate the actual debt
+
+To maintain that the keys of vaults to liquidate are stable requires that its keys are also time-independent so they're recorded as a "normalized collateralization ratio", with the actual collateral divided by the normalized debt.

packages/run-protocol/src/vaultFactory/interest.js

@@ -2,33 +2,31 @@
 
 import '@agoric/zoe/exported.js';
 import '@agoric/zoe/src/contracts/callSpread/types.js';
-import './types.js';
+import { natSafeMath } from '@agoric/zoe/src/contractSupport/index.js';
 import {
-  ceilMultiplyBy,
   makeRatio,
+  multiplyRatios,
+  quantize,
 } from '@agoric/zoe/src/contractSupport/ratio.js';
-import { AmountMath } from '@agoric/ertp';
-
-const makeResult = (latestInterestUpdate, interest, newDebt) => ({
-  latestInterestUpdate,
-  interest,
-  newDebt,
-});
+import './types.js';
 
 export const SECONDS_PER_YEAR = 60n * 60n * 24n * 365n;
 const BASIS_POINTS = 10000;
 // single digit APR is less than a basis point per day.
 const LARGE_DENOMINATOR = BASIS_POINTS * BASIS_POINTS;
 
 /**
- * @param {Brand} brand
+ * Number chosen from 6 digits for a basis point, doubled for multiplication.
+ */
+const COMPOUNDED_INTEREST_DENOMINATOR = 10n ** 20n;
+
+/**
  * @param {Ratio} annualRate
  * @param {RelativeTime} chargingPeriod
  * @param {RelativeTime} recordingPeriod
  * @returns {CalculatorKit}
  */
 export const makeInterestCalculator = (
-  brand,
   annualRate,
   chargingPeriod,
   recordingPeriod,
@@ -47,27 +45,41 @@ export const makeInterestCalculator = (
     BigInt(LARGE_DENOMINATOR),
   );
 
-  // Calculate new debt for charging periods up to the present.
-  /** @type {Calculate} */
+  /**
+   * Calculate new debt for charging periods up to the present.
+   *
+   * @type {Calculate}
+   */
   const calculate = (debtStatus, currentTime) => {
     const { newDebt, latestInterestUpdate } = debtStatus;
     let newRecent = latestInterestUpdate;
     let growingInterest = debtStatus.interest;
     let growingDebt = newDebt;
     while (newRecent + chargingPeriod <= currentTime) {
       newRecent += chargingPeriod;
-      const newInterest = ceilMultiplyBy(growingDebt, ratePerChargingPeriod);
-      growingInterest = AmountMath.add(growingInterest, newInterest);
-      growingDebt = AmountMath.add(growingDebt, newInterest, brand);
+      // The `ceil` implies that a vault with any debt will accrue at least one µRUN.
+      const newInterest = natSafeMath.ceilDivide(
+        growingDebt * ratePerChargingPeriod.numerator.value,
+        ratePerChargingPeriod.denominator.value,
+      );
+      growingInterest += newInterest;
+      growingDebt += newInterest;
     }
-    return makeResult(newRecent, growingInterest, growingDebt);
+    return {
+      latestInterestUpdate: newRecent,
+      interest: growingInterest,
+      newDebt: growingDebt,
+    };
   };
 
-  // Calculate new debt for reporting periods up to the present. If some
-  // charging periods have elapsed that don't constitute whole reporting
-  // periods, the time is not updated past them and interest is not accumulated
-  // for them.
-  /** @type {Calculate} */
+  /**
+   * Calculate new debt for reporting periods up to the present. If some
+   * charging periods have elapsed that don't constitute whole reporting
+   * periods, the time is not updated past them and interest is not accumulated
+   * for them.
+   *
+   * @type {Calculate}
+   */
   const calculateReportingPeriod = (debtStatus, currentTime) => {
     const { latestInterestUpdate } = debtStatus;
     const overshoot = (currentTime - latestInterestUpdate) % recordingPeriod;
@@ -79,3 +91,23 @@ export const makeInterestCalculator = (
     calculateReportingPeriod,
   });
 };
+
+/**
+ * compoundedInterest *= (new debt) / (prior total debt)
+ *
+ * @param {Ratio} priorCompoundedInterest
+ * @param {NatValue} priorDebt
+ * @param {NatValue} newDebt
+ */
+export const calculateCompoundedInterest = (
+  priorCompoundedInterest,
+  priorDebt,
+  newDebt,
+) => {
+  const brand = priorCompoundedInterest.numerator.brand;
+  const compounded = multiplyRatios(
+    priorCompoundedInterest,
+    makeRatio(newDebt, brand, priorDebt, brand),
+  );
+  return quantize(compounded, COMPOUNDED_INTEREST_DENOMINATOR);
+};

packages/run-protocol/src/vaultFactory/liquidation.js

@@ -15,7 +15,14 @@ const trace = makeTracer('LIQ');
  * Once collateral has been sold using the contract, we burn the amount
  * necessary to cover the debt and return the remainder.
  *
- * @type {VaultFactoryLiquidate}
+ * @param {ContractFacet} zcf
+ * @param {VaultKit} vaultKit
+ * @param {(losses: AmountKeywordRecord,
+ *             zcfSeat: ZCFSeat
+ *            ) => void} burnLosses
+ * @param {LiquidationStrategy} strategy
+ * @param {Brand} collateralBrand
+ * @returns {Promise<Vault>}
  */
 const liquidate = async (
   zcf,
@@ -24,7 +31,7 @@ const liquidate = async (
   strategy,
   collateralBrand,
 ) => {
-  vaultKit.liquidating();
+  vaultKit.actions.liquidating();
   const runDebt = vaultKit.vault.getDebtAmount();
   const { brand: runBrand } = runDebt;
   const { vaultSeat, liquidationZcfSeat: liquidationSeat } = vaultKit;
@@ -57,12 +64,13 @@ const liquidate = async (
   const isUnderwater = !AmountMath.isGTE(runProceedsAmount, runDebt);
   const runToBurn = isUnderwater ? runProceedsAmount : runDebt;
   burnLosses(harden({ RUN: runToBurn }), liquidationSeat);
-  vaultKit.liquidated(AmountMath.subtract(runDebt, runToBurn));
+  vaultKit.actions.liquidated(AmountMath.subtract(runDebt, runToBurn));
 
   // any remaining RUN plus anything else leftover from the sale are refunded
   vaultSeat.exit();
   liquidationSeat.exit();
-  vaultKit.liquidationPromiseKit.resolve('Liquidated');
+
+  return vaultKit.vault;
 };
 
 /**

packages/run-protocol/src/vaultFactory/orderedVaultStore.js

@@ -0,0 +1,71 @@
+// @ts-check
+// XXX avoid deep imports https://github.com/Agoric/agoric-sdk/issues/4255#issuecomment-1032117527
+import { makeScalarBigMapStore } from '@agoric/swingset-vat/src/storeModule.js';
+import { fromVaultKey, toVaultKey } from './storeUtils.js';
+
+/**
+ * Used by prioritizedVaults to wrap the Collections API for this use case.
+ *
+ * Designed to be replaceable by naked Collections API when composite keys are available.
+ *
+ * In this module debts are encoded as the inverse quotient (collateral over debt) so that
+ * greater collaterization sorts after lower. (Higher debt-to-collateral come
+ * first.)
+ */
+
+/** @typedef {import('./vault').VaultKit} VaultKit */
+/** @typedef {import('./storeUtils').CompositeKey} CompositeKey */
+
+export const makeOrderedVaultStore = () => {
+  // TODO make it work durably https://github.com/Agoric/agoric-sdk/issues/4550
+  /** @type {MapStore<string, VaultKit>} */
+  const store = makeScalarBigMapStore('orderedVaultStore', { durable: false });
+
+  /**
+   *
+   * @param {string} vaultId
+   * @param {VaultKit} vaultKit
+   */
+  const addVaultKit = (vaultId, vaultKit) => {
+    const { vault } = vaultKit;
+    const debt = vault.getDebtAmount();
+    const collateral = vault.getCollateralAmount();
+    const key = toVaultKey(debt, collateral, vaultId);
+    store.init(key, vaultKit);
+    return key;
+  };
+
+  /**
+   *
+   * @param {string} key
+   * @returns {VaultKit}
+   */
+  const removeByKey = key => {
+    try {
+      const vaultKit = store.get(key);
+      assert(vaultKit);
+      store.delete(key);
+      return vaultKit;
+    } catch (e) {
+      const keys = Array.from(store.keys());
+      console.error(
+        'removeByKey failed to remove',
+        key,
+        'parts:',
+        fromVaultKey(key),
+      );
+      console.error('  key literals:', keys);
+      console.error('  key parts:', keys.map(fromVaultKey));
+      throw e;
+    }
+  };
+
+  return harden({
+    addVaultKit,
+    removeByKey,
+    keys: store.keys,
+    entries: store.entries,
+    getSize: store.getSize,
+    values: store.values,
+  });
+};