@agoric/inter-protocol 0.16.2-dev-7cc5def.0 → 0.16.2-u11.0

package/src/vaultFactory/proceeds.js

@@ -11,32 +11,27 @@ 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: [number, AmountKeywordRecord][];
- *   vaultsToReinstate: number[];
+ *   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.
+ * 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
- */
+/** @typedef {{ collateral: Amount<'nat'>, presaleDebt:  Amount<'nat'>, currentDebt: Amount<'nat'> }} VaultBalances */
 
 /**
  * Liquidation.md describes how to process liquidation proceeds.
@@ -51,8 +46,7 @@ import { liquidationResults } from './liquidation.js';
  * @param {Amount<'nat'>} inputs.totalDebt
  * @param {Amount<'nat'>} inputs.totalCollateral
  * @param {PriceDescription} inputs.oraclePriceAtStart
- * @param {VaultBalances[]} inputs.vaultsBalances ordered best to worst
- *   collateralized
+ * @param {Array<VaultBalances>} inputs.vaultsBalances ordered best to worst collateralized
  * @param {Ratio} inputs.penaltyRate
  * @returns {DistributionPlan}
  */

package/src/vaultFactory/storeUtils.js

@@ -19,9 +19,13 @@ const { multiply } = natSafeMath;
 
 const trace = makeTracer('Store', true);
 
-/** @typedef {import('@endo/marshal').PureData} PureData */
+/**
+ * @typedef {import('@endo/marshal').PureData} PureData
+ */
 
-/** @typedef {[normalizedCollateralization: number, vaultId: VaultId]} CompositeKey */
+/**
+ * @typedef {[normalizedCollateralization: number, vaultId: VaultId]} CompositeKey
+ */
 
 // `makeEncodePassable` has three named options:
 // `encodeRemotable`, `encodeError`, and `encodePromise`.
@@ -65,12 +69,12 @@ const decodeNumber = encoded => {
 };
 
 // Type annotations to support static testing of amount values
