WIP: Breaking changes in Zoe and ERTP in Beta - Part 1 (#2986)

* refactor!: remove deprecated `kickOut` (#2984)

* refactor!: remove makePercent (#2987)

* refactor!: move fakeVatAdmin to tools/, and remove from contractFacet/ (#2985)

* refactor!: Rename AmountMathKind and MathKind to AssetKind (#3054)

Author: katelynsills

packages/ERTP/src/amountMath.js

@@ -13,26 +13,27 @@ import {
   looksLikeBrand,
 } from './typeGuards';
 
-// We want an enum, but narrowed to the AmountMathKind type.
+// We want an enum, but narrowed to the AssetKind type.
 /**
- * Constants for the kinds of amountMath we support.
+ * Constants for the kinds of assets we support.
  *
  * @type {{ NAT: 'nat', SET: 'set' }}
  */
-const MathKind = {
+const AssetKind = {
   NAT: 'nat',
   SET: 'set',
 };
-harden(MathKind);
+harden(AssetKind);
 
 /**
  * Amounts describe digital assets. From an amount, you can learn the
- * kind of digital asset as well as "how much" or "how many". Amounts
- * have two parts: a brand (the kind 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.
+ * 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 has an internal table that maps purses and payments to
  * amounts. The issuer must be able to do things such as add digital
@@ -51,15 +52,16 @@ harden(MathKind);
  *
  * 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).
+ * 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.
  */
 
 /** @type {{ nat: NatMathHelpers, set: SetMathHelpers }} */
@@ -82,8 +84,8 @@ const getHelpersFromValue = value => {
   assert.fail(X`value ${value} must be a bigint or an array`);
 };
 
-/** @type {(amount: Amount) => AmountMathKind} */
-const getMathKind = amount => {
+/** @type {(amount: Amount) => AssetKind} */
+const getAssetKind = amount => {
   if (looksLikeSetValue(amount.value)) {
     return 'set';
   }
@@ -199,16 +201,16 @@ const AmountMath = {
   },
   // @ts-ignore TODO Why doesn't this type correctly?
   getValue: (brand, amount) => AmountMath.coerce(brand, amount).value,
-  makeEmpty: (brand, mathKind = MathKind.NAT) => {
+  makeEmpty: (brand, assetKind = AssetKind.NAT) => {
     assert(
-      helpers[mathKind],
-      X`${mathKind} must be MathKind.NAT or MathKind.SET`,
+      helpers[assetKind],
+      X`${assetKind} must be AssetKind.NAT or AssetKind.SET`,
     );
     assertLooksLikeBrand(brand);
-    return noCoerceMake(helpers[mathKind].doMakeEmpty(), brand);
+    return noCoerceMake(helpers[assetKind].doMakeEmpty(), brand);
   },
   makeEmptyFromAmount: amount =>
-    AmountMath.makeEmpty(amount.brand, getMathKind(amount)),
+    AmountMath.makeEmpty(amount.brand, getAssetKind(amount)),
   isEmpty: (amount, brand = undefined) => {
     assertLooksLikeAmount(amount);
     optionalBrandCheck(amount, brand);
@@ -253,4 +255,4 @@ harden(AmountMath);
  */
 const amountMath = AmountMath;
 
-export { amountMath, AmountMath, MathKind, getMathKind };
+export { amountMath, AmountMath, AssetKind, getAssetKind };

packages/ERTP/src/displayInfo.js

@@ -46,17 +46,20 @@ function assertDisplayInfo(allegedDisplayInfo) {
     passStyleOf(allegedDisplayInfo) === 'copyRecord',
     X`A displayInfo can only be a pass-by-copy record: ${allegedDisplayInfo}`,
   );
-  const displayInfoKeys = harden(['decimalPlaces']);
+  const displayInfoKeys = harden(['decimalPlaces', 'assetKind']);
   assertKeysAllowed(displayInfoKeys, allegedDisplayInfo);
 }
 export { assertDisplayInfo };
 
 /**
- * @param {DisplayInfo} [allegedDisplayInfo={}]
+ * @param {AdditionalDisplayInfo} allegedDisplayInfo
+ * @param {AssetKind} assetKind
  * @returns {DisplayInfo}
  */
-export const coerceDisplayInfo = (allegedDisplayInfo = {}) => {
-  const copyDisplayInfo = pureCopy(allegedDisplayInfo);
+export const coerceDisplayInfo = (allegedDisplayInfo, assetKind) => {
+  const copyDisplayInfo = pureCopy(
+    harden({ ...allegedDisplayInfo, assetKind }),
+  );
   assertDisplayInfo(copyDisplayInfo);
   return copyDisplayInfo;
 };

packages/ERTP/src/issuer.js

@@ -9,7 +9,7 @@ import { Far } from '@agoric/marshal';
 import { makeNotifierKit } from '@agoric/notifier';
 import { isPromise } from '@agoric/promise-kit';
 
-import { amountMath, MathKind } from './amountMath';
+import { amountMath, AssetKind } from './amountMath';
 import { makeFarName, ERTPKind } from './interfaces';
 import { coerceDisplayInfo } from './displayInfo';
 import { makePaymentMaker } from './payment';
@@ -21,11 +21,17 @@ import './types';
  */
 function makeIssuerKit(
   allegedName,
-  amountMathKind = MathKind.NAT,
+  assetKind = AssetKind.NAT,
   displayInfo = harden({}),
 ) {
   assert.typeof(allegedName, 'string');
-  displayInfo = coerceDisplayInfo(displayInfo);
+  assert(
+    Object.values(AssetKind).includes(assetKind),
+    X`The assetKind ${assetKind} must be either AssetKind.NAT or AssetKind.SET`,
+  );
+
+  // add assetKind to displayInfo, or override if present
+  const cleanDisplayInfo = coerceDisplayInfo(displayInfo, assetKind);
 
   /** @type {Brand} */
   const brand = Far(makeFarName(allegedName, ERTPKind.BRAND), {
@@ -38,7 +44,7 @@ function makeIssuerKit(
     getAllegedName: () => allegedName,
 
     // Give information to UI on how to display the amount.
-    getDisplayInfo: () => displayInfo,
+    getDisplayInfo: () => cleanDisplayInfo,
   });
 
   /** @type {(left: Amount, right: Amount) => Amount } */
@@ -51,7 +57,7 @@ function makeIssuerKit(
   const isEqual = (left, right) => amountMath.isEqual(left, right, brand);
 
   /** @type {Amount} */
-  const emptyAmount = amountMath.makeEmpty(brand, amountMathKind);
+  const emptyAmount = amountMath.makeEmpty(brand, assetKind);
 
   const makePayment = makePaymentMaker(allegedName, brand);
 
@@ -193,7 +199,8 @@ function makeIssuerKit(
   const issuer = Far(makeFarName(allegedName, ERTPKind.ISSUER), {
     getBrand: () => brand,
     getAllegedName: () => allegedName,
-    getAmountMathKind: () => amountMathKind,
+    getAssetKind: () => assetKind,
+    getDisplayInfo: () => cleanDisplayInfo,
     makeEmptyPurse: makePurse,
 
     isLive: paymentP => {
@@ -283,6 +290,7 @@ function makeIssuerKit(
     mint,
     issuer,
     brand,
+    displayInfo: cleanDisplayInfo,
   });
 }
 

packages/ERTP/src/mathHelpers/setMathHelpers.js

@@ -36,7 +36,7 @@ const hashBadly = thing => {
     return getKeyForRecord(thing);
   }
   assert.fail(
-    X`typeof ${typeof thing} is not allowed in an amount of MathKind.SET`,
+    X`typeof ${typeof thing} is not allowed in an amount of AssetKind.SET`,
   );
 };