@agoric/inter-protocol 0.14.1-dev-effbf7f.0 → 0.14.1-dev-72b0aa9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/inter-protocol",
-  "version": "0.14.1-dev-effbf7f.0+effbf7f",
+  "version": "0.14.1-dev-72b0aa9.0+72b0aa9",
   "description": "Core cryptoeconomy contracts",
   "type": "module",
   "main": "src/index.js",
@@ -29,29 +29,29 @@
   },
   "homepage": "https://github.com/Agoric/agoric-sdk#readme",
   "dependencies": {
-    "@agoric/assert": "0.6.1-dev-effbf7f.0+effbf7f",
-    "@agoric/ertp": "0.16.1-dev-effbf7f.0+effbf7f",
-    "@agoric/governance": "0.10.1-dev-effbf7f.0+effbf7f",
-    "@agoric/internal": "0.3.1-dev-effbf7f.0+effbf7f",
-    "@agoric/notifier": "0.6.1-dev-effbf7f.0+effbf7f",
-    "@agoric/store": "0.9.1-dev-effbf7f.0+effbf7f",
-    "@agoric/time": "0.3.1-dev-effbf7f.0+effbf7f",
-    "@agoric/vat-data": "0.5.1-dev-effbf7f.0+effbf7f",
-    "@agoric/vats": "0.14.1-dev-effbf7f.0+effbf7f",
-    "@agoric/zoe": "0.26.1-dev-effbf7f.0+effbf7f",
+    "@agoric/assert": "0.6.1-dev-72b0aa9.0+72b0aa9",
+    "@agoric/ertp": "0.16.1-dev-72b0aa9.0+72b0aa9",
+    "@agoric/governance": "0.10.1-dev-72b0aa9.0+72b0aa9",
+    "@agoric/internal": "0.3.1-dev-72b0aa9.0+72b0aa9",
+    "@agoric/notifier": "0.6.1-dev-72b0aa9.0+72b0aa9",
+    "@agoric/store": "0.9.1-dev-72b0aa9.0+72b0aa9",
+    "@agoric/time": "0.3.1-dev-72b0aa9.0+72b0aa9",
+    "@agoric/vat-data": "0.5.1-dev-72b0aa9.0+72b0aa9",
+    "@agoric/vats": "0.14.1-dev-72b0aa9.0+72b0aa9",
+    "@agoric/zoe": "0.26.1-dev-72b0aa9.0+72b0aa9",
     "@endo/captp": "^3.1.1",
     "@endo/eventual-send": "^0.17.2",
     "@endo/far": "^0.2.18",
     "@endo/marshal": "^0.8.5",
     "@endo/nat": "^4.1.27",
-    "agoric": "0.19.1-dev-effbf7f.0+effbf7f",
+    "agoric": "0.19.1-dev-72b0aa9.0+72b0aa9",
     "jessie.js": "^0.3.2"
   },
   "devDependencies": {
-    "@agoric/deploy-script-support": "0.10.1-dev-effbf7f.0+effbf7f",
-    "@agoric/smart-wallet": "0.5.1-dev-effbf7f.0+effbf7f",
-    "@agoric/swingset-liveslots": "0.10.1-dev-effbf7f.0+effbf7f",
-    "@agoric/swingset-vat": "0.32.1-dev-effbf7f.0+effbf7f",
+    "@agoric/deploy-script-support": "0.10.1-dev-72b0aa9.0+72b0aa9",
+    "@agoric/smart-wallet": "0.5.1-dev-72b0aa9.0+72b0aa9",
+    "@agoric/swingset-liveslots": "0.10.1-dev-72b0aa9.0+72b0aa9",
+    "@agoric/swingset-vat": "0.32.1-dev-72b0aa9.0+72b0aa9",
     "@endo/bundle-source": "^2.5.1",
     "@endo/init": "^0.5.56",
     "@endo/promise-kit": "^0.2.56",
@@ -79,5 +79,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "effbf7f7a278863b88419e0a19ae19f0db4b30a0"
+  "gitHead": "72b0aa9ce03797b76d8d671b010d1a1615b5ae45"
 }

package/src/contractSupport.js

@@ -2,6 +2,7 @@
 
 import { AmountMath } from '@agoric/ertp';
 import { M } from '@agoric/store';
+import { makeRatioFromAmounts } from '@agoric/zoe/src/contractSupport/index.js';
 
 const { Fail, quote: q } = assert;
 
@@ -27,6 +28,17 @@ export const ratioPattern = harden({
 export const addSubtract = (base, gain, loss) =>
   AmountMath.subtract(AmountMath.add(base, gain), loss);
 
+/**
+ * @template {Amount} T
+ * @param {T} left
+ * @param {T} right
+ * @returns {T}
+ */
+export const subtractToEmpty = (left, right) =>
+  AmountMath.isGTE(right, left)
+    ? /** @type {T} */ (AmountMath.makeEmptyFromAmount(left))
+    : /** @type {T} */ (AmountMath.subtract(left, right));
+
 /**
  * Verifies that every key in the proposal is in the provided list
  *
@@ -83,3 +95,7 @@ export const checkDebtLimit = (debtLimit, totalDebt, toMint) => {
  */
 export const makeNatAmountShape = (brand, min) =>
   harden({ brand, value: min ? M.gte(min) : M.nat() });
+
+/** @param {Pick<PriceDescription, 'amountIn' | 'amountOut'>} quoteAmount */
+export const quoteAsRatio = quoteAmount =>
+  makeRatioFromAmounts(quoteAmount.amountIn, quoteAmount.amountOut);

package/src/vaultFactory/Liquidation.md

@@ -13,7 +13,7 @@ There are two interesting exception cases. All the collateral might be sold
 without covering the debt (flow 2a), or there might not be enough bids to
 purchase all the collateral (flow 2b). In the first case, vault-holders don't
 get anything back, we burn the currency we received to cover a portion of the
-debt, any excess collateral is sent to the reserve, and we report a shortfall.
+debt, and we report a shortfall.
 
 In the second case, we can't tell whether it's due to a downturn in the
 market or a DoS attack on the exchange. In hopes that it's not the latter, we

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,
@@ -180,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
@@ -260,7 +250,7 @@ export const watchForGovernanceChange = (
  *    totalCollateral: Amount<'nat'>,
  *    liqSeat: ZCFSeat}}
  */
-const getLiquidatableVaults = (
+export const getLiquidatableVaults = (
   zcf,
   collateralizationDetails,
   prioritizedVaults,
@@ -303,9 +293,4 @@ const getLiquidatableVaults = (
 
   return { vaultData, totalDebt, totalCollateral, liqSeat };
 };
-
-harden(setWakeupsForNextAuction);
-harden(liquidationResults);
 harden(getLiquidatableVaults);
-
-export { setWakeupsForNextAuction, liquidationResults, getLiquidatableVaults };

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/vaultDirector.js

@@ -84,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,

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';