@agoric/inter-protocol 0.13.2-dev-c693f8d.0 → 0.13.2-dev-d5b2b97.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/inter-protocol",
-  "version": "0.13.2-dev-c693f8d.0+c693f8d",
+  "version": "0.13.2-dev-d5b2b97.0+d5b2b97",
   "description": "Core cryptoeconomy contracts",
   "type": "module",
   "main": "src/index.js",
@@ -29,18 +29,18 @@
   },
   "homepage": "https://github.com/Agoric/agoric-sdk#readme",
   "dependencies": {
-    "@agoric/assert": "0.5.2-dev-c693f8d.0+c693f8d",
-    "@agoric/ertp": "0.15.4-dev-c693f8d.0+c693f8d",
-    "@agoric/governance": "0.9.2-dev-c693f8d.0+c693f8d",
-    "@agoric/internal": "0.2.2-dev-c693f8d.0+c693f8d",
-    "@agoric/notifier": "0.5.2-dev-c693f8d.0+c693f8d",
-    "@agoric/store": "0.8.4-dev-c693f8d.0+c693f8d",
-    "@agoric/swingset-liveslots": "0.9.1-dev-c693f8d.0+c693f8d",
-    "@agoric/swingset-vat": "0.30.3-dev-c693f8d.0+c693f8d",
-    "@agoric/time": "0.2.2-dev-c693f8d.0+c693f8d",
-    "@agoric/vat-data": "0.4.4-dev-c693f8d.0+c693f8d",
-    "@agoric/vats": "0.13.1-dev-c693f8d.0+c693f8d",
-    "@agoric/zoe": "0.25.4-dev-c693f8d.0+c693f8d",
+    "@agoric/assert": "0.5.2-dev-d5b2b97.0+d5b2b97",
+    "@agoric/ertp": "0.15.4-dev-d5b2b97.0+d5b2b97",
+    "@agoric/governance": "0.9.2-dev-d5b2b97.0+d5b2b97",
+    "@agoric/internal": "0.2.2-dev-d5b2b97.0+d5b2b97",
+    "@agoric/notifier": "0.5.2-dev-d5b2b97.0+d5b2b97",
+    "@agoric/store": "0.8.4-dev-d5b2b97.0+d5b2b97",
+    "@agoric/swingset-liveslots": "0.9.1-dev-d5b2b97.0+d5b2b97",
+    "@agoric/swingset-vat": "0.30.3-dev-d5b2b97.0+d5b2b97",
+    "@agoric/time": "0.2.2-dev-d5b2b97.0+d5b2b97",
+    "@agoric/vat-data": "0.4.4-dev-d5b2b97.0+d5b2b97",
+    "@agoric/vats": "0.13.1-dev-d5b2b97.0+d5b2b97",
+    "@agoric/zoe": "0.25.4-dev-d5b2b97.0+d5b2b97",
     "@endo/bundle-source": "^2.4.2",
     "@endo/captp": "^2.0.18",
     "@endo/eventual-send": "^0.16.8",
@@ -50,8 +50,8 @@
     "@endo/promise-kit": "^0.2.52"
   },
   "devDependencies": {
-    "@agoric/deploy-script-support": "0.9.5-dev-c693f8d.0+c693f8d",
-    "@agoric/smart-wallet": "0.4.3-dev-c693f8d.0+c693f8d",
+    "@agoric/deploy-script-support": "0.9.5-dev-d5b2b97.0+d5b2b97",
+    "@agoric/smart-wallet": "0.4.3-dev-d5b2b97.0+d5b2b97",
     "@endo/init": "^0.5.52",
     "@fast-check/ava": "^1.1.3",
     "ava": "^5.1.0",
@@ -78,5 +78,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "c693f8d40e265277a711667b273c647adffb2191"
+  "gitHead": "d5b2b97c7023aec5ec5bbf4b58eada61b28cbd2d"
 }

package/src/proposals/demoIssuers.js

@@ -102,6 +102,7 @@ const defaultConfig = /** @type {const} */ ({
  *     liquidationPenalty: Rational,
  *     interestRate: Rational,
  *     loanFee: Rational,
+ *     liquidationPadding?: Rational,
  *   },
  *   trades: Array<{ central: number, collateral: bigint}>
  * }>}
