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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/ertp",
-  "version": "0.16.3-mainnet1B-dev-26244e8.0+26244e8",
+  "version": "0.16.3-orchestration-dev-096c4e8.0+096c4e8",
   "description": "Electronic Rights Transfer Protocol (ERTP). A smart contract framework for exchanging electronic rights",
   "type": "module",
   "main": "src/index.js",
@@ -9,7 +9,7 @@
   },
   "scripts": {
     "build": "exit 0",
-    "prepack": "echo \"export {}; \" | cat - src/types-ambient.js > src/types.js && tsc --build jsconfig.build.json",
+    "prepack": "echo \"export {}; \" | cat - src/types-ambient.js > src/types.js && tsc --build --clean tsconfig.build.json",
     "postpack": "git clean -f '*.d.ts*' src/types.js",
     "test": "ava",
     "test:c8": "c8 $C8_OPTIONS ava",
@@ -19,7 +19,7 @@
     "lint-fix": "yarn lint:eslint --fix",
     "lint": "run-s --continue-on-error lint:*",
     "lint:eslint": "eslint .",
-    "lint:types": "tsc -p jsconfig.json"
+    "lint:types": "tsc"
   },
   "repository": {
     "type": "git",
@@ -39,22 +39,24 @@
   },
   "homepage": "https://github.com/Agoric/agoric-sdk#readme",
   "dependencies": {
-    "@agoric/assert": "0.6.1-mainnet1B-dev-26244e8.0+26244e8",
-    "@agoric/notifier": "0.6.3-mainnet1B-dev-26244e8.0+26244e8",
-    "@agoric/store": "0.9.3-mainnet1B-dev-26244e8.0+26244e8",
-    "@agoric/swingset-vat": "0.32.3-mainnet1B-dev-26244e8.0+26244e8",
-    "@agoric/vat-data": "0.5.3-mainnet1B-dev-26244e8.0+26244e8",
-    "@endo/eventual-send": "0.17.2",
-    "@endo/far": "0.2.18",
-    "@endo/marshal": "0.8.5",
-    "@endo/nat": "4.1.27",
-    "@endo/promise-kit": "0.2.56"
+    "@agoric/assert": "0.6.1-orchestration-dev-096c4e8.0+096c4e8",
+    "@agoric/notifier": "0.6.3-orchestration-dev-096c4e8.0+096c4e8",
+    "@agoric/store": "0.9.3-orchestration-dev-096c4e8.0+096c4e8",
+    "@agoric/vat-data": "0.5.3-orchestration-dev-096c4e8.0+096c4e8",
+    "@agoric/zone": "0.2.3-orchestration-dev-096c4e8.0+096c4e8",
+    "@endo/eventual-send": "^1.1.2",
+    "@endo/far": "^1.0.4",
+    "@endo/marshal": "^1.3.0",
+    "@endo/nat": "^5.0.4",
+    "@endo/patterns": "^1.2.0",
+    "@endo/promise-kit": "^1.0.4"
   },
   "devDependencies": {
-    "@endo/bundle-source": "2.5.2-upstream-rollup",
-    "@fast-check/ava": "^1.1.3",
-    "ava": "^5.2.0",
-    "tsd": "^0.28.1"
+    "@agoric/swingset-vat": "0.32.3-orchestration-dev-096c4e8.0+096c4e8",
+    "@endo/bundle-source": "^3.1.0",
+    "@fast-check/ava": "^1.1.5",
+    "ava": "^5.3.0",
+    "tsd": "^0.30.4"
   },
   "files": [
     "src",
@@ -74,10 +76,16 @@
     "files": [
       "test/**/test-*.js"
     ],
+    "require": [
+      "@endo/init/debug.js"
+    ],
     "timeout": "5m"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "26244e821f1a83cd5868f0c7d54aa480c8c17e5e"
+  "typeCoverage": {
+    "atLeast": 90.56
+  },
+  "gitHead": "096c4e8fce80e9a509b0e1a30fda11736c4570e1"
 }

package/src/amountMath.js

