@agoric/ertp 0.16.3-dev-97f26d4.0 → 0.16.3-dev-d708d81.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/ertp",
-  "version": "0.16.3-dev-97f26d4.0+97f26d4",
+  "version": "0.16.3-dev-d708d81.0+d708d81",
   "description": "Electronic Rights Transfer Protocol (ERTP). A smart contract framework for exchanging electronic rights",
   "type": "module",
   "main": "src/index.js",
@@ -39,10 +39,10 @@
   },
   "homepage": "https://github.com/Agoric/agoric-sdk#readme",
   "dependencies": {
-    "@agoric/assert": "0.6.1-dev-97f26d4.0+97f26d4",
-    "@agoric/notifier": "0.6.3-dev-97f26d4.0+97f26d4",
-    "@agoric/store": "0.9.3-dev-97f26d4.0+97f26d4",
-    "@agoric/vat-data": "0.5.3-dev-97f26d4.0+97f26d4",
+    "@agoric/assert": "0.6.1-dev-d708d81.0+d708d81",
+    "@agoric/notifier": "0.6.3-dev-d708d81.0+d708d81",
+    "@agoric/store": "0.9.3-dev-d708d81.0+d708d81",
+    "@agoric/vat-data": "0.5.3-dev-d708d81.0+d708d81",
     "@endo/eventual-send": "^0.17.5",
     "@endo/far": "^0.2.21",
     "@endo/marshal": "^0.8.8",
@@ -51,7 +51,7 @@
     "@endo/promise-kit": "^0.2.59"
   },
   "devDependencies": {
-    "@agoric/swingset-vat": "0.32.3-dev-97f26d4.0+97f26d4",
+    "@agoric/swingset-vat": "0.32.3-dev-d708d81.0+d708d81",
     "@endo/bundle-source": "^2.7.0",
     "@fast-check/ava": "^1.1.5",
     "ava": "^5.3.0",
@@ -86,5 +86,5 @@
   "typeCoverage": {
     "atLeast": 90.37
   },
-  "gitHead": "97f26d4e149bd2665f96571edfdae04f1ffec22d"
+  "gitHead": "d708d81ab9cee46fe0c2dfa9555cbabd6f6f44f5"
 }

package/src/issuerKit.js

@@ -10,6 +10,8 @@ import { preparePaymentLedger } from './paymentLedger.js';
 
 import './types-ambient.js';
 
+// TODO Why does TypeScript lose the `MapStore` typing of `Baggage` here, even
+// though it knows the correct type at the exporting `@agoric/vat-data`
 /** @typedef {import('@agoric/vat-data').Baggage} Baggage */
 
 /**
@@ -22,6 +24,8 @@ 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
@@ -78,6 +82,9 @@ harden(setupIssuerKit);
 const INSTANCE_KEY = 'issuer';
 
 /**
+ * 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
@@ -89,26 +96,51 @@ const INSTANCE_KEY = 'issuer';
  *   https://github.com/Agoric/agoric-sdk/issues/3434
  * @returns {IssuerKit<K>}
  */
