@agoric/inter-protocol 0.13.3 → 0.13.4-dev-800c2bb.0

package/src/vaultFactory/liquidation.js

@@ -1,144 +1,306 @@
-// @ts-check
 // @jessie-check
 
-import { E } from '@endo/eventual-send';
 import { AmountMath } from '@agoric/ertp';
-import {
-  ceilMultiplyBy,
-  makeRatio,
-  offerTo,
-} from '@agoric/zoe/src/contractSupport/index.js';
-import { makeTracer } from '../makeTracer.js';
+import { makeTracer } from '@agoric/internal';
+import { observeIteration, subscribeEach } from '@agoric/notifier';
+import { makeScalarMapStore } from '@agoric/store';
+import { TimeMath } from '@agoric/time';
+import { atomicRearrange } from '@agoric/zoe/src/contractSupport/index.js';
+import { E } from '@endo/eventual-send';
+
+import { AUCTION_START_DELAY, PRICE_LOCK_PERIOD } from '../auction/params.js';
+import { makeCancelTokenMaker } from '../auction/util.js';
+
+const trace = makeTracer('LIQ');
 
-const trace = makeTracer('LIQ', false);
+/** @typedef {import('@agoric/time/src/types').TimerService} TimerService */
+/** @typedef {import('@agoric/time/src/types').TimerWaker} TimerWaker */
+/** @typedef {import('@agoric/time/src/types').CancelToken} CancelToken */
+/** @typedef {import('@agoric/time/src/types').RelativeTimeRecord} RelativeTimeRecord */
+
+const makeCancelToken = makeCancelTokenMaker('liq');
 
 /**
- * Threshold to alert when the price level falls enough that the vault
- * with the highest debt to collateral ratio will no longer be valued at the
- * liquidationMargin above its debt.
+ * This will normally be set. If the schedule goes sideways, we'll unschedule
+ * all events and unset it. When auction params are changed, we'll restart the schedule
  *
- * @param {Ratio} highestDebtRatio
- * @param {Ratio} liquidationMargin
+ * @type {object | undefined}
  */
