feat(ertp): review suggestions

packages/ERTP/src/issuerKit.js

@@ -86,13 +86,13 @@ harden(setupIssuerKit);
 const INSTANCE_KEY = 'issuer';
 /**
  * The key at which the issuerKit's `RecoverySetsOption` state is stored.
- * Introduced by an upgrade, so may be absent on an ancestor. See
+ * 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 an ancestor issuerKit. Use `makeDurableIssuerKit` to
+ * Used _only_ to upgrade a predecessor issuerKit. Use `makeDurableIssuerKit` to
  * make a new one.
  *
  * @template {AssetKind} K
@@ -126,16 +126,16 @@ export const upgradeIssuerKit = (
   const recoverySetsState = recoverySetsOption || oldRecoverySetsState;
   return setupIssuerKit(
     issuerRecord,
-    issuerBaggage,
     recoverySetsState,
+    issuerBaggage,
     optShutdownWithFailure,
   );
 };
 harden(upgradeIssuerKit);
 
 /**
  * Confusingly, `prepareIssuerKit` was the original name for `upgradeIssuerKit`,
- * even though it is used only to upgrade an ancestor issuerKit. Use
+ * even though it is used only to upgrade a predecessor issuerKit. Use
  * `makeDurableIssuerKit` to make a new one.
  *
  * @deprecated Use `upgradeIssuerKit` instead if that's what you want. Or
@@ -161,9 +161,9 @@ export const hasIssuer = baggage => baggage.has(INSTANCE_KEY);
  * 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 an ancestor
- * predating the introduction of recovery sets. See `RecoverySetsOption` for
- * defaulting behavior.
+ * 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;
@@ -229,9 +229,9 @@ export const makeDurableIssuerKit = (
 harden(makeDurableIssuerKit);
 
 /**
- * What _should_ have been named `prepareIssuerKit`. Used to either revive an
- * ancestor issuer kit, or to make a new durable if it absent, and to place it
- * in baggage for the next successor.
+ * What _should_ have been named `prepareIssuerKit`. Used to either revive a
+ * predecessor issuerKit, or to make a new durable one if it is absent, and to
+ * place it in baggage for the next successor.
  *
  * @template {AssetKind} K The name becomes part of the brand in asset
  *   descriptions. The name is useful for debugging and double-checking

packages/ERTP/src/paymentLedger.js

@@ -160,6 +160,17 @@ export const preparePaymentLedger = (
   }
 
   /**
+   * An issuer may choose to omit recovery sets. The quote issuer, for example,
+   * omits recovery sets since its "payments" do not actually represent
+   * transferable value. Recovery sets preserve payments that are otherwise
+   * inaccessible, so that they can be recovered. This is their point. But this
+   * means that useless payments might accumulate into a large storage leak.
+   * Quote payments should never need to be recovered, since one can always ask
+   * for a more recent quote. Thus, they should not pay the cost of this
+   * potential storage leak.
+   *
+   * For an issuerKit that has not opted out of recovery sets...
+   *
    * 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.

packages/ERTP/src/types-ambient.js

@@ -224,19 +224,19 @@
  * Issuers first became durable with recovery sets and no option to suppress
  * them. Thus, absence of a `RecoverySetsOption` state is equivalent to
  * `'hasRecoverySets'`. By contrast, the absence of `RecoverySetsOption` provide
- * parameter defaults to the ancestor's `RecoverySetsOption` state, or
+ * parameter defaults to the predecessor's `RecoverySetsOption` state, or
  * `'hasRecoverySets'` if none.
  *
  * The `'noRecoverySets'` state, if used for the first incarnation, makes an
  * issuer without recovery sets. If used for a successor incarnation, no matter
- * whether the ancestor was `'hasRecoverySets'` or `'noRecoverySets'`,
+ * whether the predecessor was `'hasRecoverySets'` or `'noRecoverySets'`,
  *
  * - will start emptying recovery sets,
  * - will prevent any new payments from being added to recovery sets,
  * - and (controversially) will not provide access via recovery sets of any
  *   payments that have not yet been emptied out.
  *
- * At this time, a `'noRecoverySets'` ancestor cannot be upgraded to a
+ * At this time, a `'noRecoverySets'` predecessor cannot be upgraded to a
  * `'hasRecoverySets'` successor. If it turns out this transition is needed, it
  * can likely be supported in a future upgrade.
  *

packages/zoe/src/zoeService/feeMint.js

@@ -41,13 +41,15 @@ const prepareFeeMint = (zoeBaggage, feeIssuerConfig, shutdownZoeVat) => {
     // Upgrade this legacy state by simply deleting it.
     mintBaggage.delete(FEE_MINT_KIT);
   }
-  /** @type {IssuerKit} */
-  const feeIssuerKit = reallyPrepareIssuerKit(
-    mintBaggage,
-    feeIssuerConfig.name,
-    feeIssuerConfig.assetKind,
-    feeIssuerConfig.displayInfo,
-    shutdownZoeVat,
+
+  const feeIssuerKit = /** @type {IssuerKit<'nat'>} */ (
+    reallyPrepareIssuerKit(
+      mintBaggage,
+      feeIssuerConfig.name,
+      feeIssuerConfig.assetKind,
+      feeIssuerConfig.displayInfo,
+      shutdownZoeVat,
+    )
   );
 
   const FeeMintIKit = harden({

packages/zoe/src/zoeService/makeInvitation.js

@@ -1,6 +1,6 @@
 // @jessie-check
 
-import { Fail } from '@agoric/assert';
+import { Fail, q } from '@agoric/assert';
 import { provideDurableMapStore } from '@agoric/vat-data';
 import { AssetKind, hasIssuer, reallyPrepareIssuerKit } from '@agoric/ertp';
 import { InvitationElementShape } from '../typeGuards.js';