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

package/src/auction/auctioneer.js

@@ -43,10 +43,11 @@ 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;
@@ -66,19 +67,17 @@ 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
  */
@@ -98,7 +97,7 @@ const distributeProportionalShares = (
 
   const collShare = makeRatioFromAmounts(unsoldCollateral, totalCollDeposited);
   const currShare = makeRatioFromAmounts(proceeds, totalCollDeposited);
-  /** @type {TransferPart[]} */
+  /** @type {import('@agoric/zoe/src/contractSupport/atomicTransfer.js').TransferPart[]} */
   const transfers = [];
   let proceedsLeft = proceeds;
   let collateralLeft = unsoldCollateral;
@@ -133,7 +132,6 @@ 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.
@@ -142,33 +140,32 @@ 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
  */
@@ -258,7 +255,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 {TransferPart[]} */
+  /** @type {import('@agoric/zoe/src/contractSupport/atomicTransfer.js').TransferPart[]} */
   const transfers = [];
   let proceedsLeft = proceeds;
   let collateralLeft = unsoldCollateral;
@@ -381,17 +378,15 @@ 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/src/types').TimerService,
+ *   reservePublicFacet: AssetReservePublicFacet,
+ *   priceAuthority: PriceAuthority
+ * }>} zcf
  * @param {{
- *   initialPoserInvitation: Invitation;
- *   storageNode: StorageNode;
- *   marshaller: Marshaller;
+ *   initialPoserInvitation: Invitation,
+ *   storageNode: StorageNode,
+ *   marshaller: Marshaller
  * }} privateArgs
  * @param {Baggage} baggage
  */