@@ -448,6 +449,10 @@ export const poolRates = (issuerName, record, kits, central) => {
     liquidationPenalty: toRatio(config.liquidationPenalty, central.brand),
     interestRate: toRatio(config.interestRate, central.brand),
     loanFee: toRatio(config.loanFee, central.brand),
+    // XXX not relevant to AMM pools but poolRates is also used for addVaultType
+    liquidationPadding:
+      config.liquidationPadding &&
+      toRatio(config.liquidationPadding, central.brand),
   };
   return { rates, initialValue: inCollateral(config.collateralValue) };
 };

package/src/vaultFactory/math.js

@@ -0,0 +1,70 @@
+/**
+ * @file calculations specific to the Vault Factory contract
+ * See also ../interest-math.js
+ */
+
+import { AmountMath } from '@agoric/ertp';
+import { getAmountOut } from '@agoric/zoe/src/contractSupport/priceQuote.js';
+import {
+  addRatios,
+  ceilMultiplyBy,
+  floorDivideBy,
+} from '@agoric/zoe/src/contractSupport/ratio.js';
+import { addSubtract } from '../contractSupport.js';
+
+/**
+ * Calculate the minimum collateralization given the liquidation margin and the "padding"
+ * from that liquidation threshold.
+ *
+ * @param {Ratio} liquidationMargin
+ * @param {Ratio} liquidationPadding
+ * @returns {Ratio}
+ */
+export const calculateMinimumCollateralization = (
+  liquidationMargin,
+  liquidationPadding,
+) => addRatios(liquidationMargin, liquidationPadding);
+
+/**
+ * Calculate the maximum debt allowed based on the price quote and the lesser of
+ * the `liquidationMargin` or the `liquidationPadding`.
+ *
+ * @param {PriceQuote} quoteAmount
+ * @param {Ratio} liquidationMargin
+ * @param {Ratio} liquidationPadding
+ * @returns {Amount<'nat'>}
+ */
+export const maxDebtForVault = (
+  quoteAmount,
+  liquidationMargin,
+  liquidationPadding,
+) => {
+  const debtByQuote = getAmountOut(quoteAmount);
+  const minimumCollateralization = calculateMinimumCollateralization(
+    liquidationMargin,
+    liquidationPadding,
+  );
+  // floorDivide because we want the debt ceiling lower
+  return floorDivideBy(debtByQuote, minimumCollateralization);
+};
+
+/**
+ * Calculate the fee, the amount to mint and the resulting debt.
+ * The give and the want together reflect a delta, where typically
+ * one is zero because they come from the gave/want of an offer
+ * proposal. If the `want` is zero, the `fee` will also be zero,
+ * so the simple math works.
+ *
+ * @param {Amount<'nat'>} currentDebt
+ * @param {Amount<'nat'>} give excess of currentDebt is returned in 'surplus'
+ * @param {Amount<'nat'>} want
+ * @param {Ratio} loanFee
+ */
+export const calculateLoanCosts = (currentDebt, give, want, loanFee) => {
+  const maxGive = AmountMath.min(currentDebt, give);
+  const surplus = AmountMath.subtract(give, maxGive);
+  const fee = ceilMultiplyBy(want, loanFee);
+  const toMint = AmountMath.add(want, fee);
+  const newDebt = addSubtract(currentDebt, toMint, maxGive);
+  return { newDebt, toMint, fee, surplus };
+};

package/src/vaultFactory/params.js

@@ -2,13 +2,14 @@ import './types.js';
 
 import {
   CONTRACT_ELECTORATE,
-  makeParamManagerSync,
   makeParamManager,
+  makeParamManagerSync,
   ParamTypes,
 } from '@agoric/governance';
 import { makeStoredPublisherKit } from '@agoric/notifier';
 import { M } from '@agoric/store';
 import { TimeMath } from '@agoric/time';
+import { subtractRatios } from '@agoric/zoe/src/contractSupport/ratio.js';
 import { amountPattern, ratioPattern } from '../contractSupport.js';
 
 export const CHARGING_PERIOD_KEY = 'ChargingPeriod';
