@agoric/inter-protocol 0.13.3 → 0.13.4-dev-800c2bb.0

package/src/auction/offerBook.js

@@ -0,0 +1,221 @@
+// book of offers to buy liquidating vaults with prices in terms of
+// discount/markup from the current oracle price.
+
+import { AmountMath } from '@agoric/ertp';
+import { M, mustMatch } from '@agoric/store';
+import { makeScalarBigMapStore, prepareExoClass } from '@agoric/vat-data';
+
+import {
+  toBidScalingComparator,
+  toPartialOfferKey,
+  toPriceOfferKey,
+  toScaledRateOfferKey,
+} from './sortedOffers.js';
+
+/** @typedef {import('@agoric/vat-data').Baggage} Baggage */
+
+// multiple offers might be provided at the same time (since the time
+// granularity is limited to blocks), so we increment a sequenceNumber with each
+// offer for uniqueness.
+let latestSequenceNumber = 0n;
+const nextSequenceNumber = () => {
+  latestSequenceNumber += 1n;
+  return latestSequenceNumber;
+};
+
+/**
+ * @typedef {{
+ * seat: ZCFSeat,
+ * wanted: Amount<'nat'>,
+ * seqNum: NatValue,
+ * received: Amount<'nat'>,
+ * } &  {exitAfterBuy: boolean} & ({ bidScaling: Pattern, price: undefined } | { bidScaling: undefined, price: Ratio})
+ * } BidderRecord
+ */
+
+const ScaledBidBookStateShape = harden({
+  bidScalingPattern: M.any(),
+  collateralBrand: M.any(),
+  records: M.any(),
+});
+
+/**
+ * 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.
+ *
+ * @param {Baggage} baggage
+ */
+export const prepareScaledBidBook = baggage =>
+  prepareExoClass(
+    baggage,
+    'scaledBidBook',
+    undefined,
+    /**
+     *
+     * @param {Pattern} bidScalingPattern
+     * @param {Brand} collateralBrand
+     */
+    (bidScalingPattern, collateralBrand) => ({
+      bidScalingPattern,
+      collateralBrand,
+      /** @type {MapStore<string, BidderRecord>} */
+      records: makeScalarBigMapStore('scaledBidRecords', { durable: true }),
+    }),
+    {
+      /**
+       * @param {ZCFSeat} seat
+       * @param {Ratio} bidScaling
+       * @param {Amount<'nat'>} wanted
+       * @param {boolean} exitAfterBuy
+       */
+      add(seat, bidScaling, wanted, exitAfterBuy) {
+        const { bidScalingPattern, collateralBrand, records } = this.state;
+        mustMatch(bidScaling, bidScalingPattern);
+
+        const seqNum = nextSequenceNumber();
+        const key = toScaledRateOfferKey(bidScaling, seqNum);
+        const empty = AmountMath.makeEmpty(collateralBrand);
+        /** @type {BidderRecord} */
+        const bidderRecord = {
+          bidScaling,
+          price: undefined,
+          received: empty,
+          seat,
+          seqNum,
+          wanted,
+          exitAfterBuy,
+        };
+        records.init(key, harden(bidderRecord));
+        return key;
+      },
+      /** @param {Ratio} bidScaling */
+      offersAbove(bidScaling) {
+        const { records } = this.state;
+        return [...records.entries(M.gte(toBidScalingComparator(bidScaling)))];
+      },
+      hasOrders() {
+        const { records } = this.state;
+        return records.getSize() > 0;
+      },
+      delete(key) {
+        const { records } = this.state;
+        records.delete(key);
+      },
+      updateReceived(key, sold) {
+        const { records } = this.state;
+        const oldRec = records.get(key);
+        records.set(
+          key,
+          harden({
+            ...oldRec,
+            received: AmountMath.add(oldRec.received, sold),
+          }),
+        );
+      },
+      exitAllSeats() {
+        const { records } = this.state;
+        for (const [key, { seat }] of records.entries()) {
+          if (!seat.hasExited()) {
+            seat.exit();
+            records.delete(key);
+          }
+        }
+      },
+    },
+    {
+      stateShape: ScaledBidBookStateShape,
+    },
+  );
+
+const PriceBookStateShape = harden({
+  priceRatioPattern: M.any(),
+  collateralBrand: M.any(),
+  records: M.any(),
+});
+
+/**
+ * Prices in this book are actual prices expressed in terms of bid amount
+ * and collateral amount.
+ *
+ * @param {Baggage} baggage
+ */
+export const preparePriceBook = baggage =>
+  prepareExoClass(
+    baggage,
+    'priceBook',
+    undefined,
+    /**
+     *
+     * @param {Pattern} priceRatioPattern
+     * @param {Brand} collateralBrand
+     */
+    (priceRatioPattern, collateralBrand) => ({
+      priceRatioPattern,
+      collateralBrand,
+      /** @type {MapStore<string, BidderRecord>} */
+      records: makeScalarBigMapStore('scaledBidRecords', { durable: true }),
+    }),
+    {
+      /**
+       * @param {ZCFSeat} seat
+       * @param {Ratio} price
+       * @param {Amount<'nat'>} wanted
+       * @param {boolean} exitAfterBuy
+       */
+      add(seat, price, wanted, exitAfterBuy) {
+        const { priceRatioPattern, collateralBrand, records } = this.state;
+        mustMatch(price, priceRatioPattern);
+
+        const seqNum = nextSequenceNumber();
+        const key = toPriceOfferKey(price, seqNum);
+        const empty = AmountMath.makeEmpty(collateralBrand);
+        /** @type {BidderRecord} */
+        const bidderRecord = {
+          bidScaling: undefined,
+          price,
+          received: empty,
+          seat,
+          seqNum,
+          wanted,
+          exitAfterBuy,
+        };
+        records.init(key, harden(bidderRecord));
+        return key;
+      },
+      offersAbove(price) {
+        const { records } = this.state;
+        return [...records.entries(M.gte(toPartialOfferKey(price)))];
+      },
+      hasOrders() {
+        const { records } = this.state;
+        return records.getSize() > 0;
+      },
+      delete(key) {
+        const { records } = this.state;
+        records.delete(key);
+      },
+      updateReceived(key, sold) {
+        const { records } = this.state;
+        const oldRec = records.get(key);
+        records.set(
+          key,
+          harden({
+            ...oldRec,
+            received: AmountMath.add(oldRec.received, sold),
+          }),
+        );
+      },
+      exitAllSeats() {
+        const { records } = this.state;
+        for (const [key, { seat }] of records.entries()) {
+          if (!seat.hasExited()) {
+            seat.exit();
+            records.delete(key);
+          }
+        }
+      },
+    },
+    {
+      stateShape: PriceBookStateShape,
+    },
+  );

