Merge pull request #6813 from Agoric/ta/type-improvements

misc types improvements

packages/inter-protocol/src/price/priceAggregatorChainlink.js

@@ -40,7 +40,7 @@ const priceDescriptionFromQuote = quote => quote.quoteAmount.value[0];
  * @typedef {object} ChainlinkConfig
  * @property {number} maxSubmissionCount
  * @property {number} minSubmissionCount
- * @property {RelativeTime} restartDelay the number of rounds an Oracle has to wait before they can initiate a round
+ * @property {RelativeTimeValue} restartDelay the number of rounds an Oracle has to wait before they can initiate a round
  * @property {number} minSubmissionValue an immutable check for a lower bound of what
  * submission values are accepted from an oracle
  * @property {number} maxSubmissionValue an immutable check for an upper bound of what

packages/inter-protocol/src/price/roundsManager.js

@@ -364,6 +364,7 @@ export const makeRoundsManagerKit = defineDurableFarClassKit(
         }
 
         /** @type {bigint | undefined} */
+        // @ts-expect-error faulty inference
         const newAnswer = calculateMedian(
           details
             .get(roundId)
@@ -478,13 +479,13 @@ export const makeRoundsManagerKit = defineDurableFarClassKit(
             overrideValueOut === undefined
               ? lastValueOutForUnitIn // Use the latest value.
               : overrideValueOut; // Override the value.
-          if (valueOutForUnitIn === undefined) {
+          if (valueOutForUnitIn === null) {
             // We don't have a quote, so abort.
             return undefined;
           }
 
           /**
-           * @param {Amount} amountIn the given amountIn
+           * @param {Amount<'nat'>} amountIn the given amountIn
            */
           const calcAmountOut = amountIn => {
             const valueIn = AmountMath.getValue(brandIn, amountIn);
@@ -495,7 +496,7 @@ export const makeRoundsManagerKit = defineDurableFarClassKit(
           };
 
           /**
-           * @param {Amount} amountOut the wanted amountOut
+           * @param {Amount<'nat'>} amountOut the wanted amountOut
            */
           const calcAmountIn = amountOut => {
             const valueOut = AmountMath.getValue(brandOut, amountOut);

packages/inter-protocol/src/vaultFactory/liquidateIncrementally.js

@@ -106,10 +106,10 @@ const start = async zcf => {
    * a price impact of MAX_IMPACT_BP.
    * This doesn't use ratios so that it is usable for any brand
    *
-   * @param {Amount} poolSize
+   * @param {Amount<'nat'>} poolSize
    * @param {bigint} maxImpactBP
    * @param {bigint} feeBP
-   * @returns {Amount}
+   * @returns {Amount<'nat'>}
    */
   const maxTrancheWithFees = (poolSize, maxImpactBP, feeBP) => {
     trace('maxTrancheWithFees', poolSize, maxImpactBP, feeBP);
@@ -143,6 +143,14 @@ const start = async zcf => {
 
   const AMMFeeBP = await getAMMFeeBP();
 
+  /**
+   *
+   * @param {Amount<'nat'>} poolCentral
+   * @param {Amount<'nat'>} poolCollateral
+   * @param {Amount<'nat'>} tranche
+   * @param {Amount<'nat'>} debt
+   * @param {Ratio} maxSlip
+   */
   const estimateAMMProceeds = (
     poolCentral,
     poolCollateral,

packages/inter-protocol/src/vaultFactory/vault.js

@@ -166,10 +166,10 @@ const initState = (zcf, manager, idInManager, storageNode, marshaller) => {
 /**
  * Check whether we can proceed with an `adjustBalances`.
  *
- * @param {Amount} newCollateralPre
- * @param {Amount} maxDebtPre
- * @param {Amount} newCollateral
- * @param {Amount} newDebt
+ * @param {Amount<'nat'>} newCollateralPre
+ * @param {Amount<'nat'>} maxDebtPre
+ * @param {Amount<'nat'>} newCollateral
+ * @param {Amount<'nat'>} newDebt
  * @returns {boolean}
  */
 const checkRestart = (newCollateralPre, maxDebtPre, newCollateral, newDebt) => {

packages/inter-protocol/src/vpool-xyk-amm/constantProduct/invariants.js

@@ -6,10 +6,10 @@ import { natSafeMath } from '@agoric/zoe/src/contractSupport/index.js';
 /**
  * xy <= (x + deltaX)(y - deltaY)
  *
- * @param {Amount} x - the amount of Brand X in pool, xPoolAllocation
- * @param {Amount} y - the amount of Brand Y in pool, yPoolAllocation
- * @param {Amount} deltaX - the amount of Brand X to be added
- * @param {Amount} deltaY - the amount of Brand Y to be taken out
+ * @param {Amount<'nat'>} x - the amount of Brand X in pool, xPoolAllocation
+ * @param {Amount<'nat'>} y - the amount of Brand Y in pool, yPoolAllocation
+ * @param {Amount<'nat'>} deltaX - the amount of Brand X to be added
+ * @param {Amount<'nat'>} deltaY - the amount of Brand Y to be taken out
  */
 export const checkKInvariantSellingX = (x, y, deltaX, deltaY) => {
   const oldK = natSafeMath.multiply(x.value, y.value);
@@ -22,10 +22,10 @@ export const checkKInvariantSellingX = (x, y, deltaX, deltaY) => {
 /**
  * xy <= (x + deltaX)(y - deltaY)
  *
- * @param {Amount} x - the amount of Brand X in pool, xPoolAllocation
- * @param {Amount} y - the amount of Brand Y in pool, yPoolAllocation
- * @param {Amount} deltaX - the amount of Brand X to be added
- * @param {Amount} deltaY - the amount of Brand Y to be taken out
+ * @param {Amount<'nat'>} x - the amount of Brand X in pool, xPoolAllocation
+ * @param {Amount<'nat'>} y - the amount of Brand Y in pool, yPoolAllocation
+ * @param {Amount<'nat'>} deltaX - the amount of Brand X to be added
+ * @param {Amount<'nat'>} deltaY - the amount of Brand Y to be taken out
  */
 export const assertKInvariantSellingX = (x, y, deltaX, deltaY) => {
   checkKInvariantSellingX(x, y, deltaX, deltaY) ||

packages/inter-protocol/src/vpool-xyk-amm/estimate.js

@@ -7,15 +7,25 @@ import { BASIS_POINTS } from './constantProduct/defaults.js';
  * into account, and not requiring a round trip to the chain.
  */
 
+/** @typedef {{ centralAmount: Amount<'nat'>, secondaryAmount: Amount<'nat'> }} Pool */
+
 const { ceilDivide, floorDivide } = natSafeMath;
 
+/**
+ * @param {bigint} chargeBP
+ * @param {Amount<'nat'>} amount
+ */
 export const charge = (chargeBP, amount) => {
   return AmountMath.make(
     amount.brand,
     ceilDivide(amount.value * chargeBP, BASIS_POINTS),
   );
 };
 
+/**
+ * @param {bigint} chargeBP
+ * @param {Amount<'nat'>} amount
+ */
 export const chargeFloor = (chargeBP, amount) => {
   return AmountMath.make(
     amount.brand,
@@ -26,7 +36,13 @@ export const chargeFloor = (chargeBP, amount) => {
 const makeEstimator = (centralBrand, rates) => {
   const { poolFeeBP, protocolFeeBP, slippageBP } = rates;
 
-  // Proceeds less slippage when specifying the amount to add to a single pool
+  /**
+   * Proceeds less slippage when specifying the amount to add to a single pool
+   *
+   * @param {Amount<'nat'>} amountIn
+   * @param {Brand<'nat'>} brandOut
+   * @param {MapStore<Brand, Pool>} pools
+   */
   function estimateSinglePoolProceeds(amountIn, brandOut, pools) {
     const isCentralIn = amountIn.brand === centralBrand;
     const pool = isCentralIn ? pools.get(brandOut) : pools.get(amountIn.brand);
@@ -65,7 +81,13 @@ const makeEstimator = (centralBrand, rates) => {
     return amountReturned;
   }
 
-  // Payment w/slippage when specifying the amount to receive from a single pool
+  /**
+   * Payment w/slippage when specifying the amount to receive from a single pool
+   *
+   * @param {Brand<'nat'>} brandIn
+   * @param {Amount<'nat'>} amountOut
+   * @param {MapStore<Brand, Pool>} pools
+   */
   function estimateSinglePoolRequired(brandIn, amountOut, pools) {
     const isCentralIn = brandIn === centralBrand;
     const pool = isCentralIn ? pools.get(amountOut.brand) : pools.get(brandIn);

packages/smart-wallet/src/smartWallet.js

@@ -56,7 +56,7 @@ const mapToRecord = map => Object.fromEntries(map.entries());
  *   brands: BrandDescriptor[],
  *   purses: Array<{brand: Brand, balance: Amount}>,
  *   offerToUsedInvitation: Record<number, Amount>,
- *   lastOfferId: number,
+ *   lastOfferId: string,
  * }} CurrentWalletRecord
  */
 
@@ -277,6 +277,7 @@ const SmartWalletKit = defineVirtualFarClassKit(
             balance: a,
           })),
           offerToUsedInvitation: mapToRecord(offerToUsedInvitation),
+          // @ts-expect-error FIXME leftover from offer id string conversion
           lastOfferId: ERROR_LAST_OFFER_ID,
         });
       },

packages/zoe/src/contractSupport/ratio.js

@@ -96,7 +96,7 @@ export const makeRatioFromAmounts = (numeratorAmount, denominatorAmount) => {
 
 /**
  *
- * @param {Amount} amount
+ * @param {Amount<'nat'>} amount
  * @param {Ratio} ratio
  * @param {*} divideOp
  */
@@ -136,7 +136,7 @@ export const multiplyBy = (amount, ratio) => {
 
 /**
  *
- * @param {Amount} amount
+ * @param {Amount<'nat'>} amount
  * @param {Ratio} ratio
  * @param {*} divideOp
  */

packages/zoe/src/contractSupport/safeMath.js

@@ -1,5 +1,7 @@
 import { Nat } from '@agoric/nat';
 
+/** @typedef {(x: number | bigint, y: number | bigint) => NatValue} NatOp */
+
 /**
  * These operations should be used for calculations with the values of
  * basic fungible tokens.
@@ -8,20 +10,24 @@ import { Nat } from '@agoric/nat';
  * validate the inputs, as well as the outputs when necessary.
  */
 export const natSafeMath = harden({
+  /** @type {NatOp} */
   // BigInts don't observably overflow
   add: (x, y) => Nat(x) + Nat(y),
+  /** @type {NatOp} */
   subtract: (x, y) => Nat(Nat(x) - Nat(y)),
+  /** @type {NatOp} */
   multiply: (x, y) => Nat(x) * Nat(y),
+  /** @type {NatOp} */
   floorDivide: (x, y) => Nat(x) / Nat(y),
+  /** @type {NatOp} */
   ceilDivide: (x, y) => {
     y = Nat(y);
     return Nat(Nat(x) + y - 1n) / y;
   },
   /**
    * Divide using half-to-even (aka Banker's Rounding) as in IEEE 774 default rounding
    *
-   * @param {NatValue} a
-   * @param {NatValue} b
+   * @type {NatOp}
    */
   bankersDivide: (a, b) => {
     a = Nat(a);
@@ -38,5 +44,6 @@ export const natSafeMath = harden({
     }
     return div;
   },
+  /** @type {(x: number | bigint, y: number | bigint) => boolean} */
   isGTE: (x, y) => Nat(x) >= Nat(y),
 });

packages/zoe/src/contractSupport/types.js

@@ -85,7 +85,7 @@
 
 /**
  * @callback ScaleAmount
- * @param {Amount} amount
+ * @param {Amount<'nat'>} amount
  * @param {Ratio} ratio
  * @returns {Amount<'nat'>}
  */

packages/zoe/src/contracts/callSpread/pricedCallSpread.js

@@ -57,12 +57,12 @@ const BASIS_POINTS = 10000n;
  * + issue multiple option pairs with the same expiration from a single instance
  *
  * @param {ZCF<{
- * strikePrice1: Amount,
- * strikePrice2: Amount,
- * settlementAmount: Amount,
+ * strikePrice1: Amount<'nat'>,
+ * strikePrice2: Amount<'nat'>,
+ * settlementAmount: Amount<'nat'>,
  * priceAuthority: PriceAuthority,
  * expiration: bigint,
- * underlyingAmount: Amount,
+ * underlyingAmount: Amount<'nat'>,
  * }>} zcf
  */
 const start = zcf => {

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

@@ -62,7 +62,7 @@
  *   The ZCFSeat holding the collateral in escrow after the borrower
  *   escrows it
  *
- * @property {() => Amount} getDebt
+ * @property {() => Amount<'nat'>} getDebt
  *
  *   A function to get the current debt
  *
@@ -148,9 +148,9 @@
 
 /**
  * @callback CalcInterestFn
- * @param {Amount} oldDebt
+ * @param {Amount<'nat'>} oldDebt
  * @param {Ratio} interestRate
- * @returns {Amount} interest
+ * @returns {Amount<'nat'>} interest
  */
 
 /**
@@ -160,7 +160,7 @@
  *   A function to calculate the interest, given the debt value and an
  *   interest rate in basis points.
  *
- * @property {Amount} originalDebt
+ * @property {Amount<'nat'>} originalDebt
  *
  *   The debt at the start of the loan, in Loan brand
  *

packages/zoe/tools/fakePriceAuthority.js

@@ -21,14 +21,14 @@ const timestampLTE = (a, b) => TimeMath.compareAbs(a, b) <= 0;
 
 /**
  * @typedef {object} FakePriceAuthorityOptions
- * @property {Brand} actualBrandIn
- * @property {Brand} actualBrandOut
+ * @property {Brand<'nat'>} actualBrandIn
+ * @property {Brand<'nat'>} actualBrandOut
  * @property {Array<number>} [priceList]
  * @property {Array<[number, number]>} [tradeList]
  * @property {ERef<TimerService>} timer
  * @property {RelativeTime} [quoteInterval]
  * @property {ERef<Mint<'set'>>} [quoteMint]
- * @property {Amount} [unitAmountIn]
+ * @property {Amount<'nat'>} [unitAmountIn]
  */
 
 /**
@@ -107,7 +107,7 @@ export async function makeFakePriceAuthority(options) {
 
   /**
    *
-   * @param {Amount} amountIn
+   * @param {Amount<'nat'>} amountIn
    * @param {Brand} brandOut
    * @param {Timestamp} quoteTime
    * @returns {PriceQuote}
@@ -139,8 +139,8 @@ export async function makeFakePriceAuthority(options) {
   }
 
   /**
-   * @param {Brand} brandIn
-   * @param {Amount} amountOut
+   * @param {Brand<'nat'>} brandIn
+   * @param {Amount<'nat'>} amountOut
    * @param {Timestamp} quoteTime
    * @returns {PriceQuote}
    */

packages/zoe/tools/types.js

@@ -15,9 +15,9 @@
 /**
  * @typedef {object} PriceDescription
  * A description of a single quote
- * @property {Amount} amountIn
+ * @property {Amount<'nat'>} amountIn
  * The amount supplied to a trade
- * @property {Amount} amountOut
+ * @property {Amount<'nat'>} amountOut
  * The quoted result of trading `amountIn`
  * @property {TimerService} timer
  * The service that gave the `timestamp`