@agoric/ertp 0.16.3-mainnet1B-dev-b0c1f78.0 → 0.16.3-orchestration-dev-096c4e8.0

package/src/types-ambient.js

@@ -4,240 +4,166 @@
 
 /**
  * @template {AssetKind} [K=AssetKind]
- * @typedef {object} Amount
- * Amounts are descriptions of digital assets, answering the questions
- * "how much" and "of what kind". Amounts are values labeled with a brand.
- * AmountMath executes the logic of how amounts are changed when digital
- * assets are merged, separated, or otherwise manipulated. For
- * example, a deposit of 2 bucks into a purse that already has 3 bucks
- * gives a new purse balance of 5 bucks. An empty purse has 0 bucks. AmountMath
- * relies heavily on polymorphic MathHelpers, which manipulate the unbranded
- * portion.
- *
+ * @typedef {object} Amount Amounts are descriptions of digital assets,
+ *   answering the questions "how much" and "of what kind". Amounts are values
+ *   labeled with a brand. AmountMath executes the logic of how amounts are
+ *   changed when digital assets are merged, separated, or otherwise
+ *   manipulated. For example, a deposit of 2 bucks into a purse that already
+ *   has 3 bucks gives a new purse balance of 5 bucks. An empty purse has 0
+ *   bucks. AmountMath relies heavily on polymorphic MathHelpers, which
+ *   manipulate the unbranded portion.
  * @property {Brand<K>} brand
  * @property {AssetValueForKind<K>} value
  */
 
 /**
- * @typedef {NatValue | SetValue | CopySet | 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
- * of that many assets.
- *
- * A non-fungible `AmountValue` uses an array or CopySet of `Key`s to represent
- * a set of whatever asset each key represents. A `Key` is a passable value
- * that can be used as an element in a set (SetStore or CopySet) or as the
- * key in a map (MapStore or CopyMap).
- *
- * `SetValue` is for the deprecated set representation, using an array directly
- * to represent the array of its elements. `CopySet` is the proper
- * representation using a CopySet.
- *
- * A semi-fungible `CopyBag` is represented as a
- * `CopyBag` of `Key` objects. "Bag" is synonymous with MultiSet, where an
- * element of a bag can be present once or more times, i.e., some positive
- * bigint number of times, representing that quantity of the asset represented
- * by that key.
+ * @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
+ *   of that many assets.
+ *
+ *   A non-fungible `AmountValue` uses an array or CopySet of `Key`s to represent
+ *   a set of whatever asset each key represents. A `Key` is a passable value
+ *   that can be used as an element in a set (SetStore or CopySet) or as the key
+ *   in a map (MapStore or CopyMap).
+ *
+ *   `SetValue` is for the deprecated set representation, using an array directly
+ *   to represent the array of its elements. `CopySet` is the proper
+ *   representation using a CopySet.
+ *
+ *   A semi-fungible `CopyBag` is represented as a `CopyBag` of `Key` objects.
+ *   "Bag" is synonymous with MultiSet, where an element of a bag can be present
+ *   once or more times, i.e., some positive bigint number of times,
+ *   representing that quantity of the asset represented by that key.
  */
 
 /**
- * @typedef {'nat' | 'set' | 'copySet' | 'copyBag' } AssetKind
- *
- * See doc-comment for `AmountValue`.
+ * @typedef {'nat' | 'set' | 'copySet' | 'copyBag'} AssetKind See doc-comment
+ *   for `AmountValue`.
  */
 
 /**
  * @template {AssetKind} K
- * @typedef {K extends 'nat' ? NatValue :
- * K extends 'set' ? SetValue :
- * K extends 'copySet' ? CopySet:
- * K extends 'copyBag' ? CopyBag :
- * never
- * } AssetValueForKind
+ * @typedef {K extends 'nat'
+ *   ? NatValue
+ *   : K extends 'set'
+ *   ? SetValue
+ *   : K extends 'copySet'
+ *   ? CopySet
+ *   : K extends 'copyBag'
+ *   ? import('@endo/patterns').CopyBag
+ *   : never} AssetValueForKind
  */
 
 /**
  * @template {AmountValue} V
- * @typedef {V extends NatValue ? 'nat' :
- *  V extends SetValue ? 'set' :
- *  V extends CopySet ? 'copySet' :
- *  V extends CopyBag ? 'copyBag' :
- *  never} AssetKindForValue
+ * @typedef {V extends NatValue
+ *   ? 'nat'
+ *   : V extends SetValue
+ *   ? 'set'
+ *   : V extends CopySet
+ *   ? 'copySet'
+ *   : V extends import('@endo/patterns').CopyBag
+ *   ? 'copyBag'
+ *   : never} AssetKindForValue
  */
 
 /**
  * @template {AssetKind} [K=AssetKind]
  * @typedef {object} DisplayInfo
- * @property {number} [decimalPlaces] Tells the display software how
- *   many decimal places to move the decimal over to the left, or in
- *   other words, which position corresponds to whole numbers. We
- *   require fungible digital assets to be represented in integers, in
- *   the smallest unit (i.e. USD might be represented in mill, a
- *   thousandth of a dollar. In that case, `decimalPlaces` would be
- *   3.) This property is optional, and for non-fungible digital
- *   assets, should not be specified. The decimalPlaces property
- *   should be used for *display purposes only*. Any other use is an
+ * @property {number} [decimalPlaces] Tells the display software how many
+ *   decimal places to move the decimal over to the left, or in other words,
+ *   which position corresponds to whole numbers. We require fungible digital
+ *   assets to be represented in integers, in the smallest unit (i.e. USD might
+ *   be represented in mill, a thousandth of a dollar. In that case,
+ *   `decimalPlaces` would be 3.) This property is optional, and for
+ *   non-fungible digital assets, should not be specified. The decimalPlaces
+ *   property should be used for _display purposes only_. Any other use is an
  *   anti-pattern.
- * @property {K} assetKind - the kind of asset, either
- *   AssetKind.NAT (fungible) or
- *   AssetKind.SET or AssetKind.COPY_SET (non-fungible)
+ * @property {K} assetKind - the kind of asset, either AssetKind.NAT (fungible)
+ *   or AssetKind.SET or AssetKind.COPY_SET (non-fungible)
  */
 
 /**
  * @template {AssetKind} [K=AssetKind]
- * @typedef {object} Brand
- * The brand identifies the kind of issuer, and has a function to get the
- * alleged name for the kind of asset described. The alleged name (such
- * as 'BTC' or 'moola') is provided by the maker of the issuer and should
- * not be trusted as accurate.
- *
- * Every amount created by a particular AmountMath will share the same brand,
- * but recipients cannot rely on the brand to verify that a purported amount
- * represents the issuer they intended, since the same brand can be reused by
- * a misbehaving issuer.
- *
+ * @typedef {object} Brand The brand identifies the kind of issuer, and has a
+ *   function to get the alleged name for the kind of asset described. The
+ *   alleged name (such as 'BTC' or 'moola') is provided by the maker of the
+ *   issuer and should not be trusted as accurate.
+ *
+ *   Every amount created by a particular AmountMath will share the same brand,
+ *   but recipients cannot rely on the brand to verify that a purported amount
+ *   represents the issuer they intended, since the same brand can be reused by
+ *   a misbehaving issuer.
  * @property {(allegedIssuer: ERef<Issuer>) => Promise<boolean>} isMyIssuer
- * Should be used with `issuer.getBrand` to ensure an issuer and brand match.
+ *   Should be used with `issuer.getBrand` to ensure an issuer and brand match.
  * @property {() => string} getAllegedName
- * @property {() => DisplayInfo<K>} getDisplayInfo
- * Give information to UI on how to display the amount.
+ * @property {() => DisplayInfo<K>} getDisplayInfo Give information to UI on how
+ *   to display the amount.
  * @property {() => Pattern} getAmountShape
  */
 
 // /////////////////////////// Issuer //////////////////////////////////////////
 
 /**
- * @callback IssuerIsLive
- *
- * Return true if the payment continues to exist.
- *
- * If the payment is a promise, the operation will proceed upon
- * resolution.
+ * @callback IssuerIsLive Return true if the payment continues to exist.
  *
+ *   If the payment is a promise, the operation will proceed upon fulfillment.
  * @param {ERef<Payment>} payment
  * @returns {Promise<boolean>}
  */
 /**
  * @template {AssetKind} K
- * @callback IssuerGetAmountOf
- *
- * Get the amount of digital assets in the payment. Because the
- * payment is not trusted, we cannot call a method on it directly, and
- * must use the issuer instead.
- *
- * If the payment is a promise, the operation will proceed upon
- * resolution.
+ * @callback IssuerGetAmountOf Get the amount of digital assets in the payment.
+ *   Because the payment is not trusted, we cannot call a method on it directly,
+ *   and must use the issuer instead.
  *
+ *   If the payment is a promise, the operation will proceed upon fulfillment.
  * @param {ERef<Payment>} payment
  * @returns {Promise<Amount<K>>}
  */
 
 /**
- * @callback IssuerBurn
- *
- * Burn all of the digital assets in the
- * payment. `optAmount` is optional. If `optAmount` is present, the
- * code will insist that the amount of the digital assets in the
- * payment is equal to `optAmount`, to prevent sending the wrong
- * payment and other confusion.
- *
- * If the payment is a promise, the operation will proceed upon
- * resolution.
- *
+ * @callback IssuerBurn Burn all of the digital assets in the payment.
+ *   `optAmountShape` is optional. If the `optAmountShape` pattern is present,
+ *   the amount of the digital assets in the payment must match
+ *   `optAmountShape`, to prevent sending the wrong payment and other
+ *   confusion.
+ *
+ *   If the payment is a promise, the operation will proceed upon fulfillment.
+ *
+ *   As always with optional `Pattern` arguments, keep in mind that technically
+ *   the value `undefined` itself is a valid `Key` and therefore a valid
+ *   `Pattern`. But in optional pattern position, a top level `undefined` will
+ *   be interpreted as absence. If you want to express a `Pattern` that will
+ *   match only `undefined`, use `M.undefined()` instead.
  * @param {ERef<Payment>} payment
  * @param {Pattern} [optAmountShape]
  * @returns {Promise<Amount>}
  */
 