@@ -16,6 +17,7 @@ export const RECORDING_PERIOD_KEY = 'RecordingPeriod';
 
 export const DEBT_LIMIT_KEY = 'DebtLimit';
 export const LIQUIDATION_MARGIN_KEY = 'LiquidationMargin';
+export const LIQUIDATION_PADDING_KEY = 'LiquidationPadding';
 export const LIQUIDATION_PENALTY_KEY = 'LiquidationPenalty';
 export const INTEREST_RATE_KEY = 'InterestRate';
 export const LOAN_FEE_KEY = 'LoanFee';
@@ -69,27 +71,48 @@ harden(makeVaultDirectorParams);
 
 /** @typedef {import('@agoric/governance/src/contractGovernance/typedParamManager').ParamTypesMapFromRecord<ReturnType<typeof makeVaultDirectorParams>>} VaultDirectorParams */
 
+/** @type {(liquidationMargin: Ratio) => Ratio} */
+const zeroRatio = liquidationMargin =>
+  subtractRatios(liquidationMargin, liquidationMargin);
+
 /**
  * @param {import('@agoric/notifier').StoredPublisherKit<GovernanceSubscriptionState>} publisherKit
  * @param {VaultManagerParamValues} initial
  */
-export const makeVaultParamManager = (publisherKit, initial) =>
+export const makeVaultParamManager = (
+  publisherKit,
+  {
+    debtLimit,
+    interestRate,
+    liquidationMargin,
+    liquidationPadding = zeroRatio(liquidationMargin),
+    liquidationPenalty,
+    loanFee,
+  },
+) =>
   makeParamManagerSync(publisherKit, {
-    [DEBT_LIMIT_KEY]: [ParamTypes.AMOUNT, initial.debtLimit],
-    [LIQUIDATION_MARGIN_KEY]: [ParamTypes.RATIO, initial.liquidationMargin],
-    [LIQUIDATION_PENALTY_KEY]: [ParamTypes.RATIO, initial.liquidationPenalty],
-    [INTEREST_RATE_KEY]: [ParamTypes.RATIO, initial.interestRate],
-    [LOAN_FEE_KEY]: [ParamTypes.RATIO, initial.loanFee],
+    [DEBT_LIMIT_KEY]: [ParamTypes.AMOUNT, debtLimit],
+    [INTEREST_RATE_KEY]: [ParamTypes.RATIO, interestRate],
+    [LIQUIDATION_PADDING_KEY]: [ParamTypes.RATIO, liquidationPadding],
+    [LIQUIDATION_MARGIN_KEY]: [ParamTypes.RATIO, liquidationMargin],
+    [LIQUIDATION_PENALTY_KEY]: [ParamTypes.RATIO, liquidationPenalty],
+    [LOAN_FEE_KEY]: [ParamTypes.RATIO, loanFee],
   });
 /** @typedef {ReturnType<typeof makeVaultParamManager>} VaultParamManager */
 
-export const vaultParamPattern = M.splitRecord({
-  liquidationMargin: ratioPattern,
-  liquidationPenalty: ratioPattern,
-  interestRate: ratioPattern,
-  loanFee: ratioPattern,
-  debtLimit: amountPattern,
-});
+export const vaultParamPattern = M.splitRecord(
+  {
+    liquidationMargin: ratioPattern,
+    liquidationPenalty: ratioPattern,
+    interestRate: ratioPattern,
+    loanFee: ratioPattern,
+    debtLimit: amountPattern,
+  },
+  {
+    // optional for backwards compatibility, e.g. with loadgen
+    liquidationPadding: ratioPattern,
+  },
+);
 
 /**
  * @param {import('@agoric/notifier').StoredPublisherKit<GovernanceSubscriptionState>} publisherKit

package/src/vaultFactory/types.js

@@ -35,6 +35,7 @@
  * @property {Ratio} loanFee - The fee (in BasisPoints) charged when opening
  * or increasing a loan.
  * @property {Amount<'nat'>} debtLimit
+ * @property {Ratio} [liquidationPadding] - vault must maintain this in order to remove collateral or add debt
  */
 
 /**

package/src/vaultFactory/vault.js

@@ -5,7 +5,6 @@ import { M, prepareExoClassKit } from '@agoric/vat-data';
 import {
   assertProposalShape,
   atomicTransfer,
-  ceilMultiplyBy,
   floorMultiplyBy,
   makeRatioFromAmounts,
 } from '@agoric/zoe/src/contractSupport/index.js';
@@ -21,6 +20,7 @@ import { UnguardedHelperI } from '../typeGuards.js';
 import { prepareVaultKit } from './vaultKit.js';
 
 import '@agoric/zoe/exported.js';
+import { calculateLoanCosts } from './math.js';
 
 const { quote: q, Fail } = assert;
 
@@ -126,7 +126,18 @@ const validTransitions = {
  * @param {Amount<'nat'>} newDebt
  * @returns {boolean}
  */
