@agoric/ertp 0.16.3-dev-64cb69f.0 → 0.16.3-dev-c5284e4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/ertp",
-  "version": "0.16.3-dev-64cb69f.0+64cb69f",
+  "version": "0.16.3-dev-c5284e4.0+c5284e4",
   "description": "Electronic Rights Transfer Protocol (ERTP). A smart contract framework for exchanging electronic rights",
   "type": "module",
   "main": "src/index.js",
@@ -39,23 +39,24 @@
   },
   "homepage": "https://github.com/Agoric/agoric-sdk#readme",
   "dependencies": {
-    "@agoric/assert": "0.6.1-dev-64cb69f.0+64cb69f",
-    "@agoric/notifier": "0.6.3-dev-64cb69f.0+64cb69f",
-    "@agoric/store": "0.9.3-dev-64cb69f.0+64cb69f",
-    "@agoric/vat-data": "0.5.3-dev-64cb69f.0+64cb69f",
-    "@endo/eventual-send": "^1.1.0",
-    "@endo/far": "^1.0.2",
-    "@endo/marshal": "^1.1.0",
-    "@endo/nat": "^5.0.2",
-    "@endo/patterns": "^1.1.0",
-    "@endo/promise-kit": "^1.0.2"
+    "@agoric/assert": "0.6.1-dev-c5284e4.0+c5284e4",
+    "@agoric/notifier": "0.6.3-dev-c5284e4.0+c5284e4",
+    "@agoric/store": "0.9.3-dev-c5284e4.0+c5284e4",
+    "@agoric/vat-data": "0.5.3-dev-c5284e4.0+c5284e4",
+    "@agoric/zone": "0.2.3-dev-c5284e4.0+c5284e4",
+    "@endo/eventual-send": "^1.1.2",
+    "@endo/far": "^1.0.4",
+    "@endo/marshal": "^1.3.0",
+    "@endo/nat": "^5.0.4",
+    "@endo/patterns": "^1.2.0",
+    "@endo/promise-kit": "^1.0.4"
   },
   "devDependencies": {
-    "@agoric/swingset-vat": "0.32.3-dev-64cb69f.0+64cb69f",
-    "@endo/bundle-source": "^3.0.2",
+    "@agoric/swingset-vat": "0.32.3-dev-c5284e4.0+c5284e4",
+    "@endo/bundle-source": "^3.1.0",
     "@fast-check/ava": "^1.1.5",
     "ava": "^5.3.0",
-    "tsd": "^0.28.1"
+    "tsd": "^0.30.4"
   },
   "files": [
     "src",
@@ -84,7 +85,7 @@
     "access": "public"
   },
   "typeCoverage": {
-    "atLeast": 90.6
+    "atLeast": 90.56
   },
-  "gitHead": "64cb69fccd4b6ababc0f089dd80b4955a70f1da3"
+  "gitHead": "c5284e4721ad2702c4551f216bb8eed7abe4d7cf"
 }

package/src/amountStore.js

@@ -0,0 +1,32 @@
+import { AmountMath } from './amountMath.js';
+
+/**
+ * @template {AssetKind} [K=AssetKind]
+ * @typedef {object} AmountStore
+ * @property {() => Amount<K>} getAmount
+ * @property {(delta: Amount<K>) => void} increment
+ * @property {(delta: Amount<K>) => boolean} decrement
+ */
+
+/**
+ * @template {AssetKind} [K=AssetKind]
+ * @param {object} state
+ * @param {string} key
+ * @returns {AmountStore<K>}
+ */
+export const makeAmountStore = (state, key) => {
+  return harden({
+    getAmount: () => state[key],
+    increment: delta => {
+      state[key] = AmountMath.add(state[key], delta);
+    },
+    decrement: delta => {
+      if (AmountMath.isGTE(state[key], delta)) {
+        state[key] = AmountMath.subtract(state[key], delta);
+        return true;
+      }
+      return false;
+    },
+  });
+};
+harden(makeAmountStore);

package/src/index.js

@@ -3,3 +3,10 @@
 export * from './amountMath.js';
 export * from './issuerKit.js';
 export * from './typeGuards.js';
+
+/**
+ * Importing Baggage from `@agoric/ertp` is deprecated. Import Baggage from
+ * `@agoric/vat-data` instead
+ *
+ * @typedef {import('@agoric/vat-data').Baggage} Baggage
+ */

package/src/issuerKit.js

@@ -1,8 +1,9 @@
 // @jessie-check
 
-import { assert } from '@agoric/assert';
+import { assert, Fail } from '@agoric/assert';
 import { assertPattern } from '@agoric/store';
 import { makeScalarBigMapStore } from '@agoric/vat-data';
+import { makeDurableZone } from '@agoric/zone/durable.js';
 
 import { AssetKind, assertAssetKind } from './amountMath.js';
 import { coerceDisplayInfo } from './displayInfo.js';
@@ -10,10 +11,6 @@ import { preparePaymentLedger } from './paymentLedger.js';
 
 import './types-ambient.js';
 
