@agoric/inter-protocol 0.17.0 → 0.17.1-upgrade-23-dev-bd79330.0.bd79330

package/src/auction/scheduleMath.js

@@ -1,169 +0,0 @@
-// @jessie-check
-
-import { Fail } from '@endo/errors';
-import { TimeMath } from '@agoric/time';
-import { natSafeMath } from '@agoric/zoe/src/contractSupport/index.js';
-import { assertAllDefined, makeTracer } from '@agoric/internal';
-
-/** @import {TimestampRecord} from '@agoric/time'; */
-
-const { subtract, multiply, floorDivide } = natSafeMath;
-
-const trace = makeTracer('SMath', true);
-
-const subtract1 = relTime =>
-  TimeMath.subtractRelRel(
-    relTime,
-    TimeMath.coerceRelativeTimeRecord(1n, relTime.timerBrand),
-  );
-
-/**
- * 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%)
- * 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.
- *
- * Therefore, the duration is `(StartingRate - LowestRate) / DiscountStep *
- * ClockStep`.
- *
- * 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).
- *
- * @param {Awaited<import('./params.js').AuctionParamManager>} params
- * @param {TimestampRecord} baseTime
- * @returns {import('./scheduler.js').Schedule}
- */
-export const computeRoundTiming = (params, baseTime) => {
-  const freq = params.getStartFrequency();
-  const clockStep = params.getClockStep();
-  const startingRate = params.getStartingRate();
-  const discountStep = params.getDiscountStep();
-  const lockPeriod = params.getPriceLockPeriod();
-  const lowestRate = params.getLowestRate();
-  const startDelay = params.getAuctionStartDelay();
-
-  TimeMath.compareRel(freq, startDelay) > 0 ||
-    Fail`startFrequency must exceed startDelay, ${freq}, ${startDelay}`;
-  TimeMath.compareRel(freq, lockPeriod) > 0 ||
-    Fail`startFrequency must exceed lock period, ${freq}, ${lockPeriod}`;
-  TimeMath.compareRel(freq, clockStep) >= 0 ||
-    Fail`clockStep ${TimeMath.relValue(
-      clockStep,
-    )} must be shorter than startFrequency ${TimeMath.relValue(
-      freq,
-    )} to allow at least one step down`;
-
-  startingRate > lowestRate ||
-    Fail`startingRate ${startingRate} must be more than lowest: ${lowestRate}`;
-
-  const rateChange = subtract(startingRate, lowestRate);
-  const requestedSteps = floorDivide(rateChange, discountStep);
-  requestedSteps > 0n ||
-    Fail`discountStep ${discountStep} too large for requested rates`;
-
-  // How many steps fit in a full auction? We want the biggest integer for which
-  // steps * discountStep <= startingRate - lowestRate, and
-  // steps * clockStep < freq
-  const maxRateSteps = floorDivide(startingRate - lowestRate, discountStep);
-  const maxTimeSteps = TimeMath.divideRelRel(subtract1(freq), clockStep);
-  const steps = maxRateSteps < maxTimeSteps ? maxRateSteps : maxTimeSteps;
-
-  const duration = TimeMath.multiplyRelNat(clockStep, steps);
-  steps > 0n ||
-    Fail`clockStep ${clockStep} too long for auction duration ${duration}`;
-  const endRate = subtract(startingRate, multiply(steps, discountStep));
-
-  // Use a duration that exactly matches the last step completing (no remainder)
-  const actualDuration = TimeMath.multiplyRelNat(clockStep, steps);
-  // computed start is `startDelay + baseTime + freq - (baseTime mod freq)`.
-  // That is, if there are hourly starts, we add an hour to the time, and
-  // subtract baseTime mod freq. Then we add the delay.
-  /** @type {TimestampRecord} */
-  const startTime = TimeMath.addAbsRel(
-    TimeMath.addAbsRel(
-      baseTime,
-      TimeMath.subtractRelRel(freq, TimeMath.modAbsRel(baseTime, freq)),
-    ),
-    startDelay,
-  );
-  const endTime = TimeMath.addAbsRel(startTime, actualDuration);
-  const lockTime = TimeMath.subtractAbsRel(startTime, lockPeriod);
-
-  /** @type {import('./scheduler.js').Schedule} */
-  const next = {
-    startTime,
-    endTime,
-    steps,
-    endRate,
-    startDelay,
-    clockStep,
-    lockTime,
-  };
-  return harden(next);
-};
-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.
- *
- * @param {import('./scheduler.js').Schedule | null} liveSchedule
- * @param {import('./scheduler.js').Schedule | null} nextSchedule
- * @param {Timestamp} now
- * @returns {Timestamp | null}
- */
-export const nextDescendingStepTime = (liveSchedule, nextSchedule, now) => {
-  if (!liveSchedule) {
-    return nextSchedule?.startTime || null;
-  }
-
-  const { startTime, endTime, clockStep } = liveSchedule;
-  trace('calc', startTime, now);
-  if (TimeMath.compareAbs(startTime, now) > 0) {
-    return startTime;
-  }
-
-  const elapsed = TimeMath.subtractAbsAbs(now, startTime);
-  const sinceLastStep = TimeMath.modRelRel(elapsed, clockStep);
-  const lastStepStart = TimeMath.subtractAbsRel(now, sinceLastStep);
-  const expectedNext = TimeMath.addAbsRel(lastStepStart, clockStep);
-
-  if (TimeMath.compareAbs(expectedNext, endTime) > 0) {
-    return nextSchedule?.startTime || null;
-  }
-
-  return expectedNext;
-};
-harden(nextDescendingStepTime);
-
-/**
- * @param {Timestamp} time
- * @param {import('./scheduler.js').Schedule} schedule
- * @returns {'before' | 'during' | 'endExactly' | 'after'}
- */
-export const timeVsSchedule = (time, schedule) => {
-  const { startTime, endTime } = schedule;
-  assertAllDefined({ startTime, endTime });
-
-  if (TimeMath.compareAbs(time, schedule.startTime) < 0) {
-    return 'before';
-  }
-  if (TimeMath.compareAbs(time, schedule.endTime) < 0) {
-    return 'during';
-  }
-  if (TimeMath.compareAbs(time, schedule.endTime) === 0) {
-    return 'endExactly';
-  }
-
-  return 'after';
-};
-harden(timeVsSchedule);