-/**
- * @template {AssetKind} K
- * @callback IssuerClaim
- *
- * Transfer all digital assets from the payment to a new payment and
- * delete the original. `optAmount` is optional. If `optAmount` is
- * present, the code will insist that the amount of digital assets in
- * the payment is equal to `optAmount`, to prevent sending the wrong
- * payment and other confusion.
- *
- * If the payment is a promise, the operation will proceed upon
- * resolution.
- *
- * @param {ERef<Payment<K>>} payment
- * @param {Pattern} [optAmountShape]
- * @returns {Promise<Payment<K>>}
- */
-
-/**
- * @template {AssetKind} K
- * @callback IssuerCombine
- *
- * Combine multiple payments into one payment.
- *
- * If any of the payments is a promise, the operation will proceed
- * upon resolution.
- *
- * @param {ERef<Payment<K>>[]} paymentsArray
- * @param {Amount<K>} [optTotalAmount]
- * @returns {Promise<Payment<K>>}
- */
-
-/**
- * @template {AssetKind} K
- * @callback IssuerSplit
- *
- * Split a single payment into two payments,
- * A and B, according to the paymentAmountA passed in.
- *
- * If the payment is a promise, the operation will proceed upon
- * resolution.
- *
- * @param {ERef<Payment<K>>} payment
- * @param {Amount<K>} paymentAmountA
- * @returns {Promise<Payment<K>[]>}
- */
-
-/**
- * @callback IssuerSplitMany
- *
- * Split a single payment into many payments, according to the amounts
- * passed in.
- *
- * If the payment is a promise, the operation will proceed upon
- * resolution.
- *
- * @param {ERef<Payment>} payment
- * @param {Amount[]} amounts
- * @returns {Promise<Payment[]>}
- */
-
 /**
  * @template {AssetKind} [K=AssetKind]
- * @typedef {object} Issuer
- *
- * The issuer cannot mint a new amount, but it can create empty purses
- * and payments. The issuer can also transform payments (splitting
- * payments, combining payments, burning payments, and claiming
- * payments exclusively). The issuer should be gotten from a trusted
- * source and then relied upon as the decider of whether an untrusted
- * payment is valid.
- *
- * @property {() => Brand<K>} getBrand Get the Brand for this Issuer. The
- * Brand indicates the type of digital asset and is shared by the
- * mint, the issuer, and any purses and payments of this particular
- * kind. The brand is not closely held, so this function should not be
- * trusted to identify an issuer alone. Fake digital assets and amount
- * can use another issuer's brand.
- *
- * @property {() => string} getAllegedName Get the allegedName for
- * this mint/issuer
- * @property {() => AssetKind} getAssetKind Get the kind of
- * MathHelpers used by this Issuer.
- * @property {() => DisplayInfo<K>} getDisplayInfo Give information to UI
- *  on how to display amounts for this issuer.
- * @property {() => Purse<K>} makeEmptyPurse Make an empty purse of this
- * brand.
+ * @typedef {object} Issuer The issuer cannot mint a new amount, but it can
+ *   create empty purses and payments. The issuer can also transform payments
+ *   (splitting payments, combining payments, burning payments, and claiming
+ *   payments exclusively). The issuer should be gotten from a trusted source
+ *   and then relied upon as the decider of whether an untrusted payment is
+ *   valid.
+ * @property {() => Brand<K>} getBrand Get the Brand for this Issuer. The Brand
+ *   indicates the type of digital asset and is shared by the mint, the issuer,
+ *   and any purses and payments of this particular kind. The brand is not
+ *   closely held, so this function should not be trusted to identify an issuer
+ *   alone. Fake digital assets and amount can use another issuer's brand.
+ * @property {() => string} getAllegedName Get the allegedName for this
+ *   mint/issuer
+ * @property {() => AssetKind} getAssetKind Get the kind of MathHelpers used by
+ *   this Issuer.
+ * @property {() => DisplayInfo<K>} getDisplayInfo Give information to UI on how
+ *   to display amounts for this issuer.
+ * @property {() => Purse<K>} makeEmptyPurse Make an empty purse of this brand.
  * @property {IssuerIsLive} isLive
  * @property {IssuerGetAmountOf<K>} getAmountOf
  * @property {IssuerBurn} burn
@@ -247,7 +173,9 @@
  * @template {AssetKind} [K=AssetKind]
  * @typedef {object} PaymentLedger
  * @property {Mint<K>} mint
- * @property {Purse<K>} mintRecoveryPurse
+ * @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
  */