-export const prepareIssuerKit = (
+export const upgradeIssuerKit = (
   issuerBaggage,
   optShutdownWithFailure = undefined,
 ) => {
   const issuerRecord = issuerBaggage.get(INSTANCE_KEY);
   return setupIssuerKit(issuerRecord, issuerBaggage, optShutdownWithFailure);
 };
-harden(prepareIssuerKit);
+harden(upgradeIssuerKit);
 
 /**
- * Does baggage already have an issuer from prepareIssuerKit()? That is: does it
- * have the relevant keys defined?
+ * Confusingly, `prepareIssuerKit` was the original name for `upgradeIssuerKit`,
+ * even though it is used only to upgrade a predecessor issuerKit. Use
+ * `makeDurableIssuerKit` to make a new one.
+ *
+ * @deprecated Use `upgradeIssuerKit` instead if that's what you want. Or
+ *   `reallyPrepareIssuerKit` if you want the behavior that should have been
+ *   bound to this name.
+ */
+export const prepareIssuerKit = upgradeIssuerKit;
+
+/**
+ * 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".)
+ *
+ * @typedef {Partial<{
+ *   elementShape: Pattern;
+ * }>} IssuerOptionsRecord
+ */
 
 /**
+ * Used _only_ to make a _new_ durable issuer, i.e., the initial incarnation of
+ * that issuer.
+ *
  * @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
@@ -151,6 +183,78 @@ export const makeDurableIssuerKit = (
 harden(makeDurableIssuerKit);
 
 /**
+ * What _should_ have been named `prepareIssuerKit`. Used to either revive a
+ * predecessor issuerKit, or to make a new durable one if it is absent, and to
+ * place it in baggage for the next successor.
+ *
+ * @template {AssetKind} K The name becomes part of the brand in asset
+ *   descriptions. The name is useful for debugging and double-checking
+ *   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 {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 reallyPrepareIssuerKit = (
+  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 } = options;
+    const issuerKit = upgradeIssuerKit(issuerBaggage, optShutdownWithFailure);
+
+    // 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.
+
+    // @ts-expect-error Type parameter confusion.
+    return issuerKit;
+  } else {
+    const issuerKit = makeDurableIssuerKit(
+      issuerBaggage,
+      name,
+      assetKind,
+      displayInfo,
+      optShutdownWithFailure,
+      options,
+    );
+    return issuerKit;
+  }
+};
+harden(reallyPrepareIssuerKit);
+
+/**
+ * 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

package/src/paymentLedger.js

@@ -310,6 +310,8 @@ export const preparePaymentLedger = (
     return payment;
   };
 
+  /** @type {() => Purse<K>} */
+  // @ts-expect-error type parameter confusion
   const makeEmptyPurse = preparePurseKind(
     issuerBaggage,
     name,

package/src/purse.js

@@ -3,8 +3,26 @@ import { prepareExoClassKit, makeScalarBigSetStore } from '@agoric/vat-data';
 import { AmountMath } from './amountMath.js';
 import { makeTransientNotifierKit } from './transientNotifier.js';
 
+// TODO `InterfaceGuard` type parameter
+/** @typedef {import('@endo/patterns').InterfaceGuard} InterfaceGuard */
+/** @typedef {import('@agoric/vat-data').Baggage} Baggage */
+
 const { Fail } = assert;
 
+/**
+ * @param {Baggage} issuerBaggage
+ * @param {string} name
+ * @param {AssetKind} assetKind
+ * @param {Brand} brand
+ * @param {{
+ *   purse: InterfaceGuard;
+ *   depositFacet: InterfaceGuard;
+ * }} PurseIKit
+ * @param {{
+ *   depositInternal: any;
+ *   withdrawInternal: any;
+ * }} purseMethods
+ */
 export const preparePurseKind = (
   issuerBaggage,
   name,

package/src/types-ambient.js

@@ -115,7 +115,7 @@
 /**
  * @callback IssuerIsLive Return true if the payment continues to exist.
  *
- *   If the payment is a promise, the operation will proceed upon resolution.
+ *   If the payment is a promise, the operation will proceed upon fulfillment.
  * @param {ERef<Payment>} payment
  * @returns {Promise<boolean>}
  */
@@ -125,18 +125,25 @@
  *   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.
+ *   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.
+ *   `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 resolution.
+ *   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>}
@@ -171,7 +178,8 @@
  * @template {AssetKind} [K=AssetKind]
  * @typedef {object} PaymentLedger
  * @property {Mint<K>} mint
- * @property {Purse<K>} mintRecoveryPurse
+ * @property {Purse<K>} mintRecoveryPurse Useful only to get the recovery set
+ *   associated with minted payments that are still live.
  * @property {Issuer<K>} issuer
  * @property {Brand<K>} brand
  */
@@ -180,7 +188,8 @@
  * @template {AssetKind} [K=AssetKind]
  * @typedef {object} IssuerKit
  * @property {Mint<K>} mint
- * @property {Purse<K>} mintRecoveryPurse
+ * @property {Purse<K>} mintRecoveryPurse Useful only to get the recovery set
+ *   associated with minted payments that are still live.
  * @property {Issuer<K>} issuer
  * @property {Brand<K>} brand
  * @property {DisplayInfo} displayInfo
@@ -211,6 +220,8 @@
  *   Payment containing newly minted amount.
  */
 
+// /////////////////////////// Purse / Payment /////////////////////////////////
+
 /**
  * @callback DepositFacetReceive
  * @param {Payment} payment
@@ -298,6 +309,8 @@
  *   be treated with suspicion and verified elsewhere.
  */
 
+// /////////////////////////// MathHelpers /////////////////////////////////////
+
 /**
  * @template {AmountValue} V
  * @typedef {object} MathHelpers All of the difference in how digital asset

package/src/types.js

@@ -116,7 +116,7 @@ export {};
 /**
  * @callback IssuerIsLive Return true if the payment continues to exist.
  *
- *   If the payment is a promise, the operation will proceed upon resolution.
+ *   If the payment is a promise, the operation will proceed upon fulfillment.
  * @param {ERef<Payment>} payment
  * @returns {Promise<boolean>}
  */
@@ -126,18 +126,25 @@ export {};
  *   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.
+ *   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.
+ *   `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 resolution.
+ *   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>}
@@ -172,7 +179,8 @@ export {};
  * @template {AssetKind} [K=AssetKind]
  * @typedef {object} PaymentLedger
  * @property {Mint<K>} mint
- * @property {Purse<K>} mintRecoveryPurse
+ * @property {Purse<K>} mintRecoveryPurse Useful only to get the recovery set
+ *   associated with minted payments that are still live.
  * @property {Issuer<K>} issuer
  * @property {Brand<K>} brand
  */
@@ -181,7 +189,8 @@ export {};
  * @template {AssetKind} [K=AssetKind]
  * @typedef {object} IssuerKit
  * @property {Mint<K>} mint
- * @property {Purse<K>} mintRecoveryPurse
+ * @property {Purse<K>} mintRecoveryPurse Useful only to get the recovery set
+ *   associated with minted payments that are still live.
  * @property {Issuer<K>} issuer
  * @property {Brand<K>} brand
  * @property {DisplayInfo} displayInfo
@@ -212,6 +221,8 @@ export {};
  *   Payment containing newly minted amount.
  */
 
+// /////////////////////////// Purse / Payment /////////////////////////////////
+
 /**
  * @callback DepositFacetReceive
  * @param {Payment} payment
@@ -299,6 +310,8 @@ export {};
  *   be treated with suspicion and verified elsewhere.
  */
 
+// /////////////////////////// MathHelpers /////////////////////////////////////
+
 /**
  * @template {AmountValue} V
  * @typedef {object} MathHelpers All of the difference in how digital asset