@@ -404,12 +399,7 @@ export const start = async (zcf, privateArgs, baggage) => {
 
   /** @type {MapStore<Brand, import('./auctionBook.js').AuctionBook>} */
   const books = provideDurableMapStore(baggage, 'auctionBooks');
-  /**
-   * @type {MapStore<
-   *   Brand,
-   *   { seat: ZCFSeat; amount: Amount<'nat'>; goal: Amount<'nat'> }[]
-   * >}
-   */
+  /** @type {MapStore<Brand, Array<{ seat: ZCFSeat, amount: Amount<'nat'>, goal: Amount<'nat'>}>>} */
   const deposits = provideDurableMapStore(baggage, 'deposits');
   /** @type {MapStore<Brand, Keyword>} */
   const brandToKeyword = provideDurableMapStore(baggage, 'brandToKeyword');
@@ -437,11 +427,9 @@ 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()
+    ),
   );
 
   /**
@@ -590,7 +578,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 });

package/src/auction/offerBook.js

@@ -25,14 +25,12 @@ const nextSequenceNumber = () => {
 
 /**
  * @typedef {{
- *   seat: ZCFSeat;
- *   wanted: Amount<'nat'>;
- *   seqNum: NatValue;
- *   received: Amount<'nat'>;
- * } & { exitAfterBuy: boolean } & (
- *     | { bidScaling: Pattern; price: undefined }
- *     | { bidScaling: undefined; price: Ratio }
- *   )} BidderRecord
+ * seat: ZCFSeat,
+ * wanted: Amount<'nat'>,
+ * seqNum: NatValue,
+ * received: Amount<'nat'>,
+ * } &  {exitAfterBuy: boolean} & ({ bidScaling: Pattern, price: undefined } | { bidScaling: undefined, price: Ratio})
+ * } BidderRecord
  */
 
 const ScaledBidBookStateShape = harden({
@@ -43,8 +41,7 @@ const ScaledBidBookStateShape = harden({
 
 /**
  * Prices in this book are expressed as percentage of the full oracle price
- * snapshot taken when the auction started. .4 is 60% off. 1.1 is 10% above
- * par.
+ * snapshot taken when the auction started. .4 is 60% off. 1.1 is 10% above par.
  *
  * @param {Baggage} baggage
  */
@@ -54,6 +51,7 @@ export const prepareScaledBidBook = baggage =>
     'scaledBidBook',
     undefined,
     /**
+     *
      * @param {Pattern} bidScalingPattern
      * @param {Brand} collateralBrand
      */
@@ -136,8 +134,8 @@ const PriceBookStateShape = harden({
 });
 
 /**
- * Prices in this book are actual prices expressed in terms of bid amount and
- * collateral amount.
+ * Prices in this book are actual prices expressed in terms of bid amount
+ * and collateral amount.
  *
  * @param {Baggage} baggage
  */
@@ -147,6 +145,7 @@ export const preparePriceBook = baggage =>
     'priceBook',
     undefined,
     /**
+     *
      * @param {Pattern} priceRatioPattern
      * @param {Brand} collateralBrand
      */

package/src/auction/params.js

@@ -13,7 +13,7 @@ import { M } from '@agoric/store';
 export const InvitationShape = M.remotable('Invitation');
 
 /**
- * In seconds, how often to start an auction. The auction will start at
+ * In seconds, how often to start an auction.  The auction will start at
  * AUCTION_START_DELAY seconds after a multiple of START_FREQUENCY, with the
  * price at STARTING_RATE_BP. Every CLOCK_STEP, the price will be reduced by
  * DISCOUNT_STEP_BP, as long as the rate is at or above LOWEST_RATE_BP, or until
@@ -73,7 +73,9 @@ export const auctioneerParamTypes = harden({
  * @property {import('@agoric/time/src/types').TimerBrand} TimerBrand
  */
 
-/** @param {AuctionParams} initial */
+/**
+ * @param {AuctionParams} initial
+ */
 export const makeAuctioneerParams = ({
   ElectorateInvitationAmount,
   StartFrequency,
@@ -146,7 +148,7 @@ export const makeAuctioneerParamManager = (publisherKit, zcf, initial) => {
 harden(makeAuctioneerParamManager);
 
 /**
- * @param {{ storageNode: ERef<StorageNode>; marshaller: ERef<Marshaller> }} caps
+ * @param {{storageNode: ERef<StorageNode>, marshaller: ERef<Marshaller>}} caps
  * @param {ERef<Timer>} timer
  * @param {ERef<PriceAuthority>} priceAuthority
  * @param {ERef<AssetReservePublicFacet>} reservePublicFacet

package/src/auction/scheduleMath.js

@@ -18,18 +18,17 @@ const subtract1 = relTime =>
 /**
  * The length of the auction has to be inferred from the governed params.
  *
- * 1. The auction starts by offering collateral at a `StartingRate` (e.g., 105%) of
- *    the market price at auction start, and continues until it reaches (or
- *    would exceed on its next step) LowestRate (e.g., 65%)
+ * 1. The auction starts by offering collateral at a `StartingRate` (e.g., 105%)
+ *    of the market price at auction start, and continues until it reaches
+ *    (or would exceed on its next step) LowestRate (e.g., 65%)
  * 2. The offer price changes every `ClockStep` seconds
- * 3. The offer price changes by `DiscountStep` amount (e.g., 5%) each step So it
- *    must run however many `ClockSteps` are required to get from `StartingRate`
- *    to `LowestRate` changing by `DiscountStep` each time.
+ * 3. The offer price changes by `DiscountStep` amount (e.g., 5%) each step So
+ *    it must run however many `ClockSteps` are required to get from
+ *    `StartingRate` to `LowestRate` changing by `DiscountStep` each time.
  *
- * Therefore, the duration is `(StartingRate - LowestRate) / DiscountStep *
- * ClockStep`.
+ * Therefore, the duration is `(StartingRate - LowestRate) / DiscountStep * ClockStep`.
  *
- * Note that this is what's _scheduled_. More than one auction can be running
+ * Note that this is what's *scheduled*. More than one auction can be running
  * simultaneously, and some conditions can cause some of the auctions to stop
  * selling early (e.g. reaching their target debt to raise or selling all of
  * their collateral).
@@ -109,10 +108,10 @@ export const computeRoundTiming = (params, baseTime) => {
 harden(computeRoundTiming);
 
 /**
- * Calculate when the next descending step will start. If we're between auctions
- * (i.e. liveSchedule is undefined), or the last step of the current auction has
- * started, then it'll be nextSchedule.startTime. Otherwise, it's the start of
- * the step following the current step.
+ * Calculate when the next descending step will start. If we're between
+ * auctions (i.e. liveSchedule is undefined), or the last step of the current
+ * auction has started, then it'll be nextSchedule.startTime. Otherwise, it's
+ * the start of the step following the current step.
  *
  * @param {import('./scheduler.js').Schedule | null} liveSchedule
  * @param {import('./scheduler.js').Schedule | null} nextSchedule
@@ -144,6 +143,7 @@ export const nextDescendingStepTime = (liveSchedule, nextSchedule, now) => {
 harden(nextDescendingStepTime);
 
 /**
+ *
  * @param {Timestamp} time
  * @param {import('./scheduler.js').Schedule} schedule
  * @returns {'before' | 'during' | 'endExactly' | 'after'}

package/src/auction/scheduler.js

@@ -20,22 +20,21 @@ const MAX_LATE_TICK = 300n;
 
 /**
  * @file The scheduler is presumed to be quiescent between auction rounds. Each
- *   Auction round consists of a sequence of steps with decreasing prices. There
- *   should always be a next schedule, but between rounds, liveSchedule is
- *   null.
+ * Auction round consists of a sequence of steps with decreasing prices. There
+ * should always be a next schedule, but between rounds, liveSchedule is null.
  *
- *   The lock period that the liquidators use might start before the previous
- *   round has finished, so we need to schedule the next round each time an
- *   auction starts. This means if the scheduling parameters change, it'll be a
- *   full cycle before we switch. Otherwise, the vaults wouldn't know when to
- *   start their lock period. If the lock period for the next auction hasn't
- *   started when each aucion ends, we recalculate it, in case the parameters
- *   have changed.
+ * The lock period that the liquidators use might start before the previous
+ * round has finished, so we need to schedule the next round each time an
+ * auction starts. This means if the scheduling parameters change, it'll be a
+ * full cycle before we switch. Otherwise, the vaults wouldn't know when to
+ * start their lock period. If the lock period for the next auction hasn't
+ * started when each aucion ends, we recalculate it, in case the parameters have
+ * changed.
  *
- *   If the clock skips forward (because of a chain halt, for instance), the
- *   scheduler will try to cleanly and quickly finish any round already in
- *   progress. It would take additional work on the manual timer to test this
- *   thoroughly.
+ * If the clock skips forward (because of a chain halt, for instance), the
+ * scheduler will try to cleanly and quickly finish any round already in
+ * progress. It would take additional work on the manual timer to test this
+ * thoroughly.
  */
 
 const makeCancelToken = makeCancelTokenMaker('scheduler');
@@ -50,11 +49,12 @@ const makeCancelToken = makeCancelTokenMaker('scheduler');
 
 /**
  * @typedef {object} ScheduleNotification
- * @property {Timestamp | null} activeStartTime start time of current auction if
- *   auction is active
+ *
+ * @property {Timestamp | null} activeStartTime start time of current
+ *    auction if auction is active
  * @property {Timestamp | null} nextStartTime start time of next auction
- * @property {Timestamp | null} nextDescendingStepTime when the next descending
- *   step will take place
+ * @property {Timestamp | null} nextDescendingStepTime when the next descending step
+ *    will take place
  */
 
 const safelyComputeRoundTiming = (params, baseTime) => {
@@ -92,7 +92,7 @@ export const makeScheduler = async (
    */
   let liveSchedule = null;
 
-  /** @returns {Promise<{ now: Timestamp; nextSchedule: Schedule | null }>} */
+  /** @returns {Promise<{ now: Timestamp, nextSchedule: Schedule | null }>} */
   const initializeNextSchedule = async () => {
     return E.when(
       // XXX manualTimer returns a bigint, not a timeRecord.
@@ -114,7 +114,7 @@ export const makeScheduler = async (
 
   const stepCancelToken = makeCancelToken();
 
-  /** @type {(typeof AuctionState)[keyof typeof AuctionState]} */
+  /** @type {typeof AuctionState[keyof typeof AuctionState]} */
   let auctionState = AuctionState.WAITING;
 
   /**
@@ -149,7 +149,18 @@ export const makeScheduler = async (
       auctionState = AuctionState.WAITING;
       auctionDriver.finalize();
 
-      if (!nextSchedule) {
+      if (nextSchedule) {
+        // only recalculate the next schedule at this point if the lock time has
+        // not been reached.
+        const nextLock = nextSchedule.lockTime;
+        if (nextLock && TimeMath.compareAbs(now, nextLock) < 0) {
+          const afterNow = TimeMath.addAbsRel(
+            now,
+            TimeMath.coerceRelativeTimeRecord(1n, timerBrand),
+          );
+          nextSchedule = safelyComputeRoundTiming(params, afterNow);
+        }
+      } else {
         console.error(
           '🛠️ finishAuctionRound without scheduling the next; repair with new auctioneer params',
         );
@@ -322,18 +333,7 @@ export const makeScheduler = async (
       // NB: may be fired with the initial params as well
       async updateState(_newState) {
         trace('received param update', _newState);
-        await null;
-
-        let fixableSchedule;
         if (!nextSchedule) {
-          fixableSchedule = true;
-        } else {
-          now = await E(timer).getCurrentTimestamp();
-          fixableSchedule =
-            TimeMath.compareAbs(nextSchedule.startTime, now) < 0;
-        }
-
-        if (fixableSchedule) {
           trace('repairing nextSchedule and restarting');
           ({ nextSchedule } = await initializeNextSchedule());
           startSchedulingFromScratch();

package/src/auction/sortedOffers.js

@@ -13,13 +13,12 @@ const { Fail } = assert;
 
 /**
  * @file we use a floating point representation of the price or rate as the
- *   first part of the key in the store. The second part is the sequence number
- *   of the bid, but it doesn't matter for sorting. When we retrieve multiple
- *   bids, it's only by bid value, so we don't care how the sequence numbers
- *   sort.
+ * first part of the key in the store. The second part is the sequence number of
+ * the bid, but it doesn't matter for sorting. When we retrieve multiple bids,
+ * it's only by bid value, so we don't care how the sequence numbers sort.
  *
- *   We take advantage of the fact that encodeData takes a passable and turns it
- *   into a sort key. Arrays of passable data sort like composite keys.
+ * We take advantage of the fact that encodeData takes a passable and turns it
+ * into a sort key. Arrays of passable data sort like composite keys.
  */
 
 /**
@@ -40,7 +39,7 @@ export const toPartialOfferKey = offerPrice => {
  * @param {Ratio} offerPrice IST/collateral
  * @param {bigint} sequenceNumber
  * @returns {string} lexically sortable string in which highest price is first,
- *   ties will be broken by sequenceNumber of offer
+ *    ties will be broken by sequenceNumber of offer
  */
 export const toPriceOfferKey = (offerPrice, sequenceNumber) => {
   mustMatch(offerPrice, RatioShape);
@@ -108,7 +107,7 @@ export const toBidScalingComparator = rate => {
  * @param {Ratio} rate discount/markup rate expressed as a ratio IST/IST
  * @param {bigint} sequenceNumber
  * @returns {string} lexically sortable string in which highest price is first,
- *   ties will be broken by sequenceNumber of offer
+ *    ties will be broken by sequenceNumber of offer
  */
 export const toScaledRateOfferKey = (rate, sequenceNumber) => {
   mustMatch(rate, RatioShape);

package/src/auction/util.js

@@ -10,7 +10,7 @@ import { Far } from '@endo/marshal';
 /**
  * Constants for Auction State.
  *
- * @type {{ ACTIVE: 'active'; WAITING: 'waiting' }}
+ * @type {{ ACTIVE: 'active', WAITING: 'waiting' }}
  */
 export const AuctionState = {
   ACTIVE: 'active',
@@ -18,8 +18,8 @@ export const AuctionState = {
 };
 
 /**
- * @param {{ brand: Brand; value: Pattern }} numeratorAmountShape
- * @param {{ brand: Brand; value: Pattern }} denominatorAmountShape
+ * @param {{ brand: Brand, value: Pattern }} numeratorAmountShape
+ * @param {{ brand: Brand, value: Pattern }} denominatorAmountShape
  */
 export const makeBrandedRatioPattern = (
   numeratorAmountShape,
@@ -36,7 +36,7 @@ export const makeBrandedRatioPattern = (
  * @param {Ratio} currentPrice
  * @param {Ratio} oraclePrice
  * @returns {boolean} TRUE iff the discount(/markup) applied to the price is
- *   higher than the quote.
+ *          higher than the quote.
  */
 export const isScaledBidPriceHigher = (bidScaling, currentPrice, oraclePrice) =>
   ratioGTE(multiplyRatios(oraclePrice, bidScaling), currentPrice);