@agoric/inter-protocol 0.16.2-other-dev-8f8782b.0 → 0.16.2-other-dev-fbe72e7.0.fbe72e7

package/src/vaultFactory/vault.js

@@ -1,5 +1,7 @@
+import { q, Fail } from '@endo/errors';
 import { AmountMath, AmountShape } from '@agoric/ertp';
-import { makeTracer, StorageNodeShape } from '@agoric/internal';
+import { StorageNodeShape, makeTracer } from '@agoric/internal';
+import { UnguardedHelperI } from '@agoric/internal/src/typeGuards.js';
 import { M, prepareExoClassKit } from '@agoric/vat-data';
 import { atomicTransfer } from '@agoric/zoe/src/contractSupport/index.js';
 import { SeatShape } from '@agoric/zoe/src/typeGuards.js';
@@ -9,44 +11,50 @@ import {
   makeNatAmountShape,
 } from '../contractSupport.js';
 import { calculateCurrentDebt, reverseInterest } from '../interest-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;
+import { prepareVaultKit } from './vaultKit.js';
 
 const trace = makeTracer('Vault', true);
 
-/** @typedef {import('./storeUtils.js').NormalizedDebt} NormalizedDebt */
+/**
+ * @import {EReturn} from '@endo/far';
+ * @import {Brand} from '@agoric/ertp/src/types.js';
+ * @import {NormalizedDebt} from './storeUtils.js';
+ */
 
 /**
- * @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:
  *
- * 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`
+ *   - `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
+ *
+ * @enum {(typeof Phase)[keyof typeof Phase]}
  */
 export const Phase = /** @type {const} */ ({
   ACTIVE: 'active',
@@ -55,10 +63,11 @@ export const Phase = /** @type {const} */ ({
   LIQUIDATED: 'liquidated',
   TRANSFER: 'transfer',
 });
+harden(Phase);
 
 /**
- * @typedef {Phase[keyof Omit<typeof Phase, 'TRANSFER'>]} VaultPhase
- * @type {{[K in VaultPhase]: Array<VaultPhase>}}
+ * @typedef {Exclude<Phase, 'transfer'>} VaultPhase
+ * @type {{ [K in VaultPhase]: VaultPhase[] }}
  */
 const validTransitions = {
   [Phase.ACTIVE]: [Phase.LIQUIDATING, Phase.CLOSED],
@@ -68,46 +77,54 @@ const validTransitions = {
 };
 
 /**
- * @typedef {Phase[keyof typeof Phase]} HolderPhase
- *
  * @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 {HolderPhase} vaultState
+ * @property {{ debt: Amount<'nat'>; interest: Ratio }} debtSnapshot 'debt' at
+ *   the point the compounded interest was 'interest'
+ * @property {Phase} vaultState
  */
 
 // XXX masks typedef from types.js, but using that causes circular def problems
 /**
  * @typedef {object} VaultManager
- * @property {() => Subscriber<import('./vaultManager').AssetState>} getAssetSubscriber
+ * @property {() => Subscriber<import('./vaultManager.js').AssetState>} getAssetSubscriber
  * @property {(collateralAmount: Amount) => Amount<'nat'>} maxDebtFor
- * @property {() => Brand} getCollateralBrand
+ * @property {() => Brand<'nat'>} getCollateralBrand
  * @property {(base: string) => string} scopeDescription
  * @property {() => Brand<'nat'>} getDebtBrand
  * @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
  */
 
@@ -137,7 +154,7 @@ const VaultStateShape = harden({
 });
 
 /**
- * @param {import('@agoric/ertp').Baggage} baggage
+ * @param {import('@agoric/swingset-liveslots').Baggage} baggage
  * @param {import('@agoric/zoe/src/contractSupport/recorder.js').MakeRecorderKit} makeRecorderKit
  * @param {ZCF} zcf
  */
@@ -195,7 +212,10 @@ 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
@@ -220,9 +240,7 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
         //#endregion
 
         //#region Phase logic
-        /**
-         * @param {VaultPhase} newPhase
-         */
+        /** @param {VaultPhase} newPhase */
         assignPhase(newPhase) {
           const { state } = this;
 
@@ -261,12 +279,14 @@ 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;
@@ -283,8 +303,8 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
         },
 
         /**
-         *
          * @param {ZCFSeat} seat
+         * @returns {Amount<'nat'>}
          */
         getCollateralAllocated(seat) {
           return seat.getAmountAllocated(
@@ -292,6 +312,10 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
             this.facets.helper.collateralBrand(),
           );
         },
+        /**
+         * @param {ZCFSeat} seat
+         * @returns {Amount<'nat'>}
+         */
         getMintedAllocated(seat) {
           return seat.getAmountAllocated(
             'Minted',
@@ -307,7 +331,6 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
         },
 
         /**
-         *
          * @param {Amount<'nat'>} collateralAmount
          * @param {Amount<'nat'>} proposedDebt
          */
@@ -320,10 +343,7 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
             )} for ${q(collateralAmount)} collateral`;
         },
 
-        /**
-         *
-         * @param {HolderPhase} newPhase
-         */
+        /** @param {Phase} newPhase */
         getStateSnapshot(newPhase) {
           const { state, facets } = this;
 
@@ -338,9 +358,7 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
           });
         },
 
-        /**
-         * call this whenever anything changes!
-         */
+        /** call this whenever anything changes! */
         updateUiState() {
           const { state, facets } = this;
           const { outerUpdater } = state;
@@ -368,9 +386,7 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
           }
         },
 
-        /**
-         * @param {ZCFSeat} seat
-         */
+        /** @param {ZCFSeat} seat */
         async closeHook(seat) {
           const { state, facets } = this;
 
@@ -440,11 +456,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
@@ -522,7 +538,6 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
         },
 
         /**
-         *
          * @param {ZCFSeat} clientSeat
          * @param {FullProposal} fp
          * @param {ReturnType<typeof calculateDebtCosts>} costs
@@ -543,7 +558,7 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
 
           const giveMintedTaken = AmountMath.subtract(fp.give.Minted, surplus);
 
-          /** @type {import('@agoric/zoe/src/contractSupport/atomicTransfer.js').TransferPart[]} */
+          /** @type {TransferPart[]} */
           const transfers = harden([
             [clientSeat, vaultSeat, { Collateral: fp.give.Collateral }],
             [vaultSeat, clientSeat, { Collateral: fp.want.Collateral }],
@@ -568,7 +583,6 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
         },
 
         /**
-         *
          * @param {ZCFSeat} seat
          * @returns {VaultKit}
          */
@@ -579,7 +593,6 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
           helper.assertCloseable();
           seat.exit();
 
-          // eslint-disable-next-line no-use-before-define
           const vaultKit = makeVaultKit(self, state.storageNode);
           state.outerUpdater = vaultKit.vaultUpdater;
           helper.updateUiState();
@@ -669,9 +682,7 @@ 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;
 
@@ -681,8 +692,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;
@@ -774,9 +785,7 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
           );
         },
 
-        /**
-         * @returns {Promise<Invitation>}
-         */
+        /** @returns {Promise<Invitation<VaultKit>>} */
         makeTransferInvitation() {
           const { state, facets } = this;
           const { outerUpdater } = state;
@@ -808,10 +817,7 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
 
         // for status/debugging
 
-        /**
-         *
-         * @returns {Amount<'nat'>}
-         */
+        /** @returns {Amount<'nat'>} */
         getCollateralAmount() {
           const { state, facets } = this;
           const { vaultSeat } = state;
@@ -825,15 +831,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.
-         *
-         * @see getNormalizedDebt
+         * 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
          */
         getCurrentDebt() {
           const { state } = this;
@@ -845,14 +851,15 @@ 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;
@@ -868,4 +875,4 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
   return maker;
 };
 
-/** @typedef {ReturnType<ReturnType<typeof prepareVault>>['self']} Vault */
+/** @typedef {EReturn<EReturn<typeof prepareVault>>['self']} Vault */