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

package/src/psm/psm.js

@@ -1,27 +1,43 @@
-// @ts-check
+// @jessie-check
+
+import '@agoric/governance/exported.js';
 import '@agoric/zoe/exported.js';
 import '@agoric/zoe/src/contracts/exported.js';
-import '@agoric/governance/src/exported.js';
 
-import { E } from '@endo/eventual-send';
+import { AmountMath, AmountShape, BrandShape, RatioShape } from '@agoric/ertp';
 import {
+  CONTRACT_ELECTORATE,
+  handleParamGovernance,
+  ParamTypes,
+  publicMixinAPI,
+} from '@agoric/governance';
+import { StorageNodeShape } from '@agoric/internal';
+import { M, prepareExo, provide } from '@agoric/vat-data';
+import {
+  atomicRearrange,
+  atomicTransfer,
   ceilMultiplyBy,
   floorDivideBy,
   floorMultiplyBy,
+  makeRecorderTopic,
+  prepareRecorderKitMakers,
+  provideAll,
+  provideEmptySeat,
+  TopicsRecordShape,
 } from '@agoric/zoe/src/contractSupport/index.js';
-import { Far } from '@endo/marshal';
 import {
-  handleParamGovernance,
-  ParamTypes,
-  publicMixinAPI,
-} from '@agoric/governance';
-import { M, provide, vivifyFarInstance } from '@agoric/vat-data';
-import { AmountMath } from '@agoric/ertp';
+  AmountKeywordRecordShape,
+  FeeMintAccessShape,
+  InstanceHandleShape,
+  InvitationShape,
+} from '@agoric/zoe/src/typeGuards.js';
+import { E } from '@endo/eventual-send';
 
-import { makeMakeCollectFeesInvitation } from '../collectFees.js';
-import { makeMetricsPublishKit } from '../contractSupport.js';
+import { mustMatch } from '@agoric/store';
+import { makeCollectFeesInvitation } from '../collectFees.js';
+import { makeNatAmountShape } from '../contractSupport.js';
 
-const { details: X } = assert;
+const { Fail } = assert;
 
 /**
  * @file The Parity Stability Module supports efficiently minting/burning a
@@ -29,7 +45,6 @@ const { details: X } = assert;
  * thereby acts as an anchor to provide additional stability. For flexible
  * economic policies, the fee percentage for trading into and out of the stable
  * token are specified separately.
- *
  */
 
 /**
@@ -39,6 +54,8 @@ const { details: X } = assert;
  *
  * @property {Amount<'nat'>} anchorPoolBalance  amount of Anchor token
  * available to be swapped
+ * @property {Amount<'nat'>} mintedPoolBalance  amount of Minted token
+ * outstanding (the amount minted minus the amount burned).
  * @property {Amount<'nat'>} feePoolBalance     amount of Minted token
  * fees available to be collected
  *
@@ -48,22 +65,42 @@ const { details: X } = assert;
  * ever given by this contract
  */
 
