feat(vault): econ metrics notifiers (#5260)

* chore(vault): type VaultUIState -> VaultTitleState

* chore(zoe): type setupZCFTest

* chore(vault): disambiguate VaultManager type (facet naming confusion)

* feat(vault): vaultDirector econ notifier

* feat(vault): vaultManager econNotifier

* feat(vault): number of vaults per manager in EconState

* style: fix 'object' type casing

* fixup! chore(vault): type VaultUIState -> VaultTitleState

* 'econ' -> 'metrics' (will squash)

* fixup! chore(vault): disambiguate VaultManager type (facet naming confusion)

* size -> count

* undo name change in test

* lint

* handleFooOffer style per #5179

* chore(zoe): more typing offerTo and Invitation

* plan

* factored penalties into liquidation contracts

* rm obsolete partitionProceeds

* lint and comments

* named parameters for makeGovernedTerms()

* wire reservePublicFacet into vaultFactory terms

* rm obsolete penaltyPoolSeat

* fixup! wire reservePublicFacet into vaultFactory terms

* fixup! rm obsolete penaltyPoolSeat

* consume reserve instance instead of facet

* typecheck liquidator,vaultFactory tests

* fix test typo tsc caught

* fix invitation param and typecheck that would have caught it

* update comment docs

* work around type resolution shortcomings

* better comments

* fixup undo vaultFactoryCreator

* getMetrics

* use subscriptions

* revert rename getNotifier (no ambiguity anymore)

* fix lint my editor didn't show 🤷

* fixup! getMetrics

* update metrics after each liquidation

* fix test for manager notifiers

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

packages/run-protocol/src/runStake/runStakeKit.js

@@ -166,7 +166,7 @@ const helperBehavior = {
   snapshotState: ({ state, facets }, newActive) => {
     const { debtSnapshot: debt, interestSnapshot: interest, manager } = state;
     const { helper } = facets;
-    /** @type {VaultUIState} */
+    /** @type {VaultNotification} */
     const result = harden({
       // TODO move manager state to a separate notifer https://github.com/Agoric/agoric-sdk/issues/4540
       interestRate: manager.getInterestRate(),

packages/run-protocol/src/vaultFactory/prioritizedVaults.js

@@ -174,6 +174,7 @@ export const makePrioritizedVaults = (reschedulePriceCheck = () => {}) => {
     addVault,
     entries: vaults.entries,
     entriesPrioritizedGTE,
+    getCount: vaults.getSize,
     highestRatio: firstDebtRatio,
     refreshVaultPriority,
     removeVault,

packages/run-protocol/src/vaultFactory/types.js

@@ -1,7 +1,7 @@
 // @ts-check
 
 /**
- * @typedef {import('./vault').VaultUIState} VaultUIState
+ * @typedef {import('./vault').VaultNotification} VaultNotification
  * @typedef {import('./vault').Vault} Vault
  * @typedef {import('./vaultKit').VaultKit} VaultKit
  * @typedef {import('./vaultManager').VaultManager} VaultManager
@@ -51,6 +51,7 @@
  * @property {() => Allocation} getRewardAllocation
  * @property {() => Instance} getContractGovernor
  * @property {() => Promise<Invitation>} makeCollectFeesInvitation
+ * @property {() => void} updateMetrics
  */
 
 /**

packages/run-protocol/src/vaultFactory/vault.js

@@ -66,14 +66,15 @@ const validTransitions = {
 /**
  * @typedef {Phase[keyof typeof Phase]} TitlePhase
  *
- * @typedef {object} VaultUIState
+ * @typedef {object} VaultNotification
  * @property {Amount<'nat'>} locked Amount of Collateral locked
  * @property {{debt: Amount<'nat'>, interest: Ratio}} debtSnapshot 'debt' at the point the compounded interest was 'interest'
  * @property {Ratio} interestRate Annual interest rate charge
  * @property {Ratio} liquidationRatio
  * @property {TitlePhase} vaultState
  */
 
+// XXX masks typedef from types.js, but using that causes circular def problems
 /**
  * @typedef {object} VaultManager
  * @property {() => Notifier<import('./vaultManager').AssetState>} getNotifier
@@ -101,7 +102,7 @@ const validTransitions = {
  *
  * @typedef {{
  *   interestSnapshot: Ratio,
- *   outerUpdater: IterationObserver<VaultUIState> | null,
+ *   outerUpdater: IterationObserver<VaultNotification> | null,
  *   phase: VaultPhase,
  *   debtSnapshot: Amount<'nat'>,
  * }} MutableState
@@ -302,7 +303,7 @@ const helperBehavior = {
    */
   getStateSnapshot: ({ state, facets }, newPhase) => {
     const { debtSnapshot: debt, interestSnapshot: interest } = state;
-    /** @type {VaultUIState} */
+    /** @type {VaultNotification} */
     return harden({
       // TODO move manager state to a separate notifer https://github.com/Agoric/agoric-sdk/issues/4540
       interestRate: state.manager.getGovernedParams().getInterestRate(),

packages/run-protocol/src/vaultFactory/vaultDirector.js

@@ -18,7 +18,7 @@ import { Far } from '@endo/marshal';
 import { AmountMath } from '@agoric/ertp';
 import { assertKeywordName } from '@agoric/zoe/src/cleanProposal.js';
 import { defineKindMulti } from '@agoric/vat-data';
-import { observeIteration } from '@agoric/notifier';
+import { makeSubscriptionKit, observeIteration } from '@agoric/notifier';
 import { makeVaultManager } from './vaultManager.js';
 import { makeMakeCollectFeesInvitation } from '../collectFees.js';
 import {
@@ -31,11 +31,18 @@ import {
 const { details: X } = assert;
 
 /**
+ * @typedef {{
+ * collaterals: Brand[],
+ * rewardPoolAllocation: AmountKeywordRecord,
+ * }} MetricsNotification
+ *
  * @typedef {Readonly<{
  * debtMint: ZCFMint<'nat'>,
  * collateralTypes: Store<Brand,VaultManager>,
  * electionManager: Instance,
  * directorParamManager: import('@agoric/governance/src/contractGovernance/typedParamManager').TypedParamManager<import('./params.js').VaultDirectorParams>,
+ * metricsPublication: IterationObserver<MetricsNotification>
+ * metricsSubscription: Subscription<MetricsNotification>
  * mintSeat: ZCFSeat,
  * rewardPoolSeat: ZCFSeat,
  * vaultParamManagers: Store<Brand, import('./params.js').VaultParamManager>,
@@ -68,10 +75,15 @@ const initState = (zcf, directorParamManager, debtMint) => {
 
   const vaultParamManagers = makeScalarMap('brand');
 
+  const { publication: metricsPublication, subscription: metricsSubscription } =
+    makeSubscriptionKit();
+
   return {
     collateralTypes,
     debtMint,
     directorParamManager,
+    metricsSubscription,
+    metricsPublication,
     mintSeat,
     rewardPoolSeat,
     vaultParamManagers,
@@ -149,9 +161,8 @@ const getCollaterals = async ({ state }) => {
     ),
   );
 };
-
 /**
- * @param {import('@agoric/governance/src/contractGovernance/typedParamManager').TypedParamManager<import('./params.js').VaultDirectorParams>} directorParamManager
+ * @param {ImmutableState['directorParamManager']} directorParamManager
  */
 const getLiquidationConfig = directorParamManager => ({
   install: directorParamManager.getLiquidationInstall(),
@@ -160,7 +171,7 @@ const getLiquidationConfig = directorParamManager => ({
 
 /**
  *
- * @param {*} govParams
+ * @param {ImmutableState['directorParamManager']} govParams
  * @param {VaultManager} vaultManager
  * @param {*} oldInstall
  * @param {*} oldTerms
@@ -192,7 +203,7 @@ const machineBehavior = {
    * @param {VaultManagerParamValues} initialParamValues
    */
   addVaultType: async (
-    { state },
+    { state, facets },
     collateralIssuer,
     collateralKeyword,
     initialParamValues,
@@ -256,6 +267,7 @@ const machineBehavior = {
       }
       // TODO add aggregate debt tracking at the vaultFactory level #4482
       // totalDebt = AmountMath.add(totalDebt, toMint);
+      facets.machine.updateMetrics();
     };
 
     /**
@@ -291,6 +303,7 @@ const machineBehavior = {
     const { install, terms } = getLiquidationConfig(directorParamManager);
     await vm.setupLiquidator(install, terms);
     watchGovernance(directorParamManager, vm, install, terms);
+    facets.machine.updateMetrics();
     return vm;
   },
   getCollaterals,
@@ -306,6 +319,15 @@ const machineBehavior = {
   },
   /** @param {MethodContext} context */
   getContractGovernor: ({ state }) => state.zcf.getTerms().electionManager,
+  /** @param {MethodContext} context */
+  updateMetrics: ({ state }) => {
+    /** @type {MetricsNotification} */
+    const metrics = harden({
+      collaterals: Array.from(state.collateralTypes.keys()),
+      rewardPoolAllocation: state.rewardPoolSeat.getCurrentAllocation(),
+    });
+    state.metricsPublication.updateState(metrics);
+  },
 
   // XXX accessors for tests
   /** @param {MethodContext} context */
@@ -356,6 +378,11 @@ const publicBehavior = {
     /** @type {VaultManager} */
     return collateralTypes.get(brandIn).getPublicFacet();
   },
+  /**
+   * @param {MethodContext} context
+   */
+  getMetrics: ({ state }) => state.metricsSubscription,
+
   /** @deprecated use getCollateralManager and then makeVaultInvitation instead */
   makeLoanInvitation: makeVaultInvitation,
   /** @deprecated use getCollateralManager and then makeVaultInvitation instead */