@agoric/inter-protocol 0.15.0 → 0.16.0

package/src/vaultFactory/liquidation.js

@@ -144,7 +144,7 @@ const setWakeups = ({
  * @param {TimerWaker} reschedulerWaker
  * @returns {Promise<void>}
  */
-const setWakeupsForNextAuction = async (
+export const setWakeupsForNextAuction = async (
   auctioneerPublicFacet,
   timer,
   priceLockWaker,
@@ -157,7 +157,12 @@ const setWakeupsForNextAuction = async (
     E(timer).getCurrentTimestamp(),
   ]);
 
-  trace('SCHEDULE', now.absValue, nextAuctionSchedule);
+  trace(
+    'setWakeupsForNextAuction at',
+    now.absValue,
+    'with',
+    nextAuctionSchedule,
+  );
   if (!nextAuctionSchedule) {
     // There should always be a nextAuctionSchedule. If there isn't, give up for now.
     cancelWakeups(timer);
@@ -175,35 +180,25 @@ const setWakeupsForNextAuction = async (
     params,
   });
 };
+harden(setWakeupsForNextAuction);
 
 /**
  * @param {Amount<'nat'>} debt
  * @param {Amount<'nat'>} minted
- * @returns {{ overage: Amount<'nat'>, shortfall: Amount<'nat'>, toBurn: Amount<'nat'>}}
+ * @returns {{ overage: Amount<'nat'>, shortfall: Amount<'nat'>}}
  */
-const liquidationResults = (debt, minted) => {
+export const liquidationResults = (debt, minted) => {
   if (AmountMath.isEmpty(minted)) {
-    return {
-      overage: minted,
-      toBurn: minted,
-      shortfall: debt,
-    };
+    return { overage: minted, shortfall: debt };
   }
 
   const [overage, shortfall] = AmountMath.isGTE(debt, minted)
     ? [AmountMath.makeEmptyFromAmount(debt), AmountMath.subtract(debt, minted)]
     : [AmountMath.subtract(minted, debt), AmountMath.makeEmptyFromAmount(debt)];
 
-  const toBurn = AmountMath.min(minted, debt);
-  // debt is fully accounted for, with toBurn and shortfall
-  assert(AmountMath.isEqual(debt, AmountMath.add(toBurn, shortfall)));
-
-  return {
-    overage,
-    toBurn,
-    shortfall,
-  };
+  return { overage, shortfall };
 };
+harden(liquidationResults);
 
 /**
  * Watch governed params for change
@@ -255,7 +250,7 @@ export const watchForGovernanceChange = (
  *    totalCollateral: Amount<'nat'>,
  *    liqSeat: ZCFSeat}}
  */
-const getLiquidatableVaults = (
+export const getLiquidatableVaults = (
   zcf,
   collateralizationDetails,
   prioritizedVaults,
@@ -298,9 +293,4 @@ const getLiquidatableVaults = (
 
   return { vaultData, totalDebt, totalCollateral, liqSeat };
 };
-
-harden(setWakeupsForNextAuction);
-harden(liquidationResults);
 harden(getLiquidatableVaults);
-
-export { setWakeupsForNextAuction, liquidationResults, getLiquidatableVaults };

package/src/vaultFactory/params.js

@@ -25,13 +25,13 @@ export const INTEREST_RATE_KEY = 'InterestRate';
 export const MINT_FEE_KEY = 'MintFee';
 export const MIN_INITIAL_DEBT_KEY = 'MinInitialDebt';
 export const SHORTFALL_INVITATION_KEY = 'ShortfallInvitation';
-export const ENDORSED_UI_KEY = 'EndorsedUI';
+export const REFERENCED_UI_KEY = 'ReferencedUI';
 
 export const vaultDirectorParamTypes = {
   [MIN_INITIAL_DEBT_KEY]: ParamTypes.AMOUNT,
   [CHARGING_PERIOD_KEY]: ParamTypes.NAT,
   [RECORDING_PERIOD_KEY]: ParamTypes.NAT,
-  [ENDORSED_UI_KEY]: ParamTypes.STRING,
+  [REFERENCED_UI_KEY]: ParamTypes.STRING,
 };
 harden(vaultDirectorParamTypes);
 
@@ -39,14 +39,14 @@ harden(vaultDirectorParamTypes);
  * @param {Amount<'set'>} electorateInvitationAmount
  * @param {Amount<'nat'>} minInitialDebt
  * @param {Amount<'set'>} shortfallInvitationAmount
- * @param {string} endorsedUi
+ * @param {string} referencedUi
  * @param {InterestTiming} interestTiming
  */
 const makeVaultDirectorParams = (
   electorateInvitationAmount,
   minInitialDebt,
   shortfallInvitationAmount,
-  endorsedUi,
+  referencedUi,
   interestTiming,
 ) => {
   return harden({
@@ -62,7 +62,7 @@ const makeVaultDirectorParams = (
       type: ParamTypes.INVITATION,
       value: shortfallInvitationAmount,
     },
-    [ENDORSED_UI_KEY]: { type: ParamTypes.STRING, value: endorsedUi },
+    [REFERENCED_UI_KEY]: { type: ParamTypes.STRING, value: referencedUi },
     [CHARGING_PERIOD_KEY]: {
       type: ParamTypes.NAT,
       value: TimeMath.relValue(interestTiming.chargingPeriod),
@@ -131,7 +131,7 @@ export const vaultParamPattern = M.splitRecord(
  *   reservePublicFacet: AssetReservePublicFacet,
  *   interestTiming: InterestTiming,
  *   shortfallInvitationAmount: Amount<'set'>,
- *   endorsedUi?: string,
+ *   referencedUi?: string,
  * }} opts
  */
 export const makeGovernedTerms = ({
@@ -144,7 +144,7 @@ export const makeGovernedTerms = ({
   reservePublicFacet,
   timer,
   shortfallInvitationAmount,
-  endorsedUi = 'NO ENDORSEMENT',
+  referencedUi = 'NO REFERENCE',
 }) => {
   return harden({
     auctioneerPublicFacet,
@@ -155,7 +155,7 @@ export const makeGovernedTerms = ({
       electorateInvitationAmount,
       minInitialDebt,
       shortfallInvitationAmount,
-      endorsedUi,
+      referencedUi,
       interestTiming,
     ),
     bootstrapPaymentValue,

package/src/vaultFactory/proceeds.js

@@ -0,0 +1,274 @@
+import { AmountMath } from '@agoric/ertp';
+import {
+  ceilDivideBy,
+  ceilMultiplyBy,
+  floorMultiplyBy,
+  makeRatioFromAmounts,
+  multiplyRatios,
+} from '@agoric/zoe/src/contractSupport/index.js';
+import { quoteAsRatio, subtractToEmpty } from '../contractSupport.js';
+import { liquidationResults } from './liquidation.js';
+
+/**
+ * @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
+ *
+ * The plan to execute for distributing proceeds of a liquidation.
+ *
+ * Vaults are referenced by index in the list sent to the calculator.
+ */
+
+/** @typedef {{ collateral: Amount<'nat'>, presaleDebt:  Amount<'nat'>, currentDebt: Amount<'nat'> }} VaultBalances */
+
+/**
+ * Liquidation.md describes how to process liquidation proceeds.
+ *
+ * This function is complex and may fail. To defend against this possibility, it
+ * starts with a base plan and updates it. The updating is the complex portion
+ * and is wrapped in a try/catch. If at any point the plan revising fails, the
+ * plan is returned as is.
+ *
+ * @param {object} inputs
+ * @param {AmountKeywordRecord} inputs.proceeds
+ * @param {Amount<'nat'>} inputs.totalDebt
+ * @param {Amount<'nat'>} inputs.totalCollateral
+ * @param {PriceDescription} inputs.oraclePriceAtStart
+ * @param {Array<VaultBalances>} inputs.vaultsBalances ordered best to worst collateralized
+ * @param {Ratio} inputs.penaltyRate
+ * @returns {DistributionPlan}
+ */
+export const calculateDistributionPlan = ({
+  proceeds,
+  totalDebt,
+  totalCollateral,
+  oraclePriceAtStart,
+  vaultsBalances,
+  penaltyRate,
+}) => {
+  const emptyCollateral = AmountMath.makeEmptyFromAmount(totalCollateral);
+  const emptyMinted = AmountMath.makeEmptyFromAmount(totalDebt);
+
+  const { Collateral: collateralProceeds } = proceeds;
+  /** @type {Amount<'nat'>} */
+  const collateralSold = AmountMath.subtract(
+    totalCollateral,
+    collateralProceeds,
+  );
+
+  const mintedProceeds = proceeds.Minted || emptyMinted;
+  const accounting = liquidationResults(totalDebt, mintedProceeds);
+
+  // charged in collateral
+  const totalPenalty = ceilMultiplyBy(
+    totalDebt,
+    multiplyRatios(penaltyRate, quoteAsRatio(oraclePriceAtStart)),
+  );
+
+  const debtPortion = makeRatioFromAmounts(totalPenalty, totalDebt);
+
+  // We mutate the plan so that at any point if there's an error the plan can be returned and executed.
+  // IOW the plan must always be in a valid state, though perhaps incomplete.
+  /** @type {DistributionPlan} */
+  const plan = {
+    overage: accounting.overage,
+    shortfallToReserve: accounting.shortfall,
+    collateralForReserve: emptyCollateral,
+    actualCollateralSold: emptyCollateral,
+    collateralSold,
+    collatRemaining: emptyCollateral,
+    debtToBurn: emptyMinted,
+    mintedForReserve: emptyMinted,
+    mintedProceeds,
+    phantomDebt: emptyMinted,
+    transfersToVault: [],
+    vaultsToReinstate: [],
+    totalPenalty,
+  };
+
+  /**
+   * If interest was charged between liquidating and liquidated, erase it.
+   *
+   * @param {VaultBalances} balances
+   */
+  const updatePhantomDebt = ({ presaleDebt, currentDebt }) => {
+    if (AmountMath.isEqual(presaleDebt, currentDebt)) {
+      return;
+    }
+    const accrued = AmountMath.subtract(currentDebt, presaleDebt);
+    plan.phantomDebt = AmountMath.add(plan.phantomDebt, accrued);
+  };
+
+  const runFlow1 = () => {
+    // Flow #1: no shortfall
+
+    const distributableCollateral = subtractToEmpty(
+      collateralProceeds,
+      totalPenalty,
+    );
+
+    plan.debtToBurn = totalDebt;
+    plan.mintedForReserve = accounting.overage;
+
+    // return remaining funds to vaults before closing
+
+    let leftToStage = distributableCollateral;
+    const price = makeRatioFromAmounts(mintedProceeds, collateralSold);
+
+    // iterate from best to worst, returning collateral until it has
+    // been exhausted. Vaults after that get nothing.
+    for (const [vaultIndex, balances] of vaultsBalances.entries()) {
+      const { collateral: vCollat, presaleDebt } = balances;
+      updatePhantomDebt(balances);
+
+      // max return is vault value reduced by debt and penalty value
+      const debtCollat = ceilDivideBy(presaleDebt, price);
+      const penaltyCollat = ceilMultiplyBy(presaleDebt, debtPortion);
+      const lessCollat = AmountMath.add(debtCollat, penaltyCollat);
+
+      const maxCollat = subtractToEmpty(vCollat, lessCollat);
+      if (!AmountMath.isEmpty(leftToStage)) {
+        const collatReturn = AmountMath.min(leftToStage, maxCollat);
+        leftToStage = AmountMath.subtract(leftToStage, collatReturn);
+        plan.transfersToVault.push([vaultIndex, { Collateral: collatReturn }]);
+      }
+    }
+
+    const hasCollateralToDistribute = !AmountMath.isEmpty(
+      distributableCollateral,
+    );
+    plan.collateralForReserve = hasCollateralToDistribute
+      ? AmountMath.add(leftToStage, totalPenalty)
+      : collateralProceeds;
+  };
+
+  // Flow 2a: all collateral was sold but debt was not covered
+  const runFlow2a = () => {
+    // charge penalty if proceeds are sufficient
+    const penaltyInMinted = ceilMultiplyBy(totalDebt, penaltyRate);
+    const recoveredDebt = AmountMath.min(
+      AmountMath.add(totalDebt, penaltyInMinted),
+      mintedProceeds,
+    );
+
+    plan.debtToBurn = recoveredDebt;
+
+    const distributable = subtractToEmpty(mintedProceeds, recoveredDebt);
+    let mintedRemaining = distributable;
+
+    const vaultPortion = makeRatioFromAmounts(distributable, totalCollateral);
+
+    // iterate from best to worst returning remaining funds to vaults
+    for (const [vaultIndex, balances] of vaultsBalances.entries()) {
+      // from best to worst, return minted above penalty if any remains
+      const vaultShare = floorMultiplyBy(balances.collateral, vaultPortion);
+      updatePhantomDebt(balances);
+
+      if (!AmountMath.isEmpty(mintedRemaining)) {
+        const mintedToReturn = AmountMath.min(mintedRemaining, vaultShare);
+        mintedRemaining = AmountMath.subtract(mintedRemaining, mintedToReturn);
+        plan.transfersToVault.push([vaultIndex, { Minted: mintedToReturn }]);
+      }
+    }
+  };
+
+  // Flow 2b: collateral remains but debt was not covered
+  const runFlow2b = () => {
+    plan.debtToBurn = totalDebt;
+    plan.mintedForReserve = accounting.overage;
+
+    // reconstitute vaults until collateral is insufficient
+    let reconstituteVaults = AmountMath.isGTE(collateralProceeds, totalPenalty);
+
+    // charge penalty if proceeds are sufficient
+    const distributableCollateral = subtractToEmpty(
+      collateralProceeds,
+      totalPenalty,
+    );
+
+    plan.collatRemaining = distributableCollateral;
+
+    let shortfallToReserve = accounting.shortfall;
+    const reduceCollateral = amount =>
+      (plan.actualCollateralSold = AmountMath.add(
+        plan.actualCollateralSold,
+        amount,
+      ));
+
+    // iterate from best to worst attempting to reconstitute, by
+    // returning remaining funds to vaults
+    for (const [vaultIndex, balances] of vaultsBalances.entries()) {
+      const { collateral: vCollat, presaleDebt } = balances;
+
+      // according to #7123, Collateral for penalty =
+      //   total liquidation penalty * vault debt / total debt
+      const vaultPenalty = ceilMultiplyBy(presaleDebt, debtPortion);
+      const collatPostPenalty = subtractToEmpty(vCollat, vaultPenalty);
+      const vaultDebt = floorMultiplyBy(presaleDebt, debtPortion);
+
+      // Should we continue reconstituting vaults?
+      reconstituteVaults =
+        reconstituteVaults &&
+        !AmountMath.isEmpty(collatPostPenalty) &&
+        AmountMath.isGTE(plan.collatRemaining, collatPostPenalty) &&
+        AmountMath.isGTE(totalDebt, presaleDebt);
+
+      if (reconstituteVaults) {
+        plan.collatRemaining = AmountMath.subtract(
+          plan.collatRemaining,
+          collatPostPenalty,
+        );
+        shortfallToReserve = subtractToEmpty(shortfallToReserve, presaleDebt);
+        // must reinstate after atomicRearrange(), so we record them.
+        plan.vaultsToReinstate.push(vaultIndex);
+        reduceCollateral(vaultDebt);
+        plan.transfersToVault.push([
+          vaultIndex,
+          { Collateral: collatPostPenalty },
+        ]);
+      } else {
+        updatePhantomDebt(balances);
+
+        reduceCollateral(vCollat);
+      }
+    }
+
+    plan.collateralForReserve = AmountMath.add(
+      plan.collatRemaining,
+      totalPenalty,
+    );
+
+    plan.shortfallToReserve = shortfallToReserve;
+  };
+
+  try {
+    if (AmountMath.isEmpty(accounting.shortfall)) {
+      // Flow #1: no shortfall
+      runFlow1();
+    } else if (AmountMath.isEmpty(collateralProceeds)) {
+      // Flow 2a: all collateral was sold but debt was not covered
+      runFlow2a();
+    } else {
+      // Flow #2b: There's unsold collateral; some vaults may be reinstated.
+      runFlow2b();
+    }
+  } catch (err) {
+    console.error('🚨 Failure running distribution flow:', err);
+    // continue to return `plan` in the state that was reached
+  }
+
+  return harden(plan);
+};
+harden(calculateDistributionPlan);

package/src/vaultFactory/types.js

@@ -21,15 +21,6 @@
  * @property {() => Invitation} makeSwapInvitation
  */
 
-/**
- * @typedef {object} Collateral
- * @property {Ratio} liquidationMargin
- * @property {Ratio} stabilityFee
- * @property {Ratio} marketPrice
- * @property {Ratio} interestRate
- * @property {Brand} brand
- */
-
 /**
  * @typedef {object} VaultManagerParamValues
  * @property {Ratio} liquidationMargin - margin below which collateral will be
@@ -108,7 +99,7 @@
  * @typedef {object} LiquidationStrategy
  * @property {() => KeywordKeywordRecord} keywordMapping
  * @property {(collateral: Amount, run: Amount) => Proposal} makeProposal
- * @property {(runDebt: Amount) => Promise<Invitation>} makeInvitation
+ * @property {(debt: Amount) => Promise<Invitation>} makeInvitation
  */
 
 /**

package/src/vaultFactory/vaultDirector.js

@@ -15,9 +15,6 @@ import {
 import { assertKeywordName } from '@agoric/zoe/src/cleanProposal.js';
 import {
   atomicRearrange,
-  getAmountIn,
-  getAmountOut,
-  makeRatioFromAmounts,
   makeRecorderTopic,
   provideEmptySeat,
   SubscriberShape,
@@ -87,7 +84,7 @@ const shortfallInvitationKey = 'shortfallInvitation';
  * @param {import('@agoric/zoe/src/contractSupport/recorder.js').MakeRecorderKit} makeRecorderKit
  * @param {import('@agoric/zoe/src/contractSupport/recorder.js').MakeERecorderKit} makeERecorderKit
  */
-export const prepareVaultDirector = (
+const prepareVaultDirector = (
   baggage,
   zcf,
   directorParamManager,
@@ -299,9 +296,7 @@ export const prepareVaultDirector = (
       }),
       public: M.interface('public', {
         getCollateralManager: M.call(BrandShape).returns(M.remotable()),
-        getCollaterals: M.call().returns(M.promise()),
-        getMetrics: M.call().returns(SubscriberShape),
-        getRunIssuer: M.call().returns(IssuerShape),
+        getDebtIssuer: M.call().returns(IssuerShape),
         getSubscription: M.call({ collateralBrand: BrandShape }).returns(
           SubscriberShape,
         ),
@@ -454,44 +449,10 @@ export const prepareVaultDirector = (
           /** @type {VaultManager} */
           return managerForCollateral(brandIn).getPublicFacet();
         },
-        /**
-         * @deprecated get `collaterals` list from metrics
-         */
-        async getCollaterals() {
-          // should be collateralManagers.map((vm, brand) => ({
-          return harden(
-            Promise.all(
-              [...collateralManagers.entries()].map(
-                async ([brand, managerIndex]) => {
-                  const vm = vaultManagers.get(managerIndex).self;
-                  const priceQuote = await vm.getCollateralQuote();
-                  return {
-                    brand,
-                    interestRate: vm.getGovernedParams().getInterestRate(),
-                    liquidationMargin: vm
-                      .getGovernedParams()
-                      .getLiquidationMargin(),
-                    stabilityFee: vm.getGovernedParams().getMintFee(),
-                    marketPrice: makeRatioFromAmounts(
-                      getAmountOut(priceQuote),
-                      getAmountIn(priceQuote),
-                    ),
-                  };
-                },
-              ),
-            ),
-          );
-        },
-        /** @deprecated use getPublicTopics */
-        getMetrics() {
-          return metricsKit.subscriber;
-        },
-        getRunIssuer() {
+        getDebtIssuer() {
           return debtMint.getIssuerRecord().issuer;
         },
         /**
-         * @deprecated get from the CollateralManager directly
-         *
          * subscription for the paramManager for a particular vaultManager
          *
          * @param {{ collateralBrand: Brand }} selector

package/src/vaultFactory/vaultFactory.js

@@ -13,9 +13,9 @@ import '@agoric/zoe/src/contracts/exported.js';
 
 // This contract wants to be managed by a contractGovernor, but it isn't
 // compatible with contractGovernor, since it has a separate paramManager for
-// each Vault. This requires it to manually replicate the API of contractHelper
-// to satisfy contractGovernor. It needs to return a creatorFacet with
-// { getParamMgrRetriever, getInvitation, getLimitedCreatorFacet }.
+// each VaultManager. This requires it to manually replicate the API of
+// contractHelper to satisfy contractGovernor. It needs to return a creatorFacet
+// with { getParamMgrRetriever, getInvitation, getLimitedCreatorFacet }.
 
 import { CONTRACT_ELECTORATE } from '@agoric/governance';
 import { makeParamManagerFromTerms } from '@agoric/governance/src/contractGovernance/typedParamManager.js';

package/src/vaultFactory/vaultHolder.js

@@ -3,10 +3,7 @@
  */
 import { AmountShape } from '@agoric/ertp';
 import { M, prepareExoClassKit } from '@agoric/vat-data';
-import {
-  SubscriberShape,
-  TopicsRecordShape,
-} from '@agoric/zoe/src/contractSupport/index.js';
+import { TopicsRecordShape } from '@agoric/zoe/src/contractSupport/index.js';
 import { UnguardedHelperI } from '../typeGuards.js';
 
 const { Fail } = assert;
@@ -22,7 +19,6 @@ const HolderI = M.interface('holder', {
   getCollateralAmount: M.call().returns(AmountShape),
   getCurrentDebt: M.call().returns(AmountShape),
   getNormalizedDebt: M.call().returns(AmountShape),
-  getSubscriber: M.call().returns(SubscriberShape),
   getPublicTopics: M.call().returns(TopicsRecordShape),
   makeAdjustBalancesInvitation: M.call().returns(M.promise()),
   makeCloseInvitation: M.call().returns(M.promise()),
@@ -91,10 +87,6 @@ export const prepareVaultHolder = (baggage, makeRecorderKit) => {
         },
       },
       holder: {
-        /** @deprecated use getPublicTopics */
-        getSubscriber() {
-          return this.state.topicKit.subscriber;
-        },
         getPublicTopics() {
           const { topicKit } = this.state;
           return harden({