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

package/src/vaultFactory/vaultDirector.js

@@ -1,64 +1,49 @@
-// @ts-check
-
 import '@agoric/zoe/exported.js';
 import '@agoric/zoe/src/contracts/exported.js';
 
-import '@agoric/governance/src/exported.js';
-import { E } from '@endo/eventual-send';
+import '@agoric/governance/exported.js';
 
-import { fit, keyEQ, M, makeScalarMap } from '@agoric/store';
+import { AmountMath, AmountShape, BrandShape, IssuerShape } from '@agoric/ertp';
+import { GovernorFacetShape } from '@agoric/governance/src/typeGuards.js';
+import { makeTracer } from '@agoric/internal';
+import { M, mustMatch } from '@agoric/store';
+import {
+  prepareExoClassKit,
+  provide,
+  provideDurableMapStore,
+} from '@agoric/vat-data';
+import { assertKeywordName } from '@agoric/zoe/src/cleanProposal.js';
 import {
-  assertProposalShape,
+  atomicRearrange,
   getAmountIn,
   getAmountOut,
+  makeRatioFromAmounts,
+  makeRecorderTopic,
+  provideEmptySeat,
+  SubscriberShape,
+  TopicsRecordShape,
+  unitAmount,
 } from '@agoric/zoe/src/contractSupport/index.js';
-import { makeRatioFromAmounts } from '@agoric/zoe/src/contractSupport/ratio.js';
+import { E } from '@endo/eventual-send';
 import { Far } from '@endo/marshal';
-
-import { AmountMath } from '@agoric/ertp';
-import { makeStoredPublisherKit, observeIteration } from '@agoric/notifier';
+import { makeCollectFeesInvitation } from '../collectFees.js';
 import {
-  defineDurableKindMulti,
-  makeKindHandle,
-  makeScalarBigMapStore,
-} from '@agoric/vat-data';
-import { assertKeywordName } from '@agoric/zoe/src/cleanProposal.js';
-import { makeMakeCollectFeesInvitation } from '../collectFees.js';
-import { makeMetricsPublisherKit } from '../contractSupport.js';
+  setWakeupsForNextAuction,
+  watchForGovernanceChange,
+} from './liquidation.js';
 import {
-  CHARGING_PERIOD_KEY,
-  makeVaultParamManager,
-  RECORDING_PERIOD_KEY,
+  provideVaultParamManagers,
   SHORTFALL_INVITATION_KEY,
   vaultParamPattern,
 } from './params.js';
-import { makeVaultManager } from './vaultManager.js';
-
-const { details: X, quote: q } = assert;
-
-/** @typedef {{
- * debtMint: ZCFMint<'nat'>,
- * directorParamManager: import('@agoric/governance/src/contractGovernance/typedParamManager').TypedParamManager<import('./params.js').VaultDirectorParams>,
- * marshaller: ERef<Marshaller>,
- * metricsPublication: IterationObserver<MetricsNotification>
- * metricsSubscription: StoredSubscription<MetricsNotification>
- * shortfallReporter: import('../reserve/assetReserve.js').ShortfallReporter,
- * storageNode: ERef<StorageNode>,
- * vaultParamManagers: Store<Brand, import('./params.js').VaultParamManager>,
- * zcf: import('./vaultFactory.js').VaultFactoryZCF,
- * }} Ephemera
- */
+import {
+  prepareVaultManagerKit,
+  provideAndStartVaultManagerKits,
+} from './vaultManager.js';
 
-/**
- * Ephemera is the state we cannot (or merely need not) keep durably. For
- * vaultDirector we can keep it in module scope because there is (exactly) one
- * vaultDirector per vaultFactory contract and (exactly) one contract per vat.
- *
- * @type {Ephemera}
- */
-// @ts-expect-error not actually full until after initState
-// UNTIL resolution to https://github.com/Agoric/agoric-sdk/issues/5759
-const ephemera = {};
+const { Fail, quote: q } = assert;
+
+const trace = makeTracer('VD', true);
 
 /**
  * @typedef {{
@@ -67,513 +52,525 @@ const ephemera = {};
  * }} MetricsNotification
  *
  * @typedef {Readonly<{
- * collateralTypes: Store<Brand,VaultManager>,
- * mintSeat: ZCFSeat,
- * rewardPoolSeat: ZCFSeat,
- * shortfallInvitation: Invitation,
  * }>} ImmutableState
  *
  * @typedef {{
- * managerCounter: number,
  * }} MutableState
  *
  * @typedef {ImmutableState & MutableState} State
  *
- *  @typedef {{
+ * @typedef {{
  *  burnDebt: BurnDebt,
- *  getGovernedParams: () => import('./vaultManager.js').GovernedParamGetters,
- *  mintAndReallocate: MintAndReallocate,
+ *  getGovernedParams: (collateralBrand: Brand) => import('./vaultManager.js').GovernedParamGetters,
+ *  mintAndTransfer: MintAndTransfer,
  *  getShortfallReporter: () => Promise<import('../reserve/assetReserve.js').ShortfallReporter>,
  * }} FactoryPowersFacet
  *
  * @typedef {Readonly<{
  *   state: State;
- *   facets: import('@agoric/vat-data/src/types').KindFacets<typeof behavior>;
  * }>} MethodContext
+ *
+ * @typedef {import('@agoric/governance/src/contractGovernance/typedParamManager').TypedParamManager<import('./params.js').VaultDirectorParams>} VaultDirectorParamManager
  */
 
