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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/inter-protocol",
-  "version": "0.14.1-dev-13c169c.0+13c169c",
+  "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-13c169c.0+13c169c",
-    "@agoric/ertp": "0.16.1-dev-13c169c.0+13c169c",
-    "@agoric/governance": "0.10.1-dev-13c169c.0+13c169c",
-    "@agoric/internal": "0.3.1-dev-13c169c.0+13c169c",
-    "@agoric/notifier": "0.6.1-dev-13c169c.0+13c169c",
-    "@agoric/store": "0.9.1-dev-13c169c.0+13c169c",
-    "@agoric/time": "0.3.1-dev-13c169c.0+13c169c",
-    "@agoric/vat-data": "0.5.1-dev-13c169c.0+13c169c",
-    "@agoric/vats": "0.14.1-dev-13c169c.0+13c169c",
-    "@agoric/zoe": "0.26.1-dev-13c169c.0+13c169c",
+    "@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-13c169c.0+13c169c",
+    "agoric": "0.19.1-dev-72b0aa9.0+72b0aa9",
     "jessie.js": "^0.3.2"
   },
   "devDependencies": {
-    "@agoric/deploy-script-support": "0.10.1-dev-13c169c.0+13c169c",
-    "@agoric/smart-wallet": "0.5.1-dev-13c169c.0+13c169c",
-    "@agoric/swingset-liveslots": "0.10.1-dev-13c169c.0+13c169c",
-    "@agoric/swingset-vat": "0.32.1-dev-13c169c.0+13c169c",
+    "@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": "13c169c76c103c45fb952d4e3362a40a8b56a0d2"
+  "gitHead": "72b0aa9ce03797b76d8d671b010d1a1615b5ae45"
 }

package/src/contractSupport.js

@@ -1,9 +1,8 @@
 // @jessie-check
 
 import { AmountMath } from '@agoric/ertp';
-import { makeStoredPublisherKit, makeStoredPublishKit } from '@agoric/notifier';
 import { M } from '@agoric/store';
-import { E } from '@endo/eventual-send';
+import { makeRatioFromAmounts } from '@agoric/zoe/src/contractSupport/index.js';
 
 const { Fail, quote: q } = assert;
 
@@ -29,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
  *