-// TODO Why does TypeScript lose the `MapStore` typing of `Baggage` here, even
-// though it knows the correct type at the exporting `@agoric/vat-data`
-/** @typedef {import('@agoric/vat-data').Baggage} Baggage */
-
 /**
  * @template {AssetKind} K
  * @typedef {object} IssuerRecord
@@ -28,7 +25,9 @@ import './types-ambient.js';
  *
  * @template {AssetKind} K
  * @param {IssuerRecord<K>} issuerRecord
- * @param {Baggage} issuerBaggage
+ * @param {import('@agoric/zone').Zone} issuerZone
+ * @param {RecoverySetsOption} recoverySetsState Omitted from issuerRecord
+ *   because it was added in an upgrade.
  * @param {ShutdownWithFailure} [optShutdownWithFailure] If this issuer fails in
  *   the middle of an atomic action (which btw should never happen), it
  *   potentially leaves its ledger in a corrupted state. If this function was
@@ -40,7 +39,8 @@ import './types-ambient.js';
  */
 const setupIssuerKit = (
   { name, assetKind, displayInfo, elementShape },
-  issuerBaggage,
+  issuerZone,
+  recoverySetsState,
   optShutdownWithFailure = undefined,
 ) => {
   assert.typeof(name, 'string');
@@ -60,11 +60,12 @@ const setupIssuerKit = (
   /** @type {PaymentLedger<K>} */
   // @ts-expect-error could be instantiated with different subtype of AssetKind
   const { issuer, mint, brand, mintRecoveryPurse } = preparePaymentLedger(
-    issuerBaggage,
+    issuerZone,
     name,
     assetKind,
     cleanDisplayInfo,
     elementShape,
+    recoverySetsState,
     optShutdownWithFailure,
   );
 
@@ -80,13 +81,19 @@ harden(setupIssuerKit);
 
 /** The key at which the issuer record is stored. */
 const INSTANCE_KEY = 'issuer';
+/**
+ * The key at which the issuerKit's `RecoverySetsOption` state is stored.
+ * Introduced by an upgrade, so may be absent on a predecessor incarnation. See
+ * `RecoverySetsOption` for defaulting behavior.
+ */
+const RECOVERY_SETS_STATE = 'recoverySetsState';
 
 /**
  * Used _only_ to upgrade a predecessor issuerKit. Use `makeDurableIssuerKit` to
  * make a new one.
  *
  * @template {AssetKind} K
- * @param {Baggage} issuerBaggage
+ * @param {import('@agoric/vat-data').Baggage} issuerBaggage
  * @param {ShutdownWithFailure} [optShutdownWithFailure] If this issuer fails in
  *   the middle of an atomic action (which btw should never happen), it
  *   potentially leaves its ledger in a corrupted state. If this function was
@@ -94,21 +101,46 @@ const INSTANCE_KEY = 'issuer';
  *   unit of computation, like the enclosing vat, can be shutdown before
  *   anything else is corrupted by that corrupted state. See
  *   https://github.com/Agoric/agoric-sdk/issues/3434
+ * @param {RecoverySetsOption} [recoverySetsOption] Added in upgrade, so last
+ *   and optional. See `RecoverySetsOption` for defaulting behavior.
  * @returns {IssuerKit<K>}
  */
 export const upgradeIssuerKit = (
   issuerBaggage,
   optShutdownWithFailure = undefined,
+  recoverySetsOption = undefined,
 ) => {
   const issuerRecord = issuerBaggage.get(INSTANCE_KEY);
-  return setupIssuerKit(issuerRecord, issuerBaggage, optShutdownWithFailure);
+  const issuerZone = makeDurableZone(issuerBaggage);
+  const oldRecoverySetsState = issuerBaggage.has(RECOVERY_SETS_STATE)
+    ? issuerBaggage.get(RECOVERY_SETS_STATE)
+    : 'hasRecoverySets';
+  if (
+    oldRecoverySetsState === 'noRecoverySets' &&
+    recoverySetsOption === 'hasRecoverySets'
+  ) {
+    Fail`Cannot (yet?) upgrade from 'noRecoverySets' to 'hasRecoverySets'`;
+  }
+  if (
+    oldRecoverySetsState === 'hasRecoverySets' &&
+    recoverySetsOption === 'noRecoverySets'
+  ) {
+    Fail`Cannot (yet?) upgrade from 'hasRecoverySets' to 'noRecoverySets'`;
+  }
+  const recoverySetsState = recoverySetsOption || oldRecoverySetsState;
+  return setupIssuerKit(
+    issuerRecord,
+    issuerZone,
+    recoverySetsState,
+    optShutdownWithFailure,
+  );
 };
 harden(upgradeIssuerKit);
 
 /**
  * Does baggage already have an issuerKit?
  *
- * @param {Baggage} baggage
+ * @param {import('@agoric/vat-data').Baggage} baggage
  */
 export const hasIssuer = baggage => baggage.has(INSTANCE_KEY);
 
@@ -121,8 +153,14 @@ export const hasIssuer = baggage => baggage.has(INSTANCE_KEY);
  * typically, the amount of an invitation payment is a singleton set. Such a
  * payment is often referred to in the singular as "an invitation".)
  *
+ * `recoverySetsOption` added in upgrade. Note that `IssuerOptionsRecord` is
+ * never stored, so we never need to worry about inheriting one from a
+ * predecessor predating the introduction of recovery sets. See
+ * `RecoverySetsOption` for defaulting behavior.
+ *
  * @typedef {Partial<{
  *   elementShape: Pattern;
+ *   recoverySetsOption: RecoverySetsOption;
  * }>} IssuerOptionsRecord
  */
 
@@ -142,7 +180,7 @@ export const hasIssuer = baggage => baggage.has(INSTANCE_KEY);
  *   basic fungible tokens.
  *
  *   `displayInfo` gives information to the UI on how to display the amount.
- * @param {Baggage} issuerBaggage
+ * @param {import('@agoric/vat-data').Baggage} issuerBaggage
  * @param {string} name
  * @param {K} [assetKind]
  * @param {AdditionalDisplayInfo} [displayInfo]
@@ -163,11 +201,24 @@ export const makeDurableIssuerKit = (
   assetKind = AssetKind.NAT,
   displayInfo = harden({}),
   optShutdownWithFailure = undefined,
-  { elementShape = undefined } = {},
+  { elementShape = undefined, recoverySetsOption = undefined } = {},
 ) => {
-  const issuerData = harden({ name, assetKind, displayInfo, elementShape });
+  const issuerData = harden({
+    name,
+    assetKind,
+    displayInfo,
+    elementShape,
+  });
   issuerBaggage.init(INSTANCE_KEY, issuerData);
-  return setupIssuerKit(issuerData, issuerBaggage, optShutdownWithFailure);
+  const issuerZone = makeDurableZone(issuerBaggage);
+  const recoverySetsState = recoverySetsOption || 'hasRecoverySets';
+  issuerBaggage.init(RECOVERY_SETS_STATE, recoverySetsState);
+  return setupIssuerKit(
+    issuerData,
+    issuerZone,
+    recoverySetsState,
+    optShutdownWithFailure,
+  );
 };
 harden(makeDurableIssuerKit);
 
@@ -187,7 +238,7 @@ harden(makeDurableIssuerKit);
  *   basic fungible tokens.
  *
  *   `displayInfo` gives information to the UI on how to display the amount.
- * @param {Baggage} issuerBaggage
+ * @param {import('@agoric/vat-data').Baggage} issuerBaggage
  * @param {string} name
  * @param {K} [assetKind]
  * @param {AdditionalDisplayInfo} [displayInfo]
@@ -211,12 +262,19 @@ export const prepareIssuerKit = (
   options = {},
 ) => {
   if (hasIssuer(issuerBaggage)) {
-    const { elementShape: _ = undefined } = options;
-    const issuerKit = upgradeIssuerKit(issuerBaggage, optShutdownWithFailure);
+    const { elementShape: _ = undefined, recoverySetsOption = undefined } =
+      options;
+    const issuerKit = upgradeIssuerKit(
+      issuerBaggage,
+      optShutdownWithFailure,
+      recoverySetsOption,
+    );
 
     // TODO check consistency with name, assetKind, displayInfo, elementShape.
     // Consistency either means that these are the same, or that they differ
-    // in a direction we are prepared to upgrade.
+    // in a direction we are prepared to upgrade. Note that it is the
+    // responsibility of `upgradeIssuerKit` to check consistency of
+    // `recoverySetsOption`, so continue to not do that here.
 
     // @ts-expect-error Type parameter confusion.
     return issuerKit;
@@ -274,7 +332,7 @@ export const makeIssuerKit = (
   assetKind = AssetKind.NAT,
   displayInfo = harden({}),
   optShutdownWithFailure = undefined,
-  { elementShape = undefined } = {},
+  { elementShape = undefined, recoverySetsOption = undefined } = {},
 ) =>
   makeDurableIssuerKit(
     makeScalarBigMapStore('dropped issuer kit', { durable: true }),
@@ -282,6 +340,6 @@ export const makeIssuerKit = (
     assetKind,
     displayInfo,
     optShutdownWithFailure,
-    { elementShape },
+    { elementShape, recoverySetsOption },
   );
 harden(makeIssuerKit);

package/src/mathHelpers/copyBagMathHelpers.js

@@ -12,10 +12,10 @@ import {
 } from '@agoric/store';
 import '../types-ambient.js';
 
-/** @type {CopyBag} */
+/** @type {import('@endo/patterns').CopyBag} */
 const empty = makeCopyBag([]);
 
-/** @type {MathHelpers<CopyBag>} */
+/** @type {MathHelpers<import('@endo/patterns').CopyBag>} */
 export const copyBagMathHelpers = harden({
   doCoerce: bag => {
     mustMatch(bag, M.bag(), 'bag of amount');

package/src/payment.js

@@ -1,26 +1,18 @@
 // @jessie-check
 
 import { initEmpty } from '@agoric/store';
-import { prepareExoClass } from '@agoric/vat-data';
-
-/** @typedef {import('@endo/patterns').MethodGuard} MethodGuard */
-/**
- * @template {Record<string | symbol, MethodGuard>} [T=Record<string | symbol, MethodGuard>]
- * @typedef {import('@endo/patterns').InterfaceGuard<T>} InterfaceGuard
- */
-/** @typedef {import('@agoric/vat-data').Baggage} Baggage */
 
+// TODO Type InterfaceGuard better than InterfaceGuard<any>
 /**
  * @template {AssetKind} K
- * @param {Baggage} issuerBaggage
+ * @param {import('@agoric/zone').Zone} issuerZone
  * @param {string} name
  * @param {Brand<K>} brand
- * @param {InterfaceGuard} PaymentI
+ * @param {import('@endo/patterns').InterfaceGuard<any>} PaymentI
  * @returns {() => Payment<K>}
  */
-export const preparePaymentKind = (issuerBaggage, name, brand, PaymentI) => {
-  const makePayment = prepareExoClass(
-    issuerBaggage,
+export const preparePaymentKind = (issuerZone, name, brand, PaymentI) => {
+  const makePayment = issuerZone.exoClass(
     `${name} payment`,
     PaymentI,
     initEmpty,

package/src/paymentLedger.js

@@ -3,11 +3,6 @@
 /* eslint-disable no-use-before-define */
 import { isPromise } from '@endo/promise-kit';
 import { mustMatch, M, keyEQ } from '@agoric/store';
-import {
-  provideDurableWeakMapStore,
-  prepareExo,
-  provide,
-} from '@agoric/vat-data';
 import { AmountMath } from './amountMath.js';
 import { preparePaymentKind } from './payment.js';
 import { preparePurseKind } from './purse.js';
@@ -15,8 +10,6 @@ import { preparePurseKind } from './purse.js';
 import '@agoric/store/exported.js';
 import { BrandI, makeIssuerInterfaces } from './typeGuards.js';
 
-/** @typedef {import('@agoric/vat-data').Baggage} Baggage */
-
 const { details: X, quote: q, Fail } = assert;
 
 /**
@@ -74,25 +67,31 @@ const amountShapeFromElementShape = (brand, assetKind, elementShape) => {
  * minting and transfer authority originates here.
  *
  * @template {AssetKind} K
- * @param {Baggage} issuerBaggage
+ * @param {import('@agoric/zone').Zone} issuerZone
  * @param {string} name
  * @param {K} assetKind
  * @param {DisplayInfo<K>} displayInfo
  * @param {Pattern} elementShape
+ * @param {RecoverySetsOption} recoverySetsState
  * @param {ShutdownWithFailure} [optShutdownWithFailure]
  * @returns {PaymentLedger<K>}
  */
 export const preparePaymentLedger = (
-  issuerBaggage,
+  issuerZone,
   name,
   assetKind,
   displayInfo,
   elementShape,
+  recoverySetsState,
   optShutdownWithFailure = undefined,
 ) => {
   /** @type {Brand<K>} */
-  // @ts-expect-error XXX callWhen
-  const brand = prepareExo(issuerBaggage, `${name} brand`, BrandI, {
+  // Should be
+  // at-ts-expect-error XXX callWhen
+  // but ran into the usual disagreement between local lint and CI
+  // eslint-disable-next-line @typescript-eslint/prefer-ts-expect-error
+  // @ts-ignore
+  const brand = issuerZone.exo(`${name} brand`, BrandI, {
     isMyIssuer(allegedIssuer) {
       // BrandI delays calling this method until `allegedIssuer` is a Remotable
       return allegedIssuer === issuer;
@@ -121,7 +120,7 @@ export const preparePaymentLedger = (
     amountShape,
   );
 
-  const makePayment = preparePaymentKind(issuerBaggage, name, brand, PaymentI);
+  const makePayment = preparePaymentKind(issuerZone, name, brand, PaymentI);
 
   /** @type {ShutdownWithFailure} */
   const shutdownLedgerWithFailure = reason => {
@@ -139,18 +138,16 @@ export const preparePaymentLedger = (
   };
 
   /** @type {WeakMapStore<Payment, Amount>} */
-  const paymentLedger = provideDurableWeakMapStore(
-    issuerBaggage,
-    'paymentLedger',
-    { valueShape: amountShape },
-  );
+  const paymentLedger = issuerZone.weakMapStore('paymentLedger', {
+    valueShape: amountShape,
+  });
 
   /**
-   * A withdrawn live payment is associated with the recovery set of the purse
-   * it was withdrawn from. Let's call these "recoverable" payments. All
-   * recoverable payments are live, but not all live payments are recoverable.
-   * We do the bookkeeping for payment recovery with this weakmap from
-   * recoverable payments to the recovery set they are in. A bunch of
+   * A (non-empty) withdrawn live payment is associated with the recovery set of
+   * the purse it was withdrawn from. Let's call these "recoverable" payments.
+   * All recoverable payments are live, but not all live payments are
+   * recoverable. We do the bookkeeping for payment recovery with this weakmap
+   * from recoverable payments to the recovery set they are in. A bunch of
    * interesting invariants here:
    *
    * - Every payment that is a key in the outer `paymentRecoverySets` weakMap is
@@ -162,12 +159,12 @@ export const preparePaymentLedger = (
    * - A purse's recovery set only contains payments withdrawn from that purse and
    *   not yet consumed.
    *
+   * If `recoverySetsState === 'noRecoverySets'`, then nothing should ever be
+   * added to this WeakStore.
+   *
    * @type {WeakMapStore<Payment, SetStore<Payment>>}
    */
-  const paymentRecoverySets = provideDurableWeakMapStore(
-    issuerBaggage,
-    'paymentRecoverySets',
-  );
+  const paymentRecoverySets = issuerZone.weakMapStore('paymentRecoverySets');
 
   /**
    * To maintain the invariants listed in the `paymentRecoverySets` comment,
@@ -178,7 +175,11 @@ export const preparePaymentLedger = (
    * @param {SetStore<Payment>} [optRecoverySet]
    */
   const initPayment = (payment, amount, optRecoverySet = undefined) => {
-    if (optRecoverySet !== undefined) {
+    if (recoverySetsState === 'noRecoverySets') {
+      optRecoverySet === undefined ||
+        Fail`when recoverSetsState === 'noRecoverySets', optRecoverySet must be empty`;
+    }
+    if (optRecoverySet !== undefined && !AmountMath.isEmpty(amount)) {
       optRecoverySet.add(payment);
       paymentRecoverySets.init(payment, optRecoverySet);
     }
@@ -200,10 +201,6 @@ export const preparePaymentLedger = (
     }
   };
 
-  /** @type {(left: Amount, right: Amount) => Amount} */
-  const add = (left, right) => AmountMath.add(left, right, brand);
-  /** @type {(left: Amount, right: Amount) => Amount} */
-  const subtract = (left, right) => AmountMath.subtract(left, right, brand);
   /** @type {(allegedAmount: Amount) => Amount} */
   const coerce = allegedAmount => AmountMath.coerce(brand, allegedAmount);
   /** @type {(left: Amount, right: Amount) => boolean} */
@@ -239,17 +236,13 @@ export const preparePaymentLedger = (
   /**
    * Used by the purse code to implement purse.deposit
    *
-   * @param {Amount} currentBalance - the current balance of the purse before a
-   *   deposit
-   * @param {(newPurseBalance: Amount) => void} updatePurseBalance - commit the
-   *   purse balance
+   * @param {import('./amountStore.js').AmountStore} balanceStore
    * @param {Payment} srcPayment
    * @param {Pattern} [optAmountShape]
    * @returns {Amount}
    */
   const depositInternal = (
-    currentBalance,
-    updatePurseBalance,
+    balanceStore,
     srcPayment,
     optAmountShape = undefined,
   ) => {
@@ -261,13 +254,12 @@ export const preparePaymentLedger = (
     assertLivePayment(srcPayment);
     const srcPaymentBalance = paymentLedger.get(srcPayment);
     assertAmountConsistent(srcPaymentBalance, optAmountShape);
-    const newPurseBalance = add(srcPaymentBalance, currentBalance);
     try {
       // COMMIT POINT
       // Move the assets in `srcPayment` into this purse, using up the
       // source payment, such that total assets are conserved.
       deletePayment(srcPayment);
-      updatePurseBalance(newPurseBalance);
+      balanceStore.increment(srcPaymentBalance);
     } catch (err) {
       shutdownLedgerWithFailure(err);
       throw err;
@@ -278,30 +270,19 @@ export const preparePaymentLedger = (
   /**
    * Used by the purse code to implement purse.withdraw
    *
-   * @param {Amount} currentBalance - the current balance of the purse before a
-   *   withdrawal
-   * @param {(newPurseBalance: Amount) => void} updatePurseBalance - commit the
-   *   purse balance
+   * @param {import('./amountStore.js').AmountStore} balanceStore
    * @param {Amount} amount - the amount to be withdrawn
-   * @param {SetStore<Payment>} recoverySet
+   * @param {SetStore<Payment>} [recoverySet]
    * @returns {Payment}
    */
-  const withdrawInternal = (
-    currentBalance,
-    updatePurseBalance,
-    amount,
-    recoverySet,
-  ) => {
+  const withdrawInternal = (balanceStore, amount, recoverySet = undefined) => {
     amount = coerce(amount);
-    AmountMath.isGTE(currentBalance, amount) ||
-      Fail`Withdrawal of ${amount} failed because the purse only contained ${currentBalance}`;
-    const newPurseBalance = subtract(currentBalance, amount);
-
     const payment = makePayment();
+    // COMMIT POINT Move the withdrawn assets from this purse into
+    // payment. Total assets must remain conserved.
+    balanceStore.decrement(amount) ||
+      Fail`Withdrawal of ${amount} failed because the purse only contained ${balanceStore.getAmount()}`;
     try {
-      // COMMIT POINT Move the withdrawn assets from this purse into
-      // payment. Total assets must remain conserved.
-      updatePurseBalance(newPurseBalance);
       initPayment(payment, amount, recoverySet);
     } catch (err) {
       shutdownLedgerWithFailure(err);
@@ -313,7 +294,7 @@ export const preparePaymentLedger = (
   /** @type {() => Purse<K>} */
   // @ts-expect-error type parameter confusion
   const makeEmptyPurse = preparePurseKind(
-    issuerBaggage,
+    issuerZone,
     name,
     assetKind,
     brand,
@@ -322,11 +303,17 @@ export const preparePaymentLedger = (
       depositInternal,
       withdrawInternal,
     }),
+    recoverySetsState,
+    paymentRecoverySets,
   );
 
   /** @type {Issuer<K>} */
-  // @ts-expect-error cast due to callWhen discrepancy
-  const issuer = prepareExo(issuerBaggage, `${name} issuer`, IssuerI, {
+  // Should be
+  // at-ts-expect-error cast due to callWhen discrepancy
+  // but ran into the usual disagreement between local lint and CI
+  // eslint-disable-next-line @typescript-eslint/prefer-ts-expect-error
+  // @ts-ignore
+  const issuer = issuerZone.exo(`${name} issuer`, IssuerI, {
     getBrand() {
       return brand;
     },
@@ -379,20 +366,28 @@ export const preparePaymentLedger = (
    * Because the `mintRecoveryPurse` is placed in baggage, even if the caller of
    * `makeIssuerKit` drops it on the floor, it can still be recovered in an
    * emergency upgrade.
-   *
-   * @type {Purse<K>}
    */
-  const mintRecoveryPurse = provide(issuerBaggage, 'mintRecoveryPurse', () =>
-    makeEmptyPurse(),
+  // Should be
+  // at-ts-expect-error checked cast
+  // but ran into the usual disagreement between local lint and IDE lint.
+  // Don't know yet about lint under CI.
+  // eslint-disable-next-line @typescript-eslint/prefer-ts-expect-error
+  // @ts-ignore
+  const mintRecoveryPurse = /** @type {Purse<K>} */ (
+    issuerZone.makeOnce('mintRecoveryPurse', () => makeEmptyPurse())
   );
 
   /** @type {Mint<K>} */
-  const mint = prepareExo(issuerBaggage, `${name} mint`, MintI, {
+  const mint = issuerZone.exo(`${name} mint`, MintI, {
     getIssuer() {
       return issuer;
     },
     mintPayment(newAmount) {
-      // @ts-expect-error checked cast
+      // Should be
+      // at-ts-expect-error checked cast
+      // but ran into the usual disagreement between local lint and CI
+      // eslint-disable-next-line @typescript-eslint/prefer-ts-expect-error
+      // @ts-ignore
       newAmount = coerce(newAmount);
       mustMatch(newAmount, amountShape, 'minted amount');
       // `rawPayment` is not associated with any recovery set, and

package/src/purse.js

@@ -1,45 +1,72 @@
-import { M } from '@agoric/store';
-import { prepareExoClassKit, makeScalarBigSetStore } from '@agoric/vat-data';
+import { M, makeCopySet } from '@agoric/store';
 import { AmountMath } from './amountMath.js';
 import { makeTransientNotifierKit } from './transientNotifier.js';
-
-// TODO `InterfaceGuard` type parameter
-/** @typedef {import('@endo/patterns').InterfaceGuard} InterfaceGuard */
-/** @typedef {import('@agoric/vat-data').Baggage} Baggage */
+import { makeAmountStore } from './amountStore.js';
 
 const { Fail } = assert;
 
+const EMPTY_COPY_SET = makeCopySet([]);
+
+// TODO Type InterfaceGuard better than InterfaceGuard<any>
 /**
- * @param {Baggage} issuerBaggage
+ * @param {import('@agoric/zone').Zone} issuerZone
  * @param {string} name
  * @param {AssetKind} assetKind
  * @param {Brand} brand
  * @param {{
- *   purse: InterfaceGuard;
- *   depositFacet: InterfaceGuard;
+ *   purse: import('@endo/patterns').InterfaceGuard<any>;
+ *   depositFacet: import('@endo/patterns').InterfaceGuard<any>;
  * }} PurseIKit
  * @param {{
  *   depositInternal: any;
  *   withdrawInternal: any;
  * }} purseMethods
+ * @param {RecoverySetsOption} recoverySetsState
+ * @param {WeakMapStore<Payment, SetStore<Payment>>} paymentRecoverySets
  */
 export const preparePurseKind = (
-  issuerBaggage,
+  issuerZone,
   name,
   assetKind,
   brand,
   PurseIKit,
   purseMethods,
+  recoverySetsState,
+  paymentRecoverySets,
 ) => {
   const amountShape = brand.getAmountShape();
 
   // Note: Virtual for high cardinality, but *not* durable, and so
   // broken across an upgrade.
+  // TODO propagate zonifying to notifiers, maybe?
   const { provideNotifier, update: updateBalance } = makeTransientNotifierKit();
 
-  const updatePurseBalance = (state, newPurseBalance, purse) => {
-    state.currentBalance = newPurseBalance;
-    updateBalance(purse, purse.getCurrentAmount());
+  /**
+   * If `recoverySetsState === 'hasRecoverySets'` (the normal state), then just
+   * return `state.recoverySet`.
+   *
+   * If `recoverySetsState === 'noRecoverySets'`, return `undefined`. Callers
+   * must be aware that the `undefined` return happens iff `recoverySetsState
+   * === 'noRecoverySets'`, and to avoid storing or retrieving anything from the
+   * actual recovery set.
+   *
+   * @param {{ recoverySet: SetStore<Payment> }} state
+   * @returns {SetStore<Payment> | undefined}
+   */
+  const maybeRecoverySet = state => {
+    const { recoverySet } = state;
+    if (recoverySetsState === 'hasRecoverySets') {
+      return recoverySet;
+    } else {
+      recoverySetsState === 'noRecoverySets' ||
+        Fail`recoverSetsState must be noRecoverySets if it isn't hasRecoverSets`;
+      paymentRecoverySets !== undefined ||
+        Fail`paymentRecoverySets must always be defined`;
+      recoverySet.getSize() === 0 ||
+        Fail`With noRecoverySets, recoverySet must be empty`;
+
+      return undefined;
+    }
   };
 
   // - This kind is a pair of purse and depositFacet that have a 1:1
@@ -49,17 +76,14 @@ export const preparePurseKind = (
   //   that created depositFacet as needed. But this approach ensures a constant
   //   identity for the facet and exercises the multi-faceted object style.
   const { depositInternal, withdrawInternal } = purseMethods;
-  const makePurseKit = prepareExoClassKit(
-    issuerBaggage,
+  const makePurseKit = issuerZone.exoClassKit(
     `${name} Purse`,
     PurseIKit,
     () => {
       const currentBalance = AmountMath.makeEmpty(brand, assetKind);
 
       /** @type {SetStore<Payment>} */
-      const recoverySet = makeScalarBigSetStore('recovery set', {
-        durable: true,
-      });
+      const recoverySet = issuerZone.detached().setStore('recovery set');
 
       return {
         currentBalance,
@@ -72,28 +96,36 @@ export const preparePurseKind = (
           // PurseI does *not* delay `deposit` until `srcPayment` is fulfulled.
           // See the comments on PurseI.deposit in typeGuards.js
           const { state } = this;
+          const { purse } = this.facets;
+          const balanceStore = makeAmountStore(state, 'currentBalance');
           // Note COMMIT POINT within deposit.
-          return depositInternal(
-            state.currentBalance,
-            newPurseBalance =>
-              updatePurseBalance(state, newPurseBalance, this.facets.purse),
+          const srcPaymentBalance = depositInternal(
+            balanceStore,
             srcPayment,
             optAmountShape,
           );
+          updateBalance(purse, balanceStore.getAmount());
+          return srcPaymentBalance;
         },
         withdraw(amount) {
           const { state } = this;
+          const { purse } = this.facets;
+
+          const optRecoverySet = maybeRecoverySet(state);
+          const balanceStore = makeAmountStore(state, 'currentBalance');
           // Note COMMIT POINT within withdraw.
-          return withdrawInternal(
-            state.currentBalance,
-            newPurseBalance =>
-              updatePurseBalance(state, newPurseBalance, this.facets.purse),
+          const payment = withdrawInternal(
+            balanceStore,
             amount,
-            state.recoverySet,
+            optRecoverySet,
           );
+          updateBalance(purse, balanceStore.getAmount());
+          return payment;
         },
         getCurrentAmount() {
-          return this.state.currentBalance;
+          const { state } = this;
+          const balanceStore = makeAmountStore(state, 'currentBalance');
+          return balanceStore.getAmount();
         },
         getCurrentAmountNotifier() {
           return provideNotifier(this.facets.purse);
@@ -107,18 +139,27 @@ export const preparePurseKind = (
         },
 
         getRecoverySet() {
-          return this.state.recoverySet.snapshot();
+          const { state } = this;
+          const optRecoverySet = maybeRecoverySet(state);
+          if (optRecoverySet === undefined) {
+            return EMPTY_COPY_SET;
+          }
+          return optRecoverySet.snapshot();
         },
         recoverAll() {
           const { state, facets } = this;
           let amount = AmountMath.makeEmpty(brand, assetKind);
-          for (const payment of state.recoverySet.keys()) {
+          const optRecoverySet = maybeRecoverySet(state);
+          if (optRecoverySet === undefined) {
+            return amount; // empty at this time
+          }
+          for (const payment of optRecoverySet.keys()) {
             // This does cause deletions from the set while iterating,
             // but this special case is allowed.
             const delta = facets.purse.deposit(payment);
             amount = AmountMath.add(amount, delta, brand);
           }
-          state.recoverySet.getSize() === 0 ||
+          optRecoverySet.getSize() === 0 ||
             Fail`internal: Remaining unrecovered payments: ${facets.purse.getRecoverySet()}`;
           return amount;
         },

package/src/types-ambient.js

@@ -2,11 +2,6 @@
 
 /// <reference types="ses"/>
 
-/**
- * @template {Key} [K=Key]
- * @typedef {import('@endo/patterns').CopyBag<K>} CopyBag
- */
-
 /**
  * @template {AssetKind} [K=AssetKind]
  * @typedef {object} Amount Amounts are descriptions of digital assets,
@@ -22,8 +17,8 @@
  */
 
 /**
- * @typedef {NatValue | SetValue | CopySet | CopyBag} AmountValue An
- *   `AmountValue` describes a set or quantity of assets that can be owned or
+ * @typedef {NatValue | SetValue | CopySet | import('@endo/patterns').CopyBag} AmountValue
+ *   An `AmountValue` describes a set or quantity of assets that can be owned or
  *   shared.
  *
  *   A fungible `AmountValue` uses a non-negative bigint to represent a quantity
@@ -58,7 +53,7 @@
  *   : K extends 'copySet'
  *   ? CopySet
  *   : K extends 'copyBag'
- *   ? CopyBag
+ *   ? import('@endo/patterns').CopyBag
  *   : never} AssetValueForKind
  */
 
@@ -70,7 +65,7 @@
  *   ? 'set'
  *   : V extends CopySet
  *   ? 'copySet'
- *   : V extends CopyBag
+ *   : V extends import('@endo/patterns').CopyBag
  *   ? 'copyBag'
  *   : never} AssetKindForValue
  */
@@ -178,8 +173,9 @@
  * @template {AssetKind} [K=AssetKind]
  * @typedef {object} PaymentLedger
  * @property {Mint<K>} mint
- * @property {Purse<K>} mintRecoveryPurse Useful only to get the recovery set
- *   associated with minted payments that are still live.
+ * @property {Purse<K>} mintRecoveryPurse Externally useful only if this issuer
+ *   uses recovery sets. Can be used to get the recovery set associated with
+ *   minted payments that are still live.
  * @property {Issuer<K>} issuer
  * @property {Brand<K>} brand
  */
@@ -188,8 +184,9 @@
  * @template {AssetKind} [K=AssetKind]
  * @typedef {object} IssuerKit
  * @property {Mint<K>} mint
- * @property {Purse<K>} mintRecoveryPurse Useful only to get the recovery set
- *   associated with minted payments that are still live.
+ * @property {Purse<K>} mintRecoveryPurse Externally useful only if this issuer
+ *   uses recovery sets. Can be used to get the recovery set associated with
+ *   minted payments that are still live.
  * @property {Issuer<K>} issuer
  * @property {Brand<K>} brand
  * @property {DisplayInfo} displayInfo
@@ -222,6 +219,24 @@
 
 // /////////////////////////// Purse / Payment /////////////////////////////////
 
+/**
+ * Issuers first became durable with mandatory recovery sets. Later they were
+ * made optional, but there is no support for converting from one state to the
+ * other. Thus, absence of a `RecoverySetsOption` state is equivalent to
+ * `'hasRecoverySets'`. In the absence of a `recoverySetsOption` parameter,
+ * upgradeIssuerKit defaults to the predecessor's `RecoverySetsOption` state, or
+ * `'hasRecoverySets'` if none.
+ *
+ * At this time, issuers started in one of the states (`'noRecoverySets'`, or
+ * `'hasRecoverySets'`) cannot be converted to the other on upgrade. If this
+ * transition is needed, it can likely be supported in a future upgrade. File an
+ * issue on github and explain what you need and why.
+ *
+ * @typedef {'hasRecoverySets' | 'noRecoverySets'} RecoverySetsOption
+ */
+
+// /////////////////////////// Purse / Payment /////////////////////////////////
+
 /**
  * @callback DepositFacetReceive
  * @param {Payment} payment
@@ -281,10 +296,14 @@
  *   can spend the assets at stake on other things. Afterwards, if the recipient
  *   of the original check finally gets around to depositing it, their deposit
  *   fails.
+ *
+ *   Returns an empty set if this issuer does not support recovery sets.
  * @property {() => Amount<K>} recoverAll For use in emergencies, such as coming
  *   back from a traumatic crash and upgrade. This deposits all the payments in
  *   this purse's recovery set into the purse itself, returning the total amount
  *   of assets recovered.
+ *
+ *   Returns an empty amount if this issuer does not support recovery sets.
  */
 
 /**

package/src/types.js

@@ -3,11 +3,6 @@ export {};
 
 /// <reference types="ses"/>
 
-/**
- * @template {Key} [K=Key]
- * @typedef {import('@endo/patterns').CopyBag<K>} CopyBag
- */
-
 /**
  * @template {AssetKind} [K=AssetKind]
  * @typedef {object} Amount Amounts are descriptions of digital assets,
@@ -23,8 +18,8 @@ export {};
  */
 
 /**
- * @typedef {NatValue | SetValue | CopySet | CopyBag} AmountValue An
- *   `AmountValue` describes a set or quantity of assets that can be owned or
+ * @typedef {NatValue | SetValue | CopySet | import('@endo/patterns').CopyBag} AmountValue
+ *   An `AmountValue` describes a set or quantity of assets that can be owned or
  *   shared.
  *
  *   A fungible `AmountValue` uses a non-negative bigint to represent a quantity
@@ -59,7 +54,7 @@ export {};
  *   : K extends 'copySet'
  *   ? CopySet
  *   : K extends 'copyBag'
- *   ? CopyBag
+ *   ? import('@endo/patterns').CopyBag
  *   : never} AssetValueForKind
  */
 
@@ -71,7 +66,7 @@ export {};
  *   ? 'set'
  *   : V extends CopySet
  *   ? 'copySet'
- *   : V extends CopyBag
+ *   : V extends import('@endo/patterns').CopyBag
  *   ? 'copyBag'
  *   : never} AssetKindForValue
  */
@@ -179,8 +174,9 @@ export {};
  * @template {AssetKind} [K=AssetKind]
  * @typedef {object} PaymentLedger
  * @property {Mint<K>} mint
- * @property {Purse<K>} mintRecoveryPurse Useful only to get the recovery set
- *   associated with minted payments that are still live.
+ * @property {Purse<K>} mintRecoveryPurse Externally useful only if this issuer
+ *   uses recovery sets. Can be used to get the recovery set associated with
+ *   minted payments that are still live.
  * @property {Issuer<K>} issuer
  * @property {Brand<K>} brand
  */
@@ -189,8 +185,9 @@ export {};
  * @template {AssetKind} [K=AssetKind]
  * @typedef {object} IssuerKit
  * @property {Mint<K>} mint
- * @property {Purse<K>} mintRecoveryPurse Useful only to get the recovery set
- *   associated with minted payments that are still live.
+ * @property {Purse<K>} mintRecoveryPurse Externally useful only if this issuer
+ *   uses recovery sets. Can be used to get the recovery set associated with
+ *   minted payments that are still live.
  * @property {Issuer<K>} issuer
  * @property {Brand<K>} brand
  * @property {DisplayInfo} displayInfo
@@ -223,6 +220,24 @@ export {};
 
 // /////////////////////////// Purse / Payment /////////////////////////////////
 
+/**
+ * Issuers first became durable with mandatory recovery sets. Later they were
+ * made optional, but there is no support for converting from one state to the
+ * other. Thus, absence of a `RecoverySetsOption` state is equivalent to
+ * `'hasRecoverySets'`. In the absence of a `recoverySetsOption` parameter,
+ * upgradeIssuerKit defaults to the predecessor's `RecoverySetsOption` state, or
+ * `'hasRecoverySets'` if none.
+ *
+ * At this time, issuers started in one of the states (`'noRecoverySets'`, or
+ * `'hasRecoverySets'`) cannot be converted to the other on upgrade. If this
+ * transition is needed, it can likely be supported in a future upgrade. File an
+ * issue on github and explain what you need and why.
+ *
+ * @typedef {'hasRecoverySets' | 'noRecoverySets'} RecoverySetsOption
+ */
+
+// /////////////////////////// Purse / Payment /////////////////////////////////
+
 /**
  * @callback DepositFacetReceive
  * @param {Payment} payment
@@ -282,10 +297,14 @@ export {};
  *   can spend the assets at stake on other things. Afterwards, if the recipient
  *   of the original check finally gets around to depositing it, their deposit
  *   fails.
+ *
+ *   Returns an empty set if this issuer does not support recovery sets.
  * @property {() => Amount<K>} recoverAll For use in emergencies, such as coming
  *   back from a traumatic crash and upgrade. This deposits all the payments in
  *   this purse's recovery set into the purse itself, returning the total amount
  *   of assets recovered.
+ *
+ *   Returns an empty amount if this issuer does not support recovery sets.
  */
 
 /**