package/src/auction/scheduler.d.ts

@@ -1,50 +0,0 @@
-export function makeScheduler(auctionDriver: AuctionDriver, timer: import("@agoric/time").TimerService, params: Awaited<import("./params.js").AuctionParamManager>, timerBrand: import("@agoric/time").TimerBrand, scheduleRecorder: import("@agoric/zoe/src/contractSupport/recorder.js").Recorder<ScheduleNotification>, paramUpdateSubscription: StoredSubscription<GovernanceSubscriptionState>): Promise<{
-    getSchedule: () => {
-        liveAuctionSchedule: Schedule | null;
-        nextAuctionSchedule: Schedule | null;
-    };
-    getAuctionState: () => AuctionState;
-} & RemotableObject<`Alleged: ${string}`> & import("@endo/eventual-send").RemotableBrand<{}, {
-    getSchedule: () => {
-        liveAuctionSchedule: Schedule | null;
-        nextAuctionSchedule: Schedule | null;
-    };
-    getAuctionState: () => AuctionState;
-}>>;
-export type AuctionDriver = {
-    reducePriceAndTrade: () => void;
-    finalize: () => void;
-    startRound: () => void;
-    capturePrices: () => void;
-};
-export type ScheduleNotification = {
-    /**
-     * start time of current auction if
-     * auction is active
-     */
-    activeStartTime: Timestamp | null;
-    /**
-     * start time of next auction
-     */
-    nextStartTime: Timestamp | null;
-    /**
-     * when the next descending
-     * step will take place
-     */
-    nextDescendingStepTime: Timestamp | null;
-};
-export type Schedule = {
-    startTime: import("@agoric/time").TimestampRecord;
-    endTime: import("@agoric/time").TimestampRecord;
-    steps: NatValue;
-    endRate: NatValue;
-    startDelay: RelativeTime;
-    clockStep: RelativeTime;
-    lockTime?: Timestamp | undefined;
-};
-export type FullSchedule = {
-    nextAuctionSchedule: Schedule | null;
-    liveAuctionSchedule: Schedule | null;
-};
-import { AuctionState } from './util.js';
-//# sourceMappingURL=scheduler.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["scheduler.js"],"names":[],"mappings":"AA8EO,6CAPI,aAAa,SACb,OAAO,cAAc,EAAE,YAAY,UACnC,OAAO,CAAC,OAAO,aAAa,EAAE,mBAAmB,CAAC,cAClD,OAAO,cAAc,EAAE,UAAU,oBACjC,OAAO,6CAA6C,EAAE,QAAQ,CAAC,oBAAoB,CAAC,2BACpF,kBAAkB,CAAC,2BAA2B,CAAC;;;;;;;;;;;;IA0RzD;;yBA3Ta,MAAM,IAAI;cACV,MAAM,IAAI;gBACV,MAAM,IAAI;mBACV,MAAM,IAAI;;;;;;;qBAKV,SAAS,GAAG,IAAI;;;;mBAEhB,SAAS,GAAG,IAAI;;;;;4BAChB,SAAS,GAAG,IAAI;;;eAoThB,OAAO,cAAc,EAAE,eAAe;aACtC,OAAO,cAAc,EAAE,eAAe;WACtC,QAAQ;aACR,QAAQ;gBACR,YAAY;eACZ,YAAY;;;;yBAMZ,QAAQ,GAAG,IAAI;yBACf,QAAQ,GAAG,IAAI;;6BA/WsB,WAAW"}