-const checkRestart = (newCollateralPre, maxDebtPre, newCollateral, newDebt) => {
+const allocationsChangedSinceQuote = (
+  newCollateralPre,
+  maxDebtPre,
+  newCollateral,
+  newDebt,
+) => {
+  trace('allocationsChangedSinceQuote', {
+    newCollateralPre,
+    maxDebtPre,
+    newCollateral,
+    newDebt,
+  });
   if (AmountMath.isGTE(newCollateralPre, newCollateral)) {
     // The collateral did not go up. If the collateral decreased, we pro-rate maxDebt.
     // We can pro-rate maxDebt because the quote is either linear (price is
@@ -222,6 +233,30 @@ export const prepareVault = (baggage, marshaller, zcf) => {
         emptyDebt() {
           return AmountMath.makeEmpty(this.facets.helper.debtBrand());
         },
+        /**
+         * @typedef {{ give: { Collateral: Amount<'nat'>, Minted: Amount<'nat'> }, want: { Collateral: Amount<'nat'>, Minted: Amount<'nat'> } }} FullProposal
+         */
+        /**
+         * @param {ProposalRecord} partial
+         * @returns {FullProposal}
+         */
+        fullProposal(partial) {
+          assertOnlyKeys(partial, ['Collateral', 'Minted']);
+          return {
+            give: {
+              Collateral:
+                partial.give?.Collateral ||
+                this.facets.helper.emptyCollateral(),
+              Minted: partial.give?.Minted || this.facets.helper.emptyDebt(),
+            },
+            want: {
+              Collateral:
+                partial.want?.Collateral ||
+                this.facets.helper.emptyCollateral(),
+              Minted: partial.want?.Minted || this.facets.helper.emptyDebt(),
+            },
+          };
+        },
         // #endregion
 
         // #region Phase logic
@@ -459,13 +494,12 @@ export const prepareVault = (baggage, marshaller, zcf) => {
         loanFee(currentDebt, giveAmount, wantAmount) {
           const { state } = this;
 
-          const fee = ceilMultiplyBy(
+          return calculateLoanCosts(
+            currentDebt,
+            giveAmount,
             wantAmount,
             state.manager.getGovernedParams().getLoanFee(),
           );
-          const toMint = AmountMath.add(wantAmount, fee);
-          const newDebt = addSubtract(currentDebt, toMint, giveAmount);
-          return { newDebt, toMint, fee };
         },
 
         /**
@@ -480,77 +514,145 @@ export const prepareVault = (baggage, marshaller, zcf) => {
           const { self, helper } = facets;
           const { outerUpdater: updaterPre } = state;
           const { vaultSeat } = state;
-          const proposal = clientSeat.getProposal();
-          assertOnlyKeys(proposal, ['Collateral', 'Minted']);
+          const fp = helper.fullProposal(clientSeat.getProposal());
+
+          if (
+            allEmpty([
+              fp.give.Collateral,
+              fp.give.Minted,
+              fp.want.Collateral,
+              fp.want.Minted,
+            ])
+          ) {
+            clientSeat.exit();
+            return 'no transaction, as requested';
+          }
+
+          // Calculate the fee, the amount to mint and the resulting debt. We'll
+          // verify that the target debt doesn't violate the collateralization ratio,
+          // then mint, reallocate, and burn.
+          const { newDebt, fee, surplus, toMint } = helper.loanFee(
+            self.getCurrentDebt(),
+            fp.give.Minted,
+            fp.want.Minted,
+          );
 
           const normalizedDebtPre = self.getNormalizedDebt();
           const collateralPre = helper.getCollateralAllocated(vaultSeat);
-
-          const giveColl = proposal.give.Collateral || helper.emptyCollateral();
-          const wantColl = proposal.want.Collateral || helper.emptyCollateral();
+          const hasWants = !allEmpty([fp.want.Collateral, fp.want.Minted]);
+
+          if (!hasWants) {
+            // allow deposits regardless of max debt allowed
+            return helper.commitBalanceAdjustment(
+              clientSeat,
+              fp,
+              {
+                newDebt,
+                fee,
+                surplus,
+                toMint,
+              },
+              { normalizedDebtPre, collateralPre },
+            );
+          }
 
           const newCollateralPre = addSubtract(
             collateralPre,
-            giveColl,
-            wantColl,
+            fp.give.Collateral,
+            fp.want.Collateral,
           );
-          // max debt supported by current Collateral as modified by proposal
+          // max debt supported by the vault Collateral implied by the proposal
           const maxDebtPre = await state.manager.maxDebtFor(newCollateralPre);
           updaterPre === state.outerUpdater ||
             Fail`Transfer during vault adjustment`;
           helper.assertActive();
 
-          // After the `await`, we retrieve the vault's allocations again,
-          // so we can compare to the debt limit based on the new values.
-          const collateral = helper.getCollateralAllocated(vaultSeat);
-          const newCollateral = addSubtract(collateral, giveColl, wantColl);
-
-          const debt = self.getCurrentDebt();
-          const giveMinted = AmountMath.min(
-            proposal.give.Minted || helper.emptyDebt(),
-            debt,
-          );
-          const wantMinted = proposal.want.Minted || helper.emptyDebt();
-          if (allEmpty([giveColl, giveMinted, wantColl, wantMinted])) {
-            clientSeat.exit();
-            return 'no transaction, as requested';
-          }
-
-          // Calculate the fee, the amount to mint and the resulting debt. We'll
-          // verify that the target debt doesn't violate the collateralization ratio,
-          // then mint, reallocate, and burn.
-          const { newDebt, fee, toMint } = helper.loanFee(
-            debt,
-            giveMinted,
-            wantMinted,
-          );
-
-          trace('adjustBalancesHook', state.idInManager, {
+          trace('adjustBalancesHook after quote', state.idInManager, {
             newCollateralPre,
-            newCollateral,
             fee,
             toMint,
+            maxDebtPre,
             newDebt,
           });
 
+          // While awaiting maxDebtFor, the allocations may have changed.
+          // After the `await`, we retrieve the vault's allocations again,
+          // so we can compare to the debt limit based on the new values.
+          const collateral = helper.getCollateralAllocated(vaultSeat);
+          const newCollateral = addSubtract(
+            collateral,
+            fp.give.Collateral,
+            fp.want.Collateral,
+          );
           if (
-            checkRestart(newCollateralPre, maxDebtPre, newCollateral, newDebt)
+            allocationsChangedSinceQuote(
+              newCollateralPre,
+              maxDebtPre,
+              newCollateral,
+              newDebt,
+            )
           ) {
             return helper.adjustBalancesHook(clientSeat);
           }
 
-          stageDelta(clientSeat, vaultSeat, giveColl, wantColl, 'Collateral');
+          return helper.commitBalanceAdjustment(
+            clientSeat,
+            fp,
+            {
+              newDebt,
+              fee,
+              surplus,
+              toMint,
+            },
+            { normalizedDebtPre, collateralPre },
+          );
+        },
+
+        /**
+         *
+         * @param {ZCFSeat} clientSeat
+         * @param {FullProposal} fp
+         * @param {ReturnType<typeof calculateLoanCosts>} costs
+         * @param {object} accounting
+         * @param {NormalizedDebt} accounting.normalizedDebtPre
+         * @param {Amount<'nat'>} accounting.collateralPre
+         * @returns {Promise<string>} success message
+         */
+        async commitBalanceAdjustment(
+          clientSeat,
+          fp,
+          { newDebt, fee, surplus, toMint },
+          { normalizedDebtPre, collateralPre },
+        ) {
+          const { state, facets } = this;
+          const { helper } = facets;
+          const { vaultSeat } = state;
+
+          const giveMintedTaken = AmountMath.subtract(fp.give.Minted, surplus);
+
+          // TODO use atomicRearrange https://github.com/Agoric/agoric-sdk/issues/5605
+          stageDelta(
+            clientSeat,
+            vaultSeat,
+            fp.give.Collateral,
+            fp.want.Collateral,
+            'Collateral',
+          );
           // `wantMinted` is allocated in the reallocate and mint operation, and so not here
           stageDelta(
             clientSeat,
             vaultSeat,
-            giveMinted,
+            giveMintedTaken,
             helper.emptyDebt(),
             'Minted',
           );
 
           /** @type {Array<ZCFSeat>} */
-          const vaultSeatOpt = allEmpty([giveColl, giveMinted, wantColl])
+          const vaultSeatOpt = allEmpty([
+            fp.give.Collateral,
+            giveMintedTaken,
+            fp.want.Collateral,
+          ])
             ? []
             : [vaultSeat];
           state.manager.mintAndReallocate(
@@ -566,7 +668,7 @@ export const prepareVault = (baggage, marshaller, zcf) => {
             collateralPre,
             newDebt,
           );
-          state.manager.burnAndRecord(giveMinted, vaultSeat);
+          state.manager.burnAndRecord(giveMintedTaken, vaultSeat);
           helper.assertVaultHoldsNoMinted();
 
           helper.updateUiState();

package/src/vaultFactory/vaultKit.js

@@ -3,7 +3,7 @@ import '@agoric/zoe/exported.js';
 import { Far } from '@endo/marshal';
 import { prepareVaultHolder } from './vaultHolder.js';
 
-const trace = makeTracer('IV', false);
+const trace = makeTracer('VK', false);
 
 /**
  *

package/src/vaultFactory/vaultManager.js

@@ -41,7 +41,6 @@ import {
   assertProposalShape,
   atomicTransfer,
   ceilDivideBy,
-  floorDivideBy,
   getAmountIn,
   getAmountOut,
   makeRatio,
@@ -53,6 +52,7 @@ import { E } from '@endo/eventual-send';
 import { checkDebtLimit } from '../contractSupport.js';
 import { chargeInterest } from '../interest.js';
 import { liquidate, makeQuote, updateQuote } from './liquidation.js';
+import { maxDebtForVault } from './math.js';
 import { makePrioritizedVaults } from './prioritizedVaults.js';
 import { Phase, prepareVault } from './vault.js';
 
@@ -94,6 +94,7 @@ const trace = makeTracer('VM', false);
  *  getRecordingPeriod: () => RelativeTime,
  *  getDebtLimit: () => Amount<'nat'>,
  *  getInterestRate: () => Ratio,
+ *  getLiquidationPadding: () => Ratio,
  *  getLiquidationMargin: () => Ratio,
  *  getLiquidationPenalty: () => Ratio,
  *  getLoanFee: () => Ratio,
@@ -435,6 +436,7 @@ export const prepareVaultManagerKit = (
           const { facets } = this;
           trace('reschedulePriceCheck', collateralBrand, {
             liquidationQueueing,
+            outstandingQuote: !!outstandingQuote,
           });
           // INTERLOCK: the first time through, start the activity to wait for
           // and process liquidations over time.
@@ -622,20 +624,23 @@ export const prepareVaultManagerKit = (
         },
 
         /**
+         * Consults a price authority to determine the max debt this manager
+         * config will allow for the collateral.
+         *
          * @param {Amount<'nat'>} collateralAmount
          */
         async maxDebtFor(collateralAmount) {
           trace('maxDebtFor', collateralAmount);
           assert(factoryPowers && priceAuthority);
-          const quoteAmount = await E(priceAuthority).quoteGiven(
+          const quote = await E(priceAuthority).quoteGiven(
             collateralAmount,
             debtBrand,
           );
-          trace('maxDebtFor got quote', quoteAmount);
-          // floorDivide because we want the debt ceiling lower
-          return floorDivideBy(
-            getAmountOut(quoteAmount),
+          trace('maxDebtFor got quote', quote.quoteAmount.value[0]);
+          return maxDebtForVault(
+            quote,
             factoryPowers.getGovernedParams().getLiquidationMargin(),
+            factoryPowers.getGovernedParams().getLiquidationPadding(),
           );
         },
         /**