@@ -256,7 +184,9 @@
  * @template {AssetKind} [K=AssetKind]
  * @typedef {object} IssuerKit
  * @property {Mint<K>} mint
- * @property {Purse<K>} mintRecoveryPurse
+ * @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
@@ -264,35 +194,49 @@
 
 /**
  * @typedef {object} AdditionalDisplayInfo
- *
- * @property {number} [decimalPlaces] Tells the display software how
- *   many decimal places to move the decimal over to the left, or in
- *   other words, which position corresponds to whole numbers. We
- *   require fungible digital assets to be represented in integers, in
- *   the smallest unit (i.e. USD might be represented in mill, a
- *   thousandth of a dollar. In that case, `decimalPlaces` would be
- *   3.) This property is optional, and for non-fungible digital
- *   assets, should not be specified. The decimalPlaces property
- *   should be used for *display purposes only*. Any other use is an
+ * @property {number} [decimalPlaces] Tells the display software how many
+ *   decimal places to move the decimal over to the left, or in other words,
+ *   which position corresponds to whole numbers. We require fungible digital
+ *   assets to be represented in integers, in the smallest unit (i.e. USD might
+ *   be represented in mill, a thousandth of a dollar. In that case,
+ *   `decimalPlaces` would be 3.) This property is optional, and for
+ *   non-fungible digital assets, should not be specified. The decimalPlaces
+ *   property should be used for _display purposes only_. Any other use is an
  *   anti-pattern.
  * @property {AssetKind} [assetKind]
  */
 
