@agoric/inter-protocol 0.16.2-dev-57802f9.0 → 0.16.2-other-dev-70beeb7.0

package/src/vaultFactory/math.js

@@ -1,8 +1,8 @@
 // @jessie-check
 
 /**
- * @file calculations specific to the Vault Factory contract See also
- *   ../interest-math.js
+ * @file calculations specific to the Vault Factory contract
+ * See also ../interest-math.js
  */
 
 import { AmountMath } from '@agoric/ertp';
@@ -17,8 +17,8 @@ import { priceFrom } from '../auction/util.js';
 import { addSubtract } from '../contractSupport.js';
 
 /**
- * Calculate the minimum collateralization given the liquidation margin and the
- * "padding" from that liquidation threshold.
+ * Calculate the minimum collateralization given the liquidation margin and the "padding"
+ * from that liquidation threshold.
  *
  * @param {Ratio} liquidationMargin
  * @param {Ratio} liquidationPadding
@@ -74,10 +74,11 @@ export const maxDebtForVault = (
 };
 
 /**
- * Calculate the fee, the amount to mint and the resulting debt. The give and
- * the want together reflect a delta, where typically one is zero because they
- * come from the gave/want of an offer proposal. If the `want` is zero, the
- * `fee` will also be zero, so the simple math works.
+ * Calculate the fee, the amount to mint and the resulting debt.
+ * The give and the want together reflect a delta, where typically
+ * one is zero because they come from the gave/want of an offer
+ * proposal. If the `want` is zero, the `fee` will also be zero,
+ * so the simple math works.
  *
  * @param {Amount<'nat'>} currentDebt
  * @param {Amount<'nat'>} give excess of currentDebt is returned in 'surplus'

package/src/vaultFactory/orderedVaultStore.js

@@ -3,20 +3,22 @@ import { fromVaultKey, toVaultKey } from './storeUtils.js';
 /**
  * Used by prioritizedVaults to wrap the Collections API for this use case.
  *
- * Designed to be replaceable by naked Collections API when composite keys are
- * available.
+ * Designed to be replaceable by naked Collections API when composite keys are available.
  *
- * In this module debts are encoded as the inverse quotient (collateral over
- * debt) so that greater collateralization sorts after lower. (Higher
- * debt-to-collateral come first.)
+ * In this module debts are encoded as the inverse quotient (collateral over debt) so that
+ * greater collateralization sorts after lower. (Higher debt-to-collateral come
+ * first.)
  */
 
 /** @typedef {import('./vault').Vault} Vault */
 /** @typedef {import('./storeUtils').CompositeKey} CompositeKey */
 
