@agoric/ertp 0.15.6-pismo-dev-0d5327f.0 → 0.16.1-dev-bf4b59f.0

package/src/issuerKit.js

@@ -1,4 +1,3 @@
-// @ts-check
 // @jessie-check
 
 import { assert } from '@agoric/assert';
@@ -7,16 +6,26 @@ import { makeScalarBigMapStore } from '@agoric/vat-data';
 
 import { AssetKind, assertAssetKind } from './amountMath.js';
 import { coerceDisplayInfo } from './displayInfo.js';
-import { vivifyPaymentLedger } from './paymentLedger.js';
+import { preparePaymentLedger } from './paymentLedger.js';
 
-import './types.js';
+import './types-ambient.js';
 
 /** @typedef {import('@agoric/vat-data').Baggage} Baggage */
 
 /**
  * @template {AssetKind} K
+ * @typedef {object} IssuerRecord
+ * @property {string} name
+ * @property {K} assetKind
+ * @property {AdditionalDisplayInfo} displayInfo
+ * @property {Pattern} elementShape
+ */
+
+/**
+ * @template {AssetKind} K
+ * @param {IssuerRecord<K>} issuerRecord
  * @param {Baggage} issuerBaggage
- * @param {ShutdownWithFailure=} optShutdownWithFailure If this issuer fails
+ * @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
@@ -25,14 +34,11 @@ import './types.js';
  * See https://github.com/Agoric/agoric-sdk/issues/3434
  * @returns {IssuerKit<K>}
  */
