@agoric/inter-protocol 0.13.3 → 0.13.4-dev-800c2bb.0

package/src/reserve/assetReserveKit.js

@@ -0,0 +1,303 @@
+import { Fail } from '@agoric/assert';
+import { AmountMath, AmountShape, IssuerShape } from '@agoric/ertp';
+import { makeTracer } from '@agoric/internal';
+import { M, makeScalarBigMapStore, prepareExoClassKit } from '@agoric/vat-data';
+import { atomicTransfer } from '@agoric/zoe/src/contractSupport/atomicTransfer.js';
+import {
+  makeRecorderTopic,
+  SubscriberShape,
+  TopicsRecordShape,
+} from '@agoric/zoe/src/contractSupport/topics.js';
+import { AmountKeywordRecordShape } from '@agoric/zoe/src/typeGuards.js';
+import { E } from '@endo/eventual-send';
+import { UnguardedHelperI } from '../typeGuards.js';
+
+const { quote: q } = assert;
+
+const trace = makeTracer('ReserveKit', true);
+
+/**
+ * @typedef {object} MetricsNotification
+ *
+ * @property {AmountKeywordRecord} allocations
+ * @property {Amount<'nat'>} shortfallBalance shortfall from liquidation that
+ *   has not yet been compensated.
+ * @property {Amount<'nat'>} totalFeeMinted total Fee tokens minted to date
+ * @property {Amount<'nat'>} totalFeeBurned total Fee tokens burned to date
+ */
+
+/**
+ * @param {import('@agoric/vat-data').Baggage} baggage
+ * @param {{
+ * feeMint: ZCFMint<'nat'>,
+ * makeRecorderKit: import('@agoric/zoe/src/contractSupport/recorder.js').MakeRecorderKit,
+ * storageNode: StorageNode,
+ * zcf: ZCF}} powers
+ */
+export const prepareAssetReserveKit = async (
+  baggage,
+  { feeMint, makeRecorderKit, storageNode, zcf },
+) => {
+  trace('prepareAssetReserveKit', [...baggage.keys()]);
+  const feeKit = feeMint.getIssuerRecord();
+  const emptyAmount = AmountMath.makeEmpty(feeKit.brand);
+
+  const makeAssetReserveKitInternal = prepareExoClassKit(
+    baggage,
+    'AssetReserveKit',
+    {
+      helper: UnguardedHelperI,
+      governedApis: M.interface('AssetReserve governedApis', {
+        burnFeesToReduceShortfall: M.call(AmountShape).returns(),
+      }),
+      machine: M.interface('AssetReserve machine', {
+        addIssuer: M.call(IssuerShape, M.string()).returns(M.promise()),
+        getAllocations: M.call().returns(AmountKeywordRecordShape),
+        makeShortfallReportingInvitation: M.call().returns(M.promise()),
+      }),
+      public: M.interface('AssetReserve public', {
+        makeAddCollateralInvitation: M.call().returns(M.promise()),
+        getMetrics: M.call().returns(SubscriberShape),
+        getPublicTopics: M.call().returns(TopicsRecordShape),
+      }),
+      shortfallReportingFacet: M.interface('AssetReserve shortfall reporter', {
+        increaseLiquidationShortfall: M.call(AmountShape).returns(),
+        reduceLiquidationShortfall: M.call(AmountShape).returns(),
+      }),
+    },
+    /**
+     *
+     * @param {StorageNode} metricsNode
+     */
+    metricsNode => {
+      /**
+       * Used to look up the unique keyword for each brand, including Fee brand.
+       *
+       * @type {MapStore<Brand, Keyword>}
+       */
+      const keywordForBrand = makeScalarBigMapStore('keywordForBrand', {
+        durable: true,
+      });
+      /**
+       * Used to look up the brands for keywords, excluding Fee because it's a special case.
+       *
+       * @type {MapStore<Keyword, Brand>}
+       */
+      const brandForKeyword = makeScalarBigMapStore('brandForKeyword', {
+        durable: true,
+      });
+
+      return {
+        brandForKeyword,
+        // We keep the associated liquidity tokens in the same seat
+        collateralSeat: zcf.makeEmptySeatKit().zcfSeat,
+        keywordForBrand,
+        metricsKit: makeRecorderKit(
+          metricsNode,
+          /** @type {import('@agoric/zoe/src/contractSupport/recorder.js').TypedMatcher<MetricsNotification>} */ (
+            M.any()
+          ),
+        ),
+        totalFeeMinted: emptyAmount,
+        totalFeeBurned: emptyAmount,
+        shortfallBalance: emptyAmount,
+      };
+    },
+    {
+      helper: {
+        /** @param {Brand} brand */
+        getKeywordForBrand(brand) {
+          const { keywordForBrand } = this.state;
+          keywordForBrand.has(brand) ||
+            Fail`Issuer not defined for brand ${q(
+              brand,
+            )}; first call addIssuer()`;
+          return keywordForBrand.get(brand);
+        },
+
+        /**
+         * @param {Brand} brand
+         * @param {Keyword} keyword
+         */
+        saveBrandKeyword(brand, keyword) {
+          trace('saveBrandKeyword', brand, keyword);
+          const { keywordForBrand, brandForKeyword } = this.state;
+          keywordForBrand.init(brand, keyword);
+          brandForKeyword.init(keyword, brand);
+        },
+
+        writeMetrics() {
+          const { state } = this;
+          const metrics = harden({
+            allocations: state.collateralSeat.getCurrentAllocation(),
+            shortfallBalance: state.shortfallBalance,
+            totalFeeMinted: state.totalFeeMinted,
+            totalFeeBurned: state.totalFeeBurned,
+          });
+          void state.metricsKit.recorder.write(metrics);
+        },
+      },
+      governedApis: {
+        /**
+         *
+         * @param {Amount<'nat'>} reduction
+         * @returns {void}
+         */
+        burnFeesToReduceShortfall(reduction) {
+          const { facets, state } = this;
+          trace('burnFeesToReduceShortfall', reduction);
+          reduction = AmountMath.coerce(feeKit.brand, reduction);
+          const feeKeyword = state.keywordForBrand.get(feeKit.brand);
+          const feeBalance =
+            state.collateralSeat.getAmountAllocated(feeKeyword);
+          const amountToBurn = AmountMath.min(reduction, feeBalance);
+          if (AmountMath.isEmpty(amountToBurn)) {
+            return;
+          }
+
+          feeMint.burnLosses(
+            harden({ [feeKeyword]: amountToBurn }),
+            state.collateralSeat,
+          );
+          state.totalFeeBurned = AmountMath.add(
+            state.totalFeeBurned,
+            amountToBurn,
+          );
+          facets.helper.writeMetrics();
+        },
+      },
+      machine: {
+        // add makeRedeemLiquidityTokensInvitation later. For now just store them
+        /**
+         * @param {Issuer} issuer
+         * @param {string} keyword
+         */
+        async addIssuer(issuer, keyword) {
+          const brand = await E(issuer).getBrand();
+          trace('addIssuer', { brand, keyword });
+          assert(
+            keyword !== 'Fee' && brand !== feeKit.brand,
+            `'Fee' brand is a special case handled by the reserve contract`,
+          );
+
+          trace('addIssuer storing', {
+            keyword,
+            brand,
+          });
+
+          this.facets.helper.saveBrandKeyword(brand, keyword);
+          await zcf.saveIssuer(issuer, keyword);
+        },
+
+        /** @deprecated use getPublicTopics metrics allocation */
+        getAllocations() {
+          return this.state.collateralSeat.getCurrentAllocation();
+        },
+
+        makeShortfallReportingInvitation() {
+          const { facets } = this;
+          const handleShortfallReportingOffer = () => {
+            return facets.shortfallReportingFacet;
+          };
+
+          return zcf.makeInvitation(
+            handleShortfallReportingOffer,
+            'getFacetForReportingShortfalls',
+          );
+        },
+      },
+      /**
+       * XXX missing governance public methods https://github.com/Agoric/agoric-sdk/issues/5200
+       */
+      public: {
+        /**
+         * Anyone can deposit any assets to the reserve
+         */
+        makeAddCollateralInvitation() {
+          /** @type {OfferHandler<Promise<string>>} */
+          const handler = async seat => {
+            const {
+              give: { Collateral: amountIn },
+            } = seat.getProposal();
+            const { facets, state } = this;
+            const { helper } = facets;
+
+            const collateralKeyword = helper.getKeywordForBrand(amountIn.brand);
+
+            atomicTransfer(
+              zcf,
+              seat,
+              state.collateralSeat,
+              { Collateral: amountIn },
+              { [collateralKeyword]: amountIn },
+            );
+            seat.exit();
+            helper.writeMetrics();
+
+            trace('received collateral', amountIn);
+            return 'added Collateral to the Reserve';
+          };
+          return zcf.makeInvitation(handler, 'Add Collateral');
+        },
+        /** @deprecated */
+        getMetrics() {
+          return this.state.metricsKit.subscriber;
+        },
+        getPublicTopics() {
+          return {
+            metrics: makeRecorderTopic(
+              'Asset Reserve metrics',
+              this.state.metricsKit,
+            ),
+          };
+        },
+      },
+      shortfallReportingFacet: {
+        /**
+         * @param {Amount<"nat">} shortfall
+         */
+        increaseLiquidationShortfall(shortfall) {
+          const { facets, state } = this;
+          state.shortfallBalance = AmountMath.add(
+            state.shortfallBalance,
+            shortfall,
+          );
+          facets.helper.writeMetrics();
+        },
+
+        // currently exposed for testing. Maybe it only gets called internally?
+        /**
+         * @param {Amount<"nat">} reduction
+         */
+        reduceLiquidationShortfall(reduction) {
+          const { state } = this;
+          if (AmountMath.isGTE(reduction, state.shortfallBalance)) {
+            state.shortfallBalance = emptyAmount;
+          } else {
+            state.shortfallBalance = AmountMath.subtract(
+              state.shortfallBalance,
+              reduction,
+            );
+          }
+          this.facets.helper.writeMetrics();
+        },
+      },
+    },
+    {
+      finish: ({ facets: { helper } }) => {
+        // no need to saveIssuer() b/c registerFeeMint did it
+        helper.saveBrandKeyword(feeKit.brand, 'Fee');
+
+        helper.writeMetrics();
+      },
+    },
+  );
+
+  const makeAssetReserveKit = async () => {
+    const metricsNode = await E(storageNode).makeChildNode('metrics');
+    return makeAssetReserveKitInternal(metricsNode);
+  };
+  return makeAssetReserveKit;
+};
+harden(prepareAssetReserveKit);
+/** @typedef {ReturnType<Awaited<ReturnType<typeof prepareAssetReserveKit>>>} AssetReserveKit */

