feat(auction): add an auctioneer to manage vault liquiditation

Separate pieces include a scheduler that manages the phases of an
auction, the AuctionBook that holds onto offers to buy, and the
auctioneer, which accepts good for sale and has the APIs. Params are
managed via governance. The classes are not durable.

This is DRAFT, for early review.

The changes to VaultFactory to make use of this approach to
liquidation rather than the AMM are in a separate PR, which will be
available before this PR is finalized.

closes: #6992

packages/governance/src/constants.js

@@ -15,6 +15,9 @@ export const ParamTypes = /** @type {const} */ ({
   RATIO: 'ratio',
   STRING: 'string',
   PASSABLE_RECORD: 'record',
+  TIMER_SERVICE: 'timerService',
+  TIMESTAMP: 'timestamp',
+  RELATIVE_TIME: 'relativeTime',
   UNKNOWN: 'unknown',
 });
 

packages/governance/src/contractGovernance/assertions.js

@@ -41,9 +41,32 @@ const makeAssertBrandedRatio = (name, modelRatio) => {
 };
 harden(makeAssertBrandedRatio);
 
+const assertRelativeTime = value => {
+  isRemotable(value.timerBrand) || Fail`relativeTime must have a brand`;
+  typeof value.relValue === 'bigint' || Fail`must have a relValue field`;
+};
+harden(assertRelativeTime);
+
+const assertTimestamp = value => {
+  isRemotable(value.timerBrand) || Fail`timestamp must have a brand`;
+  typeof value.absValue === 'bigint' || Fail`must have an absValue field`;
+};
+harden(assertTimestamp);
+
+const makeAssertTimerService = name => {
+  return timerService => {
+    typeof timerService === 'object' ||
+      Fail`value for ${name} must be a TimerService, was ${timerService}`;
+  };
+};
+harden(makeAssertTimerService);
+
 export {
   makeLooksLikeBrand,
   makeAssertInstallation,
   makeAssertInstance,
   makeAssertBrandedRatio,
+  assertRelativeTime,
+  assertTimestamp,
+  makeAssertTimerService,
 };

packages/governance/src/contractGovernance/paramManager.js

@@ -8,10 +8,13 @@ import { assertAllDefined } from '@agoric/internal';
 import { ParamTypes } from '../constants.js';
 
 import {
+  assertTimestamp,
+  assertRelativeTime,
   makeAssertBrandedRatio,
   makeAssertInstallation,
   makeAssertInstance,
   makeLooksLikeBrand,
+  makeAssertTimerService,
 } from './assertions.js';
 import { CONTRACT_ELECTORATE } from './governParam.js';
 