-const liquidationThreshold = (highestDebtRatio, liquidationMargin) =>
-  ceilMultiplyBy(
-    highestDebtRatio.numerator, // debt
-    liquidationMargin,
+let cancelToken = makeCancelToken();
+
+const waitForRepair = () => {
+  // the params observer will setWakeup to resume.
+  console.warn(
+    '🛠️ No wake for reschedule. Repair by resetting auction params.',
   );
+};
+
+// Generally, canceling wakups has to be followed by setting up new ones but
+// not in the case of pausing wakeups. We do that in the event of invalid
+// schedule params. When they are repaired by governance, the wakers resume.
+/** @param {ERef<TimerService>} timer */
+const cancelWakeups = timer => {
+  if (cancelToken) {
+    void E(timer).cancel(cancelToken);
+  }
+  cancelToken = undefined;
+};
 
 /**
- * @param {ERef<PriceAuthority>} priceAuthority
- * @param {Ratio} highestDebtRatio
- * @param {Ratio} liquidationMargin
+ * Schedule wakeups for the *next* auction round.
+ *
+ * In practice, there are these cases to handle (with N as "live" and N+1 is "next"):
+ *
+ * | when (now within the range)      | what                                    |
+ * | -------------------------------- | --------------------------------------- |
+ * | [start N, nominalStart N+1]      | good: schedule normally the three wakers|
+ * | (nominalStart N+1, endTime N+1]  | recover: skip round N+1 and schedule N+2|
+ * | (endTime N+1, ∞)                 | give up: wait for repair by governance  |
+ *
+ * @param {object} opts
+ * @param {ERef<TimerService>} opts.timer
+ * @param {TimerWaker} opts.priceLockWaker
+ * @param {TimerWaker} opts.liquidationWaker
+ * @param {TimerWaker} opts.reschedulerWaker
+ * @param {import('../auction/scheduler.js').Schedule} opts.nextAuctionSchedule
+ * @param {import('@agoric/time/src/types').TimestampRecord} opts.now
+ * @param {ParamStateRecord} opts.params
+ * @returns {void}
  */
-const makeQuote = (priceAuthority, highestDebtRatio, liquidationMargin) => {
-  return E(priceAuthority).mutableQuoteWhenLT(
-    highestDebtRatio.denominator, // collateral
-    liquidationThreshold(highestDebtRatio, liquidationMargin),
+const setWakeups = ({
+  nextAuctionSchedule,
+  now,
+  timer,
+  reschedulerWaker,
+  liquidationWaker,
+  priceLockWaker,
+  params,
+}) => {
+  const { startTime, endTime } = nextAuctionSchedule;
+
+  /** @type {RelativeTimeRecord} */
+  // @ts-expect-error Casting
+  // eslint-disable-next-line no-restricted-syntax -- https://github.com/Agoric/eslint-config-jessie/issues/33
+  const priceLockPeriod = params[PRICE_LOCK_PERIOD].value;
+  /** @type {RelativeTimeRecord} */
+  // @ts-expect-error Casting
+  // eslint-disable-next-line no-restricted-syntax -- https://github.com/Agoric/eslint-config-jessie/issues/33
+  const auctionStartDelay = params[AUCTION_START_DELAY].value;
+
+  // nominal is the declared start time, but the actual auctioning begins after auctionStartDelay
+  const nominalStart = TimeMath.subtractAbsRel(startTime, auctionStartDelay);
+
+  // Is there a problem (case 2 or 3)?
+  // setWakeupsForNextAuction is supposed to be called just after an auction
+  // started. If we're late but there's still time for the nominal start, then
+  // we'll proceed. Reschedule for the next round if that's still in the future.
+  // Otherwise, wait for governance params to change.
+  if (TimeMath.compareAbs(now, nominalStart) > 0) {
+    // nominalStart is past, so cancel timers and plan to recover
+    cancelWakeups(timer);
+
+    if (TimeMath.compareAbs(now, endTime) < 0) {
+      // We're currently scheduling the N+1 (where N is live), but we need to skip it.
+      // So wake up for the N+2 round's startTime
+      const afterNextStartTime = TimeMath.addAbsRel(endTime, 1n);
+      trace(
+        'CASE 2: endTime is in the future or now so reschedule waking to startTime of the following round',
+        afterNextStartTime,
+      );
+      void E(timer).setWakeup(afterNextStartTime, reschedulerWaker);
+    } else {
+      trace('CASE 3: endTime is past; wait for repair');
+      waitForRepair();
+    }
+
+    return;
+  }
+  trace('CASE 1: nominalStart is now or in the future');
+
+  cancelToken = cancelToken || makeCancelToken();
+  const priceLockWakeTime = TimeMath.subtractAbsRel(
+    nominalStart,
+    priceLockPeriod,
   );
+  const a = t => TimeMath.absValue(t);
+  trace('scheduling ', a(priceLockWakeTime), a(nominalStart), a(startTime));
+  void E(timer).setWakeup(priceLockWakeTime, priceLockWaker, cancelToken);
+  void E(timer).setWakeup(nominalStart, liquidationWaker, cancelToken);
+  // Call setWakeupsForNextAuction again one tick after nominalStart
+  const afterStart = TimeMath.addAbsRel(startTime, 1n);
+  void E(timer).setWakeup(afterStart, reschedulerWaker, cancelToken);
 };
 
 /**
+ * Schedule wakeups for the *next* auction round.
+ *
+ * Called by vaultDirector's resetWakeupsForNextAuction at start() and every
+ * time there's a "reschedule" wakeup.
  *
- * @param {PromiseLike<MutableQuote>} quote
- * @param {Ratio} highestDebtRatio
- * @param {Ratio} liquidationMargin
+ * @param {ERef<import('../auction/auctioneer.js').AuctioneerPublicFacet>} auctioneerPublicFacet
+ * @param {ERef<TimerService>} timer
+ * @param {TimerWaker} priceLockWaker
+ * @param {TimerWaker} liquidationWaker
+ * @param {TimerWaker} reschedulerWaker
+ * @returns {Promise<void>}
  */
-const updateQuote = (quote, highestDebtRatio, liquidationMargin) => {
-  E(quote).updateLevel(
-    highestDebtRatio.denominator, // collateral
-    liquidationThreshold(highestDebtRatio, liquidationMargin),
-  );
+const setWakeupsForNextAuction = async (
+  auctioneerPublicFacet,
+  timer,
+  priceLockWaker,
+  liquidationWaker,
+  reschedulerWaker,
+) => {
+  const [{ nextAuctionSchedule }, params, now] = await Promise.all([
+    E(auctioneerPublicFacet).getSchedules(),
+    E(auctioneerPublicFacet).getGovernedParams(),
+    E(timer).getCurrentTimestamp(),
+  ]);
+
+  trace('SCHEDULE', now.absValue, nextAuctionSchedule);
+  if (!nextAuctionSchedule) {
+    // There should always be a nextAuctionSchedule. If there isn't, give up for now.
+    cancelWakeups(timer);
+    waitForRepair();
+    return;
+  }
+
+  setWakeups({
+    nextAuctionSchedule,
+    now,
+    timer,
+    reschedulerWaker,
+    liquidationWaker,
+    priceLockWaker,
+    params,
+  });
 };
 
 /**
- * Liquidates a Vault, using the strategy to parameterize the particular
- * contract being used. The strategy provides a KeywordMapping and proposal
- * suitable for `offerTo()`, and an invitation.
- *
- * Once collateral has been sold using the contract, we burn the amount
- * necessary to cover the debt and return the remainder.
+ * @param {Amount<'nat'>} debt
+ * @param {Amount<'nat'>} minted
+ * @returns {{ overage: Amount<'nat'>, shortfall: Amount<'nat'>, toBurn: Amount<'nat'>}}
+ */
+const liquidationResults = (debt, minted) => {
+  if (AmountMath.isEmpty(minted)) {
+    return {
+      overage: minted,
+      toBurn: 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,
+  };
+};
+
+/**
+ * Watch governed params for change
  *
+ * @param {ERef<import('../auction/auctioneer.js').AuctioneerPublicFacet>} auctioneerPublicFacet
+ * @param {ERef<TimerService>} timer
+ * @param {TimerWaker} reschedulerWaker
+ * @returns {void}
+ */
+export const watchForGovernanceChange = (
+  auctioneerPublicFacet,
+  timer,
+  reschedulerWaker,
+) => {
+  void E.when(E(timer).getCurrentTimestamp(), now =>
+    // make one observer that will usually ignore the update.
+    observeIteration(
+      subscribeEach(E(auctioneerPublicFacet).getSubscription()),
+      harden({
+        async updateState(_newState) {
+          if (!cancelToken) {
+            cancelToken = makeCancelToken();
+            void E(timer).setWakeup(
+              // bump one tick to prevent an infinite loop
+              TimeMath.addAbsRel(now, 1n),
+              reschedulerWaker,
+              cancelToken,
+            );
+          }
+        },
+      }),
+    ),
+  );
+};
+
+/**
  * @param {ZCF} zcf
- * @param {Vault} vault
- * @param {Liquidator}  liquidator
- * @param {Brand} collateralBrand
- * @param {Ratio} penaltyRate
+ * @param {object} collateralizationDetails
+ * @param {PriceQuote} collateralizationDetails.quote
+ * @param {Ratio} collateralizationDetails.interest
+ * @param {Ratio} collateralizationDetails.margin
+ * @param {ReturnType<typeof import('./prioritizedVaults.js').makePrioritizedVaults>} prioritizedVaults
+ * @param {SetStore<Vault>} liquidatingVaults
+ * @param {Brand<'nat'>} debtBrand
+ * @param {Brand<'nat'>} collateralBrand
+ * @returns {{
+ *    vaultData: MapStore<Vault, { collateralAmount: Amount<'nat'>, debtAmount:  Amount<'nat'>}>,
+ *    totalDebt: Amount<'nat'>,
+ *    totalCollateral: Amount<'nat'>,
+ *    liqSeat: ZCFSeat}}
  */
-const liquidate = async (
+const getLiquidatableVaults = (
   zcf,
-  vault,
-  liquidator,
+  collateralizationDetails,
+  prioritizedVaults,
+  liquidatingVaults,
+  debtBrand,
   collateralBrand,
-  penaltyRate,
 ) => {
-  trace('liquidate start', vault);
-  vault.liquidating();
+  const vaultsToLiquidate = prioritizedVaults.removeVaultsBelow(
+    collateralizationDetails,
+  );
+  /** @type {MapStore<Vault, { collateralAmount: Amount<'nat'>, debtAmount:  Amount<'nat'>}>} */
+  const vaultData = makeScalarMapStore();
 
-  const debt = vault.getCurrentDebt();
+  const { zcfSeat: liqSeat } = zcf.makeEmptySeatKit();
+  let totalDebt = AmountMath.makeEmpty(debtBrand);
+  let totalCollateral = AmountMath.makeEmpty(collateralBrand);
+  /** @type {import('@agoric/zoe/src/contractSupport/atomicTransfer.js').TransferPart[]} */
+  const transfers = [];
 
-  const vaultZcfSeat = vault.getVaultSeat();
+  for (const vault of vaultsToLiquidate.values()) {
+    vault.liquidating();
+    liquidatingVaults.add(vault);
 
-  const collateralToSell = vaultZcfSeat.getAmountAllocated(
-    'Collateral',
-    collateralBrand,
-  );
-  trace(`liq prep`, { collateralToSell, debt, liquidator });
-
-  const { deposited, userSeatPromise: liqSeat } = await offerTo(
-    zcf,
-    E(liquidator).makeLiquidateInvitation(),
-    harden({ Collateral: 'In', Minted: 'Out' }),
-    harden({
-      give: { In: collateralToSell },
-      want: { Out: AmountMath.makeEmpty(debt.brand) },
-    }),
-    vaultZcfSeat,
-    vaultZcfSeat,
-    harden({ debt, penaltyRate }),
-  );
-  trace(` offeredTo`, { collateralToSell, debt });
+    const collateralAmount = vault.getCollateralAmount();
+    totalCollateral = AmountMath.add(totalCollateral, collateralAmount);
 
-  // await deposited and offer result, but ignore the latter
-  const [proceeds] = await Promise.all([
-    deposited,
-    E(liqSeat).getOfferResult(),
-  ]);
-  // NB: all the proceeds from AMM sale are on the vault seat instead of a staging seat
-
-  const [overage, shortfall] = AmountMath.isGTE(debt, proceeds.Minted)
-    ? [
-        AmountMath.makeEmptyFromAmount(debt),
-        AmountMath.subtract(debt, proceeds.Minted),
-      ]
-    : [
-        AmountMath.subtract(proceeds.Minted, debt),
-        AmountMath.makeEmptyFromAmount(debt),
-      ];
-
-  const toBurn = AmountMath.min(proceeds.Minted, debt);
-  // debt is fully accounted for, with toBurn and shortfall
-  assert(AmountMath.isEqual(debt, AmountMath.add(toBurn, shortfall)));
+    const debtAmount = vault.getCurrentDebt();
+    totalDebt = AmountMath.add(totalDebt, debtAmount);
+    transfers.push([
+      vault.getVaultSeat(),
+      liqSeat,
+      { Collateral: collateralAmount },
+    ]);
+    vaultData.init(vault, { collateralAmount, debtAmount });
+  }
 
-  // Manager accounting changes determined. Update the vault state.
-  vault.liquidated();
-  // remaining funds are left on the vault for the user to close and claim
+  if (transfers.length > 0) {
+    atomicRearrange(zcf, harden(transfers));
+  }
 
-  // for manager's accounting
-  return { proceeds: proceeds.Minted, overage, toBurn, shortfall };
+  return { vaultData, totalDebt, totalCollateral, liqSeat };
 };
 
-const liquidationDetailTerms = debtBrand =>
-  harden({
-    MaxImpactBP: 50n,
-    OracleTolerance: makeRatio(30n, debtBrand),
-    AMMMaxSlippage: makeRatio(30n, debtBrand),
-  });
-/** @typedef {ReturnType<typeof liquidationDetailTerms>} LiquidationTerms */
-
-harden(liquidate);
-harden(liquidationDetailTerms);
-harden(makeQuote);
-harden(updateQuote);
+harden(setWakeupsForNextAuction);
+harden(liquidationResults);
+harden(getLiquidatableVaults);
 
-export { liquidate, liquidationDetailTerms, makeQuote, updateQuote };
+export { setWakeupsForNextAuction, liquidationResults, getLiquidatableVaults };

package/src/vaultFactory/math.js

@@ -0,0 +1,95 @@
+// @jessie-check
+
+/**
+ * @file calculations specific to the Vault Factory contract
+ * See also ../interest-math.js
+ */
+
+import { AmountMath } from '@agoric/ertp';
+import { getAmountOut } from '@agoric/zoe/src/contractSupport/priceQuote.js';
+import {
+  addRatios,
+  ceilMultiplyBy,
+  floorDivideBy,
+  ratioGTE,
+} from '@agoric/zoe/src/contractSupport/ratio.js';
+import { priceFrom } from '../auction/util.js';
+import { addSubtract } from '../contractSupport.js';
+
+/**
+ * Calculate the minimum collateralization given the liquidation margin and the "padding"
+ * from that liquidation threshold.
+ *
+ * @param {Ratio} liquidationMargin
+ * @param {Ratio} liquidationPadding
+ * @returns {Ratio}
+ */
+export const calculateMinimumCollateralization = (
+  liquidationMargin,
+  liquidationPadding,
+) => addRatios(liquidationMargin, liquidationPadding);
+
+/**
+ * Calculate the lesser price of the given quotes.
+ *
+ * @param {PriceQuote} quoteA
+ * @param {PriceQuote} [quoteB]
+ * @returns {Ratio}
+ */
+export const minimumPrice = (quoteA, quoteB) => {
+  const priceA = priceFrom(quoteA);
+  if (quoteB === undefined) {
+    return priceA;
+  }
+  const priceB = priceFrom(quoteB);
+  if (ratioGTE(priceA, priceB)) {
+    return priceB;
+  } else {
+    return priceA;
+  }
+};
+harden(minimumPrice);
+
+/**
+ * Calculate the maximum debt allowed based on the price quote and the lesser of
+ * the `liquidationMargin` or the `liquidationPadding`.
+ *
+ * @param {PriceQuote} quoteAmount
+ * @param {Ratio} liquidationMargin
+ * @param {Ratio} liquidationPadding
+ * @returns {Amount<'nat'>}
+ */
+export const maxDebtForVault = (
+  quoteAmount,
+  liquidationMargin,
+  liquidationPadding,
+) => {
+  const debtByQuote = getAmountOut(quoteAmount);
+  const minimumCollateralization = calculateMinimumCollateralization(
+    liquidationMargin,
+    liquidationPadding,
+  );
+  // floorDivide because we want the debt ceiling lower
+  return floorDivideBy(debtByQuote, minimumCollateralization);
+};
+
+/**
+ * Calculate the fee, the amount to mint and the resulting debt.
+ * The give and the want together reflect a delta, where typically
+ * one is zero because they come from the gave/want of an offer
+ * proposal. If the `want` is zero, the `fee` will also be zero,
+ * so the simple math works.
+ *
+ * @param {Amount<'nat'>} currentDebt
+ * @param {Amount<'nat'>} give excess of currentDebt is returned in 'surplus'
+ * @param {Amount<'nat'>} want
+ * @param {Ratio} debtFee
+ */
+export const calculateDebtCosts = (currentDebt, give, want, debtFee) => {
+  const maxGive = AmountMath.min(currentDebt, give);
+  const surplus = AmountMath.subtract(give, maxGive);
+  const fee = ceilMultiplyBy(want, debtFee);
+  const toMint = AmountMath.add(want, fee);
+  const newDebt = addSubtract(currentDebt, toMint, maxGive);
+  return { newDebt, toMint, fee, surplus };
+};

package/src/vaultFactory/orderedVaultStore.js

@@ -1,4 +1,3 @@
-// @ts-check
 import { fromVaultKey, toVaultKey } from './storeUtils.js';
 
 /**