package/src/auction/scheduler.js

@@ -1,376 +0,0 @@
-import { X, Fail, q, makeError } from '@endo/errors';
-import { E } from '@endo/eventual-send';
-import { Far } from '@endo/marshal';
-import { TimeMath } from '@agoric/time';
-import { makeTracer } from '@agoric/internal';
-import { observeIteration, subscribeEach } from '@agoric/notifier';
-
-import { AuctionState, makeCancelTokenMaker } from './util.js';
-import {
-  computeRoundTiming,
-  nextDescendingStepTime,
-  timeVsSchedule,
-} from './scheduleMath.js';
-
-const trace = makeTracer('SCHED', true);
-
-// If the startAuction wakeup is no more than 5 minutes late, go ahead with it.
-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.
- *
- *   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.
- */
-
-const makeCancelToken = makeCancelTokenMaker('scheduler');
-
-/**
- * @typedef {object} AuctionDriver
- * @property {() => void} reducePriceAndTrade
- * @property {() => void} finalize
- * @property {() => void} startRound
- * @property {() => void} capturePrices
- */
-
-/**
- * @typedef {object} ScheduleNotification
- * @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
- */
-
-const safelyComputeRoundTiming = (params, baseTime) => {
-  try {
-    return computeRoundTiming(params, baseTime);
-  } catch (e) {
-    console.error('🚨 No Next Auction', e);
-    return null;
-  }
-};
-
-const nominalStartTime = nextSchedule =>
-  TimeMath.subtractAbsRel(nextSchedule.startTime, nextSchedule.startDelay);
-
-/**
- * @param {AuctionDriver} auctionDriver
- * @param {import('@agoric/time').TimerService} timer
- * @param {Awaited<import('./params.js').AuctionParamManager>} params
- * @param {import('@agoric/time').TimerBrand} timerBrand
- * @param {import('@agoric/zoe/src/contractSupport/recorder.js').Recorder<ScheduleNotification>} scheduleRecorder
- * @param {StoredSubscription<GovernanceSubscriptionState>} paramUpdateSubscription
- */
-export const makeScheduler = async (
-  auctionDriver,
-  timer,
-  params,
-  timerBrand,
-  scheduleRecorder,
-  paramUpdateSubscription,
-) => {
-  /**
-   * live version is defined when an auction is active.
-   *
-   * @type {Schedule | null}
-   */
-  let liveSchedule = null;
-
-  /** @returns {Promise<{ now: Timestamp; nextSchedule: Schedule | null }>} */
-  const initializeNextSchedule = async () => {
-    return E.when(
-      // XXX manualTimer returns a bigint, not a timeRecord.
-      E(timer).getCurrentTimestamp(),
-      now => {
-        const nextSchedule = safelyComputeRoundTiming(
-          params,
-          TimeMath.coerceTimestampRecord(now, timerBrand),
-        );
-        return { now, nextSchedule };
-      },
-    );
-  };
-  let { now, nextSchedule } = await initializeNextSchedule();
-  const setTimeMonotonically = time => {
-    TimeMath.compareAbs(time, now) >= 0 || Fail`Time only moves forward`;
-    now = time;
-  };
-
-  const stepCancelToken = makeCancelToken();
-
-  /** @type {AuctionState} */
-  let auctionState = AuctionState.WAITING;
-
-  /**
-   * Publish the schedule. To be called after clockTick() (which processes a
-   * descending step) or when the next round is scheduled.
-   */
-  const publishSchedule = () => {
-    const sched = harden({
-      activeStartTime: liveSchedule?.startTime || null,
-      nextStartTime: nextSchedule?.startTime || null,
-      nextDescendingStepTime: nextDescendingStepTime(
-        liveSchedule,
-        nextSchedule,
-        now,
-      ),
-    });
-    return scheduleRecorder.write(sched);
-  };
-
-  /**
-   * @param {Schedule | null} schedule
-   * @returns {void}
-   */
-  const clockTick = schedule => {
-    trace('clockTick', schedule?.startTime, now);
-    if (!schedule) {
-      return;
-    }
-
-    /** @type {() => void} */
-    const finishAuctionRound = () => {
-      auctionState = AuctionState.WAITING;
-      auctionDriver.finalize();
-
-      if (!nextSchedule) {
-        console.error(
-          '🛠️ finishAuctionRound without scheduling the next; repair with new auctioneer params',
-        );
-      }
-
-      liveSchedule = null;
-
-      // Async because a remote call. In rare event of failure, wakeup is robust.
-      void E(timer).cancel(stepCancelToken);
-    };
-
-    const advanceRound = () => {
-      if (auctionState === AuctionState.ACTIVE) {
-        auctionDriver.reducePriceAndTrade();
-      } else {
-        auctionState = AuctionState.ACTIVE;
-        try {
-          auctionDriver.startRound();
-          // This has been observed to fail because prices hadn't been locked.
-          // This may be an issue about timing during chain start-up.
-        } catch (err) {
-          console.error(
-            'Unable to start auction cleanly. skipping this auction round.',
-            err,
-          );
-        }
-      }
-    };
-
-    switch (timeVsSchedule(now, schedule)) {
-      case 'before':
-        break;
-      case 'during':
-        advanceRound();
-        break;
-      case 'endExactly':
-        // do both the "during" and "after" behaviors
-        advanceRound();
-        finishAuctionRound();
-        break;
-      case 'after':
-        finishAuctionRound();
-        break;
-      default:
-        Fail`invalid case`;
-    }
-
-    void publishSchedule();
-  };
-
-  // set wakeups for the steps of this round
-  const scheduleDescendingSteps = () => {
-    if (!liveSchedule) {
-      console.error('🚨 scheduleDescendingSteps called with no liveSchedule');
-      return;
-    }
-
-    const { startTime } = liveSchedule;
-    trace('START ', startTime);
-
-    const delayFromNow =
-      TimeMath.compareAbs(startTime, now) > 0
-        ? TimeMath.subtractAbsAbs(startTime, now)
-        : TimeMath.subtractAbsAbs(startTime, startTime);
-
-    trace('scheduleDescendingSteps repeating', now, delayFromNow, startTime);
-
-    void E(timer).repeatAfter(
-      delayFromNow,
-      liveSchedule.clockStep,
-      Far('PriceStepWaker', {
-        wake(time) {
-          try {
-            setTimeMonotonically(time);
-            trace('wake step', now);
-            clockTick(liveSchedule);
-          } catch (e) {
-            console.error(`⚠️ Auction threw ${e}. Caught in PriceStepWaker.`);
-          }
-        },
-      }),
-      stepCancelToken,
-    );
-  };
-
-  // schedule a wakeup for the next round
-  const scheduleNextRound = start => {
-    trace(`nextRound`, start);
-    void E(timer).setWakeup(
-      start,
-      Far('SchedulerWaker', {
-        wake(time) {
-          try {
-            setTimeMonotonically(time);
-            auctionDriver.capturePrices();
-            return startAuction();
-          } catch (e) {
-            console.error(`⚠️ Auction threw ${e}. Caught in SchedulerWaker.`);
-          }
-        },
-      }),
-    );
-    void publishSchedule();
-  };
-
-  const relativeTime = t => TimeMath.coerceRelativeTimeRecord(t, timerBrand);
-
-  const startAuction = async () => {
-    !liveSchedule || Fail`can't start an auction round while one is active`;
-
-    if (!nextSchedule) {
-      console.error(
-        makeError(X`tried to start auction when none is scheduled`),
-      );
-      return;
-    }
-
-    // The clock tick may have arrived too late to trigger the next scheduled
-    // round, for example because of a chain halt.  When this happens the oracle
-    // quote may out of date and so must be ignored. Recover by returning
-    // deposits and scheduling the next round. If it's only a little late,
-    // continue with auction, just starting late.
-    const nominalStart = nominalStartTime(nextSchedule);
-    if (TimeMath.compareAbs(now, nominalStart) > 0) {
-      const late = TimeMath.subtractAbsAbs(now, nominalStart);
-      const maxLate = relativeTime(MAX_LATE_TICK);
-
-      if (TimeMath.compareRel(late, maxLate) > 0) {
-        console.warn(
-          `Auction time jumped to ${q(now)} before next scheduled start ${q(
-            nextSchedule.startTime,
-          )}. Skipping that round.`,
-        );
-        nextSchedule = safelyComputeRoundTiming(params, now);
-      } else {
-        console.warn(`Auction started late by ${q(late)}. Starting ${q(now)}`);
-      }
-    }
-
-    if (!nextSchedule) {
-      // nothing new to schedule
-      return;
-    }
-    // activate the nextSchedule as the live one
-    // (read here and in function calls below)
-    liveSchedule = nextSchedule;
-    scheduleDescendingSteps();
-    nextSchedule = safelyComputeRoundTiming(
-      params,
-      TimeMath.addAbsRel(liveSchedule.endTime, relativeTime(1n)),
-    );
-
-    if (nextSchedule) {
-      scheduleNextRound(nominalStartTime(nextSchedule));
-    } else {
-      console.warn(
-        'no nextSchedule so cannot schedule next round or price capture',
-      );
-    }
-  };
-
-  // initial setting:  firstStart is startDelay before next's startTime
-  const startSchedulingFromScratch = () => {
-    trace('startSchedulingFromScratch');
-    if (nextSchedule) {
-      scheduleNextRound(nominalStartTime(nextSchedule));
-    }
-  };
-  startSchedulingFromScratch();
-
-  // when auction parameters change, schedule a next auction if one isn't
-  // already scheduled.
-  // NB: what is already scheduled (live or next) is unaffected by param changes
-  void observeIteration(
-    subscribeEach(paramUpdateSubscription),
-    harden({
-      // 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();
-        }
-      },
-    }),
-  );
-
-  return Far('scheduler', {
-    getSchedule: () =>
-      harden({
-        liveAuctionSchedule: liveSchedule,
-        nextAuctionSchedule: nextSchedule,
-      }),
-    getAuctionState: () => auctionState,
-  });
-};
-
-/**
- * @typedef {object} Schedule
- * @property {import('@agoric/time').TimestampRecord} startTime
- * @property {import('@agoric/time').TimestampRecord} endTime
- * @property {NatValue} steps
- * @property {NatValue} endRate
- * @property {RelativeTime} startDelay
- * @property {RelativeTime} clockStep
- * @property {Timestamp} [lockTime]
- */
-
-/**
- * @typedef {object} FullSchedule
- * @property {Schedule | null} nextAuctionSchedule
- * @property {Schedule | null} liveAuctionSchedule
- */

