@agoric/inter-protocol 0.16.2-dev-857e650.0 → 0.16.2-dev-fb922d3.0

package/src/vaultFactory/vaultManager.d.ts

@@ -24,20 +24,15 @@ export function prepareVaultManagerKit(baggage: MapStore<string, unknown>, { zcf
         };
     };
     helper: {
-        /**
-         * Start non-durable processes (or restart if needed after vat restart)
-         */
+        /** Start non-durable processes (or restart if needed after vat restart) */
         start(): void;
-        /**
-         * @param {Timestamp} updateTime
-         */
+        /** @param {Timestamp} updateTime */
         chargeAllVaults(updateTime: Timestamp): Promise<void>;
         assetNotify(): Promise<void>;
         burnToCoverDebt(debt: any, proceeds: any, seat: any): void;
         sendToReserve(penalty: any, seat: any, seatKeyword?: string): void;
         markLiquidating(debt: any, collateral: any): void;
         /**
-         *
          * @param {Amount<'nat'>} debt
          * @param {Amount<'nat'>} collateral
          * @param {Amount<'nat'>} overage
@@ -46,14 +41,18 @@ export function prepareVaultManagerKit(baggage: MapStore<string, unknown>, { zcf
         markDoneLiquidating(debt: Amount<'nat'>, collateral: Amount<'nat'>, overage: Amount<'nat'>, shortfall: Amount<'nat'>): void;
         writeMetrics(): Promise<void>;
         /**
-         * This is designed to tolerate an incomplete plan, in case calculateDistributionPlan encounters
-         * an error during its calculation. We don't have a way to induce such errors in CI so we've
-         * done so manually in dev and verified this function recovers as expected.
+         * This is designed to tolerate an incomplete plan, in case
+         * calculateDistributionPlan encounters an error during its calculation.
+         * We don't have a way to induce such errors in CI so we've done so
+         * manually in dev and verified this function recovers as expected.
          *
          * @param {AmountKeywordRecord} proceeds
          * @param {Amount<'nat'>} totalDebt
          * @param {Pick<PriceQuote, 'quoteAmount'>} oraclePriceAtStart
-         * @param {MapStore<Vault, { collateralAmount: Amount<'nat'>, debtAmount:  Amount<'nat'>}>} vaultData
+         * @param {MapStore<
+         *   Vault,
+         *   { collateralAmount: Amount<'nat'>; debtAmount: Amount<'nat'> }
+         * >} vaultData
          * @param {Amount<'nat'>} totalCollateral
          */
         planProceedsDistribution(proceeds: AmountKeywordRecord, totalDebt: Amount<'nat'>, oraclePriceAtStart: Pick<PriceQuote, 'quoteAmount'>, vaultData: MapStore<Vault, {
@@ -72,6 +71,102 @@ export function prepareVaultManagerKit(baggage: MapStore<string, unknown>, { zcf
                         };
                     };
                     invitationMakers: {
+                        /** @typedef {import('@agoric/time/src/types').RelativeTime} RelativeTime */
+                        /**
+                         * @typedef {object} MetricsNotification
+                         * @property {Ratio | null} lockedQuote priceQuote that will be used for
+                         *   liquidation. Non-null from priceLock time until liquidation has taken
+                         *   place.
+                         * @property {number} numActiveVaults present count of vaults
+                         * @property {number} numLiquidatingVaults present count of liquidating vaults
+                         * @property {Amount<'nat'>} totalCollateral present sum of collateral across
+                         *   all vaults
+                         * @property {Amount<'nat'>} totalDebt present sum of debt across all vaults
+                         * @property {Amount<'nat'>} retainedCollateral collateral held as a result of
+                         *   not returning excess refunds to owners of vaults liquidated with
+                         *   shortfalls
+                         * @property {Amount<'nat'>} liquidatingCollateral present sum of collateral in
+                         *   vaults sent for liquidation
+                         * @property {Amount<'nat'>} liquidatingDebt present sum of debt in vaults sent
+                         *   for liquidation
+                         * @property {Amount<'nat'>} totalCollateralSold running sum of collateral sold
+                         *   in liquidation
+                         * @property {Amount<'nat'>} totalOverageReceived running sum of overages,
+                         *   central received greater than debt
+                         * @property {Amount<'nat'>} totalProceedsReceived running sum of minted
+                         *   received from liquidation
+                         * @property {Amount<'nat'>} totalShortfallReceived running sum of shortfalls,
+                         *   minted received less than debt
+                         * @property {number} numLiquidationsCompleted running count of liquidated
+                         *   vaults
+                         * @property {number} numLiquidationsAborted running count of vault liquidations
+                         *   that were reverted.
+                         */
+                        /**
+                         * @typedef {{
+                         *   compoundedStabilityFee: Ratio;
+                         *   stabilityFee: Ratio;
+                         *   latestStabilityFeeUpdate: Timestamp;
+                         * }} AssetState
+                         *
+                         * @typedef {{
+                         *   getChargingPeriod: () => RelativeTime;
+                         *   getRecordingPeriod: () => RelativeTime;
+                         *   getDebtLimit: () => Amount<'nat'>;
+                         *   getStabilityFee: () => Ratio;
+                         *   getLiquidationPadding: () => Ratio;
+                         *   getLiquidationMargin: () => Ratio;
+                         *   getLiquidationPenalty: () => Ratio;
+                         *   getMintFee: () => Ratio;
+                         *   getMinInitialDebt: () => Amount<'nat'>;
+                         * }} GovernedParamGetters
+                         */
+                        /**
+                         * @typedef {Readonly<{
+                         *   debtMint: ZCFMint<'nat'>;
+                         *   collateralBrand: Brand<'nat'>;
+                         *   collateralUnit: Amount<'nat'>;
+                         *   descriptionScope: string;
+                         *   startTimeStamp: Timestamp;
+                         *   storageNode: StorageNode;
+                         * }>} HeldParams
+                         */
+                        /**
+                         * @typedef {{
+                         *   assetTopicKit: import('@agoric/zoe/src/contractSupport/recorder.js').RecorderKit<AssetState>;
+                         *   debtBrand: Brand<'nat'>;
+                         *   liquidatingVaults: SetStore<Vault>;
+                         *   metricsTopicKit: import('@agoric/zoe/src/contractSupport/recorder.js').RecorderKit<MetricsNotification>;
+                         *   poolIncrementSeat: ZCFSeat;
+                         *   retainedCollateralSeat: ZCFSeat;
+                         *   unsettledVaults: MapStore<string, Vault>;
+                         * }} ImmutableState
+                         */
+                        /**
+                         * @typedef {{
+                         *   compoundedStabilityFee: Ratio;
+                         *   latestStabilityFeeUpdate: Timestamp;
+                         *   numLiquidationsCompleted: number;
+                         *   numLiquidationsAborted: number;
+                         *   totalCollateral: Amount<'nat'>;
+                         *   totalCollateralSold: Amount<'nat'>;
+                         *   totalDebt: Amount<'nat'>;
+                         *   liquidatingCollateral: Amount<'nat'>;
+                         *   liquidatingDebt: Amount<'nat'>;
+                         *   totalOverageReceived: Amount<'nat'>;
+                         *   totalProceedsReceived: Amount<'nat'>;
+                         *   totalShortfallReceived: Amount<'nat'>;
+                         *   vaultCounter: number;
+                         *   lockedQuote: PriceQuote | undefined;
+                         * }} MutableState
+                         */
+                        /**
+                         * @type {(brand: Brand) => {
+                         *   prioritizedVaults: ReturnType<typeof makePrioritizedVaults>;
+                         *   storedQuotesNotifier: import('@agoric/notifier').StoredNotifier<PriceQuote>;
+                         *   storedCollateralQuote: PriceQuote;
+                         * }}
+                         */
                         AdjustBalances(): Promise<Invitation<R, A>>;
                         CloseVault(): Promise<Invitation<R, A>>;
                         TransferVault(): Promise<Invitation<R, A>>;
@@ -105,13 +200,14 @@ export function prepareVaultManagerKit(baggage: MapStore<string, unknown>, { zcf
             }[];
         };
         /**
-         * This is designed to tolerate an incomplete plan, in case calculateDistributionPlan encounters
-         * an error during its calculation. We don't have a way to induce such errors in CI so we've
-         * done so manually in dev and verified this function recovers as expected.
+         * This is designed to tolerate an incomplete plan, in case
+         * calculateDistributionPlan encounters an error during its calculation.
+         * We don't have a way to induce such errors in CI so we've done so
+         * manually in dev and verified this function recovers as expected.
          *
          * @param {object} obj
          * @param {import('./proceeds.js').DistributionPlan} obj.plan
-         * @param {Array<Vault>} obj.vaultsInPlan
+         * @param {Vault[]} obj.vaultsInPlan
          * @param {ZCFSeat} obj.liqSeat
          * @param {Amount<'nat'>} obj.totalCollateral
          * @param {Amount<'nat'>} obj.totalDebt
@@ -119,7 +215,7 @@ export function prepareVaultManagerKit(baggage: MapStore<string, unknown>, { zcf
          */
         distributeProceeds({ plan, vaultsInPlan, liqSeat, totalCollateral, totalDebt, }: {
             plan: import('./proceeds.js').DistributionPlan;
-            vaultsInPlan: Array<Vault>;
+            vaultsInPlan: Vault[];
             liqSeat: ZCFSeat;
             totalCollateral: Amount<'nat'>;
             totalDebt: Amount<'nat'>;
@@ -150,9 +246,7 @@ export function prepareVaultManagerKit(baggage: MapStore<string, unknown>, { zcf
          * @param {string} base
          */
         scopeDescription(base: string): string;
-        /**
-         * coefficient on existing debt to calculate new debt
-         */
+        /** coefficient on existing debt to calculate new debt */
         getCompoundedStabilityFee(): Ratio;
         /**
          * Called by a vault when its balances change.
@@ -160,7 +254,8 @@ export function prepareVaultManagerKit(baggage: MapStore<string, unknown>, { zcf
          * @param {NormalizedDebt} oldDebtNormalized
          * @param {Amount<'nat'>} oldCollateral
          * @param {VaultId} vaultId
-         * @param {import('./vault.js').VaultPhase} vaultPhase at the end of whatever change updated balances
+         * @param {import('./vault.js').VaultPhase} vaultPhase at the end of
+         *   whatever change updated balances
          * @param {Vault} vault
          * @returns {void}
          */
@@ -168,9 +263,7 @@ export function prepareVaultManagerKit(baggage: MapStore<string, unknown>, { zcf
     };
     self: {
         getGovernedParams(): GovernedParamGetters;
-        /**
-         * @param {ZCFSeat} seat
-         */
+        /** @param {ZCFSeat} seat */
         makeVaultKit(seat: ZCFSeat): Promise<{
             publicSubscribers: {
                 vault: {
@@ -180,6 +273,102 @@ export function prepareVaultManagerKit(baggage: MapStore<string, unknown>, { zcf
                 };
             };
             invitationMakers: {
+                /** @typedef {import('@agoric/time/src/types').RelativeTime} RelativeTime */
+                /**
+                 * @typedef {object} MetricsNotification
+                 * @property {Ratio | null} lockedQuote priceQuote that will be used for
+                 *   liquidation. Non-null from priceLock time until liquidation has taken
+                 *   place.
+                 * @property {number} numActiveVaults present count of vaults
+                 * @property {number} numLiquidatingVaults present count of liquidating vaults
+                 * @property {Amount<'nat'>} totalCollateral present sum of collateral across
+                 *   all vaults
+                 * @property {Amount<'nat'>} totalDebt present sum of debt across all vaults
+                 * @property {Amount<'nat'>} retainedCollateral collateral held as a result of
+                 *   not returning excess refunds to owners of vaults liquidated with
+                 *   shortfalls
+                 * @property {Amount<'nat'>} liquidatingCollateral present sum of collateral in
+                 *   vaults sent for liquidation
+                 * @property {Amount<'nat'>} liquidatingDebt present sum of debt in vaults sent
+                 *   for liquidation
+                 * @property {Amount<'nat'>} totalCollateralSold running sum of collateral sold
+                 *   in liquidation
+                 * @property {Amount<'nat'>} totalOverageReceived running sum of overages,
+                 *   central received greater than debt
+                 * @property {Amount<'nat'>} totalProceedsReceived running sum of minted
+                 *   received from liquidation
+                 * @property {Amount<'nat'>} totalShortfallReceived running sum of shortfalls,
+                 *   minted received less than debt
+                 * @property {number} numLiquidationsCompleted running count of liquidated
+                 *   vaults
+                 * @property {number} numLiquidationsAborted running count of vault liquidations
+                 *   that were reverted.
+                 */
+                /**
+                 * @typedef {{
+                 *   compoundedStabilityFee: Ratio;
+                 *   stabilityFee: Ratio;
+                 *   latestStabilityFeeUpdate: Timestamp;
+                 * }} AssetState
+                 *
+                 * @typedef {{
+                 *   getChargingPeriod: () => RelativeTime;
+                 *   getRecordingPeriod: () => RelativeTime;
+                 *   getDebtLimit: () => Amount<'nat'>;
+                 *   getStabilityFee: () => Ratio;
+                 *   getLiquidationPadding: () => Ratio;
+                 *   getLiquidationMargin: () => Ratio;
+                 *   getLiquidationPenalty: () => Ratio;
+                 *   getMintFee: () => Ratio;
+                 *   getMinInitialDebt: () => Amount<'nat'>;
+                 * }} GovernedParamGetters
+                 */
+                /**
+                 * @typedef {Readonly<{
+                 *   debtMint: ZCFMint<'nat'>;
+                 *   collateralBrand: Brand<'nat'>;
+                 *   collateralUnit: Amount<'nat'>;
+                 *   descriptionScope: string;
+                 *   startTimeStamp: Timestamp;
+                 *   storageNode: StorageNode;
+                 * }>} HeldParams
+                 */
+                /**
+                 * @typedef {{
+                 *   assetTopicKit: import('@agoric/zoe/src/contractSupport/recorder.js').RecorderKit<AssetState>;
+                 *   debtBrand: Brand<'nat'>;
+                 *   liquidatingVaults: SetStore<Vault>;
+                 *   metricsTopicKit: import('@agoric/zoe/src/contractSupport/recorder.js').RecorderKit<MetricsNotification>;
+                 *   poolIncrementSeat: ZCFSeat;
+                 *   retainedCollateralSeat: ZCFSeat;
+                 *   unsettledVaults: MapStore<string, Vault>;
+                 * }} ImmutableState
+                 */
+                /**
+                 * @typedef {{
+                 *   compoundedStabilityFee: Ratio;
+                 *   latestStabilityFeeUpdate: Timestamp;
+                 *   numLiquidationsCompleted: number;
+                 *   numLiquidationsAborted: number;
+                 *   totalCollateral: Amount<'nat'>;
+                 *   totalCollateralSold: Amount<'nat'>;
+                 *   totalDebt: Amount<'nat'>;
+                 *   liquidatingCollateral: Amount<'nat'>;
+                 *   liquidatingDebt: Amount<'nat'>;
+                 *   totalOverageReceived: Amount<'nat'>;
+                 *   totalProceedsReceived: Amount<'nat'>;
+                 *   totalShortfallReceived: Amount<'nat'>;
+                 *   vaultCounter: number;
+                 *   lockedQuote: PriceQuote | undefined;
+                 * }} MutableState
+                 */
+                /**
+                 * @type {(brand: Brand) => {
+                 *   prioritizedVaults: ReturnType<typeof makePrioritizedVaults>;
+                 *   storedQuotesNotifier: import('@agoric/notifier').StoredNotifier<PriceQuote>;
+                 *   storedCollateralQuote: PriceQuote;
+                 * }}
+                 */
                 AdjustBalances(): Promise<Invitation<R, A>>;
                 CloseVault(): Promise<Invitation<R, A>>;
                 TransferVault(): Promise<Invitation<R, A>>;
@@ -212,9 +401,7 @@ export function prepareVaultManagerKit(baggage: MapStore<string, unknown>, { zcf
             };
         };
         lockOraclePrices(): PriceQuote;
-        /**
-         * @param {ERef<AuctioneerPublicFacet>} auctionPF
-         */
+        /** @param {ERef<AuctioneerPublicFacet>} auctionPF */
         liquidateVaults(auctionPF: ERef<AuctioneerPublicFacet>): Promise<void>;
     };
 } & import("@endo/eventual-send").RemotableBrand<{}, {
@@ -228,20 +415,15 @@ export function prepareVaultManagerKit(baggage: MapStore<string, unknown>, { zcf
         };
     };
     helper: {
-        /**
-         * Start non-durable processes (or restart if needed after vat restart)
-         */
+        /** Start non-durable processes (or restart if needed after vat restart) */
         start(): void;
-        /**
-         * @param {Timestamp} updateTime
-         */
+        /** @param {Timestamp} updateTime */
         chargeAllVaults(updateTime: Timestamp): Promise<void>;
         assetNotify(): Promise<void>;
         burnToCoverDebt(debt: any, proceeds: any, seat: any): void;
         sendToReserve(penalty: any, seat: any, seatKeyword?: string): void;
         markLiquidating(debt: any, collateral: any): void;
         /**
-         *
          * @param {Amount<'nat'>} debt
          * @param {Amount<'nat'>} collateral
          * @param {Amount<'nat'>} overage
@@ -250,14 +432,18 @@ export function prepareVaultManagerKit(baggage: MapStore<string, unknown>, { zcf
         markDoneLiquidating(debt: Amount<'nat'>, collateral: Amount<'nat'>, overage: Amount<'nat'>, shortfall: Amount<'nat'>): void;
         writeMetrics(): Promise<void>;
         /**
-         * This is designed to tolerate an incomplete plan, in case calculateDistributionPlan encounters
-         * an error during its calculation. We don't have a way to induce such errors in CI so we've
-         * done so manually in dev and verified this function recovers as expected.
+         * This is designed to tolerate an incomplete plan, in case
+         * calculateDistributionPlan encounters an error during its calculation.
+         * We don't have a way to induce such errors in CI so we've done so
+         * manually in dev and verified this function recovers as expected.
          *
          * @param {AmountKeywordRecord} proceeds
          * @param {Amount<'nat'>} totalDebt
          * @param {Pick<PriceQuote, 'quoteAmount'>} oraclePriceAtStart
-         * @param {MapStore<Vault, { collateralAmount: Amount<'nat'>, debtAmount:  Amount<'nat'>}>} vaultData
+         * @param {MapStore<
+         *   Vault,
+         *   { collateralAmount: Amount<'nat'>; debtAmount: Amount<'nat'> }
+         * >} vaultData
          * @param {Amount<'nat'>} totalCollateral
          */
         planProceedsDistribution(proceeds: AmountKeywordRecord, totalDebt: Amount<'nat'>, oraclePriceAtStart: Pick<PriceQuote, 'quoteAmount'>, vaultData: MapStore<Vault, {
@@ -276,6 +462,102 @@ export function prepareVaultManagerKit(baggage: MapStore<string, unknown>, { zcf
                         };
                     };
                     invitationMakers: {
+                        /** @typedef {import('@agoric/time/src/types').RelativeTime} RelativeTime */
+                        /**
+                         * @typedef {object} MetricsNotification
+                         * @property {Ratio | null} lockedQuote priceQuote that will be used for
+                         *   liquidation. Non-null from priceLock time until liquidation has taken
+                         *   place.
+                         * @property {number} numActiveVaults present count of vaults
+                         * @property {number} numLiquidatingVaults present count of liquidating vaults
+                         * @property {Amount<'nat'>} totalCollateral present sum of collateral across
+                         *   all vaults
+                         * @property {Amount<'nat'>} totalDebt present sum of debt across all vaults
+                         * @property {Amount<'nat'>} retainedCollateral collateral held as a result of
+                         *   not returning excess refunds to owners of vaults liquidated with
+                         *   shortfalls
+                         * @property {Amount<'nat'>} liquidatingCollateral present sum of collateral in
+                         *   vaults sent for liquidation
+                         * @property {Amount<'nat'>} liquidatingDebt present sum of debt in vaults sent
+                         *   for liquidation
+                         * @property {Amount<'nat'>} totalCollateralSold running sum of collateral sold
+                         *   in liquidation
+                         * @property {Amount<'nat'>} totalOverageReceived running sum of overages,
+                         *   central received greater than debt
+                         * @property {Amount<'nat'>} totalProceedsReceived running sum of minted
+                         *   received from liquidation
+                         * @property {Amount<'nat'>} totalShortfallReceived running sum of shortfalls,
+                         *   minted received less than debt
+                         * @property {number} numLiquidationsCompleted running count of liquidated
+                         *   vaults
+                         * @property {number} numLiquidationsAborted running count of vault liquidations
+                         *   that were reverted.
+                         */
+                        /**
+                         * @typedef {{
+                         *   compoundedStabilityFee: Ratio;
+                         *   stabilityFee: Ratio;
+                         *   latestStabilityFeeUpdate: Timestamp;
+                         * }} AssetState
+                         *
+                         * @typedef {{
+                         *   getChargingPeriod: () => RelativeTime;
+                         *   getRecordingPeriod: () => RelativeTime;
+                         *   getDebtLimit: () => Amount<'nat'>;
+                         *   getStabilityFee: () => Ratio;
+                         *   getLiquidationPadding: () => Ratio;
+                         *   getLiquidationMargin: () => Ratio;
+                         *   getLiquidationPenalty: () => Ratio;
+                         *   getMintFee: () => Ratio;
+                         *   getMinInitialDebt: () => Amount<'nat'>;
+                         * }} GovernedParamGetters
+                         */
+                        /**
+                         * @typedef {Readonly<{
+                         *   debtMint: ZCFMint<'nat'>;
+                         *   collateralBrand: Brand<'nat'>;
+                         *   collateralUnit: Amount<'nat'>;
+                         *   descriptionScope: string;
+                         *   startTimeStamp: Timestamp;
+                         *   storageNode: StorageNode;
+                         * }>} HeldParams
+                         */
+                        /**
+                         * @typedef {{
+                         *   assetTopicKit: import('@agoric/zoe/src/contractSupport/recorder.js').RecorderKit<AssetState>;
+                         *   debtBrand: Brand<'nat'>;
+                         *   liquidatingVaults: SetStore<Vault>;
+                         *   metricsTopicKit: import('@agoric/zoe/src/contractSupport/recorder.js').RecorderKit<MetricsNotification>;
+                         *   poolIncrementSeat: ZCFSeat;
+                         *   retainedCollateralSeat: ZCFSeat;
+                         *   unsettledVaults: MapStore<string, Vault>;
+                         * }} ImmutableState
+                         */
+                        /**
+                         * @typedef {{
+                         *   compoundedStabilityFee: Ratio;
+                         *   latestStabilityFeeUpdate: Timestamp;
+                         *   numLiquidationsCompleted: number;
+                         *   numLiquidationsAborted: number;
+                         *   totalCollateral: Amount<'nat'>;
+                         *   totalCollateralSold: Amount<'nat'>;
+                         *   totalDebt: Amount<'nat'>;
+                         *   liquidatingCollateral: Amount<'nat'>;
+                         *   liquidatingDebt: Amount<'nat'>;
+                         *   totalOverageReceived: Amount<'nat'>;
+                         *   totalProceedsReceived: Amount<'nat'>;
+                         *   totalShortfallReceived: Amount<'nat'>;
+                         *   vaultCounter: number;
+                         *   lockedQuote: PriceQuote | undefined;
+                         * }} MutableState
+                         */
+                        /**
+                         * @type {(brand: Brand) => {
+                         *   prioritizedVaults: ReturnType<typeof makePrioritizedVaults>;
+                         *   storedQuotesNotifier: import('@agoric/notifier').StoredNotifier<PriceQuote>;
+                         *   storedCollateralQuote: PriceQuote;
+                         * }}
+                         */
                         AdjustBalances(): Promise<Invitation<R, A>>;
                         CloseVault(): Promise<Invitation<R, A>>;
                         TransferVault(): Promise<Invitation<R, A>>;
@@ -309,13 +591,14 @@ export function prepareVaultManagerKit(baggage: MapStore<string, unknown>, { zcf
             }[];
         };
         /**
-         * This is designed to tolerate an incomplete plan, in case calculateDistributionPlan encounters
-         * an error during its calculation. We don't have a way to induce such errors in CI so we've
-         * done so manually in dev and verified this function recovers as expected.
+         * This is designed to tolerate an incomplete plan, in case
+         * calculateDistributionPlan encounters an error during its calculation.
+         * We don't have a way to induce such errors in CI so we've done so
+         * manually in dev and verified this function recovers as expected.
          *
          * @param {object} obj
          * @param {import('./proceeds.js').DistributionPlan} obj.plan
-         * @param {Array<Vault>} obj.vaultsInPlan
+         * @param {Vault[]} obj.vaultsInPlan
          * @param {ZCFSeat} obj.liqSeat
          * @param {Amount<'nat'>} obj.totalCollateral
          * @param {Amount<'nat'>} obj.totalDebt
@@ -323,7 +606,7 @@ export function prepareVaultManagerKit(baggage: MapStore<string, unknown>, { zcf
          */
         distributeProceeds({ plan, vaultsInPlan, liqSeat, totalCollateral, totalDebt, }: {
             plan: import('./proceeds.js').DistributionPlan;
-            vaultsInPlan: Array<Vault>;
+            vaultsInPlan: Vault[];
             liqSeat: ZCFSeat;
             totalCollateral: Amount<'nat'>;
             totalDebt: Amount<'nat'>;
@@ -354,9 +637,7 @@ export function prepareVaultManagerKit(baggage: MapStore<string, unknown>, { zcf
          * @param {string} base
          */
         scopeDescription(base: string): string;
-        /**
-         * coefficient on existing debt to calculate new debt
-         */
+        /** coefficient on existing debt to calculate new debt */
         getCompoundedStabilityFee(): Ratio;
         /**
          * Called by a vault when its balances change.
@@ -364,7 +645,8 @@ export function prepareVaultManagerKit(baggage: MapStore<string, unknown>, { zcf
          * @param {NormalizedDebt} oldDebtNormalized
          * @param {Amount<'nat'>} oldCollateral
          * @param {VaultId} vaultId
-         * @param {import('./vault.js').VaultPhase} vaultPhase at the end of whatever change updated balances
+         * @param {import('./vault.js').VaultPhase} vaultPhase at the end of
+         *   whatever change updated balances
          * @param {Vault} vault
          * @returns {void}
          */
@@ -372,9 +654,7 @@ export function prepareVaultManagerKit(baggage: MapStore<string, unknown>, { zcf
     };
     self: {
         getGovernedParams(): GovernedParamGetters;
-        /**
-         * @param {ZCFSeat} seat
-         */
+        /** @param {ZCFSeat} seat */
         makeVaultKit(seat: ZCFSeat): Promise<{
             publicSubscribers: {
                 vault: {
@@ -384,6 +664,102 @@ export function prepareVaultManagerKit(baggage: MapStore<string, unknown>, { zcf
                 };
             };
             invitationMakers: {
+                /** @typedef {import('@agoric/time/src/types').RelativeTime} RelativeTime */
+                /**
+                 * @typedef {object} MetricsNotification
+                 * @property {Ratio | null} lockedQuote priceQuote that will be used for
+                 *   liquidation. Non-null from priceLock time until liquidation has taken
+                 *   place.
+                 * @property {number} numActiveVaults present count of vaults
+                 * @property {number} numLiquidatingVaults present count of liquidating vaults
+                 * @property {Amount<'nat'>} totalCollateral present sum of collateral across
+                 *   all vaults
+                 * @property {Amount<'nat'>} totalDebt present sum of debt across all vaults
+                 * @property {Amount<'nat'>} retainedCollateral collateral held as a result of
+                 *   not returning excess refunds to owners of vaults liquidated with
+                 *   shortfalls
+                 * @property {Amount<'nat'>} liquidatingCollateral present sum of collateral in
+                 *   vaults sent for liquidation
+                 * @property {Amount<'nat'>} liquidatingDebt present sum of debt in vaults sent
+                 *   for liquidation
+                 * @property {Amount<'nat'>} totalCollateralSold running sum of collateral sold
+                 *   in liquidation
+                 * @property {Amount<'nat'>} totalOverageReceived running sum of overages,
+                 *   central received greater than debt
+                 * @property {Amount<'nat'>} totalProceedsReceived running sum of minted
+                 *   received from liquidation
+                 * @property {Amount<'nat'>} totalShortfallReceived running sum of shortfalls,
+                 *   minted received less than debt
+                 * @property {number} numLiquidationsCompleted running count of liquidated
+                 *   vaults
+                 * @property {number} numLiquidationsAborted running count of vault liquidations
+                 *   that were reverted.
+                 */
+                /**
+                 * @typedef {{
+                 *   compoundedStabilityFee: Ratio;
+                 *   stabilityFee: Ratio;
+                 *   latestStabilityFeeUpdate: Timestamp;
+                 * }} AssetState
+                 *
+                 * @typedef {{
+                 *   getChargingPeriod: () => RelativeTime;
+                 *   getRecordingPeriod: () => RelativeTime;
+                 *   getDebtLimit: () => Amount<'nat'>;
+                 *   getStabilityFee: () => Ratio;
+                 *   getLiquidationPadding: () => Ratio;
+                 *   getLiquidationMargin: () => Ratio;
+                 *   getLiquidationPenalty: () => Ratio;
+                 *   getMintFee: () => Ratio;
+                 *   getMinInitialDebt: () => Amount<'nat'>;
+                 * }} GovernedParamGetters
+                 */
+                /**
+                 * @typedef {Readonly<{
+                 *   debtMint: ZCFMint<'nat'>;
+                 *   collateralBrand: Brand<'nat'>;
+                 *   collateralUnit: Amount<'nat'>;
+                 *   descriptionScope: string;
+                 *   startTimeStamp: Timestamp;
+                 *   storageNode: StorageNode;
+                 * }>} HeldParams
+                 */
+                /**
+                 * @typedef {{
+                 *   assetTopicKit: import('@agoric/zoe/src/contractSupport/recorder.js').RecorderKit<AssetState>;
+                 *   debtBrand: Brand<'nat'>;
+                 *   liquidatingVaults: SetStore<Vault>;
+                 *   metricsTopicKit: import('@agoric/zoe/src/contractSupport/recorder.js').RecorderKit<MetricsNotification>;
+                 *   poolIncrementSeat: ZCFSeat;
+                 *   retainedCollateralSeat: ZCFSeat;
+                 *   unsettledVaults: MapStore<string, Vault>;
+                 * }} ImmutableState
+                 */
+                /**
+                 * @typedef {{
+                 *   compoundedStabilityFee: Ratio;
+                 *   latestStabilityFeeUpdate: Timestamp;
+                 *   numLiquidationsCompleted: number;
+                 *   numLiquidationsAborted: number;
+                 *   totalCollateral: Amount<'nat'>;
+                 *   totalCollateralSold: Amount<'nat'>;
+                 *   totalDebt: Amount<'nat'>;
+                 *   liquidatingCollateral: Amount<'nat'>;
+                 *   liquidatingDebt: Amount<'nat'>;
+                 *   totalOverageReceived: Amount<'nat'>;
+                 *   totalProceedsReceived: Amount<'nat'>;
+                 *   totalShortfallReceived: Amount<'nat'>;
+                 *   vaultCounter: number;
+                 *   lockedQuote: PriceQuote | undefined;
+                 * }} MutableState
+                 */
+                /**
+                 * @type {(brand: Brand) => {
+                 *   prioritizedVaults: ReturnType<typeof makePrioritizedVaults>;
+                 *   storedQuotesNotifier: import('@agoric/notifier').StoredNotifier<PriceQuote>;
+                 *   storedCollateralQuote: PriceQuote;
+                 * }}
+                 */
                 AdjustBalances(): Promise<Invitation<R, A>>;
                 CloseVault(): Promise<Invitation<R, A>>;
                 TransferVault(): Promise<Invitation<R, A>>;
@@ -416,9 +792,7 @@ export function prepareVaultManagerKit(baggage: MapStore<string, unknown>, { zcf
             };
         };
         lockOraclePrices(): PriceQuote;
-        /**
-         * @param {ERef<AuctioneerPublicFacet>} auctionPF
-         */
+        /** @param {ERef<AuctioneerPublicFacet>} auctionPF */
         liquidateVaults(auctionPF: ERef<AuctioneerPublicFacet>): Promise<void>;
     };
 }>>;
@@ -433,8 +807,9 @@ export type NormalizedDebt = import('./storeUtils.js').NormalizedDebt;
 export type RelativeTime = import('@agoric/time/src/types').RelativeTime;
 export type MetricsNotification = {
     /**
-     * priceQuote that will be used for liquidation.
-     * Non-null from priceLock time until liquidation has taken place.
+     * priceQuote that will be used for
+     * liquidation. Non-null from priceLock time until liquidation has taken
+     * place.
      */
     lockedQuote: Ratio | null;
     /**
@@ -446,7 +821,8 @@ export type MetricsNotification = {
      */
     numLiquidatingVaults: number;
     /**
-     * present sum of collateral across all vaults
+     * present sum of collateral across
+     * all vaults
      */
     totalCollateral: Amount<'nat'>;
     /**
@@ -454,40 +830,49 @@ export type MetricsNotification = {
      */
     totalDebt: Amount<'nat'>;
     /**
-     * collateral held as a result of not returning excess refunds
-     *  to owners of vaults liquidated with shortfalls
+     * collateral held as a result of
+     * not returning excess refunds to owners of vaults liquidated with
+     * shortfalls
      */
     retainedCollateral: Amount<'nat'>;
     /**
-     * present sum of collateral in vaults sent for liquidation
+     * present sum of collateral in
+     * vaults sent for liquidation
      */
     liquidatingCollateral: Amount<'nat'>;
     /**
-     * present sum of debt in vaults sent for liquidation
+     * present sum of debt in vaults sent
+     * for liquidation
      */
     liquidatingDebt: Amount<'nat'>;
     /**
-     * running sum of collateral sold in liquidation
+     * running sum of collateral sold
+     * in liquidation
      */
     totalCollateralSold: Amount<'nat'>;
     /**
-     * running sum of overages, central received greater than debt
+     * running sum of overages,
+     * central received greater than debt
      */
     totalOverageReceived: Amount<'nat'>;
     /**
-     * running sum of minted received from liquidation
+     * running sum of minted
+     * received from liquidation
      */
     totalProceedsReceived: Amount<'nat'>;
     /**
-     * running sum of shortfalls, minted received less than debt
+     * running sum of shortfalls,
+     * minted received less than debt
      */
     totalShortfallReceived: Amount<'nat'>;
     /**
-     * running count of liquidated vaults
+     * running count of liquidated
+     * vaults
      */
     numLiquidationsCompleted: number;
     /**
-     * running count of vault liquidations that were reverted.
+     * running count of vault liquidations
+     * that were reverted.
      */
     numLiquidationsAborted: number;
 };
@@ -542,10 +927,11 @@ export type MutableState = {
 };
 export type VaultManagerKit = Awaited<ReturnType<ReturnType<typeof prepareVaultManagerKit>>>;
 /**
- * Each VaultManager manages a single collateral type.
+ * Each VaultManager manages a
+ *   single collateral type.
  *
- * It manages some number of outstanding debt positions, each called a Vault,
- * for which the collateral is provided in exchange for borrowed Minted.
+ *   It manages some number of outstanding debt positions, each called a Vault,
+ *   for which the collateral is provided in exchange for borrowed Minted.
  */
 export type VaultManager = VaultManagerKit['self'];
 export type CollateralManager = VaultManagerKit['collateral'];