-/** @typedef {Amount<'nat'> & { normalized: true }} NormalizedDebt */
-/** @typedef {Amount<'nat'> & { normalized: false }} ActualDebt */
+/** @typedef {Amount<'nat'> & {normalized: true}} NormalizedDebt */
+/** @typedef {Amount<'nat'> & {normalized: false}} ActualDebt */
 
 /**
- * Overcollateralized are greater than one. The more undercollaterized the
- * smaller in [0-1].
+ * Overcollateralized are greater than one.
+ * The more undercollaterized the smaller in [0-1].
  *
  * @param {NormalizedDebt} normalizedDebt normalized (not actual) total debt
  * @param {Amount<'nat'>} collateral
@@ -91,7 +95,7 @@ const collateralizationRatio = (normalizedDebt, collateral) => {
  * @param {Amount<'nat'>} collateral
  * @param {VaultId} vaultId
  * @returns {string} lexically sortable string in which highest
- *   debt-to-collateral is earliest
+ * debt-to-collateral is earliest
  */
 export const toVaultKey = (normalizedDebt, collateral, vaultId) => {
   assert(normalizedDebt);
@@ -158,7 +162,7 @@ harden(normalizedCollRatio);
  * @param {Ratio} compoundedInterest
  * @param {Ratio} margin
  * @returns {string} lexically sortable string in which highest
- *   debt-to-collateral is earliest
+ * debt-to-collateral is earliest
  */
 export const normalizedCollRatioKey = (quote, compoundedInterest, margin) => {
   const collRatio = normalizedCollRatio(quote, compoundedInterest, margin);

package/src/vaultFactory/types.js

@@ -2,30 +2,21 @@
 
 /**
  * @typedef {import('./vault').VaultNotification} VaultNotification
- *
  * @typedef {import('./vault').Vault} Vault
- *
  * @typedef {import('./vaultKit').VaultKit} VaultKit
- *
  * @typedef {import('./vaultManager').VaultManager} VaultManager
- *
  * @typedef {import('./vaultManager').CollateralManager} CollateralManager
- *
  * @typedef {import('../reserve/assetReserve.js').AssetReserveLimitedCreatorFacet} AssetReserveCreatorFacet
- *
  * @typedef {import('../reserve/assetReserve.js').AssetReservePublicFacet} AssetReservePublicFacet
- *
  * @typedef {import('../auction/auctioneer.js').AuctioneerPublicFacet} AuctioneerPublicFacet
- *
  * @typedef {import('./vaultFactory.js').VaultFactoryContract['publicFacet']} VaultFactoryPublicFacet
  *
  * @typedef {import('@agoric/time/src/types').Timestamp} Timestamp
- *
  * @typedef {import('@agoric/time/src/types').RelativeTime} RelativeTime
  */
 
 /**
- * @typedef {object} AutoswapLocal
+ * @typedef  {object} AutoswapLocal
  * @property {(amount: Amount, brand: Brand) => Amount} getInputPrice
  * @property {() => Invitation} makeSwapInvitation
  */
@@ -33,16 +24,13 @@
 /**
  * @typedef {object} VaultManagerParamValues
  * @property {Ratio} liquidationMargin - margin below which collateral will be
- *   liquidated to satisfy the debt.
- * @property {Ratio} liquidationPenalty - penalty charged upon liquidation as
- *   proportion of debt
- * @property {Ratio} interestRate - annual interest rate charged on debt
- *   positions
- * @property {Ratio} mintFee - The fee (in BasisPoints) charged when creating or
- *   increasing a debt position.
+ * liquidated to satisfy the debt.
+ * @property {Ratio} liquidationPenalty - penalty charged upon liquidation as proportion of debt
+ * @property {Ratio} interestRate - annual interest rate charged on debt positions
+ * @property {Ratio} mintFee - The fee (in BasisPoints) charged when creating
+ * or increasing a debt position.
  * @property {Amount<'nat'>} debtLimit
- * @property {Ratio} [liquidationPadding] - vault must maintain this in order to
- *   remove collateral or add debt
+ * @property {Ratio} [liquidationPadding] - vault must maintain this in order to remove collateral or add debt
  */
 
 /**
@@ -54,7 +42,7 @@
  */
 
 /**
- * @typedef {object} VaultFactoryCreatorFacet
+ * @typedef  {object} VaultFactoryCreatorFacet
  * @property {AddVaultType} addVaultType
  * @property {() => Allocation} getRewardAllocation
  * @property {() => Promise<Invitation<string, never>>} makeCollectFeesInvitation
@@ -63,20 +51,23 @@
  */
 
 /**
- * @callback MintAndTransfer Mint new debt `toMint` and transfer the `fee`
- *   portion to the vaultFactory's reward pool. Then reallocate over all the
- *   seat arguments and the rewardPoolSeat. Update the `totalDebt` if the
- *   reallocate succeeds.
+ * @callback MintAndTransfer
+ * Mint new debt `toMint` and transfer the `fee` portion to the vaultFactory's reward
+ * pool. Then reallocate over all the seat arguments and the rewardPoolSeat. Update
+ * the `totalDebt` if the reallocate succeeds.
  * @param {ZCFSeat} mintReceiver
  * @param {Amount<'nat'>} toMint
  * @param {Amount<'nat'>} fee
- * @param {TransferPart[]} transfers
+ * @param {import('@agoric/zoe/src/contractSupport/atomicTransfer.js').TransferPart[]} transfers
  * @returns {void}
  */
 
 /**
- * @callback BurnDebt Burn debt tokens off a seat and update the `totalDebt` if
- *   the reallocate succeeds.
+ * @callback BurnDebt
+ *
+ * Burn debt tokens off a seat and update
+ * the `totalDebt` if the reallocate succeeds.
+ *
  * @param {Amount} toBurn
  * @param {ZCFSeat} fromSeat
  * @returns {void}
@@ -87,15 +78,16 @@
  * @property {() => Ratio} getLiquidationMargin
  * @property {() => Ratio} getMintFee
  * @property {() => Promise<PriceQuote>} getCollateralQuote
- * @property {() => Ratio} getInterestRate - The annual interest rate on a debt
- *   position
+ * @property {() => Ratio} getInterestRate - The annual interest rate on a debt position
  * @property {() => RelativeTime} getChargingPeriod - The period (in seconds) at
  *   which interest is charged to the debt position.
  * @property {() => RelativeTime} getRecordingPeriod - The period (in seconds)
  *   at which interest is recorded to the debt position.
  */
 
-/** @typedef {string} VaultId */
+/**
+ * @typedef {string} VaultId
+ */
 
 /**
  * @typedef {object} InterestTiming
@@ -112,9 +104,7 @@
 
 /**
  * @typedef {object} Liquidator
- * @property {() => Promise<
- *   Invitation<void, { debt: Amount<'nat'>; penaltyRate: Ratio }>
- * >} makeLiquidateInvitation
+ * @property {() => Promise<Invitation<void, { debt: Amount<'nat'>; penaltyRate: Ratio; }>>} makeLiquidateInvitation
  */
 
 /**
@@ -134,11 +124,11 @@
 /**
  * @typedef {object} CalculatorKit
  * @property {Calculate} calculate calculate new debt for charging periods up to
- *   the present.
+ * the present.
  * @property {Calculate} calculateReportingPeriod calculate new debt for
- *   reporting periods up to the present. If some charging periods have elapsed
- *   that don't constitute whole reporting periods, the time is not updated past
- *   them and interest is not accumulated for them.
+ * reporting periods up to the present. If some charging periods have elapsed
+ * that don't constitute whole reporting periods, the time is not updated past
+ * them and interest is not accumulated for them.
  */
 
-/** @typedef {{ key: 'governedParams' | { collateralBrand: Brand } }} VaultFactoryParamPath */
+/** @typedef {{key: 'governedParams' | {collateralBrand: Brand}}} VaultFactoryParamPath */

package/src/vaultFactory/vault.js

@@ -1,6 +1,5 @@
 import { AmountMath, AmountShape } from '@agoric/ertp';
-import { StorageNodeShape, makeTracer } from '@agoric/internal';
-import { UnguardedHelperI } from '@agoric/internal/src/typeGuards.js';
+import { makeTracer, StorageNodeShape } from '@agoric/internal';
 import { M, prepareExoClassKit } from '@agoric/vat-data';
 import { atomicTransfer } from '@agoric/zoe/src/contractSupport/index.js';
 import { SeatShape } from '@agoric/zoe/src/typeGuards.js';
@@ -10,10 +9,11 @@ import {
   makeNatAmountShape,
 } from '../contractSupport.js';
 import { calculateCurrentDebt, reverseInterest } from '../interest-math.js';
-import { calculateDebtCosts } from './math.js';
+import { UnguardedHelperI } from '../typeGuards.js';
 import { prepareVaultKit } from './vaultKit.js';
 
 import '@agoric/zoe/exported.js';
+import { calculateDebtCosts } from './math.js';
 
 const { quote: q, Fail } = assert;
 
@@ -22,36 +22,31 @@ const trace = makeTracer('Vault', true);
 /** @typedef {import('./storeUtils.js').NormalizedDebt} NormalizedDebt */
 
 /**
- * @file This has most of the logic for a Vault, to borrow Minted against
- *   collateral.
+ * @file This has most of the logic for a Vault, to borrow Minted against collateral.
  *
- *   The logic here is for Vault which is the majority of logic of vaults but the
- *   user view is the `vault` value contained in VaultKit.
+ * The logic here is for Vault which is the majority of logic of vaults but
+ * the user view is the `vault` value contained in VaultKit.
  *
- *   A note on naming convention:
- *
- *   - `Pre` is used as a postfix for any mutable value retrieved _before_ an
- *       `await`, to flag values that must used very carefully after the
- *       `await`
- *   - `new` is a prefix for values that describe the result of executing a
- *       transaction; e.g., `debt` is the value before the txn, and `newDebt`
- *       will be value if the txn completes.
- *   - the absence of one of these implies the opposite, so `newDebt` is the future
- *       value fo `debt`, as computed based on values after any `await`
+ * A note on naming convention:
+ * - `Pre` is used as a postfix for any mutable value retrieved *before* an
+ *    `await`, to flag values that must used very carefully after the `await`
+ * - `new` is a prefix for values that describe the result of executing a
+ *   transaction; e.g., `debt` is the value before the txn, and `newDebt`
+ *   will be value if the txn completes.
+ * - the absence of one of these implies the opposite, so `newDebt` is the
+ *   future value fo `debt`, as computed based on values after any `await`
  */
 
 /**
  * Constants for vault phase.
  *
- * - ACTIVE - vault is in use and can be changed
- * - LIQUIDATING - vault is being liquidated by the vault manager, and cannot be
- *   changed by the user. If liquidation fails, vaults may remain in this state.
- *   An upgrade to the contract might be able to recover them.
- * - TRANSFER - vault is able to be transferred (payments and debits frozen until
- *   it has a new owner)
- * - CLOSED - vault was closed by the user and all assets have been paid out
- * - LIQUIDATED - vault was closed by the manager, with remaining assets paid to
- *   owner
+ * ACTIVE       - vault is in use and can be changed
+ * LIQUIDATING  - vault is being liquidated by the vault manager, and cannot be changed by the user.
+ *                If liquidation fails, vaults may remain in this state. An upgrade to the contract
+ *                might be able to recover them.
+ * TRANSFER     - vault is able to be transferred (payments and debits frozen until it has a new owner)
+ * CLOSED       - vault was closed by the user and all assets have been paid out
+ * LIQUIDATED   - vault was closed by the manager, with remaining assets paid to owner
  */
 export const Phase = /** @type {const} */ ({
   ACTIVE: 'active',
@@ -63,7 +58,7 @@ export const Phase = /** @type {const} */ ({
 
 /**
  * @typedef {Phase[keyof Omit<typeof Phase, 'TRANSFER'>]} VaultPhase
- * @type {{ [K in VaultPhase]: VaultPhase[] }}
+ * @type {{[K in VaultPhase]: Array<VaultPhase>}}
  */
 const validTransitions = {
   [Phase.ACTIVE]: [Phase.LIQUIDATING, Phase.CLOSED],
@@ -77,8 +72,7 @@ const validTransitions = {
  *
  * @typedef {object} VaultNotification
  * @property {Amount<'nat'>} locked Amount of Collateral locked
- * @property {{ debt: Amount<'nat'>; interest: Ratio }} debtSnapshot 'debt' at
- *   the point the compounded interest was 'interest'
+ * @property {{debt: Amount<'nat'>, interest: Ratio}} debtSnapshot 'debt' at the point the compounded interest was 'interest'
  * @property {HolderPhase} vaultState
  */
 
@@ -93,36 +87,27 @@ const validTransitions = {
  * @property {MintAndTransfer} mintAndTransfer
  * @property {(amount: Amount, seat: ZCFSeat) => void} burn
  * @property {() => Ratio} getCompoundedInterest
- * @property {(
- *   oldDebt: import('./storeUtils.js').NormalizedDebt,
- *   oldCollateral: Amount<'nat'>,
- *   vaultId: VaultId,
- *   vaultPhase: VaultPhase,
- *   vault: Vault,
- * ) => void} handleBalanceChange
+ * @property {(oldDebt: import('./storeUtils.js').NormalizedDebt, oldCollateral: Amount<'nat'>, vaultId: VaultId, vaultPhase: VaultPhase, vault: Vault) => void} handleBalanceChange
  * @property {() => import('./vaultManager.js').GovernedParamGetters} getGovernedParams
  */
 
 /**
  * @typedef {Readonly<{
- *   idInManager: VaultId;
- *   manager: VaultManager;
- *   storageNode: StorageNode;
- *   vaultSeat: ZCFSeat;
+ * idInManager: VaultId,
+ * manager: VaultManager,
+ * storageNode: StorageNode,
+ * vaultSeat: ZCFSeat,
  * }>} ImmutableState
  */
 
 /**
- * Snapshot is of the debt and compounded interest when the principal was last
- * changed.
+ * Snapshot is of the debt and compounded interest when the principal was last changed.
  *
  * @typedef {{
- *   interestSnapshot: Ratio;
- *   phase: VaultPhase;
- *   debtSnapshot: Amount<'nat'>;
- *   outerUpdater:
- *     | import('@agoric/zoe/src/contractSupport/recorder.js').Recorder<VaultNotification>
- *     | null;
+ *   interestSnapshot: Ratio,
+ *   phase: VaultPhase,
+ *   debtSnapshot: Amount<'nat'>,
+ *   outerUpdater: import('@agoric/zoe/src/contractSupport/recorder.js').Recorder<VaultNotification> | null,
  * }} MutableState
  */
 
@@ -210,10 +195,7 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
           return AmountMath.makeEmpty(this.facets.helper.debtBrand());
         },
         /**
-         * @typedef {{
-         *   give: { Collateral: Amount<'nat'>; Minted: Amount<'nat'> };
-         *   want: { Collateral: Amount<'nat'>; Minted: Amount<'nat'> };
-         * }} FullProposal
+         * @typedef {{ give: { Collateral: Amount<'nat'>, Minted: Amount<'nat'> }, want: { Collateral: Amount<'nat'>, Minted: Amount<'nat'> } }} FullProposal
          */
         /**
          * @param {ProposalRecord} partial
@@ -238,7 +220,9 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
         //#endregion
 
         //#region Phase logic
-        /** @param {VaultPhase} newPhase */
+        /**
+         * @param {VaultPhase} newPhase
+         */
         assignPhase(newPhase) {
           const { state } = this;
 
@@ -277,14 +261,12 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
         },
 
         /**
-         * Update the debt balance and propagate upwards to maintain aggregate
-         * debt and liquidation order.
+         * Update the debt balance and propagate upwards to
+         * maintain aggregate debt and liquidation order.
          *
-         * @param {NormalizedDebt} oldDebtNormalized - prior principal and all
-         *   accrued interest, normalized to the launch of the vaultManager
+         * @param {NormalizedDebt} oldDebtNormalized - prior principal and all accrued interest, normalized to the launch of the vaultManager
          * @param {Amount<'nat'>} oldCollateral - actual collateral
-         * @param {Amount<'nat'>} newDebtActual - actual principal and all
-         *   accrued interest
+         * @param {Amount<'nat'>} newDebtActual - actual principal and all accrued interest
          */
         updateDebtAccounting(oldDebtNormalized, oldCollateral, newDebtActual) {
           const { state, facets } = this;
@@ -300,7 +282,10 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
           );
         },
 
-        /** @param {ZCFSeat} seat */
+        /**
+         *
+         * @param {ZCFSeat} seat
+         */
         getCollateralAllocated(seat) {
           return seat.getAmountAllocated(
             'Collateral',
@@ -322,6 +307,7 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
         },
 
         /**
+         *
          * @param {Amount<'nat'>} collateralAmount
          * @param {Amount<'nat'>} proposedDebt
          */
@@ -334,7 +320,10 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
             )} for ${q(collateralAmount)} collateral`;
         },
 
-        /** @param {HolderPhase} newPhase */
+        /**
+         *
+         * @param {HolderPhase} newPhase
+         */
         getStateSnapshot(newPhase) {
           const { state, facets } = this;
 
@@ -349,7 +338,9 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
           });
         },
 
-        /** call this whenever anything changes! */
+        /**
+         * call this whenever anything changes!
+         */
         updateUiState() {
           const { state, facets } = this;
           const { outerUpdater } = state;
@@ -377,7 +368,9 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
           }
         },
 
-        /** @param {ZCFSeat} seat */
+        /**
+         * @param {ZCFSeat} seat
+         */
         async closeHook(seat) {
           const { state, facets } = this;
 
@@ -447,11 +440,11 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
         },
 
         /**
-         * 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'>} giveAmount
@@ -529,6 +522,7 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
         },
 
         /**
+         *
          * @param {ZCFSeat} clientSeat
          * @param {FullProposal} fp
          * @param {ReturnType<typeof calculateDebtCosts>} costs
@@ -549,7 +543,7 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
 
           const giveMintedTaken = AmountMath.subtract(fp.give.Minted, surplus);
 
-          /** @type {TransferPart[]} */
+          /** @type {import('@agoric/zoe/src/contractSupport/atomicTransfer.js').TransferPart[]} */
           const transfers = harden([
             [clientSeat, vaultSeat, { Collateral: fp.give.Collateral }],
             [vaultSeat, clientSeat, { Collateral: fp.want.Collateral }],
@@ -574,6 +568,7 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
         },
 
         /**
+         *
          * @param {ZCFSeat} seat
          * @returns {VaultKit}
          */
@@ -674,7 +669,9 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
           return vaultKit;
         },
 
-        /** Called by manager at start of liquidation. */
+        /**
+         * Called by manager at start of liquidation.
+         */
         liquidating() {
           const { facets } = this;
 
@@ -684,8 +681,8 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
         },
 
         /**
-         * Called by manager at end of liquidation, at which point all debts
-         * have been covered.
+         * Called by manager at end of liquidation, at which point all debts have been
+         * covered.
          */
         liquidated() {
           const { facets } = this;
@@ -777,7 +774,9 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
           );
         },
 
-        /** @returns {Promise<Invitation>} */
+        /**
+         * @returns {Promise<Invitation>}
+         */
         makeTransferInvitation() {
           const { state, facets } = this;
           const { outerUpdater } = state;
@@ -809,7 +808,10 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
 
         // for status/debugging
 
-        /** @returns {Amount<'nat'>} */
+        /**
+         *
+         * @returns {Amount<'nat'>}
+         */
         getCollateralAmount() {
           const { state, facets } = this;
           const { vaultSeat } = state;
@@ -823,15 +825,15 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
         /**
          * The actual current debt, including accrued interest.
          *
-         * This looks like a simple getter but it does a lot of the heavy
-         * lifting for interest accrual. Rather than updating all records when
-         * interest accrues, the vault manager updates just its rolling
-         * compounded interest. Here we calculate what the current debt is given
-         * what's recorded in this vault and what interest has compounded since
-         * this vault record was written.
+         * This looks like a simple getter but it does a lot of the heavy lifting for
+         * interest accrual. Rather than updating all records when interest accrues,
+         * the vault manager updates just its rolling compounded interest. Here we
+         * calculate what the current debt is given what's recorded in this vault and
+         * what interest has compounded since this vault record was written.
          *
-         * @returns {Amount<'nat'>}
          * @see getNormalizedDebt
+         *
+         * @returns {Amount<'nat'>}
          */
         getCurrentDebt() {
           const { state } = this;
@@ -843,15 +845,14 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
         },
 
         /**
-         * The normalization puts all debts on a common time-independent scale
-         * since the launch of this vault manager. This allows the manager to
-         * order vaults by their debt-to-collateral ratios without having to
-         * mutate the debts as the interest accrues.
+         * The normalization puts all debts on a common time-independent scale since
+         * the launch of this vault manager. This allows the manager to order vaults
+         * by their debt-to-collateral ratios without having to mutate the debts as
+         * the interest accrues.
          *
-         * @returns {import('./storeUtils.js').NormalizedDebt} as if the vault
-         *   was open at the launch of this manager, before any interest
-         *   accrued
          * @see getActualDebAmount
+         *
+         * @returns {import('./storeUtils.js').NormalizedDebt} as if the vault was open at the launch of this manager, before any interest accrued
          */
         getNormalizedDebt() {
           const { state } = this;