@agoric/ertp 0.16.3-other-dev-8f8782b.0 → 0.16.3-other-dev-fbe72e7.0.fbe72e7

package/src/issuerKit.js

@@ -1,16 +1,22 @@
 // @jessie-check
 
-import { assert } from '@agoric/assert';
+import { assert, Fail } from '@endo/errors';
 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';
 import { preparePaymentLedger } from './paymentLedger.js';
 
-import './types-ambient.js';
-
-/** @typedef {import('@agoric/vat-data').Baggage} Baggage */
+/**
+ * @import {Key, Pattern} from '@endo/patterns';
+ * @import {Zone} from '@agoric/base-zone';
+ * @import {ShutdownWithFailure} from '@agoric/swingset-vat';
+ * @import {TypedPattern} from '@agoric/internal';
+ * @import {Baggage} from '@agoric/vat-data';
+ * @import {AdditionalDisplayInfo, RecoverySetsOption, IssuerKit, PaymentLedger} from './types.js';
+ */
 
 /**
  * @template {AssetKind} K
@@ -22,21 +28,26 @@ import './types-ambient.js';
  */
 
 /**
+ * Used _only_ internally, to make a new issuerKit or to revive an old one.
+ *
  * @template {AssetKind} K
  * @param {IssuerRecord<K>} issuerRecord
- * @param {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
- * provided, then the failed atomic action will call it, so that some
- * larger 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 {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
+ *   provided, then the failed atomic action will call it, so that some larger
+ *   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
  * @returns {IssuerKit<K>}
  */
 const setupIssuerKit = (
   { name, assetKind, displayInfo, elementShape },
-  issuerBaggage,
+  issuerZone,
+  recoverySetsState,
   optShutdownWithFailure = undefined,
 ) => {
   assert.typeof(name, 'string');
@@ -54,13 +65,14 @@ const setupIssuerKit = (
 
   // Attenuate the powerful authority to mint and change balances
   /** @type {PaymentLedger<K>} */
-  // @ts-expect-error could be instantiated with different subtype of AssetKind
+  // @ts-expect-error could be instantiated with a different subtype
   const { issuer, mint, brand, mintRecoveryPurse } = preparePaymentLedger(
-    issuerBaggage,
+    issuerZone,
     name,
     assetKind,
     cleanDisplayInfo,
     elementShape,
+    recoverySetsState,
     optShutdownWithFailure,
   );
 
@@ -76,66 +88,113 @@ 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 {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
- * provided, then the failed atomic action will call it, so that some
- * larger 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 {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
+ *   provided, then the failed atomic action will call it, so that some larger
+ *   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 prepareIssuerKit = (
+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'`;
+  }
+  // Extant sets are not currently deleted. If the new option is
+  // 'noRecoverySets', they won't be used but extant ones will remain. Future
+  // upgrades may make it possible to delete elements from them.
+  const recoverySetsState = recoverySetsOption || oldRecoverySetsState;
+  return setupIssuerKit(
+    issuerRecord,
+    issuerZone,
+    recoverySetsState,
+    optShutdownWithFailure,
+  );
 };
-harden(prepareIssuerKit);
+harden(upgradeIssuerKit);
 
 /**
- * Does baggage already have an issuer from prepareIssuerKit()?
- * That is: does it have the relevant keys defined?
+ * Does baggage already have an issuerKit?
  *
  * @param {Baggage} baggage
  */
 export const hasIssuer = baggage => baggage.has(INSTANCE_KEY);
 
 /**
- * @typedef {Partial<{elementShape: Pattern}>} IssuerOptionsRecord
+ * `elementShape`, may only be present for collection-style amounts. If present,
+ * it is a `Pattern` that every element of this issuerKits's amounts must
+ * satisfy. For example, the Zoe Invitation issuerKit uses an elementShape
+ * describing the invitation details for an individual invitation. An invitation
+ * purse or payment has an amount that can only be a set of these. (Though
+ * 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
  */
 
 /**
- * @template {AssetKind} K
- * The name becomes part of the brand in asset descriptions.
- * The name is useful for debugging and double-checking
- * assumptions, but should not be trusted wrt any external namespace.
- * For example, anyone could create a new issuer kit with name 'BTC', but
- * it is not bitcoin or even related. It is only the name according
- * to that issuer and brand.
+ * Used _only_ to make a _new_ durable issuer, i.e., the initial incarnation of
+ * that issuer.
  *
- * The assetKind will be used to import a specific mathHelpers
- * from the mathHelpers library. For example, natMathHelpers, the
- * default, is used for basic fungible tokens.
+ * @template {AssetKind} K The name becomes part of the brand in asset
+ *   descriptions. The name is useful for debugging and double-checking
+ *   assumptions, but should not be trusted wrt any external namespace. For
+ *   example, anyone could create a new issuer kit with name 'BTC', but it is
+ *   not bitcoin or even related. It is only the name according to that issuer
+ *   and brand.
  *
- *  `displayInfo` gives information to the UI on how to display the amount.
+ *   The assetKind will be used to import a specific mathHelpers from the
+ *   mathHelpers library. For example, natMathHelpers, the default, is used for
+ *   basic fungible tokens.
  *
+ *   `displayInfo` gives information to the UI on how to display the amount.
  * @param {Baggage} issuerBaggage
  * @param {string} name
- * @param {K} [assetKind=AssetKind.NAT]
- * @param {AdditionalDisplayInfo} [displayInfo={}]
- * @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
- * provided, then the failed atomic action will call it, so that some
- * larger 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 {K} [assetKind]
+ * @param {AdditionalDisplayInfo} [displayInfo]
+ * @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
+ *   provided, then the failed atomic action will call it, so that some larger
+ *   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 {IssuerOptionsRecord} [options]
  * @returns {IssuerKit<K>}
  */
@@ -146,41 +205,135 @@ 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);
 
 /**
- * @template {AssetKind} [K='nat']
- * The name becomes part of the brand in asset descriptions.
- * The name is useful for debugging and double-checking
- * assumptions, but should not be trusted wrt any external namespace.
- * For example, anyone could create a new issuer kit with name 'BTC', but
- * it is not bitcoin or even related. It is only the name according
- * to that issuer and brand.
+ * 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.
  *
- * The assetKind will be used to import a specific mathHelpers
- * from the mathHelpers library. For example, natMathHelpers, the
- * default, is used for basic fungible tokens.
+ * @template {IssuerOptionsRecord} O
+ * @template {AssetKind} K The name becomes part of the brand in asset
+ *   descriptions. The name is useful for debugging and double-checking
+ *   assumptions, but should not be trusted wrt any external namespace. For
+ *   example, anyone could create a new issuer kit with name 'BTC', but it is
+ *   not bitcoin or even related. It is only the name according to that issuer
+ *   and brand.
  *
- *  `displayInfo` gives information to the UI on how to display the amount.
+ *   The assetKind will be used to import a specific mathHelpers from the
+ *   mathHelpers library. For example, natMathHelpers, the default, is used for
+ *   basic fungible tokens.
  *
+ *   `displayInfo` gives information to the UI on how to display the amount.
+ * @param {Baggage} issuerBaggage
  * @param {string} name
- * @param {K} [assetKind='nat']
- * @param {AdditionalDisplayInfo} [displayInfo={}]
- * @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
- * provided, then the failed atomic action will call it, so that some
- * larger 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 {IssuerOptionsRecord} [options]
- * @returns {IssuerKit<K>}
+ * @param {K} [assetKind]
+ * @param {AdditionalDisplayInfo} [displayInfo]
+ * @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
+ *   provided, then the failed atomic action will call it, so that some larger
+ *   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 {O} [options]
+ * @returns {O['elementShape'] extends TypedPattern<infer T extends Key>
+ *     ? IssuerKit<K, T>
+ *     : IssuerKit<K>}
+ */
+export const prepareIssuerKit = (
+  issuerBaggage,
+  name,
+  // @ts-expect-error K could be instantiated with a different subtype of AssetKind
+  assetKind = AssetKind.NAT,
+  displayInfo = harden({}),
+  optShutdownWithFailure = undefined,
+  // @ts-expect-error could have a different subtype of IssuerOptionsRecord
+  options = {},
+) => {
+  if (hasIssuer(issuerBaggage)) {
+    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. 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;
+  } else {
+    const issuerKit = makeDurableIssuerKit(
+      issuerBaggage,
+      name,
+      assetKind,
+      displayInfo,
+      optShutdownWithFailure,
+      options,
+    );
+    // @ts-expect-error cast to the type parameter
+    return issuerKit;
+  }
+};
+harden(prepareIssuerKit);
+
+/**
+ * Used _only_ to make a new issuerKit that is effectively non-durable. This is
+ * currently done by making a durable one in a baggage not reachable from
+ * anywhere. TODO Once rebuilt on zones, this should instead just build on the
+ * virtual zone. See https://github.com/Agoric/agoric-sdk/pull/7116
+ *
+ * Currently used for testing only. Should probably continue to be used for
+ * testing only.
+ *
+ * @template {AssetKind} [K='nat']
+ * @template {IssuerOptionsRecord} [O={}]
+ * @param {string} name The name becomes part of the brand in asset
+ *   descriptions. The name is useful for debugging and double-checking
+ *   assumptions, but should not be trusted wrt any external namespace. For
+ *   example, anyone could create a new issuer kit with name 'BTC', but it is
+ *   not bitcoin or even related. It is only the name according to that issuer
+ *   and brand.
+ * @param {K} [assetKind] The assetKind will be used to import a specific
+ *   mathHelpers from the mathHelpers library. For example, natMathHelpers, the
+ *   default, is used for basic fungible tokens.
+ * @param {AdditionalDisplayInfo} [displayInfo] `displayInfo` gives information
+ *   to the UI on how to display the amount.
+ * @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
+ *   provided, then the failed atomic action will call it, so that some larger
+ *   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 {O} [options]
+ * @returns {O['elementShape'] extends TypedPattern<infer T extends Key>
+ *     ? IssuerKit<K, T>
+ *     : IssuerKit<K>}
  */
 export const makeIssuerKit = (
   name,
@@ -188,14 +341,16 @@ export const makeIssuerKit = (
   assetKind = AssetKind.NAT,
   displayInfo = harden({}),
   optShutdownWithFailure = undefined,
-  { elementShape = undefined } = {},
+  // @ts-expect-error O could be instantiated with a different subtype
+  { elementShape = undefined, recoverySetsOption = undefined } = {},
 ) =>
+  // @ts-expect-error cast
   makeDurableIssuerKit(
     makeScalarBigMapStore('dropped issuer kit', { durable: true }),
     name,
     assetKind,
     displayInfo,
     optShutdownWithFailure,
-    { elementShape },
+    { elementShape, recoverySetsOption },
   );
 harden(makeIssuerKit);

package/src/legacy-payment-helpers.d.ts

@@ -1,5 +1,12 @@
-export function claim<K extends AssetKind>(recoveryPurse: ERef<Purse<K>>, srcPaymentP: ERef<Payment<K>>, optAmountShape?: Pattern): Promise<Payment<K>>;
-export function combine<K extends AssetKind>(recoveryPurse: ERef<Purse<K>>, srcPaymentsPs: ERef<Payment<K>>[], optTotalAmount?: Pattern): Promise<Payment<K>>;
+export function claim<K extends AssetKind, T extends Key>(recoveryPurse: ERef<Purse<K, T>>, srcPaymentP: ERef<Payment<K, T>>, optAmountShape?: Pattern): Promise<Payment<K, T>>;
+export function combine<K extends AssetKind, T extends Key>(recoveryPurse: ERef<Purse<K, T>>, srcPaymentsPs: ERef<Payment<K, T>>[], optTotalAmount?: Pattern): Promise<Payment<K, T>>;
 export function split<K extends AssetKind>(recoveryPurse: ERef<Purse<K>>, srcPaymentP: ERef<Payment<K>>, paymentAmountA: Amount<K>): Promise<Payment<K>[]>;
 export function splitMany<K extends AssetKind>(recoveryPurse: ERef<Purse<K>>, srcPaymentP: ERef<Payment<K>>, amounts: Amount<K>[]): Promise<Payment[]>;
+import type { AssetKind } from './types.js';
+import type { Key } from '@endo/patterns';
+import type { Purse } from './types.js';
+import type { ERef } from '@endo/far';
+import type { Payment } from './types.js';
+import type { Pattern } from '@endo/patterns';
+import type { Amount } from './types.js';
 //# sourceMappingURL=legacy-payment-helpers.d.ts.map

package/src/legacy-payment-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"legacy-payment-helpers.d.ts","sourceRoot":"","sources":["legacy-payment-helpers.js"],"names":[],"mappings":"AA+BO,0HAHI,OAAO,uBAYjB;AAiBM,gIAHI,OAAO,uBA2BjB;AAiBM,2JAUN;AAkBM,oIAFM,QAAQ,OAAO,EAAE,CAAC,CAoB9B"}
+{"version":3,"file":"legacy-payment-helpers.d.ts","sourceRoot":"","sources":["legacy-payment-helpers.js"],"names":[],"mappings":"AAmCO,sBAPkB,CAAC,SAAb,SAAW,EACL,CAAC,SAAP,GAAK,iBACP,KAAK,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,eACjB,KAAK,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,mBACnB,OAAO,GACL,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAWlC;AAkBM,wBAPkB,CAAC,SAAb,SAAW,EACL,CAAC,SAAP,GAAK,iBACP,KAAK,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,iBACjB,KAAK,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,mBACrB,OAAO,GACL,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CA8BlC;AAgBM,sBANkB,CAAC,SAAb,SAAW,iBACb,KAAK,MAAM,CAAC,CAAC,CAAC,eACd,KAAK,QAAQ,CAAC,CAAC,CAAC,kBAChB,OAAO,CAAC,CAAC,GACP,OAAO,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAYjC;AAgBM,0BANkB,CAAC,SAAb,SAAW,iBACb,KAAK,MAAM,CAAC,CAAC,CAAC,eACd,KAAK,QAAQ,CAAC,CAAC,CAAC,WAChB,OAAO,CAAC,CAAC,EAAE,GACT,OAAO,CAAC,OAAO,EAAE,CAAC,CAoB9B;+BA5ImD,YAAY;yBADjC,gBAAgB;2BACK,YAAY;0BAFzC,WAAW;6BAEkB,YAAY;6BADjC,gBAAgB;4BACK,YAAY"}

package/src/legacy-payment-helpers.js

@@ -1,33 +1,37 @@
 // @jessie-check
 
-import { mustMatch } from '@agoric/store';
+import { Fail } from '@endo/errors';
 import { E } from '@endo/far';
+import { mustMatch } from '@agoric/store';
 import { AmountMath } from './amountMath.js';
 
-const { Fail } = assert;
+/**
+ * @import {ERef} from '@endo/far';
+ * @import {Key, Pattern} from '@endo/patterns';
+ * @import {Amount, AssetKind, Payment, Purse} from './types.js';
+ */
 
 /**
- * @file
- * This file contains safer helper function alternatives to the
- * similarly named methods on issuer.
- * These are parameterized by a purse used for recovering lost payments, which
- * we call a `recoveryPurse`. Any payments created by these
- * helper functions are in the recovery set of that `recoveryPurse` until
- * otherwise used up.
+ * @file This file contains safer helper function alternatives to the similarly
+ *   named methods on issuer. These are parameterized by a purse used for
+ *   recovering lost payments, which we call a `recoveryPurse`. Any payments
+ *   created by these helper functions are in the recovery set of that
+ *   `recoveryPurse` until otherwise used up.
  *
- * One of these helper functions is less safe in one way:
- * `combine` is not failure atomic. If the `combine` helper function
- * fails, some of the input payments may have been used up. However, even
- * in that case, no assets would be lost. The assets from the used up payments
- * will be in the argument `recoveryPurse`.
+ *   One of these helper functions is less safe in one way: `combine` is not
+ *   failure atomic. If the `combine` helper function fails, some of the input
+ *   payments may have been used up. However, even in that case, no assets would
+ *   be lost. The assets from the used up payments will be in the argument
+ *   `recoveryPurse`.
  */
 
 /**
  * @template {AssetKind} K
- * @param {ERef<Purse<K>>} recoveryPurse
- * @param {ERef<Payment<K>>} srcPaymentP
+ * @template {Key} T type of values in set-like kind
+ * @param {ERef<Purse<K, T>>} recoveryPurse
+ * @param {ERef<Payment<K, T>>} srcPaymentP
  * @param {Pattern} [optAmountShape]
- * @returns {Promise<Payment<K>>}
+ * @returns {Promise<Payment<K, T>>}
  */
 export const claim = async (
   recoveryPurse,
@@ -43,17 +47,18 @@ harden(claim);
 
 /**
  * Note: Not failure atomic. But as long as you don't lose the argument
- * `recoveryPurse`, no assets are lost.
- * If any of the deposits fail, or the total does not
- * match optTotalAmount, some payments may still have been deposited. Those
- * assets will be in the argument `recoveryPurse`. All undeposited payments
- * will still be in the recovery sets of their purses of origin.
+ * `recoveryPurse`, no assets are lost. If any of the deposits fail, or the
+ * total does not match optTotalAmount, some payments may still have been
+ * deposited. Those assets will be in the argument `recoveryPurse`. All
+ * undeposited payments will still be in the recovery sets of their purses of
+ * origin.
  *
  * @template {AssetKind} K
- * @param {ERef<Purse<K>>} recoveryPurse
- * @param {ERef<Payment<K>>[]} srcPaymentsPs
+ * @template {Key} T type of values in set-like kind
+ * @param {ERef<Purse<K, T>>} recoveryPurse
+ * @param {ERef<Payment<K, T>>[]} srcPaymentsPs
  * @param {Pattern} [optTotalAmount]
- * @returns {Promise<Payment<K>>}
+ * @returns {Promise<Payment<K, T>>}
  */
 export const combine = async (
   recoveryPurse,
@@ -66,7 +71,11 @@ export const combine = async (
     E(brandP).getDisplayInfo(),
     ...srcPaymentsPs,
   ]);
-  const emptyAmount = AmountMath.makeEmpty(brand, displayInfo.assetKind);
+
+  // XXX Brand lacks M
+  const emptyAmount = /** @type {Amount<K, T>} */ (
+    AmountMath.makeEmpty(brand, displayInfo.assetKind)
+  );
   const amountPs = srcPayments.map(srcPayment =>
     E(recoveryPurse).deposit(srcPayment),
   );
@@ -84,11 +93,10 @@ harden(combine);
 
 /**
  * Note: Not failure atomic. But as long as you don't lose the argument
- * `recoveryPurse`, no assets are lost.
- * If the amount in `srcPaymentP` is not >= `paymentAmountA`, the payment may
- * still be deposited anyway, before failing in the subsequent subtract.
- * In that case, those
- * assets will be in the argument `recoveryPurse`.
+ * `recoveryPurse`, no assets are lost. If the amount in `srcPaymentP` is not >=
+ * `paymentAmountA`, the payment may still be deposited anyway, before failing
+ * in the subsequent subtract. In that case, those assets will be in the
+ * argument `recoveryPurse`.
  *
  * @template {AssetKind} K
  * @param {ERef<Purse<K>>} recoveryPurse
@@ -111,12 +119,10 @@ harden(split);
 
 /**
  * Note: Not failure atomic. But as long as you don't lose the argument
- * `recoveryPurse`, no assets are lost.
- * If the amount in `srcPaymentP` is exactly the sum of the amounts,
- * the payment may
- * still be deposited anyway, before failing in the subsequent equality check.
- * In that case, those
- * assets will be in the argument `recoveryPurse`.
+ * `recoveryPurse`, no assets are lost. If the amount in `srcPaymentP` is
+ * exactly the sum of the amounts, the payment may still be deposited anyway,
+ * before failing in the subsequent equality check. In that case, those assets
+ * will be in the argument `recoveryPurse`.
  *
  * @template {AssetKind} K
  * @param {ERef<Purse<K>>} recoveryPurse

package/src/mathHelpers/copyBagMathHelpers.d.ts

@@ -1,5 +1,4 @@
-/**
- * @type {MathHelpers<CopyBag>}
- */
-export const copyBagMathHelpers: MathHelpers<CopyBag>;
+/** @type {MathHelpers<import('@endo/patterns').CopyBag>} */
+export const copyBagMathHelpers: MathHelpers<import("@endo/patterns").CopyBag>;
+import type { MathHelpers } from '../types.js';
 //# sourceMappingURL=copyBagMathHelpers.d.ts.map

package/src/mathHelpers/copyBagMathHelpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"copyBagMathHelpers.d.ts","sourceRoot":"","sources":["copyBagMathHelpers.js"],"names":[],"mappings":"AAiBA;;GAEG;AACH,iCAFU,YAAY,OAAO,CAAC,CAa3B"}
+{"version":3,"file":"copyBagMathHelpers.d.ts","sourceRoot":"","sources":["copyBagMathHelpers.js"],"names":[],"mappings":"AAkBA,4DAA4D;AAC5D,iCADW,YAAY,OAAO,gBAAgB,EAAE,OAAO,CAAC,CAYrD;iCAjB4B,aAAa"}

package/src/mathHelpers/copyBagMathHelpers.js

@@ -10,14 +10,13 @@ import {
   bagUnion,
   bagDisjointSubtract,
 } from '@agoric/store';
-import '../types-ambient.js';
 
-/** @type {CopyBag} */
+/** @import {MathHelpers} from '../types.js' */
+
+/** @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/mathHelpers/copySetMathHelpers.d.ts

@@ -1,5 +1,5 @@
-/**
- * @type {MathHelpers<CopySet>}
- */
+/** @type {MathHelpers<CopySet>} */
 export const copySetMathHelpers: MathHelpers<CopySet>;
+import type { CopySet } from '@endo/patterns';
+import type { MathHelpers } from '../types.js';
 //# sourceMappingURL=copySetMathHelpers.d.ts.map

package/src/mathHelpers/copySetMathHelpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"copySetMathHelpers.d.ts","sourceRoot":"","sources":["copySetMathHelpers.js"],"names":[],"mappings":"AAiBA;;GAEG;AACH,iCAFU,YAAY,OAAO,CAAC,CAa3B"}
+{"version":3,"file":"copySetMathHelpers.d.ts","sourceRoot":"","sources":["copySetMathHelpers.js"],"names":[],"mappings":"AAqBA,mCAAmC;AACnC,iCADW,YAAY,OAAO,CAAC,CAY5B;6BAlBuB,gBAAgB;iCADZ,aAAa"}

package/src/mathHelpers/copySetMathHelpers.js

@@ -10,14 +10,16 @@ import {
   setDisjointUnion,
   setDisjointSubtract,
 } from '@agoric/store';
-import '../types-ambient.js';
+
+/**
+ * @import {MathHelpers} from '../types.js'
+ * @import {CopySet} from '@endo/patterns'
+ */
 
 /** @type {CopySet} */
 const empty = makeCopySet([]);
 
-/**
- * @type {MathHelpers<CopySet>}
- */
+/** @type {MathHelpers<CopySet>} */
 export const copySetMathHelpers = harden({
   doCoerce: set => {
     mustMatch(set, M.set(), 'set of amount');