@agoric/inter-protocol 0.16.1 → 0.16.2-calypso-dev-84eb287.0

package/src/auction/auctionBook.js

@@ -1,8 +1,8 @@
-import '@agoric/governance/exported.js';
-import '@agoric/zoe/exported.js';
-import '@agoric/zoe/src/contracts/exported.js';
+/// <reference types="@agoric/internal/exported" />
+/// <reference types="@agoric/governance/exported" />
+/// <reference types="@agoric/zoe/exported" />
 
-import { AmountMath } from '@agoric/ertp';
+import { AmountMath, RatioShape } from '@agoric/ertp';
 import { mustMatch } from '@agoric/store';
 import { M, prepareExoClassKit } from '@agoric/vat-data';
 
@@ -27,6 +27,11 @@ import {
   priceFrom,
 } from './util.js';
 
+/**
+ * @import {Baggage} from '@agoric/vat-data';
+ * @import {PriceAuthority, PriceDescription, PriceQuote, PriceQuoteValue, PriceQuery,} from '@agoric/zoe/tools/types.js';
+ */
+
 const { Fail } = assert;
 const { makeEmpty } = AmountMath;
 
@@ -34,34 +39,38 @@ const DEFAULT_DECIMALS = 9;
 
 /**
  * @file The book represents the collateral-specific state of an ongoing
- * auction. It holds the book, the capturedPrice, and the collateralSeat that has
- * the allocation of assets for sale.
+ *   auction. It holds the book, the capturedPrice, and the collateralSeat that
+ *   has the allocation of assets for sale.
+ *
+ *   The book contains orders for the collateral. It holds two kinds of orders:
  *
- * The book contains orders for the collateral. It holds two kinds of
- * orders:
  *   - Prices express the bidding offer in terms of a Bid amount
- *   - ScaledBids express the offer in terms of a discount (or markup) from the
- *     most recent oracle price.
+ *   - ScaledBids express the offer in terms of a discount (or markup) from the most
+ *       recent oracle price.
  *
- * Offers can be added in three ways. 1) When the auction is not active, prices
- * are automatically added to the appropriate collection. When the auction is
- * active, 2) if a new offer is at or above the current price, it will be
- * settled immediately; 2) If the offer is below the current price, it will be
- * added in the appropriate place and settled when the price reaches that level.
+ *   Offers can be added in three ways. 1) When the auction is not active, prices
+ *   are automatically added to the appropriate collection. When the auction is
+ *   active, 2) if a new offer is at or above the current price, it will be
+ *   settled immediately; 2) If the offer is below the current price, it will be
+ *   added in the appropriate place and settled when the price reaches that
+ *   level.
  */
 
 const trace = makeTracer('AucBook', true);
 
 /**
  * @typedef {{
- *   maxBuy: Amount<'nat'>
+ *   maxBuy: Amount<'nat'>;
  * } & {
- *   exitAfterBuy?: boolean,
- * } & ({
- *   offerPrice: Ratio,
- * } | {
- *    offerBidScaling: Ratio,
- * })} OfferSpec
+ *   exitAfterBuy?: boolean;
+ * } & (
+ *     | {
+ *         offerPrice: Ratio;
+ *       }
+ *     | {
+ *         offerBidScaling: Ratio;
+ *       }
+ *   )} OfferSpec
  */
 /**
  * @param {Brand<'nat'>} bidBrand
@@ -84,21 +93,21 @@ export const makeOfferSpecShape = (bidBrand, collateralBrand) => {
   );
 };
 
-/** @typedef {import('@agoric/vat-data').Baggage} Baggage */
-
 /**
  * @typedef {object} BookDataNotification
- *
- * @property {Ratio         | null}      startPrice identifies the priceAuthority and price
- * @property {Ratio         | null}      currentPriceLevel the price at the current auction tier
- * @property {Amount<'nat'> | null}      startProceedsGoal The proceeds the sellers were targeting to raise
- * @property {Amount<'nat'> | null}      remainingProceedsGoal The remainder of
- *     the proceeds the sellers were targeting to raise
- * @property {Amount<'nat'> | undefined} proceedsRaised The proceeds raised so far in the auction
- * @property {Amount<'nat'>}             startCollateral How much collateral was
- *    available for sale at the start. (If more is deposited later, it'll be
- *    added in.)
- * @property {Amount<'nat'> | null}      collateralAvailable The amount of collateral remaining
+ * @property {Ratio | null} startPrice identifies the priceAuthority and price
+ * @property {Ratio | null} currentPriceLevel the price at the current auction
+ *   tier
+ * @property {Amount<'nat'> | null} startProceedsGoal The proceeds the sellers
+ *   were targeting to raise
+ * @property {Amount<'nat'> | null} remainingProceedsGoal The remainder of the
+ *   proceeds the sellers were targeting to raise
+ * @property {Amount<'nat'> | undefined} proceedsRaised The proceeds raised so
+ *   far in the auction
+ * @property {Amount<'nat'>} startCollateral How much collateral was available
+ *   for sale at the start. (If more is deposited later, it'll be added in.)
+ * @property {Amount<'nat'> | null} collateralAvailable The amount of collateral
+ *   remaining
  */
 
 /**
@@ -118,7 +127,7 @@ export const prepareAuctionBook = (baggage, zcf, makeRecorderKit) => {
     bidHoldingSeat: M.any(),
     bidAmountShape: M.any(),
     priceAuthority: M.any(),
-    updatingOracleQuote: M.any(),
+    updatingOracleQuote: M.or(RatioShape, M.null()),
     bookDataKit: M.any(),
     priceBook: M.any(),
     scaledBidBook: M.any(),
@@ -141,11 +150,6 @@ export const prepareAuctionBook = (baggage, zcf, makeRecorderKit) => {
      */
     (bidBrand, collateralBrand, pAuthority, node) => {
       assertAllDefined({ bidBrand, collateralBrand, pAuthority });
-      const zeroBid = makeEmpty(bidBrand);
-      const zeroRatio = makeRatioFromAmounts(
-        zeroBid,
-        AmountMath.make(collateralBrand, 1n),
-      );
 
       // these don't have to be durable, since we're currently assuming that upgrade
       // from a quiescent state is sufficient. When the auction is quiescent, there
@@ -182,7 +186,7 @@ export const prepareAuctionBook = (baggage, zcf, makeRecorderKit) => {
         bidAmountShape,
 
         priceAuthority: pAuthority,
-        updatingOracleQuote: zeroRatio,
+        updatingOracleQuote: /** @type {Ratio | null} */ (null),
 
         bookDataKit,
 
@@ -231,8 +235,8 @@ export const prepareAuctionBook = (baggage, zcf, makeRecorderKit) => {
     {
       helper: {
         /**
-         * remove the key from the appropriate book, indicated by whether the price
-         * is defined.
+         * remove the key from the appropriate book, indicated by whether the
+         * price is defined.
          *
          * @param {string} key
          * @param {Ratio | undefined} price
@@ -247,8 +251,8 @@ export const prepareAuctionBook = (baggage, zcf, makeRecorderKit) => {
         },
 
         /**
-         * Update the entry in the appropriate book, indicated by whether the price
-         * is defined.
+         * Update the entry in the appropriate book, indicated by whether the
+         * price is defined.
          *
          * @param {string} key
          * @param {Amount} collateralSold
@@ -264,7 +268,8 @@ export const prepareAuctionBook = (baggage, zcf, makeRecorderKit) => {
         },
 
         /**
-         * Settle with seat. The caller is responsible for updating the book, if any.
+         * Settle with seat. The caller is responsible for updating the book, if
+         * any.
          *
          * @param {ZCFSeat} seat
          * @param {Amount<'nat'>} collateralWanted
@@ -341,15 +346,16 @@ export const prepareAuctionBook = (baggage, zcf, makeRecorderKit) => {
         },
 
         /**
-         *  Accept an offer expressed as a price. If the auction is active, attempt to
-         *  buy collateral. If any of the offer remains add it to the book.
+         * Accept an offer expressed as a price. If the auction is active,
+         * attempt to buy collateral. If any of the offer remains add it to the
+         * book.
          *
-         *  @param {ZCFSeat} seat
-         *  @param {Ratio} price
-         *  @param {Amount<'nat'>} maxBuy
-         *  @param {object} opts
-         *  @param {boolean} opts.trySettle
-         *  @param {boolean} [opts.exitAfterBuy]
+         * @param {ZCFSeat} seat
+         * @param {Ratio} price
+         * @param {Amount<'nat'>} maxBuy
+         * @param {object} opts
+         * @param {boolean} opts.trySettle
+         * @param {boolean} [opts.exitAfterBuy]
          */
         acceptPriceOffer(
           seat,
@@ -388,16 +394,16 @@ export const prepareAuctionBook = (baggage, zcf, makeRecorderKit) => {
         },
 
         /**
-         *  Accept an offer expressed as a discount (or markup). If the auction is
-         *  active, attempt to buy collateral. If any of the offer remains add it to
-         *  the book.
+         * Accept an offer expressed as a discount (or markup). If the auction
+         * is active, attempt to buy collateral. If any of the offer remains add
+         * it to the book.
          *
-         *  @param {ZCFSeat} seat
-         *  @param {Ratio} bidScaling
-         *  @param {Amount<'nat'>} maxBuy
-         *  @param {object} opts
-         *  @param {boolean} opts.trySettle
-         *  @param {boolean} [opts.exitAfterBuy]
+         * @param {ZCFSeat} seat
+         * @param {Ratio} bidScaling
+         * @param {Amount<'nat'>} maxBuy
+         * @param {object} opts
+         * @param {boolean} opts.trySettle
+         * @param {boolean} [opts.exitAfterBuy]
          */
         acceptScaledBidOffer(
           seat,
@@ -460,16 +466,58 @@ export const prepareAuctionBook = (baggage, zcf, makeRecorderKit) => {
           });
           return state.bookDataKit.recorder.write(bookData);
         },
+        observeQuoteNotifier() {
+          const { state, facets } = this;
+          const { collateralBrand, bidBrand, priceAuthority } = state;
+
+          trace('observing');
+
+          void E.when(
+            E(collateralBrand).getDisplayInfo(),
+            ({ decimalPlaces = DEFAULT_DECIMALS }) => {
+              const quoteNotifier = E(priceAuthority).makeQuoteNotifier(
+                AmountMath.make(collateralBrand, 10n ** BigInt(decimalPlaces)),
+                bidBrand,
+              );
+              void observeNotifier(quoteNotifier, {
+                updateState: quote => {
+                  trace(
+                    `BOOK notifier ${priceFrom(quote).numerator.value}/${
+                      priceFrom(quote).denominator.value
+                    }`,
+                  );
+                  state.updatingOracleQuote = priceFrom(quote);
+                },
+                fail: reason => {
+                  trace(
+                    `Failure from quoteNotifier (${reason}) setting to null`,
+                  );
+                  // lack of quote will trigger restart
+                  state.updatingOracleQuote = null;
+                },
+                finish: done => {
+                  trace(
+                    `quoteNotifier invoked finish(${done}). setting quote to null`,
+                  );
+                  // lack of quote will trigger restart
+                  state.updatingOracleQuote = null;
+                },
+              });
+            },
+          );
+
+          void facets.helper.publishBookData();
+        },
       },
       self: {
         /**
          * @param {Amount<'nat'>} assetAmount
          * @param {ZCFSeat} sourceSeat
          * @param {Amount<'nat'>} [proceedsGoal] an amount that the depositor
-         *    would like to raise. The auction is requested to not sell more
-         *    collateral than required to raise that much. The auctioneer might
-         *    sell more if there is more than one supplier of collateral, and
-         *    they request inconsistent limits.
+         *   would like to raise. The auction is requested to not sell more
+         *   collateral than required to raise that much. The auctioneer might
+         *   sell more if there is more than one supplier of collateral, and
+         *   they request inconsistent limits.
          */
         addAssets(assetAmount, sourceSeat, proceedsGoal) {
           const { state, facets } = this;
@@ -547,9 +595,12 @@ export const prepareAuctionBook = (baggage, zcf, makeRecorderKit) => {
 
           trace(this.state.collateralBrand, 'settleAtNewRate', reduction);
           const { capturedPriceForRound, priceBook, scaledBidBook } = state;
-          capturedPriceForRound !== null ||
-            Fail`price must be captured before auction starts`;
-          assert(capturedPriceForRound);
+          if (!capturedPriceForRound) {
+            console.error(
+              `⚠️No price for ${this.state.collateralBrand}, skipping auction.`,
+            );
+            return;
+          }
 
           state.curAuctionPrice = multiplyRatios(
             reduction,
@@ -619,6 +670,12 @@ export const prepareAuctionBook = (baggage, zcf, makeRecorderKit) => {
           const { facets, state } = this;
 
           trace(`capturing oracle price `, state.updatingOracleQuote);
+          if (!state.updatingOracleQuote) {
+            // if the price has feed has died, try restarting it.
+            facets.helper.observeQuoteNotifier();
+            return;
+          }
+
           state.capturedPriceForRound = state.updatingOracleQuote;
           void facets.helper.publishBookData();
         },
@@ -718,43 +775,18 @@ export const prepareAuctionBook = (baggage, zcf, makeRecorderKit) => {
       finish: ({ state, facets }) => {
         const { collateralBrand, bidBrand, priceAuthority } = state;
         assertAllDefined({ collateralBrand, bidBrand, priceAuthority });
-        void E.when(
-          E(collateralBrand).getDisplayInfo(),
-          ({ decimalPlaces = DEFAULT_DECIMALS }) => {
-            // TODO(#6946) use this to keep a current price that can be published in state.
-            const quoteNotifier = E(priceAuthority).makeQuoteNotifier(
-              AmountMath.make(collateralBrand, 10n ** BigInt(decimalPlaces)),
-              bidBrand,
-            );
-            void observeNotifier(quoteNotifier, {
-              updateState: quote => {
-                trace(
-                  `BOOK notifier ${priceFrom(quote).numerator.value}/${
-                    priceFrom(quote).denominator.value
-                  }`,
-                );
-                state.updatingOracleQuote = priceFrom(quote);
-              },
-              fail: reason => {
-                throw Error(
-                  `auction observer of ${collateralBrand} failed: ${reason}`,
-                );
-              },
-              finish: done => {
-                throw Error(
-                  `auction observer for ${collateralBrand} died: ${done}`,
-                );
-              },
-            });
-          },
-        );
-        void facets.helper.publishBookData();
+
+        facets.helper.observeQuoteNotifier();
       },
       stateShape: AuctionBookStateShape,
     },
   );
 
-  /** @type {(...args: Parameters<typeof makeAuctionBookKit>) => ReturnType<typeof makeAuctionBookKit>['self']} */
+  /**
+   * @type {(
+   *   ...args: Parameters<typeof makeAuctionBookKit>
+   * ) => ReturnType<typeof makeAuctionBookKit>['self']}
+   */
   const makeAuctionBook = (...args) => makeAuctionBookKit(...args).self;
   return makeAuctionBook;
 };

package/src/auction/auctioneer.d.ts

@@ -0,0 +1,69 @@
+export function distributeProportionalSharesWithLimits(unsoldCollateral: Amount<"nat">, proceeds: Amount<"nat">, deposits: {
+    seat: ZCFSeat;
+    amount: Amount<"nat">;
+    goal: Amount<"nat">;
+}[], collateralSeat: ZCFSeat, bidHoldingSeat: ZCFSeat, collateralKeyword: string, reserveSeat: ZCFSeat, brand: Brand): TransferPart[];
+export function start(zcf: ZCF<GovernanceTerms<typeof auctioneerParamTypes> & {
+    timerService: import("@agoric/time").TimerService;
+    reservePublicFacet: AssetReservePublicFacet;
+    priceAuthority: PriceAuthority;
+}>, privateArgs: {
+    initialPoserInvitation: Invitation;
+    storageNode: StorageNode;
+    marshaller: Marshaller;
+}, baggage: Baggage): Promise<{
+    publicFacet: globalThis.GovernedPublicFacet<{
+        getElectorate: () => import("@agoric/governance/src/types.js").ParamValueForType<"invitation">;
+        getStartFrequency: () => import("@agoric/governance/src/types.js").ParamValueForType<"relativeTime">;
+        getClockStep: () => import("@agoric/governance/src/types.js").ParamValueForType<"relativeTime">;
+        getStartingRate: () => import("@agoric/governance/src/types.js").ParamValueForType<"nat">;
+        getLowestRate: () => import("@agoric/governance/src/types.js").ParamValueForType<"nat">;
+        getDiscountStep: () => import("@agoric/governance/src/types.js").ParamValueForType<"nat">;
+        getAuctionStartDelay: () => import("@agoric/governance/src/types.js").ParamValueForType<"relativeTime">;
+        getPriceLockPeriod: () => import("@agoric/governance/src/types.js").ParamValueForType<"relativeTime">;
+        /** @param {Brand<'nat'>} collateralBrand */
+        makeBidInvitation(collateralBrand: Brand<"nat">): Promise<Invitation<string, import("./auctionBook.js").OfferSpec>>;
+        getSchedules(): {
+            liveAuctionSchedule: import("./scheduler.js").Schedule | null;
+            nextAuctionSchedule: import("./scheduler.js").Schedule | null;
+        };
+        getScheduleUpdates(): globalThis.Subscriber<import("./scheduler.js").ScheduleNotification>;
+        getBookDataUpdates(brand: any): globalThis.Subscriber<import("./auctionBook.js").BookDataNotification>;
+        getPublicTopics(brand: any): {
+            bookData: import("@agoric/zoe/src/contractSupport/topics.js").PublicTopic<import("./auctionBook.js").BookDataNotification>;
+        } | {
+            schedule: import("@agoric/zoe/src/contractSupport/topics.js").PublicTopic<import("./scheduler.js").ScheduleNotification>;
+        };
+        makeDepositInvitation: () => Promise<Invitation<string, {
+            goal: Amount<"nat">;
+        }>>;
+    }>;
+    creatorFacet: globalThis.GovernedCreatorFacet<{
+        /**
+         * @param {Issuer<'nat'>} issuer
+         * @param {Keyword} kwd
+         */
+        addBrand(issuer: Issuer<"nat">, kwd: Keyword): Promise<void>;
+        /** @returns {Promise<import('./scheduler.js').FullSchedule>} */
+        getSchedule(): Promise<import("./scheduler.js").FullSchedule>;
+    } & import("@endo/marshal").RemotableObject<`Alleged: ${string}`> & import("@endo/eventual-send").RemotableBrand<{}, {
+        /**
+         * @param {Issuer<'nat'>} issuer
+         * @param {Keyword} kwd
+         */
+        addBrand(issuer: Issuer<"nat">, kwd: Keyword): Promise<void>;
+        /** @returns {Promise<import('./scheduler.js').FullSchedule>} */
+        getSchedule(): Promise<import("./scheduler.js").FullSchedule>;
+    }>>;
+}>;
+/** @typedef {ContractOf<typeof start>} AuctioneerContract */
+/** @typedef {AuctioneerContract['publicFacet']} AuctioneerPublicFacet */
+/** @typedef {AuctioneerContract['creatorFacet']} AuctioneerCreatorFacet */
+export const AuctionPFShape: import("@endo/patterns").Matcher;
+export type AuctioneerContract = ContractOf<typeof start>;
+export type AuctioneerPublicFacet = AuctioneerContract["publicFacet"];
+export type AuctioneerCreatorFacet = AuctioneerContract["creatorFacet"];
+import { auctioneerParamTypes } from './params.js';
+import type { PriceAuthority } from '@agoric/zoe/tools/types.js';
+import type { Baggage } from '@agoric/vat-data';
+//# sourceMappingURL=auctioneer.d.ts.map

package/src/auction/auctioneer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auctioneer.d.ts","sourceRoot":"","sources":["auctioneer.js"],"names":[],"mappings":"AAgLO,yEAXI,MAAM,CAAC,KAAK,CAAC,YACb,MAAM,CAAC,KAAK,CAAC,YACb;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;CAAE,EAAE,kBAC/D,OAAO,kBACP,OAAO,qBAEP,MAAM,eAEN,OAAO,SACP,KAAK,kBAgNf;AAiBM,2BAdI,GAAG,CACb,eAAmB,CAAC,OAAO,oBAAoB,CAAC,GAAG;IACnD,YAAkB,EAAE,OAAO,cAAc,EAAE,YAAY,CAAC;IACxD,kBAAwB,EAAE,uBAAuB,CAAC;IAClD,cAAoB,EAAE,cAAc,CAAC;CAChC,CACF,eACO;IACV,sBAA0B,EAAE,UAAU,CAAC;IACvC,WAAe,EAAE,WAAW,CAAC;IAC7B,UAAc,EAAE,UAAU,CAAC;CACxB,WACO,OAAO;;;;;;;;;;QAyOZ,4CAA4C;2CAAhC,KAAK,CAAC,KAAK,CAAC;;;;;;;;;;;;;kBApCT,MAAM,CAAC,KAAK,CAAC;;;;QAmG5B;;;WAGG;yBAFQ,MAAM,CAAC,KAAK,CAAC,OACb,OAAO;QAwBlB,gEAAgE;uBAAlD,OAAO,CAAC,OAAO,gBAAgB,EAAE,YAAY,CAAC;;QA1B5D;;;WAGG;yBAFQ,MAAM,CAAC,KAAK,CAAC,OACb,OAAO;QAwBlB,gEAAgE;uBAAlD,OAAO,CAAC,OAAO,gBAAgB,EAAE,YAAY,CAAC;;GAQjE;AAED,6DAA6D;AAC7D,yEAAyE;AACzE,2EAA2E;AAE3E,8DAAkE;iCAJpD,UAAU,CAAC,OAAO,KAAK,CAAC;oCACxB,kBAAkB,CAAC,aAAa,CAAC;qCACjC,kBAAkB,CAAC,cAAc,CAAC;qCA3rBX,aAAa;oCAM2C,4BAA4B;6BAD/F,kBAAkB"}

package/src/auction/auctioneer.js

@@ -1,6 +1,5 @@
-import '@agoric/governance/exported.js';
-import '@agoric/zoe/exported.js';
-import '@agoric/zoe/src/contracts/exported.js';
+/// <reference types="@agoric/governance/exported" />
+/// <reference types="@agoric/zoe/exported" />
 
 import { AmountMath, AmountShape, BrandShape } from '@agoric/ertp';
 import { handleParamGovernance } from '@agoric/governance';
@@ -35,7 +34,10 @@ import { auctioneerParamTypes } from './params.js';
 import { makeScheduler } from './scheduler.js';
 import { AuctionState } from './util.js';
 
-/** @typedef {import('@agoric/vat-data').Baggage} Baggage */
+/**
+ * @import {Baggage} from '@agoric/vat-data';
+ * @import {PriceAuthority, PriceDescription, PriceQuote, PriceQuoteValue, PriceQuery,} from '@agoric/zoe/tools/types.js';
+ */
 
 const { Fail, quote: q } = assert;
 const { add, multiply } = natSafeMath;
@@ -43,11 +45,10 @@ const { add, multiply } = natSafeMath;
 const trace = makeTracer('Auction', true);
 
 /**
- * @file
- * In this file, 'Bid' is the name of the ERTP issuer used to purchase
- * collateral from various issuers. It's too confusing to also use Bid as a verb
- * or a description of amounts offered, so we've tried to find alternatives in
- * all those cases.
+ * @file In this file, 'Bid' is the name of the ERTP issuer used to purchase
+ *   collateral from various issuers. It's too confusing to also use Bid as a
+ *   verb or a description of amounts offered, so we've tried to find
+ *   alternatives in all those cases.
  */
 
 const MINIMUM_BID_GIVE = 1n;
@@ -67,17 +68,19 @@ const makeBPRatio = (rate, bidBrand, collateralBrand = bidBrand) =>
  * The auction sold some amount of collateral, and raised a certain amount of
  * Bid. The excess collateral was returned as `unsoldCollateral`. The Bid amount
  * collected from the auction participants is `proceeds`.
+ *
  * Return a set of transfers for atomicRearrange() that distribute
  * `unsoldCollateral` and `proceeds` proportionally to each seat's deposited
  * amount. Any uneven split should be allocated to the reserve.
  *
  * @param {Amount} unsoldCollateral
  * @param {Amount} proceeds
- * @param {{seat: ZCFSeat, amount: Amount<'nat'>, goal: Amount<'nat'>}[]} deposits
+ * @param {{ seat: ZCFSeat; amount: Amount<'nat'>; goal: Amount<'nat'> }[]} deposits
  * @param {ZCFSeat} collateralSeat
- * @param {ZCFSeat} bidHoldingSeat seat with the Bid allocation to be distributed
+ * @param {ZCFSeat} bidHoldingSeat seat with the Bid allocation to be
+ *   distributed
  * @param {string} collateralKeyword The Reserve will hold multiple collaterals,
- *      so they need distinct keywords
+ *   so they need distinct keywords
  * @param {ZCFSeat} reserveSeat
  * @param {Brand} brand
  */
@@ -97,7 +100,7 @@ const distributeProportionalShares = (
 
   const collShare = makeRatioFromAmounts(unsoldCollateral, totalCollDeposited);
   const currShare = makeRatioFromAmounts(proceeds, totalCollDeposited);
-  /** @type {import('@agoric/zoe/src/contractSupport/atomicTransfer.js').TransferPart[]} */
+  /** @type {TransferPart[]} */
   const transfers = [];
   let proceedsLeft = proceeds;
   let collateralLeft = unsoldCollateral;
@@ -132,6 +135,7 @@ const distributeProportionalShares = (
  * The auction sold some amount of collateral, and raised a certain amount of
  * Bid. The excess collateral was returned as `unsoldCollateral`. The Bid amount
  * collected from the auction participants is `proceeds`.
+ *
  * Return a set of transfers for atomicRearrange() that distribute
  * `unsoldCollateral` and `proceeds` proportionally to each seat's deposited
  * amount. Any uneven split should be allocated to the reserve.
@@ -140,32 +144,33 @@ const distributeProportionalShares = (
  * outside the contract below.
  *
  * Some or all of the depositors may have specified a goal amount.
- *  * A if none did, return collateral and Bid prorated to deposits.
- *  * B if proceeds < proceedsGoal everyone gets prorated amounts of both.
- *  * C if proceeds matches proceedsGoal, everyone gets the Bid they
- *    asked for, plus enough collateral to reach the same proportional payout.
- *    If any depositor's goal amount exceeded their share of the total,
- *    we'll fall back to the first approach.
- *  * D if proceeds > proceedsGoal && all depositors specified a limit,
- *    all depositors get their goal first, then we distribute the
- *    remainder (collateral and Bid) to get the same proportional payout.
- *  * E if proceeds > proceedsGoal && some depositors didn't specify a
- *    limit, depositors who did will get their goal first, then we distribute
- *    the remainder (collateral and Bid) to get the same proportional
- *    payout. If any depositor's goal amount exceeded their share of the
- *    total, we'll fall back as above.
- * Think of it this way: those who specified a limit want as much collateral
- * back as possible, consistent with raising a certain amount of Bid. Those
- * who didn't specify a limit are trying to sell collateral, and would prefer to
- * have as much as possible converted to Bid.
+ *
+ * - A if none did, return collateral and Bid prorated to deposits.
+ * - B if proceeds < proceedsGoal everyone gets prorated amounts of both.
+ * - C if proceeds matches proceedsGoal, everyone gets the Bid they asked for,
+ *   plus enough collateral to reach the same proportional payout. If any
+ *   depositor's goal amount exceeded their share of the total, we'll fall back
+ *   to the first approach.
+ * - D if proceeds > proceedsGoal && all depositors specified a limit, all
+ *   depositors get their goal first, then we distribute the remainder
+ *   (collateral and Bid) to get the same proportional payout.
+ * - E if proceeds > proceedsGoal && some depositors didn't specify a limit,
+ *   depositors who did will get their goal first, then we distribute the
+ *   remainder (collateral and Bid) to get the same proportional payout. If any
+ *   depositor's goal amount exceeded their share of the total, we'll fall back
+ *   as above. Think of it this way: those who specified a limit want as much
+ *   collateral back as possible, consistent with raising a certain amount of
+ *   Bid. Those who didn't specify a limit are trying to sell collateral, and
+ *   would prefer to have as much as possible converted to Bid.
  *
  * @param {Amount<'nat'>} unsoldCollateral
  * @param {Amount<'nat'>} proceeds
- * @param {{seat: ZCFSeat, amount: Amount<'nat'>, goal: Amount<'nat'>}[]} deposits
+ * @param {{ seat: ZCFSeat; amount: Amount<'nat'>; goal: Amount<'nat'> }[]} deposits
  * @param {ZCFSeat} collateralSeat
- * @param {ZCFSeat} bidHoldingSeat seat with the Bid allocation to be distributed
+ * @param {ZCFSeat} bidHoldingSeat seat with the Bid allocation to be
+ *   distributed
  * @param {string} collateralKeyword The Reserve will hold multiple collaterals,
- *      so they need distinct keywords
+ *   so they need distinct keywords
  * @param {ZCFSeat} reserveSeat
  * @param {Brand} brand
  */
@@ -255,7 +260,7 @@ export const distributeProportionalSharesWithLimits = (
   // collateral to reach their share. Then see what's left, and allocate it
   // among the remaining depositors. Escape to distributeProportionalShares if
   // anything doesn't work.
-  /** @type {import('@agoric/zoe/src/contractSupport/atomicTransfer.js').TransferPart[]} */
+  /** @type {TransferPart[]} */
   const transfers = [];
   let proceedsLeft = proceeds;
   let collateralLeft = unsoldCollateral;
@@ -378,15 +383,17 @@ export const distributeProportionalSharesWithLimits = (
 };
 
 /**
- * @param {ZCF<GovernanceTerms<typeof auctioneerParamTypes> & {
- *   timerService: import('@agoric/time/src/types').TimerService,
- *   reservePublicFacet: AssetReservePublicFacet,
- *   priceAuthority: PriceAuthority
- * }>} zcf
+ * @param {ZCF<
+ *   GovernanceTerms<typeof auctioneerParamTypes> & {
+ *     timerService: import('@agoric/time').TimerService;
+ *     reservePublicFacet: AssetReservePublicFacet;
+ *     priceAuthority: PriceAuthority;
+ *   }
+ * >} zcf
  * @param {{
- *   initialPoserInvitation: Invitation,
- *   storageNode: StorageNode,
- *   marshaller: Marshaller
+ *   initialPoserInvitation: Invitation;
+ *   storageNode: StorageNode;
+ *   marshaller: Marshaller;
  * }} privateArgs
  * @param {Baggage} baggage
  */
@@ -399,7 +406,12 @@ export const start = async (zcf, privateArgs, baggage) => {
 
   /** @type {MapStore<Brand, import('./auctionBook.js').AuctionBook>} */
   const books = provideDurableMapStore(baggage, 'auctionBooks');
-  /** @type {MapStore<Brand, Array<{ seat: ZCFSeat, amount: Amount<'nat'>, goal: Amount<'nat'>}>>} */
+  /**
+   * @type {MapStore<
+   *   Brand,
+   *   { seat: ZCFSeat; amount: Amount<'nat'>; goal: Amount<'nat'> }[]
+   * >}
+   */
   const deposits = provideDurableMapStore(baggage, 'deposits');
   /** @type {MapStore<Brand, Keyword>} */
   const brandToKeyword = provideDurableMapStore(baggage, 'brandToKeyword');
@@ -427,9 +439,11 @@ export const start = async (zcf, privateArgs, baggage) => {
   });
   const scheduleKit = makeERecorderKit(
     E(privateArgs.storageNode).makeChildNode('schedule'),
-    /** @type {import('@agoric/zoe/src/contractSupport/recorder.js').TypedMatcher<import('./scheduler.js').ScheduleNotification>} */ (
-      M.any()
-    ),
+    /**
+     * @type {import('@agoric/zoe/src/contractSupport/recorder.js').TypedMatcher<
+     *     import('./scheduler.js').ScheduleNotification
+     *   >}
+     */ (M.any()),
   );
 
   /**
@@ -578,7 +592,7 @@ export const start = async (zcf, privateArgs, baggage) => {
 
   /**
    * @param {ZCFSeat} zcfSeat
-   * @param {{ goal: Amount<'nat'>}} offerArgs
+   * @param {{ goal: Amount<'nat'> }} offerArgs
    */
   const depositOfferHandler = (zcfSeat, offerArgs) => {
     const goalMatcher = M.or(undefined, { goal: bidAmountShape });
@@ -678,7 +692,7 @@ export const start = async (zcf, privateArgs, baggage) => {
   const creatorFacet = makeFarGovernorFacet(
     Far('Auctioneer creatorFacet', {
       /**
-       * @param {Issuer} issuer
+       * @param {Issuer<'nat'>} issuer
        * @param {Keyword} kwd
        */
       async addBrand(issuer, kwd) {