@@ -44,6 +47,9 @@ const assertElectorateMatches = (paramManager, governedParams) => {
  * @property {(name: string, value: Ratio) => ParamManagerBuilder} addRatio
  * @property {(name: string, value: import('@endo/marshal').CopyRecord<unknown>) => ParamManagerBuilder} addRecord
  * @property {(name: string, value: string) => ParamManagerBuilder} addString
+ * @property {(name: string, value: import('@agoric/time/src/types').TimerService) => ParamManagerBuilder} addTimerService
+ * @property {(name: string, value: import('@agoric/time/src/types').Timestamp) => ParamManagerBuilder} addTimestamp
+ * @property {(name: string, value: import('@agoric/time/src/types').RelativeTime) => ParamManagerBuilder} addRelativeTime
  * @property {(name: string, value: any) => ParamManagerBuilder} addUnknown
  * @property {() => AnyParamManager} build
  */
@@ -184,6 +190,25 @@ const makeParamManagerBuilder = (publisherKit, zoe) => {
     return builder;
   };
 
+  /** @type {(name: string, value: import('@agoric/time/src/types').TimerService, builder: ParamManagerBuilder) => ParamManagerBuilder} */
+  const addTimerService = (name, value, builder) => {
+    const assertTimerService = makeAssertTimerService(name);
+    buildCopyParam(name, value, assertTimerService, ParamTypes.TIMER_SERVICE);
+    return builder;
+  };
+
+  /** @type {(name: string, value: import('@agoric/time/src/types').Timestamp, builder: ParamManagerBuilder) => ParamManagerBuilder} */
+  const addTimestamp = (name, value, builder) => {
+    buildCopyParam(name, value, assertTimestamp, ParamTypes.TIMESTAMP);
+    return builder;
+  };
+
+  /** @type {(name: string, value: import('@agoric/time/src/types').RelativeTime, builder: ParamManagerBuilder) => ParamManagerBuilder} */
+  const addRelativeTime = (name, value, builder) => {
+    buildCopyParam(name, value, assertRelativeTime, ParamTypes.RELATIVE_TIME);
+    return builder;
+  };
+
   /** @type {(name: string, value: any, builder: ParamManagerBuilder) => ParamManagerBuilder} */
   const addUnknown = (name, value, builder) => {
     const assertUnknown = _v => true;
@@ -356,6 +381,9 @@ const makeParamManagerBuilder = (publisherKit, zoe) => {
       getRatio: name => getTypedParam(ParamTypes.RATIO, name),
       getRecord: name => getTypedParam(ParamTypes.PASSABLE_RECORD, name),
       getString: name => getTypedParam(ParamTypes.STRING, name),
+      getTimerService: name => getTypedParam(ParamTypes.TIMER_SERVICE, name),
+      getTimestamp: name => getTypedParam(ParamTypes.TIMESTAMP, name),
+      getRelativeTime: name => getTypedParam(ParamTypes.RELATIVE_TIME, name),
       getUnknown: name => getTypedParam(ParamTypes.UNKNOWN, name),
       getVisibleValue,
       getInternalParamValue,
@@ -379,6 +407,9 @@ const makeParamManagerBuilder = (publisherKit, zoe) => {
     addRatio: (n, v) => addRatio(n, v, builder),
     addRecord: (n, v) => addRecord(n, v, builder),
     addString: (n, v) => addString(n, v, builder),
+    addTimerService: (n, v) => addTimerService(n, v, builder),
+    addRelativeTime: (n, v) => addRelativeTime(n, v, builder),
+    addTimestamp: (n, v) => addTimestamp(n, v, builder),
     build,
   };
   return builder;

packages/governance/src/contractGovernance/typedParamManager.js

@@ -66,6 +66,8 @@ const isAsync = {
  * | ST<'nat'>
  * | ST<'ratio'>
  * | ST<'string'>
+ * | ST<'timestamp'>
+ * | ST<'relativeTime'>
  * | ST<'unknown'>} SyncSpecTuple
  *
  * @typedef {['invitation', Invitation]} AsyncSpecTuple

packages/governance/src/contractHelper.js

@@ -4,6 +4,11 @@ import { getMethodNames, objectMap } from '@agoric/internal';
 import { ignoreContext } from '@agoric/vat-data';
 import { keyEQ, M } from '@agoric/store';
 import { AmountShape, BrandShape } from '@agoric/ertp';
+import {
+  RelativeTimeShape,
+  TimestampShape,
+  TimerServiceShape,
+} from '@agoric/time';
 import { assertElectorateMatches } from './contractGovernance/paramManager.js';
 import { makeParamManagerFromTerms } from './contractGovernance/typedParamManager.js';
 
@@ -23,6 +28,9 @@ const publicMixinAPI = harden({
   getNat: M.call().returns(M.bigint()),
   getRatio: M.call().returns(M.record()),
   getString: M.call().returns(M.string()),
+  getTimerService: M.call().returns(TimerServiceShape),
+  getTimestamp: M.call().returns(TimestampShape),
+  getRelativeTime: M.call().returns(RelativeTimeShape),
   getUnknown: M.call().returns(M.any()),
 });
 
@@ -51,6 +59,9 @@ const facetHelpers = (zcf, paramManager) => {
     getNat: paramManager.getNat,
     getRatio: paramManager.getRatio,
     getString: paramManager.getString,
+    getTimerService: paramManager.getTimerService,
+    getTimestamp: paramManager.getTimestamp,
+    getRelativeTime: paramManager.getRelativeTime,
     getUnknown: paramManager.getUnknown,
   };
 

packages/governance/src/types-ambient.js

@@ -427,6 +427,9 @@
  * @property {(name: string) => bigint} getNat
  * @property {(name: string) => Ratio} getRatio
  * @property {(name: string) => string} getString
+ * @property {(name: string) => import('@agoric/time/src/types').TimerService} getTimerService
+ * @property {(name: string) => import('@agoric/time/src/types').Timestamp} getTimestamp
+ * @property {(name: string) => import('@agoric/time/src/types').RelativeTime} getRelativeTime
  * @property {(name: string) => any} getUnknown
  * @property {(name: string, proposedValue: ParamValue) => ParamValue} getVisibleValue - for
  *   most types, the visible value is the same as proposedValue. For Invitations

packages/inter-protocol/scripts/add-collateral-core.js

@@ -72,6 +72,18 @@ export const psmGovernanceBuilder = async ({
           psm: publishRef(
             install('../src/psm/psm.js', '../bundles/bundle-psm.js'),
           ),
+          vaults: publishRef(
+            install(
+              '../src/vaultFactory/vaultFactory.js',
+              '../bundles/bundle-vaults.js',
+            ),
+          ),
+          auction: publishRef(
+            install(
+              '../src/auction/auctioneer.js',
+              '../bundles/bundle-auction.js',
+            ),
+          ),
           econCommitteeCharter: publishRef(
             install(
               '../src/econCommitteeCharter.js',

packages/inter-protocol/scripts/deploy-contracts.js

@@ -15,6 +15,7 @@ const contractRefs = [
   '../bundles/bundle-liquidateMinimum.js',
   '../bundles/bundle-reserve.js',
   '../bundles/bundle-psm.js',
+  '../bundles/bundle-auction.js',
   '../../vats/bundles/bundle-mintHolder.js',
 ];
 const contractRoots = contractRefs.map(ref =>

packages/inter-protocol/scripts/init-core.js

@@ -44,6 +44,7 @@ const installKeyGroups = {
       '../src/interchainPool.js',
       '../bundles/bundle-interchainPool.js',
     ],
+    auction: ['../src/auction/auctioneer.js', '../bundles/bundle-auction.js'],
     vaultFactory: [
       '../src/vaultFactory/vaultFactory.js',
       '../bundles/bundle-vaultFactory.js',