@@ -65,27 +75,6 @@ export const checkDebtLimit = (debtLimit, totalDebt, toMint) => {
     )} would hit total debt limit ${q(debtLimit)}`;
 };
 
-/**
- * @deprecated incompatible with durability; instead handle vstorage ephemerally on a durable PublishKit
- * @template T
- * @param {ERef<StorageNode>} storageNode
- * @param {ERef<Marshaller>} marshaller
- * @returns {MetricsPublisherKit<T>}
- */
-export const makeMetricsPublisherKit = (storageNode, marshaller) => {
-  assert(
-    storageNode && marshaller,
-    'makeMetricsPublisherKit missing storageNode or marshaller',
-  );
-  /** @type {import('@agoric/notifier').StoredPublisherKit<T>} */
-  const kit = makeStoredPublisherKit(storageNode, marshaller, 'metrics');
-  return {
-    metricsPublication: kit.publisher,
-    metricsSubscription: kit.subscriber,
-  };
-};
-harden(makeMetricsPublisherKit);
-
 /**
  * @template T
  * @typedef {object} MetricsPublisherKit<T>
@@ -100,31 +89,13 @@ harden(makeMetricsPublisherKit);
  * @property {StoredSubscriber<T>} metricsSubscriber
  */
 
-/**
- * @deprecated incompatible with durability; instead handle vstorage ephemerally on a durable PublishKit
- * @template T
- * @param {ERef<StorageNode>} storageNode
- * @param {ERef<Marshaller>} marshaller
- * @returns {MetricsPublishKit<T>}
- */
-export const makeMetricsPublishKit = (storageNode, marshaller) => {
-  assert(
-    storageNode && marshaller,
-    'makeMetricsPublisherKit missing storageNode or marshaller',
-  );
-  const metricsNode = E(storageNode).makeChildNode('metrics');
-  /** @type {StoredPublishKit<T>} */
-  const kit = makeStoredPublishKit(metricsNode, marshaller);
-  return {
-    metricsPublisher: kit.publisher,
-    metricsSubscriber: kit.subscriber,
-  };
-};
-harden(makeMetricsPublishKit);
-
 /**
  * @param {Brand} brand must be a 'nat' brand, not checked
  * @param {NatValue} [min]
  */
 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/price/fluxAggregatorKit.js

@@ -5,11 +5,7 @@
  */
 import { AmountMath } from '@agoric/ertp';
 import { assertAllDefined, makeTracer } from '@agoric/internal';
-import {
-  makeNotifierFromSubscriber,
-  observeNotifier,
-  SubscriberShape,
-} from '@agoric/notifier';
+import { makeNotifierFromSubscriber, observeNotifier } from '@agoric/notifier';
 import { M, makeScalarBigMapStore, prepareExoClassKit } from '@agoric/vat-data';
 import {
   defineRecorderKit,
@@ -208,8 +204,6 @@ export const prepareFluxAggregatorKit = async (
       creator: M.interface('fluxAggregator creatorFacet', {}, { sloppy: true }),
       public: M.interface('fluxAggregator publicFacet', {
         getPriceAuthority: M.call().returns(M.any()),
-        getSubscriber: M.call().returns(SubscriberShape),
-        getRoundStartNotifier: M.call().returns(SubscriberShape),
         getPublicTopics: M.call().returns({
           quotes: M.any(),
           latestRound: M.any(),
@@ -346,14 +340,6 @@ export const prepareFluxAggregatorKit = async (
         getPriceAuthority() {
           return priceAuthority;
         },
-        /** @deprecated use getPublicTopics */
-        getSubscriber: () => {
-          return priceKit.subscriber;
-        },
-        /** @deprecated use getPublicTopics */
-        getRoundStartNotifier() {
-          return latestRoundKit.subscriber;
-        },
         getPublicTopics() {
           return {
             quotes: makeRecorderTopic(

package/src/proposals/econ-behaviors.js

@@ -519,7 +519,7 @@ export const startAuctioneer = async (
       },
     },
     issuer: {
-      consume: { [Stable.symbol]: runIssuerP },
+      consume: { [Stable.symbol]: stableIssuerP },
     },
   },
   {
@@ -539,11 +539,11 @@ export const startAuctioneer = async (
 
   const poserInvitationP = E(electorateCreatorFacet).getPoserInvitation();
 
-  const [initialPoserInvitation, electorateInvitationAmount, runIssuer] =
+  const [initialPoserInvitation, electorateInvitationAmount, stableIssuer] =
     await Promise.all([
       poserInvitationP,
       E(E(zoe).getInvitationIssuer()).getAmountOf(poserInvitationP),
-      runIssuerP,
+      stableIssuerP,
     ]);
 
   const timerBrand = await E(chainTimerService).getTimerBrand();
@@ -571,7 +571,7 @@ export const startAuctioneer = async (
       governedContractInstallation: auctionInstallation,
       governed: {
         terms: auctionTerms,
-        issuerKeywordRecord: { Bid: runIssuer },
+        issuerKeywordRecord: { Bid: stableIssuer },
         storageNode,
         marshaller,
         label: 'auctioneer',

package/src/reserve/assetReserveKit.js

@@ -5,7 +5,6 @@ import { M, makeScalarBigMapStore, prepareExoClassKit } from '@agoric/vat-data';
 import { atomicTransfer } from '@agoric/zoe/src/contractSupport/atomicTransfer.js';
 import {
   makeRecorderTopic,
-  SubscriberShape,
   TopicsRecordShape,
 } from '@agoric/zoe/src/contractSupport/topics.js';
 import { AmountKeywordRecordShape } from '@agoric/zoe/src/typeGuards.js';
@@ -57,7 +56,6 @@ export const prepareAssetReserveKit = async (
       }),
       public: M.interface('AssetReserve public', {
         makeAddCollateralInvitation: M.call().returns(M.promise()),
-        getMetrics: M.call().returns(SubscriberShape),
         getPublicTopics: M.call().returns(TopicsRecordShape),
       }),
       shortfallReportingFacet: M.interface('AssetReserve shortfall reporter', {
@@ -189,7 +187,7 @@ export const prepareAssetReserveKit = async (
           await zcf.saveIssuer(issuer, keyword);
         },
 
-        /** @deprecated use getPublicTopics metrics allocation */
+        /** XXX redundant with getPublicTopics metrics `allocation` */
         getAllocations() {
           return this.state.collateralSeat.getCurrentAllocation();
         },
@@ -239,10 +237,6 @@ export const prepareAssetReserveKit = async (
           };
           return zcf.makeInvitation(handler, 'Add Collateral');
         },
-        /** @deprecated */
-        getMetrics() {
-          return this.state.metricsKit.subscriber;
-        },
         getPublicTopics() {
           return {
             metrics: makeRecorderTopic(

package/src/reserve/doc.md

@@ -90,20 +90,20 @@ sequenceDiagram
 participant caller
 participant reserveContract
 participant collateralSeat
-participant runMint
+participant stableMint
 participant runSeat
 participant zcf
 participant ammPublicFacet
 participant liquidityInvite
 
-caller ->> reserveContract: addLiquidityToAmmPool(collateralAmount, runAmount)
+caller ->> reserveContract: addLiquidityToAmmPool(collateralAmount, stableAmount)
 reserveContract ->> reserveContract: get collateralKeyword from collateralAmount.brand
 reserveContract ->> collateralSeat: get current allocation for collateralKeyword
 reserveContract ->> reserveContract: ensure  current allocation for collateralKeyword is >= collateralAmount
 
 
 note right of reserveContract: create the IST
-reserveContract ->> runMint: mintGains of runAmount, and get runSeat
+reserveContract ->> stableMint: mintGains of stableAmount, and get runSeat
 reserveContract ->> runSeat: increment collateralKeyword: collateralAmount
 reserveContract ->> collateralSeat: decrement collateralKeyword: collateralAmount
 reserveContract ->> zcf: reallocate(runSeat, collateralSeat)
@@ -112,7 +112,7 @@ note right of reserveContract: Add IST and collateral to the AMM
 reserveContract ->> ammPublicFacet: get invite for makeAddLiquidityAtRateInvitation
 reserveContract ->> reserveContract: create mapping, IST = central, collateralKeyword: secondary
 reserveContract ->> reserveContract: get liquidity brand for collateralKeyword
-reserveContract ->> reserveContract: terms mapping, give Central: runAmount, Secondary collateralAmount, want liquidity
+reserveContract ->> reserveContract: terms mapping, give Central: stableAmount, Secondary collateralAmount, want liquidity
 reserveContract ->> zcf: offer
 
 

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/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
  */
 
 /**