diff --git a/packages/ERTP/src/issuerKit.js b/packages/ERTP/src/issuerKit.js index 11fe3d18fe2f..e50a1079490d 100644 --- a/packages/ERTP/src/issuerKit.js +++ b/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 @@ -135,7 +135,7 @@ 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 diff --git a/packages/ERTP/src/paymentLedger.js b/packages/ERTP/src/paymentLedger.js index 16beffd5c3bb..cca953316062 100644 --- a/packages/ERTP/src/paymentLedger.js +++ b/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 preverse 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. diff --git a/packages/ERTP/src/types-ambient.js b/packages/ERTP/src/types-ambient.js index fefe515d5fe1..9e74dff5e3e4 100644 --- a/packages/ERTP/src/types-ambient.js +++ b/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. *