-/**
- * @param {ERef<ZoeService>} zoe
- * @param {Ephemera['directorParamManager']} paramMgr
- * @param {import('../reserve/assetReserve.js').ShortfallReporter} [oldShortfallReporter]
- * @param {ERef<Invitation>} [oldInvitation]
- * @returns {Promise<{
- *   shortfallInvitation: ERef<Invitation>,
- *   shortfallReporter: import('../reserve/assetReserve.js').ShortfallReporter,
- * }>}
- */
-const updateShortfallReporter = async (
-  zoe,
-  paramMgr,
-  oldShortfallReporter,
-  oldInvitation,
-) => {
-  const newInvitation = paramMgr.getInternalParamValue(
-    SHORTFALL_INVITATION_KEY,
-  );
-
-  if (newInvitation !== oldInvitation) {
-    return {
-      // @ts-expect-error cast
-      shortfallReporter: E(E(zoe).offer(newInvitation)).getOfferResult(),
-      shortfallInvitation: newInvitation,
-    };
-  } else {
-    assert(
-      oldShortfallReporter,
-      'updateShortFallReported called with repeat invitation and no oldShortfallReporter',
-    );
-    return {
-      shortfallReporter: oldShortfallReporter,
-      shortfallInvitation: oldInvitation,
-    };
-  }
-};
-
-/**
- * @param {Pick<State, 'collateralTypes' | 'rewardPoolSeat'>} state
- * @returns {MetricsNotification}
- */
-const metricsOf = state => {
-  return harden({
-    collaterals: Array.from(state.collateralTypes.keys()),
-    rewardPoolAllocation: state.rewardPoolSeat.getCurrentAllocation(),
-  });
-};
+const shortfallInvitationKey = 'shortfallInvitation';
 
 /**
- * @param {Ephemera['zcf']} zcf
- * @param {Ephemera['directorParamManager']} directorParamManager
- * @param {Ephemera['debtMint']} debtMint
+ * @param {import('@agoric/ertp').Baggage} baggage
+ * @param {import('./vaultFactory.js').VaultFactoryZCF} zcf
+ * @param {VaultDirectorParamManager} directorParamManager
+ * @param {ZCFMint<"nat">} debtMint
+ * @param {ERef<import('@agoric/time/src/types').TimerService>} timer
+ * @param {ERef<import('../auction/auctioneer.js').AuctioneerPublicFacet>} auctioneer
  * @param {ERef<StorageNode>} storageNode
  * @param {ERef<Marshaller>} marshaller
- * @returns {State}
+ * @param {import('@agoric/zoe/src/contractSupport/recorder.js').MakeRecorderKit} makeRecorderKit
+ * @param {import('@agoric/zoe/src/contractSupport/recorder.js').MakeERecorderKit} makeERecorderKit
  */
