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

package/src/issuerKit.js

@@ -1,8 +1,9 @@
 // @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';
@@ -10,8 +11,6 @@ import { preparePaymentLedger } from './paymentLedger.js';
 
 import './types-ambient.js';
 
-/** @typedef {import('@agoric/vat-data').Baggage} Baggage */
-
 /**
  * @template {AssetKind} K
  * @typedef {object} IssuerRecord
@@ -22,21 +21,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');
@@ -56,11 +60,12 @@ const setupIssuerKit = (
   /** @type {PaymentLedger<K>} */
   // @ts-expect-error could be instantiated with different subtype of AssetKind
   const { issuer, mint, brand, mintRecoveryPurse } = preparePaymentLedger(
-    issuerBaggage,
+    issuerZone,
     name,
     assetKind,
     cleanDisplayInfo,
     elementShape,
+    recoverySetsState,
     optShutdownWithFailure,
   );
 
@@ -76,66 +81,116 @@ 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'`;
+  }
+  if (
+    oldRecoverySetsState === 'hasRecoverySets' &&
+    recoverySetsOption === 'noRecoverySets'
+  ) {
+    Fail`Cannot (yet?) upgrade from 'hasRecoverySets' to 'noRecoverySets'`;
+  }
+  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,39 +201,128 @@ 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.
+ *
+ * @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.
+ *
+ *   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]
+ * @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.
  *
- * 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='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.
  *
- *  `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 {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>}
  */
@@ -188,7 +332,7 @@ export const makeIssuerKit = (
   assetKind = AssetKind.NAT,
   displayInfo = harden({}),
   optShutdownWithFailure = undefined,
-  { elementShape = undefined } = {},
+  { elementShape = undefined, recoverySetsOption = undefined } = {},
 ) =>
   makeDurableIssuerKit(
     makeScalarBigMapStore('dropped issuer kit', { durable: true }),
@@ -196,6 +340,6 @@ export const makeIssuerKit = (
     assetKind,
     displayInfo,
     optShutdownWithFailure,
-    { elementShape },
+    { elementShape, recoverySetsOption },
   );
 harden(makeIssuerKit);

package/src/legacy-payment-helpers.js

@@ -7,19 +7,17 @@ import { AmountMath } from './amountMath.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`.
  */
 
 /**
@@ -43,11 +41,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 +82,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 +108,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.js

@@ -12,12 +12,10 @@ import {
 } from '@agoric/store';
 import '../types-ambient.js';
 
-/** @type {CopyBag} */
+/** @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.js

@@ -15,9 +15,7 @@ import '../types-ambient.js';
 /** @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.js

@@ -8,14 +8,13 @@ const { Fail } = assert;
 const empty = 0n;
 
 /**
- * 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>}
  */

package/src/payment.js

@@ -1,21 +1,18 @@
 // @jessie-check
 
 import { initEmpty } from '@agoric/store';
-import { prepareExoClass } from '@agoric/vat-data';
-
-/** @typedef {import('@agoric/vat-data').Baggage} Baggage */
 
+// TODO Type InterfaceGuard better than InterfaceGuard<any>
 /**
  * @template {AssetKind} K
- * @param {Baggage} issuerBaggage
+ * @param {import('@agoric/zone').Zone} issuerZone
  * @param {string} name
  * @param {Brand<K>} brand
- * @param {InterfaceGuard} PaymentI
+ * @param {import('@endo/patterns').InterfaceGuard<any>} PaymentI
  * @returns {() => Payment<K>}
  */
-export const preparePaymentKind = (issuerBaggage, name, brand, PaymentI) => {
-  const makePayment = prepareExoClass(
-    issuerBaggage,
+export const preparePaymentKind = (issuerZone, name, brand, PaymentI) => {
+  const makePayment = issuerZone.exoClass(
     `${name} payment`,
     PaymentI,
     initEmpty,