-/** @param {MapStore<string, Vault>} store */
+/**
+ * @param {MapStore<string, Vault>} store
+ */
 export const makeOrderedVaultStore = store => {
   /**
+   *
    * @param {string} vaultId
    * @param {Vault} vault
    */
@@ -29,6 +31,7 @@ export const makeOrderedVaultStore = store => {
   };
 
   /**
+   *
    * @param {string} key
    * @returns {Vault}
    */

package/src/vaultFactory/params.js

@@ -75,11 +75,7 @@ const makeVaultDirectorParams = (
 };
 harden(makeVaultDirectorParams);
 
-/**
- * @typedef {import('@agoric/governance/src/contractGovernance/typedParamManager').ParamTypesMapFromRecord<
- *     ReturnType<typeof makeVaultDirectorParams>
- *   >} VaultDirectorParams
- */
+/** @typedef {import('@agoric/governance/src/contractGovernance/typedParamManager').ParamTypesMapFromRecord<ReturnType<typeof makeVaultDirectorParams>>} VaultDirectorParams */
 
 /** @type {(liquidationMargin: Ratio) => Ratio} */
 const zeroRatio = liquidationMargin =>
@@ -126,16 +122,16 @@ export const vaultParamPattern = M.splitRecord(
 
 /**
  * @param {{
- *   auctioneerPublicFacet: ERef<AuctioneerPublicFacet>;
- *   electorateInvitationAmount: Amount<'set'>;
- *   minInitialDebt: Amount<'nat'>;
- *   bootstrapPaymentValue: bigint;
- *   priceAuthority: ERef<PriceAuthority>;
- *   timer: ERef<import('@agoric/time/src/types').TimerService>;
- *   reservePublicFacet: AssetReservePublicFacet;
- *   interestTiming: InterestTiming;
- *   shortfallInvitationAmount: Amount<'set'>;
- *   referencedUi?: string;
+ *   auctioneerPublicFacet: ERef<AuctioneerPublicFacet>,
+ *   electorateInvitationAmount: Amount<'set'>,
+ *   minInitialDebt: Amount<'nat'>,
+ *   bootstrapPaymentValue: bigint,
+ *   priceAuthority: ERef<PriceAuthority>,
+ *   timer: ERef<import('@agoric/time/src/types').TimerService>,
+ *   reservePublicFacet: AssetReservePublicFacet,
+ *   interestTiming: InterestTiming,
+ *   shortfallInvitationAmount: Amount<'set'>,
+ *   referencedUi?: string,
  * }} opts
  */
 export const makeGovernedTerms = ({
@@ -167,8 +163,8 @@ export const makeGovernedTerms = ({
 };
 harden(makeGovernedTerms);
 /**
- * Stop-gap which restores initial param values UNTIL
- * https://github.com/Agoric/agoric-sdk/issues/5200
+ * Stop-gap which restores initial param values
+ * UNTIL https://github.com/Agoric/agoric-sdk/issues/5200
  *
  * NB: changes from initial values will be lost upon restart
  *
@@ -180,12 +176,7 @@ export const provideVaultParamManagers = (baggage, marshaller) => {
   const managers = makeScalarMapStore();
 
   // the managers aren't durable but their arguments are
-  /**
-   * @type {MapStore<
-   *   Brand,
-   *   { storageNode: StorageNode; initialParamValues: VaultManagerParamValues }
-   * >}
-   */
+  /** @type {MapStore<Brand, {storageNode: StorageNode, initialParamValues: VaultManagerParamValues}>} */
   const managerArgs = provideDurableMapStore(
     baggage,
     'vault param manager parts',
@@ -205,6 +196,7 @@ export const provideVaultParamManagers = (baggage, marshaller) => {
 
   return {
     /**
+     *
      * @param {Brand} brand
      * @param {StorageNode} storageNode
      * @param {VaultManagerParamValues} initialParamValues
@@ -214,7 +206,9 @@ export const provideVaultParamManagers = (baggage, marshaller) => {
       managerArgs.init(brand, args);
       return makeManager(brand, args);
     },
-    /** @param {Brand} brand */
+    /**
+     * @param {Brand} brand
+     */
     get(brand) {
       return managers.get(brand);
     },

package/src/vaultFactory/prioritizedVaults.js

@@ -47,8 +47,8 @@ export const currentDebtToCollateral = vault =>
  * Vaults, ordered by their debt ratio so that all the vaults below a threshold
  * can be quickly found and liquidated.
  *
- * @param {MapStore<string, Vault>} store vault has a higher debt ratio than the
- *   previous highest
+ * @param {MapStore<string, Vault>} store
+ * vault has a higher debt ratio than the previous highest
  */
 export const makePrioritizedVaults = store => {
   const vaults = makeOrderedVaultStore(store);

package/src/vaultFactory/proceeds.js

@@ -11,32 +11,27 @@ import { liquidationResults } from './liquidation.js';
 
 /**
  * @typedef {{
- *   overage: Amount<'nat'>;
- *   shortfallToReserve: Amount<'nat'>;
- *   collateralForReserve: Amount<'nat'>;
- *   actualCollateralSold: Amount<'nat'>;
- *   collateralSold: Amount<'nat'>;
- *   collatRemaining: Amount<'nat'>;
- *   debtToBurn: Amount<'nat'>;
- *   mintedForReserve: Amount<'nat'>;
- *   mintedProceeds: Amount<'nat'>;
- *   phantomDebt: Amount<'nat'>;
- *   totalPenalty: Amount<'nat'>;
- *   transfersToVault: [number, AmountKeywordRecord][];
- *   vaultsToReinstate: number[];
+ *   overage: Amount<'nat'>,
+ *   shortfallToReserve: Amount<'nat'>,
+ *   collateralForReserve: Amount<'nat'>,
+ *   actualCollateralSold: Amount<'nat'>,
+ *   collateralSold: Amount<'nat'>,
+ *   collatRemaining: Amount<'nat'>,
+ *   debtToBurn: Amount<'nat'>,
+ *   mintedForReserve: Amount<'nat'>,
+ *   mintedProceeds: Amount<'nat'>,
+ *   phantomDebt: Amount<'nat'>,
+ *   totalPenalty: Amount<'nat'>,
+ *   transfersToVault: Array<[number, AmountKeywordRecord]>,
+ *   vaultsToReinstate: Array<number>
  * }} DistributionPlan
- *   The plan to execute for distributing proceeds of a liquidation.
  *
- *   Vaults are referenced by index in the list sent to the calculator.
+ * The plan to execute for distributing proceeds of a liquidation.
+ *
+ * Vaults are referenced by index in the list sent to the calculator.
  */
 
-/**
- * @typedef {{
- *   collateral: Amount<'nat'>;
- *   presaleDebt: Amount<'nat'>;
- *   currentDebt: Amount<'nat'>;
- * }} VaultBalances
- */
+/** @typedef {{ collateral: Amount<'nat'>, presaleDebt:  Amount<'nat'>, currentDebt: Amount<'nat'> }} VaultBalances */
 
 /**
  * Liquidation.md describes how to process liquidation proceeds.
@@ -51,8 +46,7 @@ import { liquidationResults } from './liquidation.js';
  * @param {Amount<'nat'>} inputs.totalDebt
  * @param {Amount<'nat'>} inputs.totalCollateral
  * @param {PriceDescription} inputs.oraclePriceAtStart
- * @param {VaultBalances[]} inputs.vaultsBalances ordered best to worst
- *   collateralized
+ * @param {Array<VaultBalances>} inputs.vaultsBalances ordered best to worst collateralized
  * @param {Ratio} inputs.penaltyRate
  * @returns {DistributionPlan}
  */

package/src/vaultFactory/storeUtils.js

@@ -19,9 +19,13 @@ const { multiply } = natSafeMath;
 
 const trace = makeTracer('Store', true);
 
-/** @typedef {import('@endo/marshal').PureData} PureData */
+/**
+ * @typedef {import('@endo/marshal').PureData} PureData
+ */
 
-/** @typedef {[normalizedCollateralization: number, vaultId: VaultId]} CompositeKey */
+/**
+ * @typedef {[normalizedCollateralization: number, vaultId: VaultId]} CompositeKey
+ */
 
 // `makeEncodePassable` has three named options:
 // `encodeRemotable`, `encodeError`, and `encodePromise`.
@@ -65,12 +69,12 @@ const decodeNumber = encoded => {
 };
 
 // Type annotations to support static testing of amount values
-/** @typedef {Amount<'nat'> & { normalized: true }} NormalizedDebt */
-/** @typedef {Amount<'nat'> & { normalized: false }} ActualDebt */
+/** @typedef {Amount<'nat'> & {normalized: true}} NormalizedDebt */
+/** @typedef {Amount<'nat'> & {normalized: false}} ActualDebt */
 
 /**
- * Overcollateralized are greater than one. The more undercollaterized the
- * smaller in [0-1].
+ * Overcollateralized are greater than one.
+ * The more undercollaterized the smaller in [0-1].
  *
  * @param {NormalizedDebt} normalizedDebt normalized (not actual) total debt
  * @param {Amount<'nat'>} collateral
@@ -91,7 +95,7 @@ const collateralizationRatio = (normalizedDebt, collateral) => {
  * @param {Amount<'nat'>} collateral
  * @param {VaultId} vaultId
  * @returns {string} lexically sortable string in which highest
- *   debt-to-collateral is earliest
+ * debt-to-collateral is earliest
  */
 export const toVaultKey = (normalizedDebt, collateral, vaultId) => {
   assert(normalizedDebt);
@@ -158,7 +162,7 @@ harden(normalizedCollRatio);
  * @param {Ratio} compoundedInterest
  * @param {Ratio} margin
  * @returns {string} lexically sortable string in which highest
- *   debt-to-collateral is earliest
+ * debt-to-collateral is earliest
  */
 export const normalizedCollRatioKey = (quote, compoundedInterest, margin) => {
   const collRatio = normalizedCollRatio(quote, compoundedInterest, margin);

package/src/vaultFactory/types.js

@@ -2,30 +2,21 @@
 
 /**
  * @typedef {import('./vault').VaultNotification} VaultNotification
- *
  * @typedef {import('./vault').Vault} Vault
- *
  * @typedef {import('./vaultKit').VaultKit} VaultKit
- *
  * @typedef {import('./vaultManager').VaultManager} VaultManager
- *
  * @typedef {import('./vaultManager').CollateralManager} CollateralManager
- *
  * @typedef {import('../reserve/assetReserve.js').AssetReserveLimitedCreatorFacet} AssetReserveCreatorFacet
- *
  * @typedef {import('../reserve/assetReserve.js').AssetReservePublicFacet} AssetReservePublicFacet
- *
  * @typedef {import('../auction/auctioneer.js').AuctioneerPublicFacet} AuctioneerPublicFacet
- *
  * @typedef {import('./vaultFactory.js').VaultFactoryContract['publicFacet']} VaultFactoryPublicFacet
  *
  * @typedef {import('@agoric/time/src/types').Timestamp} Timestamp
- *
  * @typedef {import('@agoric/time/src/types').RelativeTime} RelativeTime
  */
 
 /**
- * @typedef {object} AutoswapLocal
+ * @typedef  {object} AutoswapLocal
  * @property {(amount: Amount, brand: Brand) => Amount} getInputPrice
  * @property {() => Invitation} makeSwapInvitation
  */
@@ -33,16 +24,13 @@
 /**
  * @typedef {object} VaultManagerParamValues
  * @property {Ratio} liquidationMargin - margin below which collateral will be
- *   liquidated to satisfy the debt.
- * @property {Ratio} liquidationPenalty - penalty charged upon liquidation as
- *   proportion of debt
- * @property {Ratio} interestRate - annual interest rate charged on debt
- *   positions
- * @property {Ratio} mintFee - The fee (in BasisPoints) charged when creating or
- *   increasing a debt position.
+ * liquidated to satisfy the debt.
+ * @property {Ratio} liquidationPenalty - penalty charged upon liquidation as proportion of debt
+ * @property {Ratio} interestRate - annual interest rate charged on debt positions
+ * @property {Ratio} mintFee - The fee (in BasisPoints) charged when creating
+ * or increasing a debt position.
  * @property {Amount<'nat'>} debtLimit
- * @property {Ratio} [liquidationPadding] - vault must maintain this in order to
- *   remove collateral or add debt
+ * @property {Ratio} [liquidationPadding] - vault must maintain this in order to remove collateral or add debt
  */
 
 /**
@@ -54,7 +42,7 @@
  */
 
 /**
- * @typedef {object} VaultFactoryCreatorFacet
+ * @typedef  {object} VaultFactoryCreatorFacet
  * @property {AddVaultType} addVaultType
  * @property {() => Allocation} getRewardAllocation
  * @property {() => Promise<Invitation<string, never>>} makeCollectFeesInvitation
@@ -63,20 +51,23 @@
  */
 
 /**
- * @callback MintAndTransfer Mint new debt `toMint` and transfer the `fee`
- *   portion to the vaultFactory's reward pool. Then reallocate over all the
- *   seat arguments and the rewardPoolSeat. Update the `totalDebt` if the
- *   reallocate succeeds.
+ * @callback MintAndTransfer
+ * Mint new debt `toMint` and transfer the `fee` portion to the vaultFactory's reward
+ * pool. Then reallocate over all the seat arguments and the rewardPoolSeat. Update
+ * the `totalDebt` if the reallocate succeeds.
  * @param {ZCFSeat} mintReceiver
  * @param {Amount<'nat'>} toMint
  * @param {Amount<'nat'>} fee
- * @param {TransferPart[]} transfers
+ * @param {import('@agoric/zoe/src/contractSupport/atomicTransfer.js').TransferPart[]} transfers
  * @returns {void}
  */
 
 /**
- * @callback BurnDebt Burn debt tokens off a seat and update the `totalDebt` if
- *   the reallocate succeeds.
+ * @callback BurnDebt
+ *
+ * Burn debt tokens off a seat and update
+ * the `totalDebt` if the reallocate succeeds.
+ *
  * @param {Amount} toBurn
  * @param {ZCFSeat} fromSeat
  * @returns {void}
@@ -87,15 +78,16 @@
  * @property {() => Ratio} getLiquidationMargin
  * @property {() => Ratio} getMintFee
  * @property {() => Promise<PriceQuote>} getCollateralQuote
- * @property {() => Ratio} getInterestRate - The annual interest rate on a debt
- *   position
+ * @property {() => Ratio} getInterestRate - The annual interest rate on a debt position
  * @property {() => RelativeTime} getChargingPeriod - The period (in seconds) at
  *   which interest is charged to the debt position.
  * @property {() => RelativeTime} getRecordingPeriod - The period (in seconds)
  *   at which interest is recorded to the debt position.
  */
 
-/** @typedef {string} VaultId */
+/**
+ * @typedef {string} VaultId
+ */
 
 /**
  * @typedef {object} InterestTiming
@@ -112,9 +104,7 @@
 
 /**
  * @typedef {object} Liquidator
- * @property {() => Promise<
- *   Invitation<void, { debt: Amount<'nat'>; penaltyRate: Ratio }>
- * >} makeLiquidateInvitation
+ * @property {() => Promise<Invitation<void, { debt: Amount<'nat'>; penaltyRate: Ratio; }>>} makeLiquidateInvitation
  */
 
 /**
@@ -134,11 +124,11 @@
 /**
  * @typedef {object} CalculatorKit
  * @property {Calculate} calculate calculate new debt for charging periods up to
- *   the present.
+ * the present.
  * @property {Calculate} calculateReportingPeriod calculate new debt for
- *   reporting periods up to the present. If some charging periods have elapsed
- *   that don't constitute whole reporting periods, the time is not updated past
- *   them and interest is not accumulated for them.
+ * reporting periods up to the present. If some charging periods have elapsed
+ * that don't constitute whole reporting periods, the time is not updated past
+ * them and interest is not accumulated for them.
  */
 
-/** @typedef {{ key: 'governedParams' | { collateralBrand: Brand } }} VaultFactoryParamPath */
+/** @typedef {{key: 'governedParams' | {collateralBrand: Brand}}} VaultFactoryParamPath */