-const initState = (
+export const prepareVaultDirector = (
+  baggage,
   zcf,
   directorParamManager,
   debtMint,
+  timer,
+  auctioneer,
   storageNode,
   marshaller,
+  makeRecorderKit,
+  makeERecorderKit,
 ) => {
-  /** For temporary staging of newly minted tokens */
-  const { zcfSeat: mintSeat } = zcf.makeEmptySeatKit();
-  const { zcfSeat: rewardPoolSeat } = zcf.makeEmptySeatKit();
+  /** @type {import('../reserve/assetReserve.js').ShortfallReporter} */
+  let shortfallReporter;
 
-  const collateralTypes = makeScalarBigMapStore('collateralTypes', {
-    durable: true,
-  });
+  /** For holding newly minted tokens until transferred */
+  const { zcfSeat: mintSeat } = zcf.makeEmptySeatKit();
 
-  // Non-durable map because param managers aren't durable.
-  // In the event they're needed they can be reconstructed from contract terms and off-chain data.
-  const vaultParamManagers = makeScalarMap('vaultParamManagers');
+  const rewardPoolSeat = provideEmptySeat(zcf, baggage, 'rewardPoolSeat');
 
-  const { metricsPublication, metricsSubscription } = makeMetricsPublisherKit(
-    storageNode,
-    marshaller,
+  /** @type {MapStore<Brand, number>} index of manager for the given collateral */
+  const collateralManagers = provideDurableMapStore(
+    baggage,
+    'collateralManagers',
   );
 
-  Object.assign(ephemera, {
-    debtMint,
-    directorParamManager,
-    marshaller,
-    metricsPublication,
-    // Subscription can't yet be held durably https://github.com/Agoric/agoric-sdk/issues/4567
-    metricsSubscription,
-    storageNode,
-    vaultParamManagers,
-    zcf,
-  });
-
-  return {
-    collateralTypes,
-    managerCounter: 0,
-    mintSeat,
-    rewardPoolSeat,
-    // @ts-expect-error defined in finish()
-    shortfallInvitation: undefined,
-  };
-};
-
-/**
- * Make a loan in the vaultManager based on the collateral type.
- *
- * @deprecated
- * @param {MethodContext} context
- */
-const makeVaultInvitation = ({ state }) => {
-  const { zcf } = ephemera;
-
-  const { collateralTypes } = state;
-
-  /** @param {ZCFSeat} seat */
-  const makeVaultHook = async seat => {
-    assertProposalShape(seat, {
-      give: { Collateral: null },
-      want: { Minted: null },
-    });
-    const {
-      give: { Collateral: collateralAmount },
-      want: { Minted: requestedAmount },
-    } = seat.getProposal();
-    const { brand: brandIn } = collateralAmount;
-    collateralTypes.has(brandIn) ||
-      assert.fail(X`Not a supported collateral type ${brandIn}`);
-
-    assert(
-      AmountMath.isGTE(
-        requestedAmount,
-        ephemera.directorParamManager.getMinInitialDebt(),
-      ),
-      X`The request must be for at least ${
-        ephemera.directorParamManager.getMinInitialDebt().value
-      }. ${requestedAmount.value} is too small`,
-    );
+  // Non-durable map because param managers aren't durable.
+  // In the event they're needed they can be reconstructed from contract terms and off-chain data.
+  /** a powerful object; can modify parameters */
+  const vaultParamManagers = provideVaultParamManagers(baggage, marshaller);
 
-    /** @type {VaultManager} */
-    const mgr = collateralTypes.get(brandIn);
-    return mgr.makeVaultKit(seat);
-  };
-  return zcf.makeInvitation(makeVaultHook, 'MakeVault');
-};
+  const metricsNode = E(storageNode).makeChildNode('metrics');
 
-/**
- * @deprecated get `collaterals` list from metrics
- * @param {MethodContext} context
- */
-const getCollaterals = async ({ state }) => {
-  const { collateralTypes } = state;
-  // should be collateralTypes.map((vm, brand) => ({
-  return harden(
-    Promise.all(
-      [...collateralTypes.entries()].map(async ([brand, vm]) => {
-        const priceQuote = await vm.getCollateralQuote();
-        return {
-          brand,
-          interestRate: vm.getGovernedParams().getInterestRate(),
-          liquidationMargin: vm.getGovernedParams().getLiquidationMargin(),
-          stabilityFee: vm.getGovernedParams().getLoanFee(),
-          marketPrice: makeRatioFromAmounts(
-            getAmountOut(priceQuote),
-            getAmountIn(priceQuote),
-          ),
-        };
-      }),
+  const metricsKit = makeERecorderKit(
+    metricsNode,
+    /** @type {import('@agoric/zoe/src/contractSupport/recorder.js').TypedMatcher<MetricsNotification>} */ (
+      M.any()
     ),
   );
-};
-/**
- * @param {Ephemera['directorParamManager']} directorParamManager
- */
-const getLiquidationConfig = directorParamManager => ({
-  install: directorParamManager.getLiquidationInstall(),
-  terms: directorParamManager.getLiquidationTerms(),
-});
 
-/**
- *
- * @param {Ephemera['directorParamManager']} govParams
- * @param {VaultManager} vaultManager
- * @param {Installation<unknown>} oldInstall
- * @param {unknown} oldTerms
- */
-const watchGovernance = (govParams, vaultManager, oldInstall, oldTerms) => {
-  const subscription = govParams.getSubscription();
-  void observeIteration(subscription, {
-    updateState(_paramUpdate) {
-      const { install, terms } = getLiquidationConfig(govParams);
-      if (install === oldInstall && keyEQ(terms, oldTerms)) {
-        return;
-      }
-      oldInstall = install;
-      oldTerms = terms;
-      vaultManager
-        .setupLiquidator(install, terms)
-        .catch(e => console.error('Failed to setup liquidator', e));
-    },
-  });
-};
+  const managersNode = E(storageNode).makeChildNode('managers');
 
-/** @type {import('@agoric/vat-data/src/types').FunctionsPlusContext<MethodContext, VaultFactoryCreatorFacet>} */
-const machineBehavior = {
-  // TODO move this under governance #3924
   /**
-   * @param {MethodContext} context
-   * @param {Issuer} collateralIssuer
-   * @param {Keyword} collateralKeyword
-   * @param {VaultManagerParamValues} initialParamValues
+   * @returns {MetricsNotification}
    */
-  addVaultType: async (
-    { state, facets },
-    collateralIssuer,
-    collateralKeyword,
-    initialParamValues,
-  ) => {
-    const {
-      debtMint,
-      vaultParamManagers,
-      directorParamManager,
-      marshaller,
-      storageNode,
-      zcf,
-    } = ephemera;
-    const { collateralTypes, mintSeat, rewardPoolSeat } = state;
-    fit(collateralIssuer, M.remotable(), 'collateralIssuer');
-    assertKeywordName(collateralKeyword);
-    fit(initialParamValues, vaultParamPattern, 'initialParamValues');
-    await zcf.saveIssuer(collateralIssuer, collateralKeyword);
-    const collateralBrand = zcf.getBrandForIssuer(collateralIssuer);
-    // We create only one vault per collateralType.
-    !collateralTypes.has(collateralBrand) ||
-      assert.fail(
-        X`Collateral brand ${q(collateralBrand)} has already been added`,
-      );
-
-    const managerStorageNode =
-      storageNode &&
-      E(storageNode).makeChildNode(`manager${state.managerCounter}`);
-    state.managerCounter += 1;
-
-    /** a powerful object; can modify parameters */
-    const vaultParamManager = makeVaultParamManager(
-      makeStoredPublisherKit(managerStorageNode, marshaller, 'governance'),
-      initialParamValues,
+  const sampleMetrics = () => {
+    return harden({
+      collaterals: Array.from(collateralManagers.keys()),
+      rewardPoolAllocation: rewardPoolSeat.getCurrentAllocation(),
+    });
+  };
+  const writeMetrics = () => E(metricsKit.recorderP).write(sampleMetrics());
+
+  const updateShortfallReporter = async () => {
+    const oldInvitation = baggage.has(shortfallInvitationKey)
+      ? baggage.get(shortfallInvitationKey)
+      : undefined;
+    const newInvitation = await directorParamManager.getInternalParamValue(
+      SHORTFALL_INVITATION_KEY,
     );
-    vaultParamManagers.init(collateralBrand, vaultParamManager);
 
-    const { timerService } = zcf.getTerms();
-    const startTimeStamp = await E(timerService).getCurrentTimestamp();
+    if (newInvitation === oldInvitation) {
+      shortfallReporter ||
+        Fail`updateShortFallReported called with repeat invitation and no prior shortfallReporter`;
+      return;
+    }
+
+    // Update the values
+    const zoe = zcf.getZoeService();
+    // @ts-expect-error cast
+    shortfallReporter = E(E(zoe).offer(newInvitation)).getOfferResult();
+    if (oldInvitation === undefined) {
+      baggage.init(shortfallInvitationKey, newInvitation);
+    } else {
+      baggage.set(shortfallInvitationKey, newInvitation);
+    }
+  };
 
+  const factoryPowers = Far('vault factory powers', {
     /**
-     * We provide an easy way for the vaultManager to add rewards to
-     * the rewardPoolSeat, without directly exposing the rewardPoolSeat to them.
+     * Get read-only params for this manager and its director. This grants all
+     * managers access to params from all managers. It's not POLA but it's a
+     * public authority and it reduces the number of distinct power objects to
+     * create.
      *
-     * @type {MintAndReallocate}
+     * @param {Brand} brand
      */
-    const mintAndReallocate = (toMint, fee, seat, ...otherSeats) => {
+    getGovernedParams: brand => {
+      const vaultParamManager = vaultParamManagers.get(brand);
+      return Far('vault manager param manager', {
+        // merge director and manager params
+        ...directorParamManager.readonly(),
+        ...vaultParamManager.readonly(),
+        // redeclare these getters as to specify the kind of the Amount
+        getMinInitialDebt: /** @type {() => Amount<'nat'>} */ (
+          directorParamManager.readonly().getMinInitialDebt
+        ),
+        getDebtLimit: /** @type {() => Amount<'nat'>} */ (
+          vaultParamManager.readonly().getDebtLimit
+        ),
+      });
+    },
+
+    /**
+     * Let the manager add rewards to the rewardPoolSeat without
+     * exposing the rewardPoolSeat to them.
+     *
+     * @type {MintAndTransfer}
+     */
+    mintAndTransfer: (mintReceiver, toMint, fee, nonMintTransfers) => {
       const kept = AmountMath.subtract(toMint, fee);
       debtMint.mintGains(harden({ Minted: toMint }), mintSeat);
+      /** @type {import('@agoric/zoe/src/contractSupport/atomicTransfer.js').TransferPart[]} */
+      const transfers = [
+        ...nonMintTransfers,
+        [mintSeat, rewardPoolSeat, { Minted: fee }],
+        [mintSeat, mintReceiver, { Minted: kept }],
+      ];
       try {
-        rewardPoolSeat.incrementBy(
-          mintSeat.decrementBy(harden({ Minted: fee })),
-        );
-        seat.incrementBy(mintSeat.decrementBy(harden({ Minted: kept })));
-        zcf.reallocate(rewardPoolSeat, mintSeat, seat, ...otherSeats);
+        atomicRearrange(zcf, harden(transfers));
       } catch (e) {
-        console.error('mintAndReallocate caught', e);
-        mintSeat.clear();
-        rewardPoolSeat.clear();
-        // Make best efforts to burn the newly minted tokens, for hygiene.
-        // That only relies on the internal mint, so it cannot fail without
-        // there being much larger problems. There's no risk of tokens being
-        // stolen here because the staging for them was already cleared.
+        console.error('mintAndTransfer failed to rearrange', e);
+        // If the rearrange fails, burn the newly minted tokens.
+        // Assume this won't fail because it relies on the internal mint.
+        // (Failure would imply much larger problems.)
         debtMint.burnLosses(harden({ Minted: toMint }), mintSeat);
         throw e;
-      } finally {
-        // Note that if this assertion may fail because of an error in the
-        // try{} block, but that error won't be thrown because this executes
-        // before the catch that rethrows it.
-        assert(
-          Object.values(mintSeat.getCurrentAllocation()).every(a =>
-            AmountMath.isEmpty(a),
-          ),
-          X`Stage should be empty of Minted`,
-        );
       }
-      facets.machine.updateMetrics();
-    };
-
+      void writeMetrics();
+    },
+    getShortfallReporter: async () => {
+      await updateShortfallReporter();
+      return shortfallReporter;
+    },
     /**
      * @param {Amount<'nat'>} toBurn
      * @param {ZCFSeat} seat
      */
-    const burnDebt = (toBurn, seat) => {
+    burnDebt: (toBurn, seat) => {
       debtMint.burnLosses(harden({ Minted: toBurn }), seat);
-    };
+    },
+  });
 
-    const { loanTimingParams } = zcf.getTerms();
+  const makeVaultManagerKit = prepareVaultManagerKit(baggage, {
+    makeERecorderKit,
+    makeRecorderKit,
+    marshaller,
+    factoryPowers,
+    zcf,
+  });
 
-    const factoryPowers = Far('vault factory powers', {
-      getGovernedParams: () => ({
-        ...vaultParamManager.readonly(),
-        getChargingPeriod: () => loanTimingParams[CHARGING_PERIOD_KEY].value,
-        getRecordingPeriod: () => loanTimingParams[RECORDING_PERIOD_KEY].value,
-      }),
-      mintAndReallocate,
-      getShortfallReporter: async () => {
-        const reporterKit = await updateShortfallReporter(
-          zcf.getZoeService(),
-          directorParamManager,
-          ephemera.shortfallReporter,
-          state.shortfallInvitation,
-        );
-        return reporterKit.shortfallReporter;
-      },
-      burnDebt,
-    });
+  const vaultManagers = provideAndStartVaultManagerKits(baggage);
 
-    const vm = makeVaultManager(
-      zcf,
-      debtMint,
-      collateralBrand,
-      zcf.getTerms().priceAuthority,
-      factoryPowers,
-      timerService,
-      startTimeStamp,
-      managerStorageNode,
-      ephemera.marshaller,
-    );
-    collateralTypes.init(collateralBrand, vm);
-    const { install, terms } = getLiquidationConfig(directorParamManager);
-    await vm.setupLiquidator(install, terms);
-    watchGovernance(directorParamManager, vm, install, terms);
-    facets.machine.updateMetrics();
-    return vm;
-  },
-  getCollaterals,
-  /** @param {MethodContext} context */
-  makeCollectFeesInvitation: ({ state }) => {
-    const { debtMint, zcf } = ephemera;
-    const { rewardPoolSeat } = state;
-    return makeMakeCollectFeesInvitation(
-      zcf,
-      rewardPoolSeat,
-      debtMint.getIssuerRecord().brand,
-      'Minted',
-    ).makeCollectFeesInvitation();
-  },
-  getContractGovernor: () => ephemera.zcf.getTerms().electionManager,
-  /** @param {MethodContext} context */
-  updateMetrics: ({ state }) => {
-    ephemera.metricsPublication.updateState(metricsOf(harden(state)));
-  },
-
-  // XXX accessors for tests
-  /** @param {MethodContext} context */
-  getRewardAllocation: ({ state }) =>
-    state.rewardPoolSeat.getCurrentAllocation(),
-};
+  /** @type {(brand: Brand) => VaultManager} */
+  const managerForCollateral = brand => {
+    const managerIndex = collateralManagers.get(brand);
+    const manager = vaultManagers.get(managerIndex).self;
+    manager || Fail`no manager ${managerIndex} for collateral ${brand}`;
+    return manager;
+  };
 
-const creatorBehavior = {
-  getParamMgrRetriever: () =>
-    Far('paramManagerRetriever', {
-      /** @param {VaultFactoryParamPath} paramPath */
-      get: paramPath => {
-        if (paramPath.key === 'governedParams') {
-          return ephemera.directorParamManager;
-        } else if (paramPath.key.collateralBrand) {
-          return ephemera.vaultParamManagers.get(paramPath.key.collateralBrand);
-        } else {
-          assert.fail('Unsupported paramPath');
-        }
-      },
-    }),
-  /**
-   * @param {MethodContext} context
-   * @param {string} name
-   */
-  getInvitation: (context, name) =>
-    ephemera.directorParamManager.getInternalParamValue(name),
-  /** @param {MethodContext} context */
-  getLimitedCreatorFacet: context => context.facets.machine,
-  getGovernedApis: () => harden({}),
-  getGovernedApiNames: () => harden({}),
-};
+  // TODO helper to make all the topics at once
+  const topics = harden({
+    metrics: makeRecorderTopic('Vault Factory metrics', metricsKit),
+  });
+
+  const allManagersDo = fn => {
+    for (const managerIndex of collateralManagers.values()) {
+      const vm = vaultManagers.get(managerIndex).self;
+      fn(vm);
+    }
+  };
+
+  const makeWaker = (name, func) => {
+    return Far(name, {
+      wake: timestamp => func(timestamp),
+    });
+  };
 
-const publicBehavior = {
   /**
-   * @param {MethodContext} context
-   * @param {Brand} brandIn
+   * @returns {State}
    */
-  getCollateralManager: ({ state }, brandIn) => {
-    const { collateralTypes } = state;
-    collateralTypes.has(brandIn) ||
-      assert.fail(X`Not a supported collateral type ${brandIn}`);
-    /** @type {VaultManager} */
-    return collateralTypes.get(brandIn).getPublicFacet();
-  },
-  getMetrics: () => ephemera.metricsSubscription,
-
-  /** @deprecated use getCollateralManager and then makeVaultInvitation instead */
-  makeLoanInvitation: makeVaultInvitation,
-  /** @deprecated use getCollateralManager and then makeVaultInvitation instead */
-  makeVaultInvitation,
-  getCollaterals,
-  getRunIssuer: () => ephemera.debtMint.getIssuerRecord().issuer,
+  const initState = () => {
+    return {};
+  };
+
   /**
-   * subscription for the paramManager for a particular vaultManager
+   * "Director" of the vault factory, overseeing "vault managers".
    *
-   * @param {MethodContext} context
-   * @param {{ collateralBrand: Brand }} selector
+   * @param {import('./vaultFactory.js').VaultFactoryZCF} zcf
+   * @param {VaultDirectorParamManager} directorParamManager
+   * @param {ZCFMint<"nat">} debtMint
    */
-  getSubscription: (context, { collateralBrand }) =>
-    ephemera.vaultParamManagers.get(collateralBrand).getSubscription(),
-  /**
-   * subscription for the paramManager for the vaultFactory's electorate
-   */
-  getElectorateSubscription: () =>
-    ephemera.directorParamManager.getSubscription(),
-  /**
-   * @param {MethodContext} context
-   * @param {{ collateralBrand: Brand }} selector
-   */
-  getGovernedParams: (context, { collateralBrand }) =>
-    // TODO use named getters of TypedParamManager
-    ephemera.vaultParamManagers.get(collateralBrand).getParams(),
-  /**
-   * @returns {Promise<GovernorPublic>}
-   */
-  getContractGovernor: () =>
-    // PERF consider caching
-    E(ephemera.zcf.getZoeService()).getPublicFacet(
-      ephemera.zcf.getTerms().electionManager,
-    ),
-  /**
-   * @param {MethodContext} context
-   * @param {string} name
-   */
-  getInvitationAmount: (context, name) =>
-    ephemera.directorParamManager.getInvitationAmount(name),
-};
-
-const behavior = {
-  creator: creatorBehavior,
-  machine: machineBehavior,
-  public: publicBehavior,
-};
-
-/** @param {MethodContext} context */
-const finish = async ({ state }) => {
-  const { shortfallReporter, shortfallInvitation } =
-    await updateShortfallReporter(
-      ephemera.zcf.getZoeService(),
-      ephemera.directorParamManager,
-    );
-  ephemera.shortfallReporter = shortfallReporter;
-  // @ts-expect-error write once
-  state.shortfallInvitation = shortfallInvitation;
+  const makeVaultDirector = prepareExoClassKit(
+    baggage,
+    'VaultDirector',
+    {
+      creator: M.interface('creator', {
+        ...GovernorFacetShape,
+      }),
+      machine: M.interface('machine', {
+        addVaultType: M.call(IssuerShape, M.string(), M.record()).returns(
+          M.promise(),
+        ),
+        makeCollectFeesInvitation: M.call().returns(M.promise()),
+        getRewardAllocation: M.call().returns({ Minted: AmountShape }),
+        makePriceLockWaker: M.call().returns(M.remotable('TimerWaker')),
+        makeLiquidationWaker: M.call().returns(M.remotable('TimerWaker')),
+        makeReschedulerWaker: M.call().returns(M.remotable('TimerWaker')),
+      }),
+      public: M.interface('public', {
+        getCollateralManager: M.call(BrandShape).returns(M.remotable()),
+        getCollaterals: M.call().returns(M.promise()),
+        getMetrics: M.call().returns(SubscriberShape),
+        getRunIssuer: M.call().returns(IssuerShape),
+        getSubscription: M.call({ collateralBrand: BrandShape }).returns(
+          SubscriberShape,
+        ),
+        getElectorateSubscription: M.call().returns(SubscriberShape),
+        getGovernedParams: M.call({ collateralBrand: BrandShape }).returns(
+          M.record(),
+        ),
+        getInvitationAmount: M.call(M.string()).returns(AmountShape),
+        getPublicTopics: M.call().returns(TopicsRecordShape),
+      }),
+      helper: M.interface('helper', {
+        resetWakeupsForNextAuction: M.call().returns(M.promise()),
+        start: M.call().returns(M.promise()),
+      }),
+    },
+    initState,
+    {
+      creator: {
+        getParamMgrRetriever: () =>
+          Far('paramManagerRetriever', {
+            /** @param {VaultFactoryParamPath} paramPath */
+            get: (
+              paramPath = { key: /** @type {const} */ 'governedParams' },
+            ) => {
+              if (paramPath.key === 'governedParams') {
+                return directorParamManager;
+              } else if (paramPath.key.collateralBrand) {
+                return vaultParamManagers.get(paramPath.key.collateralBrand);
+              } else {
+                assert.fail('Unsupported paramPath');
+              }
+            },
+          }),
+        /**
+         * @param {string} name
+         */
+        getInvitation(name) {
+          return directorParamManager.getInternalParamValue(name);
+        },
+        getLimitedCreatorFacet() {
+          return this.facets.machine;
+        },
+        /** @returns {ERef<GovernedApis>} */
+        getGovernedApis() {
+          // @ts-expect-error cast
+          return Far('governedAPIs', {});
+        },
+        getGovernedApiNames() {
+          return harden([]);
+        },
+        setOfferFilter: strings => zcf.setOfferFilter(strings),
+      },
+      machine: {
+        // TODO move this under governance #3924
+        /**
+         * @param {Issuer<'nat'>} collateralIssuer
+         * @param {Keyword} collateralKeyword
+         * @param {VaultManagerParamValues} initialParamValues
+         */
+        async addVaultType(
+          collateralIssuer,
+          collateralKeyword,
+          initialParamValues,
+        ) {
+          trace('addVaultType', collateralKeyword, initialParamValues);
+          mustMatch(collateralIssuer, M.remotable(), 'collateralIssuer');
+          assertKeywordName(collateralKeyword);
+          mustMatch(
+            initialParamValues,
+            vaultParamPattern,
+            'initialParamValues',
+          );
+          await zcf.saveIssuer(collateralIssuer, collateralKeyword);
+          const collateralBrand = zcf.getBrandForIssuer(collateralIssuer);
+          // We create only one vault per collateralType.
+          !collateralManagers.has(collateralBrand) ||
+            Fail`Collateral brand ${q(collateralBrand)} has already been added`;
+
+          // zero-based index of the manager being made
+          const managerIndex = vaultManagers.length();
+          const managerId = `manager${managerIndex}`;
+          const managerStorageNode = await E(managersNode).makeChildNode(
+            managerId,
+          );
+
+          vaultParamManagers.addParamManager(
+            collateralBrand,
+            managerStorageNode,
+            initialParamValues,
+          );
+
+          const startTimeStamp = await E(timer).getCurrentTimestamp();
+
+          const collateralUnit = await unitAmount(collateralBrand);
+
+          const kit = await makeVaultManagerKit({
+            debtMint,
+            collateralBrand,
+            collateralUnit,
+            descriptionScope: managerId,
+            startTimeStamp,
+            storageNode: managerStorageNode,
+          });
+          vaultManagers.add(kit);
+          vaultManagers.length() - 1 === managerIndex ||
+            Fail`mismatch VaultManagerKit count`;
+          const { self: vm } = kit;
+          vm || Fail`no vault`;
+          collateralManagers.init(collateralBrand, managerIndex);
+          void writeMetrics();
+          return vm;
+        },
+        makeCollectFeesInvitation() {
+          return makeCollectFeesInvitation(
+            zcf,
+            rewardPoolSeat,
+            debtMint.getIssuerRecord().brand,
+            'Minted',
+          );
+        },
+        // XXX accessors for tests
+        getRewardAllocation() {
+          return rewardPoolSeat.getCurrentAllocation();
+        },
+
+        makeLiquidationWaker() {
+          return makeWaker('liquidationWaker', _timestamp => {
+            allManagersDo(vm => vm.liquidateVaults(auctioneer));
+          });
+        },
+        makeReschedulerWaker() {
+          const { facets } = this;
+          return makeWaker('reschedulerWaker', () => {
+            void facets.helper.resetWakeupsForNextAuction();
+          });
+        },
+        makePriceLockWaker() {
+          return makeWaker('priceLockWaker', () => {
+            allManagersDo(vm => vm.lockOraclePrices());
+          });
+        },
+      },
+      public: {
+        /**
+         * @param {Brand} brandIn
+         */
+        getCollateralManager(brandIn) {
+          collateralManagers.has(brandIn) ||
+            Fail`Not a supported collateral type ${brandIn}`;
+          /** @type {VaultManager} */
+          return managerForCollateral(brandIn).getPublicFacet();
+        },
+        /**
+         * @deprecated get `collaterals` list from metrics
+         */
+        async getCollaterals() {
+          // should be collateralManagers.map((vm, brand) => ({
+          return harden(
+            Promise.all(
+              [...collateralManagers.entries()].map(
+                async ([brand, managerIndex]) => {
+                  const vm = vaultManagers.get(managerIndex).self;
+                  const priceQuote = await vm.getCollateralQuote();
+                  return {
+                    brand,
+                    interestRate: vm.getGovernedParams().getInterestRate(),
+                    liquidationMargin: vm
+                      .getGovernedParams()
+                      .getLiquidationMargin(),
+                    stabilityFee: vm.getGovernedParams().getMintFee(),
+                    marketPrice: makeRatioFromAmounts(
+                      getAmountOut(priceQuote),
+                      getAmountIn(priceQuote),
+                    ),
+                  };
+                },
+              ),
+            ),
+          );
+        },
+        /** @deprecated use getPublicTopics */
+        getMetrics() {
+          return metricsKit.subscriber;
+        },
+        getRunIssuer() {
+          return debtMint.getIssuerRecord().issuer;
+        },
+        /**
+         * @deprecated get from the CollateralManager directly
+         *
+         * subscription for the paramManager for a particular vaultManager
+         *
+         * @param {{ collateralBrand: Brand }} selector
+         */
+        getSubscription({ collateralBrand }) {
+          return vaultParamManagers.get(collateralBrand).getSubscription();
+        },
+        getPublicTopics() {
+          return topics;
+        },
+        /**
+         * subscription for the paramManager for the vaultFactory's electorate
+         */
+        getElectorateSubscription() {
+          return directorParamManager.getSubscription();
+        },
+        /**
+         * @param {{ collateralBrand: Brand }} selector
+         */
+        getGovernedParams({ collateralBrand }) {
+          // TODO use named getters of TypedParamManager
+          return vaultParamManagers.get(collateralBrand).getParams();
+        },
+        /**
+         * @param {string} name
+         */
+        getInvitationAmount(name) {
+          return directorParamManager.getInvitationAmount(name);
+        },
+      },
+      helper: {
+        resetWakeupsForNextAuction() {
+          const { facets } = this;
+
+          const priceLockWaker = facets.machine.makePriceLockWaker();
+          const liquidationWaker = facets.machine.makeLiquidationWaker();
+          const rescheduleWaker = facets.machine.makeReschedulerWaker();
+          return setWakeupsForNextAuction(
+            auctioneer,
+            timer,
+            priceLockWaker,
+            liquidationWaker,
+            rescheduleWaker,
+          );
+        },
+        /**
+         * Start non-durable processes (or restart if needed after vat restart)
+         */
+        async start() {
+          const { helper, machine } = this.facets;
+
+          await helper.resetWakeupsForNextAuction();
+          updateShortfallReporter().catch(err =>
+            console.error(
+              '🛠️ updateShortfallReporter failed during start(); repair by updating governance',
+              err,
+            ),
+          );
+          // independent of the other one which can be canceled
+          const rescheduleWaker = machine.makeReschedulerWaker();
+          void watchForGovernanceChange(auctioneer, timer, rescheduleWaker);
+        },
+      },
+    },
+  );
+  return makeVaultDirector;
 };
+harden(prepareVaultDirector);
 
 /**
- * "Director" of the vault factory, overseeing "vault managers".
+ * Prepare the VaultDirector kind, get or make the singleton
  *
- * @param {ZCF<GovernanceTerms<{}> & {
- *   ammPublicFacet: AutoswapPublicFacet,
- *   liquidationInstall: Installation<import('./liquidateMinimum.js').start>,
- *   loanTimingParams: {ChargingPeriod: ParamValueTyped<'nat'>, RecordingPeriod: ParamValueTyped<'nat'>},
- *   reservePublicFacet: AssetReservePublicFacet,
- *   timerService: TimerService,
- *   priceAuthority: ERef<PriceAuthority>
- * }>} zcf
- * @param {import('@agoric/governance/src/contractGovernance/typedParamManager').TypedParamManager<import('./params.js').VaultDirectorParams>} directorParamManager
- * @param {ZCFMint<"nat">} debtMint
+ * @type {(...pvdArgs: Parameters<typeof prepareVaultDirector>) => ReturnType<ReturnType<typeof prepareVaultDirector>>}
  */
-const makeVaultDirector = defineDurableKindMulti(
-  makeKindHandle('VaultDirector'),
-  initState,
-  behavior,
-  { finish },
-);
-
-harden(makeVaultDirector);
-export { makeVaultDirector };
+export const provideDirector = (...args) => {
+  const makeVaultDirector = prepareVaultDirector(...args);
+
+  const [baggage] = args;
+
+  return provide(baggage, 'director', makeVaultDirector);
+};
+harden(provideDirector);