@@ -11,7 +11,12 @@ const { quote: q, Fail } = assert;
 /**
  * Constants for the kinds of assets we support.
  *
- * @type {{ NAT: 'nat', SET: 'set', COPY_SET: 'copySet', COPY_BAG: 'copyBag' }}
+ * @type {{
+ *   NAT: 'nat';
+ *   SET: 'set';
+ *   COPY_SET: 'copySet';
+ *   COPY_BAG: 'copyBag';
+ * }}
  */
 const AssetKind = harden({
   NAT: 'nat',
@@ -21,9 +26,7 @@ const AssetKind = harden({
 });
 const assetKindNames = harden(Object.values(AssetKind).sort());
 
-/**
- * @param {AssetKind} allegedAK
- */
+/** @param {AssetKind} allegedAK */
 const assertAssetKind = allegedAK => {
   assetKindNames.includes(allegedAK) ||
     Fail`The assetKind ${allegedAK} must be one of ${q(assetKindNames)}`;
@@ -31,42 +34,37 @@ const assertAssetKind = allegedAK => {
 harden(assertAssetKind);
 
 /**
- * Amounts describe digital assets. From an amount, you can learn the
- * brand of digital asset as well as "how much" or "how many". Amounts
- * have two parts: a brand (loosely speaking, the type of digital
- * asset) and the value (the answer to "how much"). For example, in
- * the phrase "5 bucks", "bucks" takes the role of the brand and the
- * value is 5. Amounts can describe fungible and non-fungible digital
- * assets. Amounts are pass-by-copy and can be made by and sent to
- * anyone.
+ * Amounts describe digital assets. From an amount, you can learn the brand of
+ * digital asset as well as "how much" or "how many". Amounts have two parts: a
+ * brand (loosely speaking, the type of digital asset) and the value (the answer
+ * to "how much"). For example, in the phrase "5 bucks", "bucks" takes the role
+ * of the brand and the value is 5. Amounts can describe fungible and
+ * non-fungible digital assets. Amounts are pass-by-copy and can be made by and
+ * sent to anyone.
  *
- * The issuer is the authoritative source of the amount in payments
- * and purses. The issuer must be able to do things such as add
- * digital assets to a purse and withdraw digital assets from a purse.
- * To do so, it must know how to add and subtract digital assets.
- * Rather than hard-coding a particular solution, we chose to
- * parameterize the issuer with a collection of polymorphic functions,
- * which we call `AmountMath`. These math functions include concepts
+ * The issuer is the authoritative source of the amount in payments and purses.
+ * The issuer must be able to do things such as add digital assets to a purse
+ * and withdraw digital assets from a purse. To do so, it must know how to add
+ * and subtract digital assets. Rather than hard-coding a particular solution,
+ * we chose to parameterize the issuer with a collection of polymorphic
+ * functions, which we call `AmountMath`. These math functions include concepts
  * like addition, subtraction, and greater than or equal to.
  *
- * We also want to make sure there is no confusion as to what kind of
- * asset we are using. Thus, AmountMath includes checks of the
- * `brand`, the unique identifier for the type of digital asset. If
- * the wrong brand is used in AmountMath, an error is thrown and the
- * operation does not succeed.
+ * We also want to make sure there is no confusion as to what kind of asset we
+ * are using. Thus, AmountMath includes checks of the `brand`, the unique
+ * identifier for the type of digital asset. If the wrong brand is used in
+ * AmountMath, an error is thrown and the operation does not succeed.
  *
- * AmountMath uses mathHelpers to do most of the work, but then adds
- * the brand to the result. The function `value` gets the value from
- * the amount by removing the brand (amount -> value), and the
- * function `make` adds the brand to produce an amount (value ->
- * amount). The function `coerce` takes an amount and checks it,
- * returning an amount (amount -> amount).
+ * AmountMath uses mathHelpers to do most of the work, but then adds the brand
+ * to the result. The function `value` gets the value from the amount by
+ * removing the brand (amount -> value), and the function `make` adds the brand
+ * to produce an amount (value -> amount). The function `coerce` takes an amount
+ * and checks it, returning an amount (amount -> amount).
  *
- * Each issuer of digital assets has an associated brand in a
- * one-to-one mapping. In untrusted contexts, such as in analyzing
- * payments and amounts, we can get the brand and find the issuer
- * which matches the brand. The issuer and the brand mutually validate
- * each other.
+ * Each issuer of digital assets has an associated brand in a one-to-one
+ * mapping. In untrusted contexts, such as in analyzing payments and amounts, we
+ * can get the brand and find the issuer which matches the brand. The issuer and
+ * the brand mutually validate each other.
  */
 
 const helpers = {
@@ -137,7 +135,7 @@ const optionalBrandCheck = (allegedBrand, brand) => {
  * @param {Amount<K>} leftAmount
  * @param {Amount<K>} rightAmount
  * @param {Brand<K> | undefined} brand
- * @returns {MathHelpers<*>}
+ * @returns {MathHelpers<any>}
  */
 const checkLRAndGetHelpers = (leftAmount, rightAmount, brand = undefined) => {
   assertRecord(leftAmount, 'leftAmount');
@@ -172,11 +170,11 @@ const coerceLR = (h, leftAmount, rightAmount) => {
 };
 
 /**
- * Returns true if the leftAmount is greater than or equal to the
- * rightAmount. The notion of "greater than or equal to" depends
- * on the kind of amount, as defined by the MathHelpers. For example,
- * whether rectangle A is greater than rectangle B depends on whether rectangle
- * A includes rectangle B as defined by the logic in MathHelpers.
+ * Returns true if the leftAmount is greater than or equal to the rightAmount.
+ * The notion of "greater than or equal to" depends on the kind of amount, as
+ * defined by the MathHelpers. For example, whether rectangle A is greater than
+ * rectangle B depends on whether rectangle A includes rectangle B as defined by
+ * the logic in MathHelpers.
  *
  * @template {AssetKind} K
  * @param {Amount<K>} leftAmount
@@ -194,9 +192,8 @@ const isGTE = (leftAmount, rightAmount, brand = undefined) => {
  *
  * Amounts are the canonical description of tradable goods. They are manipulated
  * by issuers and mints, and represent the goods and currency carried by purses
- * and
- * payments. They can be used to represent things like currency, stock, and the
- * abstract right to participate in a particular exchange.
+ * and payments. They can be used to represent things like currency, stock, and
+ * the abstract right to participate in a particular exchange.
  */
 const AmountMath = {
   /**
@@ -215,8 +212,8 @@ const AmountMath = {
     return harden({ brand, value });
   },
   /**
-   * Make sure this amount is valid enough, and return a corresponding
-   * valid amount if so.
+   * Make sure this amount is valid enough, and return a corresponding valid
+   * amount if so.
    *
    * @template {AssetKind} K
    * @param {Brand<K>} brand
@@ -242,8 +239,8 @@ const AmountMath = {
    */
   getValue: (brand, amount) => AmountMath.coerce(brand, amount).value,
   /**
-   * Return the amount representing an empty amount. This is the
-   * identity element for MathHelpers.add and MatHelpers.subtract.
+   * Return the amount representing an empty amount. This is the identity
+   * element for MathHelpers.add and MatHelpers.subtract.
    *
    * @type {{
    *   (brand: Brand): Amount<'nat'>;
@@ -257,8 +254,8 @@ const AmountMath = {
     return harden({ brand, value });
   },
   /**
-   * Return the amount representing an empty amount, using another
-   * amount as the template for the brand and assetKind.
+   * Return the amount representing an empty amount, using another amount as the
+   * template for the brand and assetKind.
    *
    * @template {AssetKind} K
    * @param {Amount<K>} amount
@@ -289,8 +286,8 @@ const AmountMath = {
   },
   isGTE,
   /**
-   * Returns true if the leftAmount equals the rightAmount. We assume
-   * that if isGTE is true in both directions, isEqual is also true
+   * Returns true if the leftAmount equals the rightAmount. We assume that if
+   * isGTE is true in both directions, isEqual is also true
    *
    * @template {AssetKind} K
    * @param {Amount<K>} leftAmount
@@ -306,8 +303,8 @@ const AmountMath = {
    * Returns a new amount that is the union of both leftAmount and rightAmount.
    *
    * For fungible amount this means adding the values. For other kinds of
-   * amount, it usually means including all of the elements from both
-   * left and right.
+   * amount, it usually means including all of the elements from both left and
+   * right.
    *
    * @template {AssetKind} K
    * @param {Amount<K>} leftAmount
@@ -321,12 +318,11 @@ const AmountMath = {
     return harden({ brand: leftAmount.brand, value });
   },
   /**
-   * Returns a new amount that is the leftAmount minus the rightAmount
-   * (i.e. everything in the leftAmount that is not in the
-   * rightAmount). If leftAmount doesn't include rightAmount
-   * (subtraction results in a negative), throw  an error. Because the
-   * left amount must include the right amount, this is NOT equivalent
-   * to set subtraction.
+   * Returns a new amount that is the leftAmount minus the rightAmount (i.e.
+   * everything in the leftAmount that is not in the rightAmount). If leftAmount
+   * doesn't include rightAmount (subtraction results in a negative), throw an
+   * error. Because the left amount must include the right amount, this is NOT
+   * equivalent to set subtraction.
    *
    * @template {AssetKind} K
    * @param {Amount<K>} leftAmount
@@ -374,9 +370,7 @@ const AmountMath = {
 };
 harden(AmountMath);
 
-/**
- * @param {Amount} amount
- */
+/** @param {Amount} amount */
 const getAssetKind = amount => {
   assertRecord(amount, 'amount');
   const { value } = amount;

package/src/amountStore.js

@@ -0,0 +1,32 @@
+import { AmountMath } from './amountMath.js';
+
+/**
+ * @template {AssetKind} [K=AssetKind]
+ * @typedef {object} AmountStore
+ * @property {() => Amount<K>} getAmount
+ * @property {(delta: Amount<K>) => void} increment
+ * @property {(delta: Amount<K>) => boolean} decrement
+ */
+
+/**
+ * @template {AssetKind} [K=AssetKind]
+ * @param {object} state
+ * @param {string} key
+ * @returns {AmountStore<K>}
+ */
+export const makeAmountStore = (state, key) => {
+  return harden({
+    getAmount: () => state[key],
+    increment: delta => {
+      state[key] = AmountMath.add(state[key], delta);
+    },
+    decrement: delta => {
+      if (AmountMath.isGTE(state[key], delta)) {
+        state[key] = AmountMath.subtract(state[key], delta);
+        return true;
+      }
+      return false;
+    },
+  });
+};
+harden(makeAmountStore);

package/src/index.js

@@ -3,3 +3,10 @@
 export * from './amountMath.js';
 export * from './issuerKit.js';
 export * from './typeGuards.js';
+
+/**
+ * Importing Baggage from `@agoric/ertp` is deprecated. Import Baggage from
+ * `@agoric/vat-data` instead
+ *
+ * @typedef {import('@agoric/vat-data').Baggage} Baggage
+ */