@agoric/inter-protocol 0.16.2-dev-5dc325b.0 → 0.16.2-getting-started-dev-d127d1d.0

package/src/proposals/utils.js

@@ -10,6 +10,7 @@ const { Fail } = assert;
  */
 export const reserveThenGetNamePaths = async (nameAdmin, paths) => {
   /**
+   *
    * @param {ERef<import('@agoric/vats').NameAdmin>} nextAdmin
    * @param {string[]} path
    */
@@ -53,7 +54,7 @@ export const reserveThenGetNames = async (nameAdmin, names) =>
  * @param {string} debugName
  * @param {ERef<import('@agoric/vats').NameAdmin>} namesByAddressAdmin
  * @param {string} addr
- * @param {ERef<Payment>[]} payments
+ * @param {Array<ERef<Payment>>} payments
  */
 export const reserveThenDeposit = async (
   debugName,
@@ -78,15 +79,7 @@ export const reserveThenDeposit = async (
   );
 };
 
-/**
- * @type {<T>(
- *   store: ERef<
- *     Map<string, T> | import('@agoric/internal/src/scratch.js').ScratchPad
- *   >,
- *   key: string,
- *   make: () => T,
- * ) => Promise<T>}
- */
+/** @type {<T>(store: ERef<Map<string, T> | import('@agoric/internal/src/scratch.js').ScratchPad>, key: string, make: () => T) => Promise<T>} */
 const provideWhen = async (store, key, make) => {
   const found = await E(store).get(key);
   if (found) {
@@ -98,33 +91,21 @@ const provideWhen = async (store, key, make) => {
 };
 
 /**
- * @param {{
- *   scratch: ERef<import('@agoric/internal/src/scratch.js').ScratchPad>;
- * }} homeP
+ * @param {{ scratch: ERef<import('@agoric/internal/src/scratch.js').ScratchPad> }} homeP
  * @param {object} opts
- * @param {(specifier: string) => Promise<{ default: Bundle }>} opts.loadBundle
+ * @param {(specifier: string) => Promise<{default: Bundle}>} opts.loadBundle
  * @param {string} [opts.installCacheKey]
  */
 export const makeInstallCache = async (
   homeP,
   { installCacheKey = 'installCache', loadBundle },
 ) => {
-  /**
-   * @type {CopyMap<
-   *   string,
-   *   { installation: Installation; boardId: string; path?: string }
-   * >}
-   */
+  /** @type {CopyMap<string, {installation: Installation, boardId: string, path?: string}>} */
   const initial = await provideWhen(E.get(homeP).scratch, installCacheKey, () =>
     makeCopyMap([]),
   );
   // ISSUE: getCopyMapEntries of CopyMap<K, V> loses K, V.
-  /**
-   * @type {Map<
-   *   string,
-   *   { installation: Installation; boardId: string; path?: string }
-   * >}
-   */
+  /** @type {Map<string, {installation: Installation, boardId: string, path?: string}>} */
   const working = new Map(getCopyMapEntries(initial));
 
   const saveCache = async () => {
@@ -156,9 +137,3 @@ export const makeInstallCache = async (
 
   return { wrapInstall, saveCache };
 };
-
-export const oracleBrandFeedName = (inBrandName, outBrandName) =>
-  `${inBrandName}-${outBrandName} price feed`;
-
-export const scaledPriceFeedName = issuerName =>
-  `scaledPriceAuthority-${issuerName}`;

package/src/psm/psm.js

@@ -41,86 +41,80 @@ const { Fail } = assert;
 
 /**
  * @file The Parity Stability Module supports efficiently minting/burning a
- *   stable token at a specified fixed ratio to a reference stable token, which
- *   thereby acts as an anchor to provide additional stability. For flexible
- *   economic policies, the fee percentage for trading into and out of the
- *   stable token are specified separately.
+ * stable token at a specified fixed ratio to a reference stable token, which
+ * thereby acts as an anchor to provide additional stability. For flexible
+ * economic policies, the fee percentage for trading into and out of the stable
+ * token are specified separately.
  */
 
 /**
- * @typedef {object} MetricsNotification Metrics naming scheme is that nouns are
- *   present values and past-participles are accumulative.
- * @property {Amount<'nat'>} anchorPoolBalance amount of Anchor token available
- *   to be swapped
- * @property {Amount<'nat'>} mintedPoolBalance amount of Minted token
- *   outstanding (the amount minted minus the amount burned).
- * @property {Amount<'nat'>} feePoolBalance amount of Minted token fees
- *   available to be collected
- * @property {Amount<'nat'>} totalAnchorProvided running sum of Anchor ever
- *   given by this contract
- * @property {Amount<'nat'>} totalMintedProvided running sum of Minted ever
- *   given by this contract
+ * @typedef {object} MetricsNotification
+ * Metrics naming scheme is that nouns are present values and past-participles
+ * are accumulative.
+ *
+ * @property {Amount<'nat'>} anchorPoolBalance  amount of Anchor token
+ * available to be swapped
+ * @property {Amount<'nat'>} mintedPoolBalance  amount of Minted token
+ * outstanding (the amount minted minus the amount burned).
+ * @property {Amount<'nat'>} feePoolBalance     amount of Minted token
+ * fees available to be collected
+ *
+ * @property {Amount<'nat'>} totalAnchorProvided  running sum of Anchor
+ * ever given by this contract
+ * @property {Amount<'nat'>} totalMintedProvided  running sum of Minted
+ * ever given by this contract
  */
 
 /** @typedef {import('@agoric/vat-data').Baggage} Baggage */
 
-/** @type {ContractMeta} */
-export const meta = {
-  upgradability: 'canUpgrade',
-  customTermsShape: {
-    anchorBrand: BrandShape,
-    anchorPerMinted: RatioShape,
-    electionManager: InstanceHandleShape,
-    governedParams: {
-      [CONTRACT_ELECTORATE]: {
-        type: ParamTypes.INVITATION,
-        value: AmountShape,
-      },
-      WantMintedFee: {
-        type: ParamTypes.RATIO,
-        value: RatioShape,
-      },
-      GiveMintedFee: {
-        type: ParamTypes.RATIO,
-        value: RatioShape,
-      },
-      MintLimit: { type: ParamTypes.AMOUNT, value: AmountShape },
+export const customTermsShape = {
+  anchorBrand: BrandShape,
+  anchorPerMinted: RatioShape,
+  electionManager: InstanceHandleShape,
+  governedParams: {
+    [CONTRACT_ELECTORATE]: {
+      type: ParamTypes.INVITATION,
+      value: AmountShape,
     },
-  },
-  privateArgsShape: M.splitRecord(
-    {
-      marshaller: M.remotable('Marshaller'),
-      storageNode: StorageNodeShape,
+    WantMintedFee: {
+      type: ParamTypes.RATIO,
+      value: RatioShape,
     },
-    {
-      // only necessary on first invocation, not subsequent
-      feeMintAccess: FeeMintAccessShape,
-      initialPoserInvitation: InvitationShape,
+    GiveMintedFee: {
+      type: ParamTypes.RATIO,
+      value: RatioShape,
     },
-  ),
+    MintLimit: { type: ParamTypes.AMOUNT, value: AmountShape },
+  },
 };
-harden(meta);
+harden(customTermsShape);
+
+export const privateArgsShape = M.splitRecord(
+  harden({
+    marshaller: M.remotable('Marshaller'),
+    storageNode: StorageNodeShape,
+  }),
+  harden({
+    // only necessary on first invocation, not subsequent
+    feeMintAccess: FeeMintAccessShape,
+    initialPoserInvitation: InvitationShape,
+  }),
+);
+harden(privateArgsShape);
 
 /**
- * @param {ZCF<
- *   GovernanceTerms<{
- *     GiveMintedFee: 'ratio';
- *     WantMintedFee: 'ratio';
- *     MintLimit: 'amount';
+ * @param {ZCF<GovernanceTerms<{
+ *    GiveMintedFee: 'ratio',
+ *    WantMintedFee: 'ratio',
+ *    MintLimit: 'amount',
  *   }> & {
- *     anchorBrand: Brand<'nat'>;
- *     anchorPerMinted: Ratio;
- *   }
- * >} zcf
- * @param {{
- *   feeMintAccess: FeeMintAccess;
- *   initialPoserInvitation: Invitation;
- *   storageNode: StorageNode;
- *   marshaller: Marshaller;
- * }} privateArgs
+ *    anchorBrand: Brand<'nat'>,
+ *    anchorPerMinted: Ratio,
+ * }>} zcf
+ * @param {{feeMintAccess: FeeMintAccess, initialPoserInvitation: Invitation, storageNode: StorageNode, marshaller: Marshaller}} privateArgs
  * @param {Baggage} baggage
  */
-export const start = async (zcf, privateArgs, baggage) => {
+export const prepare = async (zcf, privateArgs, baggage) => {
   const { anchorBrand, anchorPerMinted } = zcf.getTerms();
   console.log('PSM Starting', anchorBrand, anchorPerMinted);
 
@@ -237,7 +231,9 @@ export const start = async (zcf, privateArgs, baggage) => {
     updateMetrics();
   };
 
-  /** @param {Amount<'nat'>} toMint */
+  /**
+   * @param {Amount<'nat'>} toMint
+   */
   const assertUnderLimit = toMint => {
     const mintedAfter = AmountMath.add(
       baggage.get('mintedPoolBalance'),
@@ -266,8 +262,7 @@ export const start = async (zcf, privateArgs, baggage) => {
   /**
    * @param {ZCFSeat} seat
    * @param {Amount<'nat'>} given
-   * @param {Amount<'nat'>} [wanted] defaults to maximum anchor (given exchange
-   *   rate minus fees)
+   * @param {Amount<'nat'>} [wanted] defaults to maximum anchor (given exchange rate minus fees)
    */
   const giveMinted = (seat, given, wanted = emptyAnchor) => {
     const fee = ceilMultiplyBy(given, params.getGiveMintedFee());
@@ -445,6 +440,5 @@ export const start = async (zcf, privateArgs, baggage) => {
     publicFacet,
   });
 };
-harden(start);
 
-/** @typedef {Awaited<ReturnType<typeof start>>['publicFacet']} PsmPublicFacet */
+/** @typedef {Awaited<ReturnType<typeof prepare>>['publicFacet']} PsmPublicFacet */

package/src/reserve/assetReserve.js

@@ -10,42 +10,36 @@ import { prepareAssetReserveKit } from './assetReserveKit.js';
 
 const trace = makeTracer('AR', true);
 
-/** @type {ContractMeta} */
-export const meta = {
-  upgradability: 'canUpgrade',
-};
-harden(meta);
-
 /**
  * @typedef {{
- *   increaseLiquidationShortfall: (increase: Amount) => void;
- *   reduceLiquidationShortfall: (reduction: Amount) => void;
+ *   increaseLiquidationShortfall: (increase: Amount) => void
+ *   reduceLiquidationShortfall: (reduction: Amount) => void
  * }} ShortfallReportingFacet
  */
 
 /** @typedef {import('@agoric/vat-data').Baggage} Baggage */
 
 /**
- * Asset Reserve holds onto assets for the Inter Protocol, and can dispense it
- * for various purposes under governance control.
+ * Asset Reserve holds onto assets for the Inter Protocol, and can
+ * dispense it for various purposes under governance control.
  *
  * This contract has the ability to mint Fee tokens, granted through its private
  * arguments.
  *
- * @param {ZCF<
- *   GovernanceTerms<{}> & {
- *     governedApis: ['burnFeesToReduceShortfall'];
- *   }
+ * @param {ZCF<GovernanceTerms<{}> &
+ * {
+ *   governedApis: ['burnFeesToReduceShortfall'],
+ * }
  * >} zcf
  * @param {{
- *   feeMintAccess: FeeMintAccess;
- *   initialPoserInvitation: Invitation;
- *   marshaller: ERef<Marshaller>;
- *   storageNode: ERef<StorageNode>;
+ *   feeMintAccess: FeeMintAccess,
+ *   initialPoserInvitation: Invitation,
+ *   marshaller: ERef<Marshaller>,
+ *   storageNode: ERef<StorageNode>,
  * }} privateArgs
  * @param {Baggage} baggage
  */
-export const start = async (zcf, privateArgs, baggage) => {
+export const prepare = async (zcf, privateArgs, baggage) => {
   trace('prepare', Object.keys(privateArgs), [...baggage.keys()]);
   // This contract mixes two styles of access to durable state. durableStores
   // are declared at the top level and referenced lexically. local state is
@@ -72,11 +66,11 @@ export const start = async (zcf, privateArgs, baggage) => {
   };
   trace('awaiting takeFeeMint');
   const feeMint = await takeFeeMint();
-  const storageNode = await privateArgs.storageNode;
   const makeAssetReserveKit = await prepareAssetReserveKit(baggage, {
     feeMint,
     makeRecorderKit,
-    storageNode,
+    // eslint-disable-next-line @jessie.js/no-nested-await -- spurious
+    storageNode: await privateArgs.storageNode,
     zcf,
   });
 
@@ -112,7 +106,7 @@ export const start = async (zcf, privateArgs, baggage) => {
     publicFacet: /** @type {any} */ (assetReserveKit.public),
   };
 };
-harden(start);
+harden(prepare);
 
 /**
  * @typedef {object} ShortfallReporter
@@ -127,8 +121,5 @@ harden(start);
  * @property {() => Promise<Invitation<ShortfallReporter>>} makeShortfallReportingInvitation
  */
 
-/** @typedef {Awaited<ReturnType<typeof start>>['publicFacet']} AssetReservePublicFacet */
-/**
- * @typedef {Awaited<ReturnType<typeof start>>['creatorFacet']} AssetReserveCreatorFacet
- *   the creator facet for the governor
- */
+/** @typedef {Awaited<ReturnType<typeof prepare>>['publicFacet']} AssetReservePublicFacet */
+/** @typedef {Awaited<ReturnType<typeof prepare>>['creatorFacet']} AssetReserveCreatorFacet the creator facet for the governor */

package/src/reserve/assetReserveKit.js

@@ -9,7 +9,7 @@ import {
 } from '@agoric/zoe/src/contractSupport/topics.js';
 import { AmountKeywordRecordShape } from '@agoric/zoe/src/typeGuards.js';
 import { E } from '@endo/eventual-send';
-import { UnguardedHelperI } from '@agoric/internal/src/typeGuards.js';
+import { UnguardedHelperI } from '../typeGuards.js';
 
 const { quote: q } = assert;
 
@@ -17,6 +17,7 @@ const trace = makeTracer('ReserveKit', true);
 
 /**
  * @typedef {object} MetricsNotification
+ *
  * @property {AmountKeywordRecord} allocations
  * @property {Amount<'nat'>} shortfallBalance shortfall from liquidation that
  *   has not yet been compensated.
@@ -27,11 +28,10 @@ const trace = makeTracer('ReserveKit', true);
 /**
  * @param {import('@agoric/vat-data').Baggage} baggage
  * @param {{
- *   feeMint: ZCFMint<'nat'>;
- *   makeRecorderKit: import('@agoric/zoe/src/contractSupport/recorder.js').MakeRecorderKit;
- *   storageNode: StorageNode;
- *   zcf: ZCF;
- * }} powers
+ * feeMint: ZCFMint<'nat'>,
+ * makeRecorderKit: import('@agoric/zoe/src/contractSupport/recorder.js').MakeRecorderKit,
+ * storageNode: StorageNode,
+ * zcf: ZCF}} powers
  */
 export const prepareAssetReserveKit = async (
   baggage,
@@ -63,7 +63,10 @@ export const prepareAssetReserveKit = async (
         reduceLiquidationShortfall: M.call(AmountShape).returns(),
       }),
     },
-    /** @param {StorageNode} metricsNode */
+    /**
+     *
+     * @param {StorageNode} metricsNode
+     */
     metricsNode => {
       /**
        * Used to look up the unique keyword for each brand, including Fee brand.
@@ -74,8 +77,7 @@ export const prepareAssetReserveKit = async (
         durable: true,
       });
       /**
-       * Used to look up the brands for keywords, excluding Fee because it's a
-       * special case.
+       * Used to look up the brands for keywords, excluding Fee because it's a special case.
        *
        * @type {MapStore<Keyword, Brand>}
        */
@@ -135,6 +137,7 @@ export const prepareAssetReserveKit = async (
       },
       governedApis: {
         /**
+         *
          * @param {Amount<'nat'>} reduction
          * @returns {void}
          */
@@ -202,11 +205,12 @@ export const prepareAssetReserveKit = async (
         },
       },
       /**
-       * XXX missing governance public methods
-       * https://github.com/Agoric/agoric-sdk/issues/5200
+       * XXX missing governance public methods https://github.com/Agoric/agoric-sdk/issues/5200
        */
       public: {
-        /** Anyone can deposit any assets to the reserve */
+        /**
+         * Anyone can deposit any assets to the reserve
+         */
         makeAddCollateralInvitation() {
           /** @type {OfferHandler<Promise<string>>} */
           const handler = async seat => {
@@ -243,7 +247,9 @@ export const prepareAssetReserveKit = async (
         },
       },
       shortfallReportingFacet: {
-        /** @param {Amount<'nat'>} shortfall */
+        /**
+         * @param {Amount<"nat">} shortfall
+         */
         increaseLiquidationShortfall(shortfall) {
           const { facets, state } = this;
           state.shortfallBalance = AmountMath.add(
@@ -254,7 +260,9 @@ export const prepareAssetReserveKit = async (
         },
 
         // currently exposed for testing. Maybe it only gets called internally?
-        /** @param {Amount<'nat'>} reduction */
+        /**
+         * @param {Amount<"nat">} reduction
+         */
         reduceLiquidationShortfall(reduction) {
           const { state } = this;
           if (AmountMath.isGTE(reduction, state.shortfallBalance)) {

package/src/typeGuards.js

@@ -0,0 +1,13 @@
+// @jessie-check
+
+import { M } from '@agoric/store';
+
+/**
+ * To be used only for 'helper' facets where the calls are from trusted code.
+ */
+export const UnguardedHelperI = M.interface(
+  'helper',
+  {},
+  // not exposed so sloppy okay
+  { sloppy: true },
+);

package/src/vaultFactory/liquidation.js

@@ -22,8 +22,7 @@ const makeCancelToken = makeCancelTokenMaker('liq');
 
 /**
  * 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
+ * all events and unset it. When auction params are changed, we'll restart the schedule
  *
  * @type {object | undefined}
  */
@@ -48,16 +47,15 @@ const cancelWakeups = timer => {
 };
 
 /**
- * Schedule wakeups for the _next_ auction round.
+ * Schedule wakeups for the *next* auction round.
  *
- * In practice, there are these cases to handle (with N as "live" and N+1 is
- * "next"):
+ * 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   |
+ * | 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
@@ -134,7 +132,7 @@ const setWakeups = ({
 };
 
 /**
- * Schedule wakeups for the _next_ auction round.
+ * Schedule wakeups for the *next* auction round.
  *
  * Called by vaultDirector's resetWakeupsForNextAuction at start() and every
  * time there's a "reschedule" wakeup.
@@ -187,7 +185,7 @@ harden(setWakeupsForNextAuction);
 /**
  * @param {Amount<'nat'>} debt
  * @param {Amount<'nat'>} minted
- * @returns {{ overage: Amount<'nat'>; shortfall: Amount<'nat'> }}
+ * @returns {{ overage: Amount<'nat'>, shortfall: Amount<'nat'>}}
  */
 export const liquidationResults = (debt, minted) => {
   if (AmountMath.isEmpty(minted)) {
@@ -242,21 +240,15 @@ export const watchForGovernanceChange = (
  * @param {PriceQuote} collateralizationDetails.quote
  * @param {Ratio} collateralizationDetails.interest
  * @param {Ratio} collateralizationDetails.margin
- * @param {ReturnType<
- *   typeof import('./prioritizedVaults.js').makePrioritizedVaults
- * >} prioritizedVaults
+ * @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;
- * }}
+ *    vaultData: MapStore<Vault, { collateralAmount: Amount<'nat'>, debtAmount:  Amount<'nat'>}>,
+ *    totalDebt: Amount<'nat'>,
+ *    totalCollateral: Amount<'nat'>,
+ *    liqSeat: ZCFSeat}}
  */
 export const getLiquidatableVaults = (
   zcf,
@@ -269,18 +261,13 @@ export const getLiquidatableVaults = (
   const vaultsToLiquidate = prioritizedVaults.removeVaultsBelow(
     collateralizationDetails,
   );
-  /**
-   * @type {MapStore<
-   *   Vault,
-   *   { collateralAmount: Amount<'nat'>; debtAmount: Amount<'nat'> }
-   * >}
-   */
+  /** @type {MapStore<Vault, { collateralAmount: Amount<'nat'>, debtAmount:  Amount<'nat'>}>} */
   const vaultData = makeScalarMapStore();
 
   const { zcfSeat: liqSeat } = zcf.makeEmptySeatKit();
   let totalDebt = AmountMath.makeEmpty(debtBrand);
   let totalCollateral = AmountMath.makeEmpty(collateralBrand);
-  /** @type {TransferPart[]} */
+  /** @type {import('@agoric/zoe/src/contractSupport/atomicTransfer.js').TransferPart[]} */
   const transfers = [];
 
   for (const vault of vaultsToLiquidate.values()) {

package/src/vaultFactory/math.js

@@ -1,8 +1,8 @@
 // @jessie-check
 
 /**
- * @file calculations specific to the Vault Factory contract See also
- *   ../interest-math.js
+ * @file calculations specific to the Vault Factory contract
+ * See also ../interest-math.js
  */
 
 import { AmountMath } from '@agoric/ertp';
@@ -17,8 +17,8 @@ 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.
+ * Calculate the minimum collateralization given the liquidation margin and the "padding"
+ * from that liquidation threshold.
  *
  * @param {Ratio} liquidationMargin
  * @param {Ratio} liquidationPadding
@@ -74,10 +74,11 @@ export const maxDebtForVault = (
 };
 
 /**
- * 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.
+ * 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'

package/src/vaultFactory/orderedVaultStore.js

@@ -3,20 +3,22 @@ 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.
+ * 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 collateralization sorts after lower. (Higher
- * debt-to-collateral come first.)
+ * In this module debts are encoded as the inverse quotient (collateral over debt) so that
+ * greater collateralization sorts after lower. (Higher debt-to-collateral come
+ * first.)
  */
 
 /** @typedef {import('./vault').Vault} Vault */
 /** @typedef {import('./storeUtils').CompositeKey} CompositeKey */
 
-/** @param {MapStore<string, Vault>} store */
+/**
+ * @param {MapStore<string, Vault>} store
+ */
 export const makeOrderedVaultStore = store => {
   /**
+   *
    * @param {string} vaultId
    * @param {Vault} vault
    */
@@ -29,6 +31,7 @@ export const makeOrderedVaultStore = store => {
   };
 
   /**
+   *
    * @param {string} key
    * @returns {Vault}
    */