package/src/auction/sortedOffers.d.ts

@@ -1,8 +0,0 @@
-export function toPartialOfferKey(offerPrice: Ratio): string;
-export function toPriceOfferKey(offerPrice: Ratio, sequenceNumber: bigint): string;
-export function fromPriceOfferKey(key: string, numBrand: Brand<"nat">, denomBrand: Brand<"nat">, useDecimals: number): [normalizedPrice: Ratio, sequenceNumber: bigint];
-/** @type {(rate: Ratio) => string} */
-export const toBidScalingComparator: (rate: Ratio) => string;
-export function toScaledRateOfferKey(rate: Ratio, sequenceNumber: bigint): string;
-export function fromScaledRateOfferKey(key: string, brand: Brand, useDecimals: number): [normalizedPrice: Ratio, sequenceNumber: bigint];
-//# sourceMappingURL=sortedOffers.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"sortedOffers.d.ts","sourceRoot":"","sources":["sortedOffers.js"],"names":[],"mappings":"AA6BO,8CAFI,KAAK,UAMf;AAUM,4CALI,KAAK,kBACL,MAAM,GACJ,MAAM,CAWlB;AAqCM,uCANI,MAAM,YACN,KAAK,CAAC,KAAK,CAAC,cACZ,KAAK,CAAC,KAAK,CAAC,eACZ,MAAM,GACJ,CAAC,eAAe,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,CAAC,CAS5D;AAED,sCAAsC;AACtC,qCADW,CAAC,IAAI,EAAE,KAAK,KAAK,MAAM,CAKhC;AAUK,2CALI,KAAK,kBACL,MAAM,GACJ,MAAM,CAWlB;AAUM,4CALI,MAAM,SACN,KAAK,eACL,MAAM,GACJ,CAAC,eAAe,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,CAAC,CAQ5D"}