-export const vivifyIssuerKit = (
+const setupIssuerKit = (
+  { name, assetKind, displayInfo, elementShape },
   issuerBaggage,
   optShutdownWithFailure = undefined,
 ) => {
-  const name = issuerBaggage.get('name');
-  const assetKind = issuerBaggage.get('assetKind');
-  const displayInfo = issuerBaggage.get('displayInfo');
-  const elementShape = issuerBaggage.get('elementShape');
   assert.typeof(name, 'string');
   assertAssetKind(assetKind);
 
@@ -47,7 +53,9 @@ export const vivifyIssuerKit = (
   }
 
   // Attenuate the powerful authority to mint and change balances
-  const { issuer, mint, brand } = vivifyPaymentLedger(
+  /** @type {PaymentLedger<K>} */
+  // @ts-expect-error could be instantiated with different subtype of AssetKind
+  const { issuer, mint, brand, mintRecoveryPurse } = preparePaymentLedger(
     issuerBaggage,
     name,
     assetKind,
@@ -60,10 +68,47 @@ export const vivifyIssuerKit = (
     brand,
     issuer,
     mint,
+    mintRecoveryPurse,
     displayInfo: cleanDisplayInfo,
   });
 };
-harden(vivifyIssuerKit);
+harden(setupIssuerKit);
+
+/** The key at which the issuer record is stored. */
+const INSTANCE_KEY = 'issuer';
+
+/**
+ * @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
+ * @returns {IssuerKit<K>}
+ */
+export const prepareIssuerKit = (
+  issuerBaggage,
+  optShutdownWithFailure = undefined,
+) => {
+  const issuerRecord = issuerBaggage.get(INSTANCE_KEY);
+  return setupIssuerKit(issuerRecord, issuerBaggage, optShutdownWithFailure);
+};
+harden(prepareIssuerKit);
+
+/**
+ * Does baggage already have an issuer from prepareIssuerKit()?
+ * That is: does it have the relevant keys defined?
+ *
+ * @param {Baggage} baggage
+ */
+export const hasIssuer = baggage => baggage.has(INSTANCE_KEY);
+
+/**
+ * @typedef {Partial<{elementShape: Pattern}>} IssuerOptionsRecord
+ */
 
 /**
  * @template {AssetKind} K
@@ -84,14 +129,14 @@ harden(vivifyIssuerKit);
  * @param {string} name
  * @param {K} [assetKind=AssetKind.NAT]
  * @param {AdditionalDisplayInfo} [displayInfo={}]
- * @param {ShutdownWithFailure=} optShutdownWithFailure If this issuer fails
+ * @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 {Partial<{elementShape: Pattern}>} [options]
+ * @param {IssuerOptionsRecord} [options]
  * @returns {IssuerKit<K>}
  */
 export const makeDurableIssuerKit = (
@@ -103,16 +148,14 @@ export const makeDurableIssuerKit = (
   optShutdownWithFailure = undefined,
   { elementShape = undefined } = {},
 ) => {
-  issuerBaggage.init('name', name);
-  issuerBaggage.init('assetKind', assetKind);
-  issuerBaggage.init('displayInfo', displayInfo);
-  issuerBaggage.init('elementShape', elementShape);
-  return vivifyIssuerKit(issuerBaggage, optShutdownWithFailure);
+  const issuerData = harden({ name, assetKind, displayInfo, elementShape });
+  issuerBaggage.init(INSTANCE_KEY, issuerData);
+  return setupIssuerKit(issuerData, issuerBaggage, optShutdownWithFailure);
 };
 harden(makeDurableIssuerKit);
 
 /**
- * @template {AssetKind} K
+ * @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.
@@ -127,16 +170,16 @@ harden(makeDurableIssuerKit);
  *  `displayInfo` gives information to the UI on how to display the amount.
  *
  * @param {string} name
- * @param {K} [assetKind=AssetKind.NAT]
+ * @param {K} [assetKind='nat']
  * @param {AdditionalDisplayInfo} [displayInfo={}]
- * @param {ShutdownWithFailure=} optShutdownWithFailure If this issuer fails
+ * @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 {Partial<{elementShape: Pattern}>} [options]
+ * @param {IssuerOptionsRecord} [options]
  * @returns {IssuerKit<K>}
  */
 export const makeIssuerKit = (

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

@@ -0,0 +1,5 @@
+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 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[]>;
+//# sourceMappingURL=legacy-payment-helpers.d.ts.map

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

@@ -0,0 +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"}

package/src/legacy-payment-helpers.js

@@ -0,0 +1,146 @@
+// @jessie-check
+
+import { mustMatch } from '@agoric/store';
+import { E } from '@endo/far';
+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.
+ *
+ * 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
+ * @param {Pattern} [optAmountShape]
+ * @returns {Promise<Payment<K>>}
+ */
+export const claim = async (
+  recoveryPurse,
+  srcPaymentP,
+  optAmountShape = undefined,
+) => {
+  const srcPayment = await srcPaymentP;
+  return E.when(E(recoveryPurse).deposit(srcPayment, optAmountShape), amount =>
+    E(recoveryPurse).withdraw(amount),
+  );
+};
+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.
+ *
+ * @template {AssetKind} K
+ * @param {ERef<Purse<K>>} recoveryPurse
+ * @param {ERef<Payment<K>>[]} srcPaymentsPs
+ * @param {Pattern} [optTotalAmount]
+ * @returns {Promise<Payment<K>>}
+ */
+export const combine = async (
+  recoveryPurse,
+  srcPaymentsPs,
+  optTotalAmount = undefined,
+) => {
+  const brandP = E(recoveryPurse).getAllegedBrand();
+  const [brand, displayInfo, ...srcPayments] = await Promise.all([
+    brandP,
+    E(brandP).getDisplayInfo(),
+    ...srcPaymentsPs,
+  ]);
+  const emptyAmount = AmountMath.makeEmpty(brand, displayInfo.assetKind);
+  const amountPs = srcPayments.map(srcPayment =>
+    E(recoveryPurse).deposit(srcPayment),
+  );
+  const amounts = await Promise.all(amountPs);
+  const total = amounts.reduce(
+    (x, y) => AmountMath.add(x, y, brand),
+    emptyAmount,
+  );
+  if (optTotalAmount !== undefined) {
+    mustMatch(total, optTotalAmount, 'amount');
+  }
+  return E(recoveryPurse).withdraw(total);
+};
+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`.
+ *
+ * @template {AssetKind} K
+ * @param {ERef<Purse<K>>} recoveryPurse
+ * @param {ERef<Payment<K>>} srcPaymentP
+ * @param {Amount<K>} paymentAmountA
+ * @returns {Promise<Payment<K>[]>}
+ */
+export const split = async (recoveryPurse, srcPaymentP, paymentAmountA) => {
+  const srcPayment = await srcPaymentP;
+  // See https://github.com/Agoric/agoric-sdk/issues/7193 which explains
+  // how we would like to write the following line, and why we cannot yet do so.
+  const srcAmount = await E(recoveryPurse).deposit(srcPayment);
+  const paymentAmountB = AmountMath.subtract(srcAmount, paymentAmountA);
+  return Promise.all([
+    E(recoveryPurse).withdraw(paymentAmountA),
+    E(recoveryPurse).withdraw(paymentAmountB),
+  ]);
+};
+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`.
+ *
+ * @template {AssetKind} K
+ * @param {ERef<Purse<K>>} recoveryPurse
+ * @param {ERef<Payment<K>>} srcPaymentP
+ * @param {Amount<K>[]} amounts
+ * @returns {Promise<Payment[]>}
+ */
+export const splitMany = async (recoveryPurse, srcPaymentP, amounts) => {
+  const srcPayment = await srcPaymentP;
+  // If we could calculate `total` before the `deposit`, then we
+  // could use the `total` as the second argument to `deposit` and be
+  // failure atomic. But this would require making an empty amount first,
+  // which is possible, but too much trouble for a deprecated legacy support
+  // method.
+  const srcAmount = await E(recoveryPurse).deposit(srcPayment);
+  const brand = srcAmount.brand;
+  const emptyAmount = AmountMath.makeEmptyFromAmount(srcAmount);
+  const total = amounts.reduce(
+    (x, y) => AmountMath.add(x, y, brand),
+    emptyAmount,
+  );
+  AmountMath.isEqual(srcAmount, total) ||
+    Fail`rights were not conserved: ${total} vs ${srcAmount}`;
+
+  return Promise.all(amounts.map(amount => E(recoveryPurse).withdraw(amount)));
+};
+harden(splitMany);

package/src/mathHelpers/copyBagMathHelpers.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @type {MathHelpers<CopyBag>}
+ */
+export const copyBagMathHelpers: MathHelpers<CopyBag>;
+//# sourceMappingURL=copyBagMathHelpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"copyBagMathHelpers.d.ts","sourceRoot":"","sources":["copyBagMathHelpers.js"],"names":[],"mappings":"AAiBA;;GAEG;AACH,iCAFU,YAAY,OAAO,CAAC,CAa3B"}

package/src/mathHelpers/copyBagMathHelpers.js

@@ -1,26 +1,26 @@
-// @ts-check
+// @jessie-check
 
 import {
   keyEQ,
   makeCopyBag,
-  fit,
+  mustMatch,
   M,
   getCopyBagEntries,
   bagIsSuperbag,
   bagUnion,
   bagDisjointSubtract,
 } from '@agoric/store';
-import '../types.js';
+import '../types-ambient.js';
 
-/** @type {CopyBagValue} */
+/** @type {CopyBag} */
 const empty = makeCopyBag([]);
 
 /**
- * @type {CopyBagMathHelpers}
+ * @type {MathHelpers<CopyBag>}
  */
 export const copyBagMathHelpers = harden({
   doCoerce: bag => {
-    fit(bag, M.bag(), 'bag of amount');
+    mustMatch(bag, M.bag(), 'bag of amount');
     return bag;
   },
   doMakeEmpty: () => empty,

package/src/mathHelpers/copySetMathHelpers.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @type {MathHelpers<CopySet>}
+ */
+export const copySetMathHelpers: MathHelpers<CopySet>;
+//# sourceMappingURL=copySetMathHelpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"copySetMathHelpers.d.ts","sourceRoot":"","sources":["copySetMathHelpers.js"],"names":[],"mappings":"AAiBA;;GAEG;AACH,iCAFU,YAAY,OAAO,CAAC,CAa3B"}

package/src/mathHelpers/copySetMathHelpers.js

@@ -1,26 +1,26 @@
-// @ts-check
+// @jessie-check
 
 import {
   keyEQ,
   makeCopySet,
-  fit,
+  mustMatch,
   M,
   getCopySetKeys,
   setIsSuperset,
   setDisjointUnion,
   setDisjointSubtract,
 } from '@agoric/store';
-import '../types.js';
+import '../types-ambient.js';
 
-/** @type {CopySetValue} */
+/** @type {CopySet} */
 const empty = makeCopySet([]);
 
 /**
- * @type {CopySetMathHelpers}
+ * @type {MathHelpers<CopySet>}
  */
 export const copySetMathHelpers = harden({
   doCoerce: set => {
-    fit(set, M.set(), 'set of amount');
+    mustMatch(set, M.set(), 'set of amount');
     return set;
   },
   doMakeEmpty: () => empty,

package/src/mathHelpers/natMathHelpers.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ *
+ * @type {MathHelpers<NatValue>}
+ */
+export const natMathHelpers: MathHelpers<NatValue>;
+//# sourceMappingURL=natMathHelpers.d.ts.map

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

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

package/src/mathHelpers/natMathHelpers.js

@@ -1,10 +1,10 @@
-// @ts-check
+// @jessie-check
 
-import { Nat, isNat } from '@agoric/nat';
+import { Nat, isNat } from '@endo/nat';
 
-import '../types.js';
+import '../types-ambient.js';
 
-const { details: X } = assert;
+const { Fail } = assert;
 const empty = 0n;
 
 /**
@@ -14,16 +14,16 @@ const empty = 0n;
  *
  * 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
+ * done with the smallest whole unit such that the `natMathHelpers` never
  * deals with fractional parts.
  *
- * @type {NatMathHelpers}
+ * @type {MathHelpers<NatValue>}
  */
 export const natMathHelpers = harden({
   doCoerce: nat => {
     // TODO: tighten the definition of Nat in @agoric/nat to throw on `number`
     assert.typeof(nat, 'bigint');
-    assert(isNat(nat), X`value ${nat} must be a natural number`);
+    isNat(nat) || Fail`value ${nat} must be a natural number`;
     return Nat(nat);
   },
   doMakeEmpty: () => empty,

package/src/mathHelpers/setMathHelpers.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @deprecated Replace array-based SetMath with CopySet-based CopySetMath
+ * @type {MathHelpers<SetValue>}
+ */
+export const setMathHelpers: MathHelpers<SetValue>;
+//# sourceMappingURL=setMathHelpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"setMathHelpers.d.ts","sourceRoot":"","sources":["setMathHelpers.js"],"names":[],"mappings":"AAkBA;;;GAGG;AACH,6BAFU,qBAAqB,CAkB5B"}

package/src/mathHelpers/setMathHelpers.js

@@ -1,4 +1,4 @@
-// @ts-check
+// @jessie-check
 
 import { passStyleOf } from '@endo/marshal';
 import {
@@ -9,7 +9,7 @@ import {
   coerceToElements,
   elementsCompare,
 } from '@agoric/store';
-import '../types.js';
+import '../types-ambient.js';
 
 // Operations for arrays with unique objects identifying and providing
 // information about digital assets. Used for Zoe invites.
@@ -18,7 +18,7 @@ const empty = harden([]);
 
 /**
  * @deprecated Replace array-based SetMath with CopySet-based CopySetMath
- * @type {SetMathHelpers}
+ * @type {MathHelpers<SetValue>}
  */
 export const setMathHelpers = harden({
   doCoerce: list => {

package/src/payment.d.ts

@@ -0,0 +1,3 @@
+export function preparePaymentKind<K extends AssetKind>(issuerBaggage: MapStore<string, unknown>, name: string, brand: Brand<K>, PaymentI: InterfaceGuard): () => Payment<K>;
+export type Baggage = import('@agoric/vat-data').Baggage;
+//# sourceMappingURL=payment.d.ts.map

package/src/payment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment.d.ts","sourceRoot":"","sources":["payment.js"],"names":[],"mappings":"AAeO,wGALI,MAAM,6BAEN,cAAc,oBAgBxB;sBAvBa,OAAO,kBAAkB,EAAE,OAAO"}

package/src/payment.js

@@ -1,7 +1,7 @@
-// @ts-check
+// @jessie-check
 
 import { initEmpty } from '@agoric/store';
-import { vivifyFarClass } from '@agoric/vat-data';
+import { prepareExoClass } from '@agoric/vat-data';
 
 /** @typedef {import('@agoric/vat-data').Baggage} Baggage */
 
@@ -13,8 +13,8 @@ import { vivifyFarClass } from '@agoric/vat-data';
  * @param {InterfaceGuard} PaymentI
  * @returns {() => Payment<K>}
  */
-export const vivifyPaymentKind = (issuerBaggage, name, brand, PaymentI) => {
-  const makePayment = vivifyFarClass(
+export const preparePaymentKind = (issuerBaggage, name, brand, PaymentI) => {
+  const makePayment = prepareExoClass(
     issuerBaggage,
     `${name} payment`,
     PaymentI,
@@ -27,4 +27,4 @@ export const vivifyPaymentKind = (issuerBaggage, name, brand, PaymentI) => {
   );
   return makePayment;
 };
-harden(vivifyPaymentKind);
+harden(preparePaymentKind);

package/src/paymentLedger.d.ts

@@ -0,0 +1,3 @@
+export function preparePaymentLedger<K extends AssetKind>(issuerBaggage: MapStore<string, unknown>, name: string, assetKind: K, displayInfo: DisplayInfo<K>, elementShape: Pattern, optShutdownWithFailure?: import("@agoric/swingset-vat").ShutdownWithFailure | undefined): PaymentLedger<K>;
+export type Baggage = import('@agoric/vat-data').Baggage;
+//# sourceMappingURL=paymentLedger.d.ts.map

package/src/paymentLedger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paymentLedger.d.ts","sourceRoot":"","sources":["paymentLedger.js"],"names":[],"mappings":"AAoFO,0GAPI,MAAM,2DAGN,OAAO,6GA+UjB;sBA9Ya,OAAO,kBAAkB,EAAE,OAAO"}