chore: cleanups, renamings, type improvements

packages/zoe/src/contracts/constantProduct/calcFees.js

@@ -8,11 +8,9 @@ import { BASIS_POINTS } from './defaults.js';
 const { details: X } = assert;
 
 /**
- * Make a ratio given a nat representing basis points
+ * Make a ratio given a nat representing basis points and a brand.
  *
- * @param {NatValue} feeBP
- * @param {Brand} brandOfFee
- * @returns {Ratio}
+ * @type {MakeFeeRatio}
  */
 const makeFeeRatio = (feeBP, brandOfFee) => {
   return makeRatio(feeBP, brandOfFee, BASIS_POINTS);

packages/zoe/src/contracts/constantProduct/types.js

@@ -7,6 +7,23 @@
  * @returns {Amount}
  */
 
+/**
+ * A bigint representing a number that will be divided by 10,0000. Financial
+ * ratios are often represented in basis points.
+ *
+ * @typedef {bigint} BASIS_POINTS
+ */
+
+/**
+ * Make a Ratio representing a fee expressed in Basis Points.  (hundredths of a
+ *    percent)
+ *
+ * @callback MakeFeeRatio
+ * @param {BASIS_POINTS} feeBP
+ * @param {Brand} brandOfFee
+ * @returns {Ratio}
+ */
+
 /**
  * @callback AmountGT
  * @param {Amount} left

packages/zoe/src/contracts/vpool-xyk-amm/doublePool.js

@@ -1,6 +1,5 @@
 // @ts-check
 
-import { Far } from '@agoric/marshal';
 import { AmountMath } from '@agoric/ertp';
 import { assert, details as X } from '@agoric/assert';
 import { makeFeeRatio } from '../constantProduct/calcFees';
@@ -23,17 +22,17 @@ const publicPrices = prices => {
  * @param {ContractFacet} zcf
  * @param {XYKPool} collateralInPool
  * @param {XYKPool} collateralOutPool
- * @param {bigint} protocolFee
- * @param {bigint} poolFee
+ * @param {BASIS_POINTS} protocolFeeBP
+ * @param {BASIS_POINTS} poolFeeBP
  * @param {ZCFSeat} feeSeat
  * @returns {VPool}
  */
 export const makeDoublePool = (
   zcf,
   collateralInPool,
   collateralOutPool,
-  protocolFee,
-  poolFee,
+  protocolFeeBP,
+  poolFeeBP,
   feeSeat,
 ) => {
   const inCentral = collateralInPool.getCentralAmount();
@@ -46,9 +45,9 @@ export const makeDoublePool = (
   const outAllocation = { Central: outCentral, Secondary: outSecondary };
 
   const centralBrand = inCentral.brand;
-  const centralFeeRatio = makeFeeRatio(poolFee, centralBrand);
+  const centralFeeRatio = makeFeeRatio(poolFeeBP, centralBrand);
   const emptyCentralAmount = AmountMath.makeEmpty(centralBrand);
-  const protocolFeeRatio = makeFeeRatio(protocolFee, centralBrand);
+  const protocolFeeRatio = makeFeeRatio(protocolFeeBP, centralBrand);
   assert(
     centralBrand === outCentral.brand,
     X`The central brands on the two pools must match: ${centralBrand}, ${outCentral.brand}`,
@@ -97,7 +96,7 @@ export const makeDoublePool = (
       outAllocation,
       amountOut,
       protocolFeeRatio,
-      makeFeeRatio(poolFee, amountOut.brand),
+      makeFeeRatio(poolFeeBP, amountOut.brand),
     );
     const finalInPoolPrices = pricesForStatedOutput(
       amountIn,
@@ -154,7 +153,7 @@ export const makeDoublePool = (
       inAllocation,
       interimOutpoolPrices.swapperGets,
       protocolFeeRatio,
-      makeFeeRatio(poolFee, amountIn.brand),
+      makeFeeRatio(poolFeeBP, amountIn.brand),
     );
     const finalOutpoolPrices = pricesForStatedInput(
       inpoolPrices.swapperGives,
@@ -185,13 +184,10 @@ export const makeDoublePool = (
     return allocateGainsAndLosses(seat, prices);
   };
 
-  return Far(
-    `double pool: ${inSecondary.brand.getAllegedName()} to ${outSecondary.brand.getAllegedName()}`,
-    {
-      getInputPrice,
-      getOutputPrice,
-      swapIn,
-      swapOut,
-    },
-  );
+  return {
+    getInputPrice,
+    getOutputPrice,
+    swapIn,
+    swapOut,
+  };
 };

packages/zoe/src/contracts/vpool-xyk-amm/multipoolMarketMaker.js

@@ -59,16 +59,25 @@ import { makeDoublePool } from './doublePool';
  * @type {ContractStartFn}
  */
 const start = zcf => {
-  // This contract must have a "Central" keyword and issuer in the
-  // IssuerKeywordRecord.
-  // poolFee is the portion of the fees that go into the pool (in BP).
-  // protocolFee is the portion of the fees that are shared with validators
+  /**
+   * This contract must have a "Central" keyword and issuer in the
+   * IssuerKeywordRecord.
+   *
+   * @typedef {{
+   *   brands: { Central: Brand },
+   *   timer: TimerService,
+   *   poolFeeBP: BasisPoints, // portion of the fees that go into the pool
+   *   protocolFeeBP: BasisPoints, // portion of the fees that are shared with validators
+   * }} AMMTerms
+   *
+   * @typedef { bigint } BasisPoints -- hundredths of a percent
+   */
   const {
     brands: { Central: centralBrand },
     timer,
-    poolFee,
-    protocolFee,
-  } = zcf.getTerms();
+    poolFeeBP,
+    protocolFeeBP,
+  } = /** @type { Terms & AMMTerms } */ (zcf.getTerms());
   assertIssuerKeywords(zcf, ['Central']);
   assert(centralBrand !== undefined, X`centralBrand must be present`);
 
@@ -93,8 +102,8 @@ const start = zcf => {
     centralBrand,
     timer,
     quoteIssuerKit,
-    protocolFee,
-    poolFee,
+    protocolFeeBP,
+    poolFeeBP,
     protocolSeat,
   );
   const getPoolAllocation = brand => {
@@ -112,20 +121,18 @@ const start = zcf => {
   };
 
   /**
-   * @callback ProvideVPool
    * @param {Brand} brandIn
    * @param {Brand} brandOut
-   * @param {Ratio} poolFeeRatio
    * @returns {VPool}
    */
-  const provideVPool = (brandIn, brandOut, poolFeeRatio) => {
+  const provideVPool = (brandIn, brandOut) => {
     if (isSecondary(brandIn) && isSecondary(brandOut)) {
       return makeDoublePool(
         zcf,
         getPool(brandIn),
         getPool(brandOut),
-        protocolFee,
-        poolFeeRatio,
+        protocolFeeBP,
+        poolFeeBP,
         protocolSeat,
       );
     }
@@ -135,18 +142,18 @@ const start = zcf => {
   };
 
   const getInputPrice = (amountIn, amountOut) => {
-    const pool = provideVPool(amountIn.brand, amountOut.brand, poolFee);
+    const pool = provideVPool(amountIn.brand, amountOut.brand);
     return pool.getInputPrice(amountIn, amountOut);
   };
   const getOutputPrice = (amountIn, amountOut) => {
-    const pool = provideVPool(amountIn.brand, amountOut.brand, poolFee);
+    const pool = provideVPool(amountIn.brand, amountOut.brand);
     return pool.getOutputPrice(amountIn, amountOut);
   };
 
   const {
     makeSwapInInvitation,
     makeSwapOutInvitation,
-  } = makeMakeSwapInvitation(zcf, provideVPool, poolFee);
+  } = makeMakeSwapInvitation(zcf, provideVPool, poolFeeBP);
   const makeAddLiquidityInvitation = makeMakeAddLiquidityInvitation(
     zcf,
     getPool,
@@ -162,7 +169,7 @@ const start = zcf => {
     protocolSeat,
     centralBrand,
   );
-  const creatorFacet = Far('Private Facet', {
+  const creatorFacet = Far('Creator Facet', {
     makeCollectFeesInvitation,
   });
 

packages/zoe/src/contracts/vpool-xyk-amm/pool.js

@@ -4,7 +4,6 @@ import { E } from '@agoric/eventual-send';
 import { assert, details as X } from '@agoric/assert';
 import { AssetKind, AmountMath, isNatValue } from '@agoric/ertp';
 import { makeNotifierKit } from '@agoric/notifier';
-import { Far } from '@agoric/marshal';
 
 import {
   calcLiqValueToMint,
@@ -22,24 +21,24 @@ import { makeSinglePool } from './singlePool';
 
 /**
  * @param {ContractFacet} zcf
- * @param {(brand: Brand) => boolean} isSecondary
+ * @param {(brand: Brand) => boolean} isInSecondaries
  * @param {(brand: Brand, pool: XYKPool) => void} initPool
  * @param {Brand} centralBrand
- * @param {Timer} timer
+ * @param {ERef<Timer>} timer
  * @param {IssuerKit} quoteIssuerKit
- * @param {bigint} protocolFee - Ratio, soon to be replaced with governed value
- * @param {bigint} poolFee - Ratio, soon to be replaced with governed value
+ * @param {BASIS_POINTS} protocolFeeBP - soon to be replaced with governed value
+ * @param {BASIS_POINTS} poolFeeBP - soon to be replaced with governed value
  * @param {ZCFSeat} protocolSeat
  */
 export const makeAddPool = (
   zcf,
-  isSecondary,
+  isInSecondaries,
   initPool,
   centralBrand,
   timer,
   quoteIssuerKit,
-  protocolFee,
-  poolFee,
+  protocolFeeBP,
+  poolFeeBP,
   protocolSeat,
 ) => {
   const makePool = (liquidityZcfMint, poolSeat, secondaryBrand) => {
@@ -59,6 +58,9 @@ export const makeAddPool = (
       });
 
     const addLiquidityActual = (pool, zcfSeat, secondaryAmount) => {
+      // addLiquidity can't be called until the pool has been created. We verify
+      // that the asset is NAT before creating a pool.
+
       const liquidityValueOut = calcLiqValueToMint(
         liqTokenSupply,
         zcfSeat.getAmountAllocated('Central').value,
@@ -89,7 +91,7 @@ export const makeAddPool = (
     };
 
     /** @type {XYKPool} */
-    const pool = Far('pool', {
+    const pool = {
       getLiquiditySupply: () => liqTokenSupply,
       getLiquidityIssuer: () => liquidityIssuer,
       getPoolSeat: () => poolSeat,
@@ -181,9 +183,15 @@ export const makeAddPool = (
       getFromCentralPriceAuthority: () => fromCentralPriceAuthority,
       // eslint-disable-next-line no-use-before-define
       getVPool: () => vPool,
-    });
+    };
 
-    const vPool = makeSinglePool(zcf, pool, protocolFee, poolFee, protocolSeat);
+    const vPool = makeSinglePool(
+      zcf,
+      pool,
+      protocolFeeBP,
+      poolFeeBP,
+      protocolSeat,
+    );
 
     const getInputPriceForPA = (amountIn, brandOut) =>
       vPool.getInputPrice(amountIn, AmountMath.makeEmpty(brandOut));
@@ -232,14 +240,15 @@ export const makeAddPool = (
     ]);
 
     assert(
-      !isSecondary(secondaryBrand),
+      !isInSecondaries(secondaryBrand),
       X`issuer ${secondaryIssuer} already has a pool`,
     );
     assert(
       secondaryAssetKind === AssetKind.NAT,
-      X`${keyword} issuer must use NAT math`,
+      X`${keyword} asset not fungible (must use NAT math)`,
     );
 
+    // COMMIT POINT
     // We've checked all the foreseeable exceptions (except
     // zcf.assertUniqueKeyword(keyword), which will be checked by saveIssuer()
     // before proceeding), so we can do the work now.

packages/zoe/src/contracts/vpool-xyk-amm/singlePool.js

@@ -1,6 +1,5 @@
 // @ts-check
 
-import { Far } from '@agoric/marshal';
 import { makeFeeRatio } from '../constantProduct/calcFees';
 import {
   pricesForStatedInput,
@@ -10,15 +9,21 @@ import {
 /**
  * @param {ContractFacet} zcf
  * @param {XYKPool} pool
- * @param {bigint} protocolFee - Ratio, soon to be replaced with governed value
- * @param {bigint} poolFee - Ratio, soon to be replaced with governed value
+ * @param {BASIS_POINTS} protocolFeeBP - Ratio, soon to be replaced with governed value
+ * @param {BASIS_POINTS} poolFeeBP - Ratio, soon to be replaced with governed value
  * @param {ZCFSeat} feeSeat
  * @returns {VPool}
  */
-export const makeSinglePool = (zcf, pool, protocolFee, poolFee, feeSeat) => {
+export const makeSinglePool = (
+  zcf,
+  pool,
+  protocolFeeBP,
+  poolFeeBP,
+  feeSeat,
+) => {
   const secondaryBrand = pool.getSecondaryAmount().brand;
   const centralBrand = pool.getCentralAmount().brand;
-  const protocolFeeRatio = makeFeeRatio(protocolFee, centralBrand);
+  const protocolFeeRatio = makeFeeRatio(protocolFeeBP, centralBrand);
   const getPools = () => ({
     Central: pool.getCentralAmount(),
     Secondary: pool.getSecondaryAmount(),
@@ -53,7 +58,7 @@ export const makeSinglePool = (zcf, pool, protocolFee, poolFee, feeSeat) => {
       getPools(),
       amountOut,
       protocolFeeRatio,
-      makeFeeRatio(poolFee, amountOut.brand),
+      makeFeeRatio(poolFeeBP, amountOut.brand),
     );
   };
 
@@ -68,7 +73,7 @@ export const makeSinglePool = (zcf, pool, protocolFee, poolFee, feeSeat) => {
       getPools(),
       amountOut,
       protocolFeeRatio,
-      makeFeeRatio(poolFee, amountIn.brand),
+      makeFeeRatio(poolFeeBP, amountIn.brand),
     );
   };
   const swapOut = (seat, amountIn, amountOut) => {
@@ -77,12 +82,12 @@ export const makeSinglePool = (zcf, pool, protocolFee, poolFee, feeSeat) => {
   };
 
   /** @type {VPool} */
-  return Far(`single pool: ${secondaryBrand.getAllegedName()}`, {
+  return {
     getInputPrice: (amountIn, amountOut) =>
       publicPrices(getPriceForInput(amountIn, amountOut)),
     getOutputPrice: (amountIn, amountOut) =>
       publicPrices(getPriceForOutput(amountIn, amountOut)),
     swapIn,
     swapOut,
-  });
+  };
 };