@agoric/ertp 0.16.3-u14.0 → 0.16.3-u16.0

package/src/issuerKit.js

@@ -1,16 +1,16 @@
 // @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';
 import { preparePaymentLedger } from './paymentLedger.js';
 
-import './types-ambient.js';
-
-/** @typedef {import('@agoric/vat-data').Baggage} Baggage */
+/** @import {AdditionalDisplayInfo, RecoverySetsOption, IssuerKit, PaymentLedger} from './types.js' */
+/** @import {ShutdownWithFailure} from '@agoric/swingset-vat' */
 
 /**
  * @template {AssetKind} K
@@ -22,21 +22,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 {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
+ *   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 +59,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 +82,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 {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
+ *   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
+ * @param {import('@agoric/vat-data').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.
  *
- * @param {Baggage} issuerBaggage
+ *   `displayInfo` gives information to the UI on how to display the amount.
+ * @param {import('@agoric/vat-data').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,49 +199,138 @@ 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 {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 {import('@agoric/vat-data').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 {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>}
  */
+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,
+  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,
+    );
+    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'] 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.
+ *
+ *   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 {string} name
+ * @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, any>}
+ */
 export const makeIssuerKit = (
   name,
   // @ts-expect-error K could be instantiated with a different subtype of AssetKind
   assetKind = AssetKind.NAT,
   displayInfo = harden({}),
   optShutdownWithFailure = undefined,
-  { elementShape = undefined } = {},
+  { elementShape = undefined, recoverySetsOption = undefined } = {},
 ) =>
   makeDurableIssuerKit(
     makeScalarBigMapStore('dropped issuer kit', { durable: true }),
@@ -196,6 +338,6 @@ export const makeIssuerKit = (
     assetKind,
     displayInfo,
     optShutdownWithFailure,
-    { elementShape },
+    { elementShape, recoverySetsOption },
   );
 harden(makeIssuerKit);

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

@@ -1,5 +1,10 @@
-export function claim<K extends AssetKind>(recoveryPurse: ERef<Purse<K>>, srcPaymentP: ERef<Payment<K>>, optAmountShape?: Pattern): Promise<Payment<K>>;
+export function claim<P extends Payment>(recoveryPurse: ERef<Purse>, srcPaymentP: ERef<P>, optAmountShape?: Pattern): Promise<P>;
 export function combine<K extends AssetKind>(recoveryPurse: ERef<Purse<K>>, srcPaymentsPs: ERef<Payment<K>>[], optTotalAmount?: Pattern): Promise<Payment<K>>;
 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 { Payment } from './types.js';
+import type { Purse } from './types.js';
+import type { ERef } from '@endo/far';
+import type { AssetKind } from './types.js';
+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":"AAkCO,sBANgB,CAAC,SAAX,OAAS,iBACX,KAAK,KAAK,CAAC,eACX,KAAK,CAAC,CAAC,mBACP,OAAO,GACL,OAAO,CAAC,CAAC,CAAC,CAYtB;AAiBM,wBANkB,CAAC,SAAb,SAAW,iBACb,KAAK,MAAM,CAAC,CAAC,CAAC,iBACd,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,mBAClB,OAAO,GACL,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CA0B/B;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;6BAzI0F,YAAY;2BAAZ,YAAY;0BADhF,WAAW;+BACyD,YAAY;4BAAZ,YAAY"}

package/src/legacy-payment-helpers.js

@@ -4,30 +4,33 @@ import { mustMatch } from '@agoric/store';
 import { E } from '@endo/far';
 import { AmountMath } from './amountMath.js';
 
+/**
+ * @import {ERef} from '@endo/far');
+ * @import {Amount, AssetKind, AmountValue, AssetKindForValue, Payment, Brand, Purse} from './types.js'
+ */
+
 const { Fail } = assert;
 
 /**
- * @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 {Payment} P
+ * @param {ERef<Purse>} recoveryPurse
+ * @param {ERef<P>} srcPaymentP
  * @param {Pattern} [optAmountShape]
- * @returns {Promise<Payment<K>>}
+ * @returns {Promise<P>}
  */
 export const claim = async (
   recoveryPurse,
@@ -35,6 +38,7 @@ export const claim = async (
   optAmountShape = undefined,
 ) => {
   const srcPayment = await srcPaymentP;
+  // @ts-expect-error XXX could be instantiated with a different subtype
   return E.when(E(recoveryPurse).deposit(srcPayment, optAmountShape), amount =>
     E(recoveryPurse).withdraw(amount),
   );
@@ -43,11 +47,11 @@ 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
@@ -84,11 +88,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 +114,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');

package/src/mathHelpers/natMathHelpers.d.ts

@@ -1,14 +1,15 @@
 /**
- * Fungible digital assets use the natMathHelpers to manage balances -
- * the operations are merely arithmetic on natural, non-negative
- * numbers.
+ * Fungible digital assets use the natMathHelpers to manage balances - the
+ * operations are merely arithmetic on natural, non-negative numbers.
  *
- * Natural numbers are used for fungible erights such as money because
- * rounding issues make floats problematic. All operations should be
- * done with the smallest whole unit such that the `natMathHelpers` never
- * deals with fractional parts.
+ * Natural numbers are used for fungible erights such as money because rounding
+ * issues make floats problematic. All operations should be done with the
+ * smallest whole unit such that the `natMathHelpers` never deals with
+ * fractional parts.
  *
  * @type {MathHelpers<NatValue>}
  */
 export const natMathHelpers: MathHelpers<NatValue>;
+import type { NatValue } from '../types.js';
+import type { MathHelpers } from '../types.js';
 //# sourceMappingURL=natMathHelpers.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"natMathHelpers.d.ts","sourceRoot":"","sources":["natMathHelpers.js"],"names":[],"mappings":"AASA;;;;;;;;;;;GAWG;AACH,6BAFU,YAAY,QAAQ,CAAC,CAgB5B"}
+{"version":3,"file":"natMathHelpers.d.ts","sourceRoot":"","sources":["natMathHelpers.js"],"names":[],"mappings":"AASA;;;;;;;;;;GAUG;AACH,6BAFU,YAAY,QAAQ,CAAC,CAgB5B;8BA9BsC,aAAa;iCAAb,aAAa"}