package/src/reserve/doc.md

@@ -77,9 +77,7 @@ zoe ->> addCollateralHook: call addCollateralHook
 addCollateralHook ->> seat: get proposal
 
 addCollateralHook ->> addCollateralHook: get Keyword for amountIn brand
-addCollateralHook ->> seat: decrementBy amountIn
-addCollateralHook ->> collateralSeat: incrementBy collateralKeyword: amountIn
-addCollateralHook ->> zcf: reallocate collateralSeat, seat
+addCollateralHook ->> zcf: atomicTransfer amountIn from seat to collateralSeat
 addCollateralHook ->> seat: seat.exit()
 seat ->> zoe: added collateral to the reserve
 zoe ->> caller: return status

package/src/reserve/params.js

@@ -1,13 +1,10 @@
-// @ts-check
+// @jessie-check
 
 import { CONTRACT_ELECTORATE, ParamTypes } from '@agoric/governance';
 
-export const AMM_INSTANCE = 'AmmInstance';
-
-const makeReserveTerms = (poserInvitationAmount, ammInstance, timer) => ({
+const makeReserveTerms = (poserInvitationAmount, timer) => ({
   timer,
   governedParams: harden({
-    [AMM_INSTANCE]: { type: ParamTypes.INSTANCE, value: ammInstance },
     [CONTRACT_ELECTORATE]: {
       type: ParamTypes.INVITATION,
       value: poserInvitationAmount,

package/src/typeGuards.js

@@ -0,0 +1,13 @@
+// @jessie-check
+
+import { M } from '@agoric/store';
+
+/**
+ * To be used only for 'helper' facets where the calls are from trusted code.
+ */
+export const UnguardedHelperI = M.interface(
+  'helper',
+  {},
+  // not exposed so sloppy okay
+  { sloppy: true },
+);

package/src/vaultFactory/Liquidation.md

@@ -0,0 +1,100 @@
+The liquidation approach relies on a descending clock auction (a
+"dutch" auction). The auction runs at a rate controlled by governed
+parameters. Every auction period, each vaultManager checks to see which
+vaults are under-water compared to an oracle price captured before the
+auction start. The collateral from all those illiquid vaults are sent to the
+auction, which attempts to sell them for enough to cover their outstanding
+debt at  a discount to their value. Since they are over-collateralized this
+should normally cover the debt and possibly return excess collateral. When
+that is the case (flow 1, below) , we repay the debt, charge a liquidation fee,
+and return excess collateral to the vault holders.
+
+There are two interesting exception cases. All the collateral might be sold
+without covering the debt (flow 2a), or there might not be enough bids to
+purchase all the collateral (flow 2b). In the first case, vault-holders don't
+get anything back, we burn the currency we received to cover a portion of the
+debt, any excess collateral is sent to the reserve, and we report a shortfall.
+
+In the second case, we can't tell whether it's due to a downturn in the
+market or a DoS attack on the exchange. In hopes that it's not the latter, we
+reinstate as many vaults as can be made whole, declare the rest liquidated,
+and expect the next liquidation opportunity either to find the price has
+recovered, or to send a possibly different set of vaults to the next auction.
+
+
+**Flow 1: Auction raises enough IST to cover debt**
+
+The following steps occur in this order
+
+1. IST raised by the auction is burned to reduce debt in 1:1 ratio.
+
+- Definitionally, this should result in zero debt. Since the auction should stop
+  when it raises enough IST, it should result in zero IST remaining as well.
+  However, if some excess IST exists, it should be transferred to the reserve.
+
+2. From any remaining collateral, the liquidation penalty is taken and
+   transferred to the reserve.
+
+- Liquidation penalty is calculated as debt / current oracle price at auction
+  start * liquidation penalty
+
+3. Excess collateral - if any - is returned to vault holders
+
+- Vault holders receive collateral back sequenced by highest collateralization
+  ratio at liquidation time first.
+- The max amount of collateral a vault should be able to receive back is:
+  original collateral - collateral covering their share of debt (using average
+  liquidation price) - collateral covering their share of the penalty (their
+  debt / total debt \* total penalty)
+
+**Flow 2: Auction does not raise enough to cover IST debt**
+
+This flow further bifurcates based on whether the auction has sold all its
+collateral asset and still has not covered the debt or has collateral
+remaining (which simply did not receive bidders)
+
+**Flow 2a: all collateral sold and debt is not covered**
+
+1. IST raised by the auction is burned to reduce debt in 1:1 ratio.
+
+- Definitionally, this should result in zero IST remaining and some debt
+  remaining.
+
+2. Remaining debt is recorded in the reserve as a shortfall
+   
+   *sequence ends; no penalty is taken and vaults receive nothing back*
+
+**Flow 2b: collateral remains but debt is still not covered by IST raised by
+auction end**
+
+1. IST raised by the auction is burned to reduce debt in 1:1 ratio.
+
+- Definitionally, this should result in zero IST remaining and some debt remaining.
+
+2. From any remaining collateral, the liquidation penalty is taken and
+   transferred to the reserve.
+
+- Liquidation penalty is calculated as debt / current oracle price at auction
+  start \* liquidation penalty.
+
+  _Note: there now should be debt remaining and possibly collateral remaining_
+
+3. The vault manager now iterates through the vaults that were liquidated and
+   attempts to reconstitute them (minus collateral from the liquidation penalty)
+   starting from the best CR to worst.
+
+- Reconstitution means full prior debt AND full prior collateral minus
+  collateral used from penalty.
+- Collateral used for penalty = vault debt / total debt \* total liquidation penalty.
+- Debt that is given back to a vault should be subtracted from the vault
+  manager's view of remaining liquidation debt (i.e., it shouldn't be
+  double counted)
+- Reconstituted vaults are set to OPEN status (i.e., they are live again
+  and able to be interacted with)
+
+4. When the vault manager reaches a vault it cannot fully reconstitute
+   (both full debt and collateral as described above), it marks that vault as
+   liquidated. It then marks all other lower CR vaults as liquidated.
+5. Any remaining collateral is transferred to the reserve.
+6. Any remaining debt (subtracting debt that was given back to reconstituted
+   vaults, as described above) is transferred to the reserve as shortfall.

package/src/vaultFactory/burn.js

@@ -1,4 +1,5 @@
-// @ts-check
+// @jessie-check
+
 import '@agoric/zoe/exported.js';
 
 import { E } from '@endo/eventual-send';