-/**
- * @typedef {import('@agoric/swingset-vat').ShutdownWithFailure} ShutdownWithFailure
- */
+/** @typedef {import('@agoric/swingset-vat').ShutdownWithFailure} ShutdownWithFailure */
 
 /**
  * @template {AssetKind} [K=AssetKind]
- * @typedef {object} Mint
- * Holding a Mint carries the right to issue new digital assets. These
- * assets all have the same kind, which is called a Brand.
- *
+ * @typedef {object} Mint Holding a Mint carries the right to issue new digital
+ *   assets. These assets all have the same kind, which is called a Brand.
  * @property {() => Issuer<K>} getIssuer Gets the Issuer for this mint.
- * @property {(newAmount: Amount<K>) => Payment<K>} mintPayment
- * Creates a new Payment containing newly minted amount.
+ * @property {(newAmount: Amount<K>) => Payment<K>} mintPayment Creates a new
+ *   Payment containing newly minted amount.
  */
 
+// /////////////////////////// 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
@@ -302,12 +246,12 @@
 
 /**
  * @typedef {object} DepositFacet
- * @property {DepositFacetReceive} receive
- * Deposit all the contents of payment into the purse that made this facet,
- * returning the amount. If the optional argument `optAmount` does not equal the
- * amount of digital assets in the payment, throw an error.
+ * @property {DepositFacetReceive} receive Deposit all the contents of payment
+ *   into the purse that made this facet, returning the amount. If the optional
+ *   argument `optAmount` does not equal the amount of digital assets in the
+ *   payment, throw an error.
  *
- * If payment is a promise, throw an error.
+ *   If payment is a promise, throw an error.
  */
 
 /**
@@ -320,121 +264,100 @@
 
 /**
  * @template {AssetKind} [K=AssetKind]
- * @typedef {object} Purse
- * Purses hold amount of digital assets of the same brand, but unlike Payments,
- * they are not meant to be sent to others. To transfer digital assets, a
- * Payment should be withdrawn from a Purse. The amount of digital
- * assets in a purse can change through the action of deposit() and withdraw().
- *
- * The primary use for Purses and Payments is for currency-like and goods-like
- * digital assets, but they can also be used to represent other kinds of rights,
- * such as the right to participate in a particular contract.
- *
- * @property {() => Brand<K>} getAllegedBrand Get the alleged Brand for this Purse
- *
- * @property {() => Amount<K>} getCurrentAmount
- * Get the amount contained in this purse.
- *
- * @property {() => LatestTopic<Amount<K>>} getCurrentAmountNotifier
- * Get a lossy notifier for changes to this purse's balance.
- *
- * @property {PurseDeposit<K>} deposit
- * Deposit all the contents of payment into this purse, returning the
- * amount. If the optional argument `optAmount` does not equal the
- * amount of digital assets in the payment, throw an error.
- *
- * If payment is a promise, throw an error.
- *
- * @property {() => DepositFacet} getDepositFacet
- * Return an object whose `receive` method deposits to the current Purse.
- *
- * @property {(amount: Amount<K>) => Payment<K>} withdraw
- * Withdraw amount from this purse into a new Payment.
- *
- * @property {() => CopySet<Payment<K>>} getRecoverySet
- * The set of payments withdrawn from this purse that are still live. These
- * are the payments that can still be recovered in emergencies by, for example,
- * depositing into this purse. Such a deposit action is like canceling an
- * outstanding check because you're tired of waiting for it. Once your
- * cancellation is acknowledged, you 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.
- *
- * @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.
+ * @typedef {object} Purse Purses hold amount of digital assets of the same
+ *   brand, but unlike Payments, they are not meant to be sent to others. To
+ *   transfer digital assets, a Payment should be withdrawn from a Purse. The
+ *   amount of digital assets in a purse can change through the action of
+ *   deposit() and withdraw().
+ *
+ *   The primary use for Purses and Payments is for currency-like and goods-like
+ *   digital assets, but they can also be used to represent other kinds of
+ *   rights, such as the right to participate in a particular contract.
+ * @property {() => Brand<K>} getAllegedBrand Get the alleged Brand for this
+ *   Purse
+ * @property {() => Amount<K>} getCurrentAmount Get the amount contained in this
+ *   purse.
+ * @property {() => LatestTopic<Amount<K>>} getCurrentAmountNotifier Get a lossy
+ *   notifier for changes to this purse's balance.
+ * @property {PurseDeposit<K>} deposit Deposit all the contents of payment into
+ *   this purse, returning the amount. If the optional argument `optAmount` does
+ *   not equal the amount of digital assets in the payment, throw an error.
+ *
+ *   If payment is a promise, throw an error.
+ * @property {() => DepositFacet} getDepositFacet Return an object whose
+ *   `receive` method deposits to the current Purse.
+ * @property {(amount: Amount<K>) => Payment<K>} withdraw Withdraw amount from
+ *   this purse into a new Payment.
+ * @property {() => CopySet<Payment<K>>} getRecoverySet The set of payments
+ *   withdrawn from this purse that are still live. These are the payments that
+ *   can still be recovered in emergencies by, for example, depositing into this
+ *   purse. Such a deposit action is like canceling an outstanding check because
+ *   you're tired of waiting for it. Once your cancellation is acknowledged, you
+ *   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.
  */
 
 /**
  * @template {AssetKind} [K=AssetKind]
- * @typedef {object} Payment
- * Payments hold amount of digital assets of the same brand in transit. Payments
- * can be deposited in purses, split into multiple payments, combined, and
- * claimed (getting an exclusive payment). Payments are linear, meaning
- * that either a payment has the same amount of digital assets it
- * started with, or it is used up entirely. It is impossible to partially use a
- * payment.
- *
- * Payments are often received from other actors and therefore should
- * not be trusted themselves. To get the amount of digital assets in a payment,
- * use the trusted issuer: issuer.getAmountOf(payment),
- *
- * Payments can be converted to Purses by getting a trusted issuer and
- * calling `issuer.makeEmptyPurse()` to create a purse, then
- * `purse.deposit(payment)`.
- *
- * @property {() => Brand<K>} getAllegedBrand
- * Get the allegedBrand, indicating the type of digital asset this
- * payment purports to be, and which issuer to use. Because payments
- * are not trusted, any method calls on payments should be treated
- * with suspicion and verified elsewhere.
+ * @typedef {object} Payment Payments hold amount of digital assets of the same
+ *   brand in transit. Payments can be deposited in purses, split into multiple
+ *   payments, combined, and claimed (getting an exclusive payment). Payments
+ *   are linear, meaning that either a payment has the same amount of digital
+ *   assets it started with, or it is used up entirely. It is impossible to
+ *   partially use a payment.
+ *
+ *   Payments are often received from other actors and therefore should not be
+ *   trusted themselves. To get the amount of digital assets in a payment, use
+ *   the trusted issuer: issuer.getAmountOf(payment),
+ *
+ *   Payments can be converted to Purses by getting a trusted issuer and calling
+ *   `issuer.makeEmptyPurse()` to create a purse, then
+ *   `purse.deposit(payment)`.
+ * @property {() => Brand<K>} getAllegedBrand Get the allegedBrand, indicating
+ *   the type of digital asset this payment purports to be, and which issuer to
+ *   use. Because payments are not trusted, any method calls on payments should
+ *   be treated with suspicion and verified elsewhere.
  */
 