-/**
- * Stage a transfer of a single asset from one seat to another, with an optional
- * remapping of the Keywords. Check that the remapping is for the same amount.
- *
- * @param {ZCFSeat} from
- * @param {ZCFSeat} to
- * @param {AmountKeywordRecord} txFrom
- * @param {AmountKeywordRecord} txTo
- */
-const stageTransfer = (from, to, txFrom, txTo = txFrom) => {
-  assert(AmountMath.isEqual(Object.values(txFrom)[0], Object.values(txTo)[0]));
-  from.decrementBy(txFrom);
-  to.incrementBy(txTo);
+/** @typedef {import('@agoric/vat-data').Baggage} Baggage */
+
+export const customTermsShape = {
+  anchorBrand: BrandShape,
+  anchorPerMinted: RatioShape,
+  electionManager: InstanceHandleShape,
+  governedParams: {
+    [CONTRACT_ELECTORATE]: {
+      type: ParamTypes.INVITATION,
+      value: AmountShape,
+    },
+    WantMintedFee: {
+      type: ParamTypes.RATIO,
+      value: RatioShape,
+    },
+    GiveMintedFee: {
+      type: ParamTypes.RATIO,
+      value: RatioShape,
+    },
+    MintLimit: { type: ParamTypes.AMOUNT, value: AmountShape },
+  },
 };
+harden(customTermsShape);
 
-/** @typedef {import('@agoric/vat-data').Baggage} Baggage */
+export const privateArgsShape = M.splitRecord(
+  harden({
+    marshaller: M.remotable('Marshaller'),
+    storageNode: StorageNodeShape,
+  }),
+  harden({
+    // only necessary on first invocation, not subsequent
+    feeMintAccess: FeeMintAccessShape,
+    initialPoserInvitation: InvitationShape,
+  }),
+);
+harden(privateArgsShape);
 
 /**
  * @param {ZCF<GovernanceTerms<{
@@ -71,26 +108,28 @@ const stageTransfer = (from, to, txFrom, txTo = txFrom) => {
  *    WantMintedFee: 'ratio',
  *    MintLimit: 'amount',
  *   }> & {
- *    anchorBrand: Brand,
+ *    anchorBrand: Brand<'nat'>,
  *    anchorPerMinted: Ratio,
  * }>} zcf
  * @param {{feeMintAccess: FeeMintAccess, initialPoserInvitation: Invitation, storageNode: StorageNode, marshaller: Marshaller}} privateArgs
  * @param {Baggage} baggage
  */
-export const start = async (zcf, privateArgs, baggage) => {
+export const prepare = async (zcf, privateArgs, baggage) => {
   const { anchorBrand, anchorPerMinted } = zcf.getTerms();
   console.log('PSM Starting', anchorBrand, anchorPerMinted);
 
-  const stableMint = await zcf.registerFeeMint(
-    'Minted',
-    privateArgs.feeMintAccess,
+  const { makeRecorderKit } = prepareRecorderKitMakers(
+    baggage,
+    privateArgs.marshaller,
   );
+
+  const { stableMint } = await provideAll(baggage, {
+    stableMint: () => zcf.registerFeeMint('Minted', privateArgs.feeMintAccess),
+  });
   const { brand: stableBrand } = stableMint.getIssuerRecord();
-  assert(
-    anchorPerMinted.numerator.brand === anchorBrand &&
-      anchorPerMinted.denominator.brand === stableBrand,
-    X`Ratio ${anchorPerMinted} is not consistent with brands ${anchorBrand} and ${stableBrand}`,
-  );
+  (anchorPerMinted.numerator.brand === anchorBrand &&
+    anchorPerMinted.denominator.brand === stableBrand) ||
+    Fail`Ratio ${anchorPerMinted} is not consistent with brands ${anchorBrand} and ${stableBrand}`;
 
   zcf.setTestJig(() => ({
     stableIssuerRecord: stableMint.getIssuerRecord(),
@@ -98,7 +137,7 @@ export const start = async (zcf, privateArgs, baggage) => {
   const emptyStable = AmountMath.makeEmpty(stableBrand);
   const emptyAnchor = AmountMath.makeEmpty(anchorBrand);
 
-  const { publicMixin, creatorMixin, makeFarGovernorFacet, params } =
+  const { publicMixin, makeDurableGovernorFacet, params } =
     await handleParamGovernance(
       zcf,
       privateArgs.initialPoserInvitation,
@@ -111,60 +150,113 @@ export const start = async (zcf, privateArgs, baggage) => {
       privateArgs.marshaller,
     );
 
-  const provideEmptyZcfSeat = name => {
-    return provide(baggage, name, () => zcf.makeEmptySeatKit().zcfSeat);
-  };
+  const anchorPool = provideEmptySeat(zcf, baggage, 'anchorPoolSeat');
+  const feePool = provideEmptySeat(zcf, baggage, 'feePoolSeat');
+  const stage = provideEmptySeat(zcf, baggage, 'stageSeat');
 
-  const anchorPool = provideEmptyZcfSeat('anchorPoolSeat');
-  const feePool = provideEmptyZcfSeat('feePoolSeat');
-  const stage = provideEmptyZcfSeat('stageSeat');
-
-  let mintedPoolBalance = provide(baggage, 'mintedPoolBalance', () =>
+  // XXX access these through baggage directly so changes are saved
+  // Normally these would be in Exo class state but that's too big a change atm
+  provide(baggage, 'mintedPoolBalance', () =>
     AmountMath.makeEmpty(stableBrand),
   );
-
-  let totalAnchorProvided = provide(baggage, 'totalAnchorProvided', () =>
+  provide(baggage, 'totalAnchorProvided', () =>
     AmountMath.makeEmpty(anchorBrand),
   );
-  let totalMintedProvided = provide(baggage, 'totalMintedProvided', () =>
+  provide(baggage, 'totalMintedProvided', () =>
     AmountMath.makeEmpty(stableBrand),
   );
 
-  /** @type {import('../contractSupport.js').MetricsPublishKit<MetricsNotification>} */
-  const { metricsPublisher, metricsSubscriber } = makeMetricsPublishKit(
-    privateArgs.storageNode,
-    privateArgs.marshaller,
-  );
+  const { metricsKit } = await provideAll(baggage, {
+    metricsKit: () =>
+      E.when(E(privateArgs.storageNode).makeChildNode('metrics'), node =>
+        makeRecorderKit(
+          node,
+          /** @type {import('@agoric/zoe/src/contractSupport/recorder.js').TypedMatcher<MetricsNotification>} */ (
+            M.any()
+          ),
+        ),
+      ),
+  });
+  const topics = harden({
+    metrics: makeRecorderTopic('PSM metrics', metricsKit),
+  });
+
   const updateMetrics = () => {
-    metricsPublisher.publish(
+    void E(metricsKit.recorder).write(
       harden({
         anchorPoolBalance: anchorPool.getAmountAllocated('Anchor', anchorBrand),
         feePoolBalance: feePool.getAmountAllocated('Minted', stableBrand),
-        mintedPoolBalance,
-        totalAnchorProvided,
-        totalMintedProvided,
+        mintedPoolBalance: baggage.get('mintedPoolBalance'),
+        totalAnchorProvided: baggage.get('totalAnchorProvided'),
+        totalMintedProvided: baggage.get('totalMintedProvided'),
       }),
     );
   };
   updateMetrics();
 
+  const AnchorAmountShape = makeNatAmountShape(anchorBrand);
+  const StableAmountShape = makeNatAmountShape(stableBrand);
+
+  /**
+   * @param {ZCFSeat} seat
+   * @param {Omit<MetricsNotification, 'anchorPoolBalance'>} target
+   */
+  const restoreMetricsHook = (seat, target) => {
+    assert(
+      AmountMath.isEmpty(anchorPool.getAmountAllocated('Anchor', anchorBrand)),
+      'cannot restoreMetrics: anchorPool is not empty',
+    );
+    assert(
+      AmountMath.isEmpty(feePool.getAmountAllocated('Minted', stableBrand)),
+      'cannot restoreMetrics: feePool is not empty',
+    );
+    mustMatch(
+      target,
+      harden({
+        feePoolBalance: StableAmountShape,
+        mintedPoolBalance: StableAmountShape,
+        totalAnchorProvided: AnchorAmountShape,
+        totalMintedProvided: StableAmountShape,
+      }),
+    );
+    const {
+      give: { Anchor },
+    } = seat.getProposal();
+    stableMint.mintGains({ Minted: target.feePoolBalance }, feePool);
+    atomicTransfer(zcf, seat, anchorPool, { Anchor });
+    baggage.set('mintedPoolBalance', target.mintedPoolBalance);
+    baggage.set('totalAnchorProvided', target.totalAnchorProvided);
+    baggage.set('totalMintedProvided', target.totalMintedProvided);
+    seat.exit();
+    updateMetrics();
+  };
+
   /**
    * @param {Amount<'nat'>} toMint
    */
   const assertUnderLimit = toMint => {
-    const mintedAfter = AmountMath.add(mintedPoolBalance, toMint);
+    const mintedAfter = AmountMath.add(
+      baggage.get('mintedPoolBalance'),
+      toMint,
+    );
     AmountMath.isGTE(params.getMintLimit(), mintedAfter) ||
-      assert.fail(X`Request would exceed mint limit`);
+      Fail`Request would exceed mint limit`;
   };
 
   const burnMinted = toBurn => {
     stableMint.burnLosses({ Minted: toBurn }, stage);
-    mintedPoolBalance = AmountMath.subtract(mintedPoolBalance, toBurn);
+    baggage.set(
+      'mintedPoolBalance',
+      AmountMath.subtract(baggage.get('mintedPoolBalance'), toBurn),
+    );
   };
 
   const mintMinted = toMint => {
     stableMint.mintGains({ Minted: toMint }, stage);
-    mintedPoolBalance = AmountMath.add(mintedPoolBalance, toMint);
+    baggage.set(
+      'mintedPoolBalance',
+      AmountMath.add(baggage.get('mintedPoolBalance'), toMint),
+    );
   };
 
   /**
@@ -177,26 +269,23 @@ export const start = async (zcf, privateArgs, baggage) => {
     const afterFee = AmountMath.subtract(given, fee);
     const maxAnchor = floorMultiplyBy(afterFee, anchorPerMinted);
     AmountMath.isGTE(maxAnchor, wanted) ||
-      assert.fail(X`wanted ${wanted} is more than ${given} minus fees ${fee}`);
-    try {
-      stageTransfer(seat, stage, { In: afterFee }, { Minted: afterFee });
-      stageTransfer(seat, feePool, { In: fee }, { Minted: fee });
-      stageTransfer(
-        anchorPool,
-        seat,
-        { Anchor: maxAnchor },
-        { Out: maxAnchor },
-      );
-      zcf.reallocate(seat, anchorPool, stage, feePool);
-      burnMinted(afterFee);
-    } catch (e) {
-      stage.clear();
-      anchorPool.clear();
-      feePool.clear();
-      // TODO(#6116) someday, reallocate should guarantee that this case cannot happen
-      throw e;
-    }
-    totalAnchorProvided = AmountMath.add(totalAnchorProvided, maxAnchor);
+      Fail`wanted ${wanted} is more than ${given} minus fees ${fee}`;
+    atomicRearrange(
+      zcf,
+      harden([
+        [seat, stage, { In: afterFee }, { Minted: afterFee }],
+        [seat, feePool, { In: fee }, { Minted: fee }],
+        [anchorPool, seat, { Anchor: maxAnchor }, { Out: maxAnchor }],
+      ]),
+    );
+    // The treatment of `burnMinted` here is different than the
+    // one immediately below. This `burnMinted`
+    // happen only if the `atomicRearrange` does *not* throw.
+    burnMinted(afterFee);
+    baggage.set(
+      'totalAnchorProvided',
+      AmountMath.add(baggage.get('totalAnchorProvided'), maxAnchor),
+    );
   };
 
   /**
@@ -210,22 +299,28 @@ export const start = async (zcf, privateArgs, baggage) => {
     const fee = ceilMultiplyBy(asStable, params.getWantMintedFee());
     const afterFee = AmountMath.subtract(asStable, fee);
     AmountMath.isGTE(afterFee, wanted) ||
-      assert.fail(X`wanted ${wanted} is more than ${given} minus fees ${fee}`);
+      Fail`wanted ${wanted} is more than ${given} minus fees ${fee}`;
     mintMinted(asStable);
     try {
-      stageTransfer(seat, anchorPool, { In: given }, { Anchor: given });
-      stageTransfer(stage, seat, { Minted: afterFee }, { Out: afterFee });
-      stageTransfer(stage, feePool, { Minted: fee });
-      zcf.reallocate(seat, anchorPool, stage, feePool);
+      atomicRearrange(
+        zcf,
+        harden([
+          [seat, anchorPool, { In: given }, { Anchor: given }],
+          [stage, seat, { Minted: afterFee }, { Out: afterFee }],
+          [stage, feePool, { Minted: fee }],
+        ]),
+      );
     } catch (e) {
-      stage.clear();
-      anchorPool.clear();
-      feePool.clear();
-      // TODO(#6116) someday, reallocate should guarantee that this case cannot happen
+      // The treatment of `burnMinted` here is different than the
+      // one immediately above. This `burnMinted`
+      // happens only if the `atomicRearrange` *does* throw.
       burnMinted(asStable);
       throw e;
     }
-    totalMintedProvided = AmountMath.add(totalMintedProvided, asStable);
+    baggage.set(
+      'totalMintedProvided',
+      AmountMath.add(baggage.get('totalMintedProvided'), asStable),
+    );
   };
 
   /** @param {ZCFSeat} seat */
@@ -240,7 +335,7 @@ export const start = async (zcf, privateArgs, baggage) => {
   };
 
   /** @param {ZCFSeat} seat */
-  const wantmintedHook = seat => {
+  const wantMintedHook = seat => {
     const {
       give: { In: given },
       want: { Out: wanted } = { Out: undefined },
@@ -250,83 +345,100 @@ export const start = async (zcf, privateArgs, baggage) => {
     updateMetrics();
   };
 
-  const [anchorAmountShape, stableAmountShape] = await Promise.all([
-    E(anchorBrand).getAmountShape(),
-    E(stableBrand).getAmountShape(),
-  ]);
-
-  const PSMI = M.interface('PSM', {
-    getMetrics: M.call().returns(M.remotable('MetricsSubscriber')),
-    getPoolBalance: M.call().returns(anchorAmountShape),
-    makeWantMintedInvitation: M.call().returns(M.promise()),
-    makeGiveMintedInvitation: M.call().returns(M.promise()),
-    ...publicMixinAPI,
+  const { anchorAmountShape, stableAmountShape } = await provideAll(baggage, {
+    anchorAmountShape: () => E(anchorBrand).getAmountShape(),
+    stableAmountShape: () => E(stableBrand).getAmountShape(),
   });
 
-  const methods = {
-    getMetrics() {
-      return metricsSubscriber;
-    },
-    getPoolBalance() {
-      return anchorPool.getAmountAllocated('Anchor', anchorBrand);
-    },
-    makeWantMintedInvitation() {
-      return zcf.makeInvitation(
-        wantmintedHook,
-        'wantMinted',
-        undefined,
-        M.split({
-          give: { In: anchorAmountShape },
-          want: M.or({ Out: stableAmountShape }, {}),
-        }),
-      );
-    },
-    makeGiveMintedInvitation() {
-      return zcf.makeInvitation(
-        giveMintedHook,
-        'giveMinted',
-        undefined,
-        M.split({
-          give: { In: stableAmountShape },
-          want: M.or({ Out: anchorAmountShape }, {}),
-        }),
-      );
-    },
-    ...publicMixin,
-  };
-  const publicFacet = vivifyFarInstance(
+  const publicFacet = prepareExo(
     baggage,
     'Parity Stability Module',
-    PSMI,
-    methods,
-  );
-
-  // TODO why does this operation return an object with a single operation?
-  const { makeCollectFeesInvitation } = makeMakeCollectFeesInvitation(
-    zcf,
-    feePool,
-    stableBrand,
-    'Minted',
+    M.interface('PSM', {
+      getMetrics: M.call().returns(M.remotable('MetricsSubscriber')),
+      getPoolBalance: M.call().returns(anchorAmountShape),
+      getPublicTopics: M.call().returns(TopicsRecordShape),
+      makeWantMintedInvitation: M.call().returns(M.promise()),
+      makeGiveMintedInvitation: M.call().returns(M.promise()),
+      ...publicMixinAPI,
+    }),
+    {
+      getMetrics() {
+        return metricsKit.subscriber;
+      },
+      getPoolBalance() {
+        return anchorPool.getAmountAllocated('Anchor', anchorBrand);
+      },
+      getPublicTopics() {
+        return topics;
+      },
+      makeWantMintedInvitation() {
+        return zcf.makeInvitation(
+          wantMintedHook,
+          'wantMinted',
+          undefined,
+          M.splitRecord({
+            give: { In: anchorAmountShape },
+            want: M.or({ Out: stableAmountShape }, {}),
+          }),
+        );
+      },
+      makeGiveMintedInvitation() {
+        return zcf.makeInvitation(
+          giveMintedHook,
+          'giveMinted',
+          undefined,
+          M.splitRecord({
+            give: { In: stableAmountShape },
+            want: M.or({ Out: anchorAmountShape }, {}),
+          }),
+        );
+      },
+      ...publicMixin,
+    },
   );
 
-  // The creator facets are only accessibly to governance and bootstrap,
-  // and so do not need interface protection at this time. Additionally,
-  // all the operations take no arguments and so are largely defensive as is.
-  const limitedCreatorFacet = Far('Parity Stability Module', {
-    getRewardAllocation() {
-      return feePool.getCurrentAllocation();
-    },
-    makeCollectFeesInvitation() {
-      return makeCollectFeesInvitation();
+  const limitedCreatorFacet = prepareExo(
+    baggage,
+    'PSM machine',
+    M.interface('PSM machine', {
+      getRewardAllocation: M.call().returns(AmountKeywordRecordShape),
+      makeCollectFeesInvitation: M.call().returns(
+        M.promise(/* InvitationShape */),
+      ),
+      makeRestoreMetricsInvitation: M.call().returns(
+        M.promise(/* InvitationShape */),
+      ),
+    }),
+    {
+      getRewardAllocation() {
+        return feePool.getCurrentAllocation();
+      },
+      makeCollectFeesInvitation() {
+        return makeCollectFeesInvitation(zcf, feePool, stableBrand, 'Minted');
+      },
+      makeRestoreMetricsInvitation() {
+        return zcf.makeInvitation(
+          restoreMetricsHook,
+          'restoreMetrics',
+          undefined,
+          M.splitRecord({
+            give: {
+              Anchor: AnchorAmountShape,
+            },
+          }),
+        );
+      },
     },
-    ...creatorMixin,
-  });
+  );
 
-  const governorFacet = makeFarGovernorFacet(limitedCreatorFacet);
+  const { governorFacet } = makeDurableGovernorFacet(
+    baggage,
+    limitedCreatorFacet,
+  );
   return harden({
     creatorFacet: governorFacet,
     publicFacet,
   });
 };
 
-/** @typedef {Awaited<ReturnType<typeof start>>['publicFacet']} PsmPublicFacet */
+/** @typedef {Awaited<ReturnType<typeof prepare>>['publicFacet']} PsmPublicFacet */

package/src/psm/types.js

@@ -1 +1,3 @@
+// @jessie-check
+
 /** @typedef {import('./psm').PsmPublicFacet} PsmPublicFacet */