package/src/auction/params.js

@@ -0,0 +1,174 @@
+import {
+  CONTRACT_ELECTORATE,
+  makeParamManager,
+  ParamTypes,
+} from '@agoric/governance';
+import { TimeMath, RelativeTimeRecordShape } from '@agoric/time';
+import { M } from '@agoric/store';
+
+/** @typedef {import('@agoric/governance/src/contractGovernance/typedParamManager.js').AsyncSpecTuple} AsyncSpecTuple */
+/** @typedef {import('@agoric/governance/src/contractGovernance/typedParamManager.js').SyncSpecTuple} SyncSpecTuple */
+
+// TODO duplicated with zoe/src/TypeGuards.js
+export const InvitationShape = M.remotable('Invitation');
+
+/**
+ * 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
+ * START_FREQUENCY has elapsed.
+ */
+export const START_FREQUENCY = 'StartFrequency';
+/** in seconds, how often to reduce the price */
+export const CLOCK_STEP = 'ClockStep';
+/** discount or markup for starting price in basis points. 9999 = 1bp discount */
+export const STARTING_RATE_BP = 'StartingRate';
+/** A limit below which the price will not be discounted. */
+export const LOWEST_RATE_BP = 'LowestRate';
+/** amount to reduce prices each time step in bp, as % of the start price */
+export const DISCOUNT_STEP_BP = 'DiscountStep';
+/**
+ * VaultManagers liquidate vaults at a frequency configured by START_FREQUENCY.
+ * Auctions start this long after the hour to give vaults time to finish.
+ */
+export const AUCTION_START_DELAY = 'AuctionStartDelay';
+
+// /////// used by VaultDirector /////////////////////
+// time before each auction that the prices are locked.
+export const PRICE_LOCK_PERIOD = 'PriceLockPeriod';
+
+export const auctioneerParamPattern = M.splitRecord({
+  [CONTRACT_ELECTORATE]: InvitationShape,
+  [START_FREQUENCY]: RelativeTimeRecordShape,
+  [CLOCK_STEP]: RelativeTimeRecordShape,
+  [STARTING_RATE_BP]: M.nat(),
+  [LOWEST_RATE_BP]: M.nat(),
+  [DISCOUNT_STEP_BP]: M.nat(),
+  [AUCTION_START_DELAY]: RelativeTimeRecordShape,
+  [PRICE_LOCK_PERIOD]: RelativeTimeRecordShape,
+});
+
+export const auctioneerParamTypes = harden({
+  [CONTRACT_ELECTORATE]: ParamTypes.INVITATION,
+  [START_FREQUENCY]: ParamTypes.RELATIVE_TIME,
+  [CLOCK_STEP]: ParamTypes.RELATIVE_TIME,
+  [STARTING_RATE_BP]: ParamTypes.NAT,
+  [LOWEST_RATE_BP]: ParamTypes.NAT,
+  [DISCOUNT_STEP_BP]: ParamTypes.NAT,
+  [AUCTION_START_DELAY]: ParamTypes.RELATIVE_TIME,
+  [PRICE_LOCK_PERIOD]: ParamTypes.RELATIVE_TIME,
+});
+
+/**
+ * @typedef {object} AuctionParams
+ * @property {Amount<'set'>} ElectorateInvitationAmount
+ * @property {RelativeTime} StartFrequency
+ * @property {RelativeTime} ClockStep
+ * @property {bigint} StartingRate
+ * @property {bigint} LowestRate
+ * @property {bigint} DiscountStep
+ * @property {RelativeTime} AuctionStartDelay
+ * @property {RelativeTime} PriceLockPeriod
+ * @property {import('@agoric/time/src/types').TimerBrand} TimerBrand
+ */
+
+/**
+ * @param {AuctionParams} initial
+ */
+export const makeAuctioneerParams = ({
+  ElectorateInvitationAmount,
+  StartFrequency,
+  ClockStep,
+  LowestRate,
+  StartingRate,
+  DiscountStep,
+  AuctionStartDelay,
+  PriceLockPeriod,
+  TimerBrand,
+}) => {
+  return harden({
+    [CONTRACT_ELECTORATE]: {
+      type: ParamTypes.INVITATION,
+      value: ElectorateInvitationAmount,
+    },
+    [START_FREQUENCY]: {
+      type: ParamTypes.RELATIVE_TIME,
+      value: TimeMath.coerceRelativeTimeRecord(StartFrequency, TimerBrand),
+    },
+    [CLOCK_STEP]: {
+      type: ParamTypes.RELATIVE_TIME,
+      value: TimeMath.coerceRelativeTimeRecord(ClockStep, TimerBrand),
+    },
+    [AUCTION_START_DELAY]: {
+      type: ParamTypes.RELATIVE_TIME,
+      value: TimeMath.coerceRelativeTimeRecord(AuctionStartDelay, TimerBrand),
+    },
+    [PRICE_LOCK_PERIOD]: {
+      type: ParamTypes.RELATIVE_TIME,
+      value: TimeMath.coerceRelativeTimeRecord(PriceLockPeriod, TimerBrand),
+    },
+    [STARTING_RATE_BP]: { type: ParamTypes.NAT, value: StartingRate },
+    [LOWEST_RATE_BP]: { type: ParamTypes.NAT, value: LowestRate },
+    [DISCOUNT_STEP_BP]: { type: ParamTypes.NAT, value: DiscountStep },
+  });
+};
+harden(makeAuctioneerParams);
+
+/**
+ * @param {import('@agoric/notifier').StoredPublisherKit<GovernanceSubscriptionState>} publisherKit
+ * @param {ZCF} zcf
+ * @param {AuctionParams} initial
+ */
+export const makeAuctioneerParamManager = (publisherKit, zcf, initial) => {
+  return makeParamManager(
+    publisherKit,
+    {
+      [CONTRACT_ELECTORATE]: [
+        ParamTypes.INVITATION,
+        initial[CONTRACT_ELECTORATE],
+      ],
+      [START_FREQUENCY]: [ParamTypes.RELATIVE_TIME, initial[START_FREQUENCY]],
+      [CLOCK_STEP]: [ParamTypes.RELATIVE_TIME, initial[CLOCK_STEP]],
+      [STARTING_RATE_BP]: [ParamTypes.NAT, initial[STARTING_RATE_BP]],
+      [LOWEST_RATE_BP]: [ParamTypes.NAT, initial[LOWEST_RATE_BP]],
+      [DISCOUNT_STEP_BP]: [ParamTypes.NAT, initial[DISCOUNT_STEP_BP]],
+      [AUCTION_START_DELAY]: [
+        ParamTypes.RELATIVE_TIME,
+        initial[AUCTION_START_DELAY],
+      ],
+      [PRICE_LOCK_PERIOD]: [
+        ParamTypes.RELATIVE_TIME,
+        initial[PRICE_LOCK_PERIOD],
+      ],
+    },
+    zcf,
+  );
+};
+harden(makeAuctioneerParamManager);
+
+/**
+ * @param {{storageNode: ERef<StorageNode>, marshaller: ERef<Marshaller>}} caps
+ * @param {ERef<Timer>} timer
+ * @param {ERef<PriceAuthority>} priceAuthority
+ * @param {ERef<AssetReservePublicFacet>} reservePublicFacet
+ * @param {AuctionParams} params
+ */
+export const makeGovernedTerms = (
+  { storageNode: _storageNode, marshaller: _marshaller },
+  timer,
+  priceAuthority,
+  reservePublicFacet,
+  params,
+) => {
+  // XXX  use storageNode and Marshaller
+  return harden({
+    priceAuthority,
+    reservePublicFacet,
+    timerService: timer,
+    governedParams: makeAuctioneerParams(params),
+  });
+};
+harden(makeGovernedTerms);
+
+/** @typedef {ReturnType<typeof makeAuctioneerParamManager>} AuctionParamManager */

package/src/auction/scheduleMath.js

@@ -0,0 +1,167 @@
+// @jessie-check
+
+import { TimeMath } from '@agoric/time';
+import { natSafeMath } from '@agoric/zoe/src/contractSupport/index.js';
+import { assertAllDefined, makeTracer } from '@agoric/internal';
+
+const { subtract, multiply, floorDivide } = natSafeMath;
+const { Fail } = assert;
+
+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 {Timestamp} 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 {import('@agoric/time/src/types').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);