@agoric/inter-protocol 0.16.1 → 0.16.2-dev-8c14632.0

package/src/vaultFactory/storeUtils.js

@@ -131,15 +131,15 @@ harden(fromVaultKey);
  * For use by `normalizedCollRatioKey` and tests.
  *
  * @param {PriceQuote} quote
- * @param {Ratio} compoundedInterest
+ * @param {Ratio} compoundedStabilityFee
  * @param {Ratio} margin
  * @returns {number}
  */
-export const normalizedCollRatio = (quote, compoundedInterest, margin) => {
+export const normalizedCollRatio = (quote, compoundedStabilityFee, margin) => {
   const amountIn = getAmountIn(quote).value;
   const amountOut = getAmountOut(quote).value;
-  const interestNumerator = compoundedInterest.numerator.value;
-  const interestBase = compoundedInterest.denominator.value;
+  const interestNumerator = compoundedStabilityFee.numerator.value;
+  const interestBase = compoundedStabilityFee.denominator.value;
   const numerator = multiply(
     margin.numerator.value,
     multiply(amountIn, interestNumerator),
@@ -159,13 +159,17 @@ harden(normalizedCollRatio);
  * out the numerator and the denominator, and divide only once.
  *
  * @param {PriceQuote} quote
- * @param {Ratio} compoundedInterest
+ * @param {Ratio} compoundedStabilityFee
  * @param {Ratio} margin
  * @returns {string} lexically sortable string in which highest
  * debt-to-collateral is earliest
  */
-export const normalizedCollRatioKey = (quote, compoundedInterest, margin) => {
-  const collRatio = normalizedCollRatio(quote, compoundedInterest, margin);
+export const normalizedCollRatioKey = (
+  quote,
+  compoundedStabilityFee,
+  margin,
+) => {
+  const collRatio = normalizedCollRatio(quote, compoundedStabilityFee, margin);
   return `${encodeNumber(collRatio)}:`;
 };
 harden(normalizedCollRatioKey);

package/src/vaultFactory/types.js

@@ -26,7 +26,7 @@
  * @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} stabilityFee - 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
@@ -78,7 +78,7 @@
  * @property {() => Ratio} getLiquidationMargin
  * @property {() => Ratio} getMintFee
  * @property {() => Promise<PriceQuote>} getCollateralQuote
- * @property {() => Ratio} getInterestRate - The annual interest rate on a debt position
+ * @property {() => Ratio} getStabilityFee - 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)
@@ -109,8 +109,8 @@
 
 /**
  * @typedef {object} DebtStatus
- * @property {Timestamp} latestInterestUpdate
- * @property {NatValue} interest interest accrued since latestInterestUpdate
+ * @property {Timestamp} latestStabilityFeeUpdate
+ * @property {NatValue} interest interest accrued since latestStabilityFeeUpdate
  * @property {NatValue} newDebt total including principal and interest
  */
 

package/src/vaultFactory/vault.js

@@ -72,7 +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'>, stabilityFee: Ratio}} debtSnapshot 'debt' at the point the compounded stabilityFee was 'stabilityFee'
  * @property {HolderPhase} vaultState
  */
 
@@ -86,7 +86,7 @@ const validTransitions = {
  * @property {() => Brand<'nat'>} getDebtBrand
  * @property {MintAndTransfer} mintAndTransfer
  * @property {(amount: Amount, seat: ZCFSeat) => void} burn
- * @property {() => Ratio} getCompoundedInterest
+ * @property {() => Ratio} getCompoundedStabilityFee
  * @property {(oldDebt: import('./storeUtils.js').NormalizedDebt, oldCollateral: Amount<'nat'>, vaultId: VaultId, vaultPhase: VaultPhase, vault: Vault) => void} handleBalanceChange
  * @property {() => import('./vaultManager.js').GovernedParamGetters} getGovernedParams
  */
@@ -104,7 +104,7 @@ const validTransitions = {
  * Snapshot is of the debt and compounded interest when the principal was last changed.
  *
  * @typedef {{
- *   interestSnapshot: Ratio,
+ *   stabilityFeeSnapshot: Ratio,
  *   phase: VaultPhase,
  *   debtSnapshot: Amount<'nat'>,
  *   outerUpdater: import('@agoric/zoe/src/contractSupport/recorder.js').Recorder<VaultNotification> | null,
@@ -132,7 +132,7 @@ const VaultStateShape = harden({
   phase: M.any(),
   storageNode: M.any(),
   vaultSeat: M.any(),
-  interestSnapshot: M.any(),
+  stabilityFeeSnapshot: M.any(),
   debtSnapshot: M.any(),
 });
 
@@ -174,7 +174,7 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
         vaultSeat: zcf.makeEmptySeatKit().zcfSeat,
 
         // Two values from the same moment
-        interestSnapshot: manager.getCompoundedInterest(),
+        stabilityFeeSnapshot: manager.getCompoundedStabilityFee(),
         debtSnapshot: AmountMath.makeEmpty(manager.getDebtBrand()),
       });
     },
@@ -257,7 +257,8 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
 
           // update local state
           state.debtSnapshot = newDebt;
-          state.interestSnapshot = state.manager.getCompoundedInterest();
+          state.stabilityFeeSnapshot =
+            state.manager.getCompoundedStabilityFee();
         },
 
         /**
@@ -327,10 +328,11 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
         getStateSnapshot(newPhase) {
           const { state, facets } = this;
 
-          const { debtSnapshot: debt, interestSnapshot: interest } = state;
+          const { debtSnapshot: debt, stabilityFeeSnapshot: stabilityFee } =
+            state;
           /** @type {VaultNotification} */
           return harden({
-            debtSnapshot: { debt, interest },
+            debtSnapshot: { debt, stabilityFee },
             locked: facets.self.getCollateralAmount(),
             // newPhase param is so that makeTransferInvitation can finish without setting the vault's phase
             // TODO refactor https://github.com/Agoric/agoric-sdk/issues/4415
@@ -785,7 +787,7 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
           helper.updateDebtSnapshot(self.getCurrentDebt());
           const {
             debtSnapshot: debt,
-            interestSnapshot: interest,
+            stabilityFeeSnapshot: stabilityFee,
             phase,
           } = state;
           if (outerUpdater) {
@@ -795,7 +797,7 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
             state.outerUpdater = null;
           }
           const transferState = {
-            debtSnapshot: { debt, interest },
+            debtSnapshot: { debt, stabilityFee },
             locked: self.getCollateralAmount(),
             vaultState: phase,
           };
@@ -839,8 +841,8 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
           const { state } = this;
           return calculateCurrentDebt(
             state.debtSnapshot,
-            state.interestSnapshot,
-            state.manager.getCompoundedInterest(),
+            state.stabilityFeeSnapshot,
+            state.manager.getCompoundedStabilityFee(),
           );
         },
 
@@ -857,7 +859,10 @@ export const prepareVault = (baggage, makeRecorderKit, zcf) => {
         getNormalizedDebt() {
           const { state } = this;
           // @ts-expect-error cast
-          return reverseInterest(state.debtSnapshot, state.interestSnapshot);
+          return reverseInterest(
+            state.debtSnapshot,
+            state.stabilityFeeSnapshot,
+          );
         },
       },
     },

package/src/vaultFactory/vaultDirector.js

@@ -250,6 +250,7 @@ const prepareVaultDirector = (
     metrics: makeRecorderTopic('Vault Factory metrics', metricsKit),
   });
 
+  /** @param {(vm: VaultManager) => void} fn */
   const allManagersDo = fn => {
     for (const managerIndex of collateralManagers.values()) {
       const vm = vaultManagers.get(managerIndex).self;
@@ -424,6 +425,7 @@ const prepareVaultDirector = (
 
         makeLiquidationWaker() {
           return makeWaker('liquidationWaker', _timestamp => {
+            // XXX floating promise
             allManagersDo(vm => vm.liquidateVaults(auctioneer));
           });
         },

package/src/vaultFactory/vaultManager.js

@@ -95,16 +95,16 @@ const trace = makeTracer('VM');
 
 /**
  * @typedef {{
- *  compoundedInterest: Ratio,
- *  interestRate: Ratio,
- *  latestInterestUpdate: Timestamp,
+ *  compoundedStabilityFee: Ratio,
+ *  stabilityFee: Ratio,
+ *  latestStabilityFeeUpdate: Timestamp,
  * }} AssetState
  *
  * @typedef {{
  *  getChargingPeriod: () => RelativeTime,
  *  getRecordingPeriod: () => RelativeTime,
  *  getDebtLimit: () => Amount<'nat'>,
- *  getInterestRate: () => Ratio,
+ *  getStabilityFee: () => Ratio,
  *  getLiquidationPadding: () => Ratio,
  *  getLiquidationMargin: () => Ratio,
  *  getLiquidationPenalty: () => Ratio,
@@ -138,8 +138,8 @@ const trace = makeTracer('VM');
 
 /**
  * @typedef {{
- *   compoundedInterest: Ratio,
- *   latestInterestUpdate: Timestamp,
+ *   compoundedStabilityFee: Ratio,
+ *   latestStabilityFeeUpdate: Timestamp,
  *   numLiquidationsCompleted: number,
  *   numLiquidationsAborted: number,
  *   totalCollateral: Amount<'nat'>,
@@ -230,8 +230,8 @@ export const prepareVaultManagerKit = (
     return harden({
       ...params,
       ...immutable,
-      compoundedInterest: makeRatio(100n, debtBrand), // starts at 1.0, no interest
-      latestInterestUpdate: startTimeStamp,
+      compoundedStabilityFee: makeRatio(100n, debtBrand), // starts at 1.0, no interest
+      latestStabilityFeeUpdate: startTimeStamp,
       numLiquidationsCompleted: 0,
       numLiquidationsAborted: 0,
       totalCollateral: zeroCollateral,
@@ -255,7 +255,7 @@ export const prepareVaultManagerKit = (
         makeVaultInvitation: M.call().returns(M.promise()),
         getPublicTopics: M.call().returns(TopicsRecordShape),
         getQuotes: M.call().returns(NotifierShape),
-        getCompoundedInterest: M.call().returns(RatioShape),
+        getCompoundedStabilityFee: M.call().returns(RatioShape),
       }),
       helper: M.interface(
         'helper',
@@ -276,7 +276,7 @@ export const prepareVaultManagerKit = (
         getAssetSubscriber: M.call().returns(SubscriberShape),
         getCollateralBrand: M.call().returns(BrandShape),
         getDebtBrand: M.call().returns(BrandShape),
-        getCompoundedInterest: M.call().returns(RatioShape),
+        getCompoundedStabilityFee: M.call().returns(RatioShape),
         scopeDescription: M.call(M.string()).returns(M.string()),
         handleBalanceChange: M.call(
           AmountShape,
@@ -319,8 +319,8 @@ export const prepareVaultManagerKit = (
           const ephemera = collateralEphemera(this.state.collateralBrand);
           return ephemera.storedQuotesNotifier;
         },
-        getCompoundedInterest() {
-          return this.state.compoundedInterest;
+        getCompoundedStabilityFee() {
+          return this.state.compoundedStabilityFee;
         },
         getPublicTopics() {
           const { assetTopicKit, metricsTopicKit } = this.state;
@@ -400,7 +400,7 @@ export const prepareVaultManagerKit = (
           // throw. See https://github.com/Agoric/agoric-sdk/issues/4317
           void observeNotifier(quoteNotifier, {
             updateState(value) {
-              trace('vaultManager got new collateral quote', value);
+              trace('storing new quote', value.quoteAmount.value);
               ephemera.storedCollateralQuote = value;
             },
             fail(reason) {
@@ -419,9 +419,9 @@ export const prepareVaultManagerKit = (
             updateTime,
           });
 
-          const interestRate = factoryPowers
+          const stabilityFee = factoryPowers
             .getGovernedParams(collateralBrand)
-            .getInterestRate();
+            .getStabilityFee();
 
           // Update state with the results of charging interest
 
@@ -433,7 +433,7 @@ export const prepareVaultManagerKit = (
               seatAllocationKeyword: 'Minted',
             },
             {
-              interestRate,
+              stabilityFee,
               chargingPeriod: factoryPowers
                 .getGovernedParams(collateralBrand)
                 .getChargingPeriod(),
@@ -442,15 +442,15 @@ export const prepareVaultManagerKit = (
                 .getRecordingPeriod(),
             },
             {
-              latestInterestUpdate: state.latestInterestUpdate,
-              compoundedInterest: state.compoundedInterest,
+              latestStabilityFeeUpdate: state.latestStabilityFeeUpdate,
+              compoundedStabilityFee: state.compoundedStabilityFee,
               totalDebt: state.totalDebt,
             },
             updateTime,
           );
 
-          state.compoundedInterest = changes.compoundedInterest;
-          state.latestInterestUpdate = changes.latestInterestUpdate;
+          state.compoundedStabilityFee = changes.compoundedStabilityFee;
+          state.latestStabilityFeeUpdate = changes.latestStabilityFeeUpdate;
           state.totalDebt = changes.totalDebt;
 
           return facets.helper.assetNotify();
@@ -458,14 +458,14 @@ export const prepareVaultManagerKit = (
         assetNotify() {
           const { state } = this;
           const { collateralBrand, assetTopicKit } = state;
-          const interestRate = factoryPowers
+          const stabilityFee = factoryPowers
             .getGovernedParams(collateralBrand)
-            .getInterestRate();
+            .getStabilityFee();
           /** @type {AssetState} */
           const payload = harden({
-            compoundedInterest: state.compoundedInterest,
-            interestRate,
-            latestInterestUpdate: state.latestInterestUpdate,
+            compoundedStabilityFee: state.compoundedStabilityFee,
+            stabilityFee,
+            latestStabilityFeeUpdate: state.latestStabilityFeeUpdate,
           });
           return assetTopicKit.recorder.write(payload);
         },
@@ -843,8 +843,8 @@ export const prepareVaultManagerKit = (
         /**
          * coefficient on existing debt to calculate new debt
          */
-        getCompoundedInterest() {
-          return this.state.compoundedInterest;
+        getCompoundedStabilityFee() {
+          return this.state.compoundedStabilityFee;
         },
         /**
          * Called by a vault when its balances change.
@@ -963,7 +963,6 @@ export const prepareVaultManagerKit = (
 
           try {
             // TODO `await` is allowed until the above ordering is fixed
-            // eslint-disable-next-line @jessie.js/no-nested-await
             const vaultKit = await vault.initVaultKit(seat, vaultStorageNode);
             // initVaultKit calls back to handleBalanceChange() which will add the
             // vault to prioritizedVaults
@@ -1037,7 +1036,7 @@ export const prepareVaultManagerKit = (
           if (!storedCollateralQuote)
             throw Fail`lockOraclePrices called before a collateral quote was available`;
           trace(
-            `lockPrice`,
+            `lockOraclePrices`,
             getAmountIn(storedCollateralQuote),
             getAmountOut(storedCollateralQuote),
           );
@@ -1047,25 +1046,33 @@ export const prepareVaultManagerKit = (
           return storedCollateralQuote;
         },
         /**
-         * @param {AuctioneerPublicFacet} auctionPF
+         * @param {ERef<AuctioneerPublicFacet>} auctionPF
          */
         async liquidateVaults(auctionPF) {
           const { state, facets } = this;
           const { self, helper } = facets;
           const {
             collateralBrand,
-            compoundedInterest,
+            compoundedStabilityFee,
             debtBrand,
             liquidatingVaults,
             lockedQuote,
           } = state;
           trace(collateralBrand, 'considering liquidation');
 
+          if (!lockedQuote) {
+            // By design, the first cycle of auction may call this before a quote is locked
+            // because the schedule is global at the vaultDirector level, and if a manager
+            // starts after the price lock time there's nothing to be done.
+            // NB: this message should not log repeatedly.
+            console.error(
+              'Skipping liquidation because no quote is locked yet (may happen with new manager)',
+            );
+            return;
+          }
+
           const { prioritizedVaults } = collateralEphemera(collateralBrand);
-          assert(factoryPowers && prioritizedVaults && zcf);
-          lockedQuote ||
-            Fail`Must have locked a quote before liquidating vaults.`;
-          assert(lockedQuote); // redundant with previous line
+          prioritizedVaults || Fail`prioritizedVaults missing from ephemera`;
 
           const liqMargin = self.getGovernedParams().getLiquidationMargin();
 
@@ -1075,7 +1082,7 @@ export const prepareVaultManagerKit = (
               zcf,
               {
                 quote: lockedQuote,
-                interest: compoundedInterest,
+                interest: compoundedStabilityFee,
                 margin: liqMargin,
               },
               prioritizedVaults,
@@ -1160,11 +1167,11 @@ export const prepareVaultManagerKit = (
         helper.start();
         void state.assetTopicKit.recorder.write(
           harden({
-            compoundedInterest: state.compoundedInterest,
-            interestRate: factoryPowers
+            compoundedStabilityFee: state.compoundedStabilityFee,
+            stabilityFee: factoryPowers
               .getGovernedParams(state.collateralBrand)
-              .getInterestRate(),
-            latestInterestUpdate: state.latestInterestUpdate,
+              .getStabilityFee(),
+            latestStabilityFeeUpdate: state.latestStabilityFeeUpdate,
           }),
         );