+// /////////////////////////// MathHelpers /////////////////////////////////////
+
 /**
  * @template {AmountValue} V
- * @typedef {object} MathHelpers
- * All of the difference in how digital asset amount are manipulated can be
- * reduced to the behavior of the math on values. We extract this
- * custom logic into mathHelpers. MathHelpers are about value
- * arithmetic, whereas AmountMath is about amounts, which are the
- * values labeled with a brand. AmountMath use mathHelpers to do their value
- * arithmetic, and then brand the results, making a new amount.
- *
- * The MathHelpers are designed to be called only from AmountMath, and so
- * all methods but coerce can assume their inputs are valid. They only
- * need to do output validation, and only when there is a possibility of
- * invalid output.
- *
- * @property {(allegedValue: V) => V} doCoerce
- * Check the kind of this value and throw if it is not the
- * expected kind.
- *
- * @property {() => V} doMakeEmpty
- * Get the representation for the identity element (often 0 or an
- * empty array)
- *
- * @property {(value: V) => boolean} doIsEmpty
- * Is the value the identity element?
- *
- * @property {(left: V, right: V) => boolean} doIsGTE
- * Is the left greater than or equal to the right?
- *
- * @property {(left: V, right: V) => boolean} doIsEqual
- * Does left equal right?
- *
- * @property {(left: V, right: V) => V} doAdd
- * Return the left combined with the right.
- *
- * @property {(left: V, right: V) => V} doSubtract
- * Return what remains after removing the right from the left. If
- * something in the right was not in the left, we throw an error.
+ * @typedef {object} MathHelpers All of the difference in how digital asset
+ *   amount are manipulated can be reduced to the behavior of the math on
+ *   values. We extract this custom logic into mathHelpers. MathHelpers are
+ *   about value arithmetic, whereas AmountMath is about amounts, which are the
+ *   values labeled with a brand. AmountMath use mathHelpers to do their value
+ *   arithmetic, and then brand the results, making a new amount.
+ *
+ *   The MathHelpers are designed to be called only from AmountMath, and so all
+ *   methods but coerce can assume their inputs are valid. They only need to do
+ *   output validation, and only when there is a possibility of invalid output.
+ * @property {(allegedValue: V) => V} doCoerce Check the kind of this value and
+ *   throw if it is not the expected kind.
+ * @property {() => V} doMakeEmpty Get the representation for the identity
+ *   element (often 0 or an empty array)
+ * @property {(value: V) => boolean} doIsEmpty Is the value the identity
+ *   element?
+ * @property {(left: V, right: V) => boolean} doIsGTE Is the left greater than
+ *   or equal to the right?
+ * @property {(left: V, right: V) => boolean} doIsEqual Does left equal right?
+ * @property {(left: V, right: V) => V} doAdd Return the left combined with the
+ *   right.
+ * @property {(left: V, right: V) => V} doSubtract Return what remains after
+ *   removing the right from the left. If something in the right was not in the
+ *   left, we throw an error.
  */
 
-/**
- * @typedef {bigint} NatValue
- */
+/** @typedef {bigint} NatValue */
 
-/**
- * @typedef {Array<Key>} SetValue
- */
+/** @typedef {Key[]} SetValue */