6701 ec oracles list

packages/SwingSet/src/types-external.js

@@ -303,7 +303,7 @@ export {};
  * Vat Creation and Management
  *
  * @typedef { string } BundleID
- * @typedef {*} BundleCap
+ * @typedef {'BundleCap' & import("@endo/marshal").Remotable<'BundleCap'>} BundleCap
  * @typedef { { moduleFormat: 'endoZipBase64', endoZipBase64: string, endoZipBase64Sha512: string } } EndoZipBase64Bundle
  *
  * @typedef { unknown } Meter

packages/governance/src/contractGovernance/governApi.js

@@ -22,7 +22,7 @@ const { Fail, quote: q } = assert;
 const makeApiInvocationPositions = (apiMethodName, methodArgs) => {
   const positive = harden({ apiMethodName, methodArgs });
   const negative = harden({ dontInvoke: apiMethodName });
-  return { positive, negative };
+  return harden({ positive, negative });
 };
 
 /**
@@ -113,11 +113,11 @@ const setupApiGovernance = async (
         },
       );
 
-    return {
+    return harden({
       outcomeOfUpdate,
       instance: voteCounter,
       details: E(counterPublicFacet).getDetails(),
-    };
+    });
   };
 
   return Far('paramGovernor', {

packages/governance/src/contractGovernance/governParam.js

@@ -51,7 +51,14 @@ const assertBallotConcernsParam = (paramSpec, questionSpec) => {
     Fail`Question path (${issue.spec.paramPath}) doesn't match request (${paramPath})`;
 };
 
-/** @type {SetupGovernance} */
+/**
+ * @param {ERef<ZoeService>} zoe
+ * @param {ERef<ParamManagerRetriever>} paramManagerRetriever
+ * @param {Instance} contractInstance
+ * @param {ERef<import('@agoric/time/src/types').TimerService>} timer
+ * @param {() => Promise<PoserFacet>} getUpdatedPoserFacet
+ * @returns {Promise<ParamGovernor>}
+ */
 const setupParamGovernance = async (
   zoe,
   paramManagerRetriever,

packages/governance/src/contractGovernance/typedParamManager.js

@@ -51,6 +51,10 @@ const isAsync = {
  * @typedef {[type: T, value: ParamValueForType<T>]} ST param spec tuple
  */
 
+/**
+ * @typedef {{ type: 'invitation', value: Amount<'set'> }} InvitationParam
+ */
+
 // XXX better to use the manifest constant ParamTypes
 // but importing that here turns this file into a module,
 // breaking the ambient typing

packages/governance/src/contractGovernor.js

@@ -2,6 +2,7 @@ import { E } from '@endo/eventual-send';
 import { Far } from '@endo/marshal';
 import { mustMatch } from '@agoric/store';
 
+import { makeTracer } from '@agoric/internal';
 import {
   CONTRACT_ELECTORATE,
   setupParamGovernance,
@@ -12,6 +13,8 @@ import { ParamChangesQuestionDetailsShape } from './typeGuards.js';
 
 const { Fail } = assert;
 
+const trace = makeTracer('CGov');
+
 /**
  * Validate that the question details correspond to a parameter change question
  * that the electorate hosts, and that the voteCounter and other details are
@@ -57,7 +60,7 @@ const validateQuestionFromCounter = async (zoe, electorate, voteCounter) => {
 
 /**
  * @typedef {StandardTerms} ContractGovernorTerms
- * @property {import('@agoric/time/src/types').TimerService} timer
+ * @property {ERef<import('@agoric/time/src/types').TimerService>} timer
  * @property {Installation} governedContractInstallation
  */
 
@@ -115,27 +118,40 @@ const validateQuestionFromCounter = async (zoe, electorate, voteCounter) => {
  *   governedContractInstallation: Installation<CF>,
  *   governed: {
  *     issuerKeywordRecord: IssuerKeywordRecord,
- *     terms: {governedParams: {[CONTRACT_ELECTORATE]: Amount<'set'>}},
+ *     terms: {governedParams: {[CONTRACT_ELECTORATE]: InvitationParam}},
  *   }
  * }>}
  */
 
 /**
- * @template {() => {creatorFacet: GovernorFacet<any>, publicFacet: GovernedPublicFacetMethods} } SF Start function of governed contract
+ * @typedef {(zcf?: any, privateArgs?: any, baggage?: any) => import('type-fest').Promisable<{creatorFacet: GovernorFacet<any>, publicFacet: GovernedPublicFacetMethods}>} GovernableStartFn
+ */
+/**
+ * @template {GovernableStartFn} SF Start function of governed contract
+ * @typedef {GovernedContractFacetAccess<Awaited<ReturnType<SF>>['publicFacet'], Awaited<ReturnType<SF>>['creatorFacet']>} GovernedContractFnFacetAccess
+ * Like GovernedContractFacetAccess but templated by the start function
+ */
+
+/**
+ * Start an instance of a governor, governing a "governed" contract specified in terms.
+ *
+ * @template {GovernableStartFn} SF Start function of governed contract
  * @param {ZCF<{
- *   timer: import('@agoric/time/src/types').TimerService,
+ *   timer: ERef<import('@agoric/time/src/types').TimerService>,
  *   governedContractInstallation: Installation<SF>,
  *   governed: {
  *     issuerKeywordRecord: IssuerKeywordRecord,
- *     terms: {governedParams: {[CONTRACT_ELECTORATE]: Amount<'set'>}},
+ *     terms: {governedParams: {[CONTRACT_ELECTORATE]: import('./contractGovernance/typedParamManager.js').InvitationParam}},
  *   }
  * }>} zcf
  * @param {{
  *   governed: Record<string, unknown>
  * }} privateArgs
  */
 const start = async (zcf, privateArgs) => {
+  trace('start');
   const zoe = zcf.getZoeService();
+  trace('getTerms', zcf.getTerms());
   const {
     timer,
     governedContractInstallation,
@@ -144,6 +160,7 @@ const start = async (zcf, privateArgs) => {
       terms: contractTerms,
     },
   } = zcf.getTerms();
+  trace('contractTerms', contractTerms);
   contractTerms.governedParams[CONTRACT_ELECTORATE] ||
     Fail`Contract must declare ${CONTRACT_ELECTORATE} as a governed parameter`;
 
@@ -152,6 +169,13 @@ const start = async (zcf, privateArgs) => {
     electionManager: zcf.getInstance(),
   });
 
+  trace('starting governedContractInstallation');
+  /** @type {{
+   * creatorFacet: GovernorFacet<Awaited<ReturnType<SF>>['creatorFacet']>,
+   * instance: import('@agoric/zoe/src/zoeService/utils').Instance<SF>,
+   * publicFacet: Awaited<ReturnType<SF>>['publicFacet'],
+   * adminFacet: AdminFacet,
+   * }} */
   const {
     creatorFacet: governedCF,
     instance: governedInstance,
@@ -168,6 +192,7 @@ const start = async (zcf, privateArgs) => {
 
   /** @type {() => Promise<Instance>} */
   const getElectorateInstance = async () => {
+    // @ts-expect-error FIXME use getGovernedParams() and possibly a helper
     const invitationAmount = await E(governedPF).getInvitationAmount(
       CONTRACT_ELECTORATE,
     );
@@ -191,9 +216,11 @@ const start = async (zcf, privateArgs) => {
     }
     return poserFacet;
   };
+  trace('awaiting getUpdatedPoserFacet');
   await getUpdatedPoserFacet();
   assert(poserFacet, 'question poser facet must be initialized');
 
+  trace('awaiting setupParamGovernance');
   // All governed contracts have at least a governed electorate
   const { voteOnParamChanges, createdQuestion: createdParamQuestion } =
     await setupParamGovernance(
@@ -204,6 +231,7 @@ const start = async (zcf, privateArgs) => {
       getUpdatedPoserFacet,
     );
 
+  trace('awaiting setupFilterGovernance');
   const { voteOnFilter, createdFilterQuestion } = await setupFilterGovernance(
     zoe,
     governedInstance,
@@ -296,7 +324,11 @@ const start = async (zcf, privateArgs) => {
     voteOnOfferFilter: voteOnFilter,
     getCreatorFacet: () => limitedCreatorFacet,
     getAdminFacet: () => adminFacet,
+    // TODO use distinct names. "governed" could apply to governance aspects or the contract subject to governance
+    // "governee" could be used to name the contract that the governor instantiated
+    // TODO rename to getGoverneeInstance for clarity
     getInstance: () => governedInstance,
+    // TODO rename to getGoverneePublicFacet for clarity
     getPublicFacet: () => governedPF,
   });
 

packages/governance/src/contractHelper.js

@@ -115,7 +115,7 @@ const facetHelpers = (zcf, paramManager) => {
   /**
    * @template {{}} CF
    * @param {CF} limitedCreatorFacet
-   * @param {{}} [governedApis]
+   * @param {Record<string, (...any) => unknown>} [governedApis]
    * @returns {GovernorFacet<CF>}
    */
   const makeFarGovernorFacet = (limitedCreatorFacet, governedApis = {}) => {
@@ -127,7 +127,6 @@ const facetHelpers = (zcf, paramManager) => {
       // The contract provides a facet with the APIs that can be invoked by
       // governance
       /** @type {() => GovernedApis} */
-      // @ts-expect-error TS think this is a RemotableBrand??
       getGovernedApis: () => Far('governedAPIs', governedApis),
       // The facet returned by getGovernedApis is Far, so we can't see what
       // methods it has. There's no clean way to have contracts specify the APIs

packages/governance/src/types-ambient.js

@@ -569,31 +569,32 @@
  * @property {VoteOnParamChanges} voteOnParamChanges
  * @property {VoteOnApiInvocation} voteOnApiInvocation
  * @property {VoteOnOfferFilter} voteOnOfferFilter
- * @property {() => Promise<LimitedCreatorFacet<CF>>} getCreatorFacet - creator
+ * @property {() => ERef<LimitedCreatorFacet<CF>>} getCreatorFacet - creator
  *   facet of the governed contract, without the tightly held ability to change
  *   param values.
  * @property {(poserInvitation: Invitation) => Promise<void>} replaceElectorate
- * @property {() => Promise<AdminFacet>} getAdminFacet
+ * @property {() => ERef<AdminFacet>} getAdminFacet
  * @property {() => GovernedPublicFacet<PF>} getPublicFacet - public facet of the governed contract
  * @property {() => Instance} getInstance - instance of the governed
  *   contract
  */
 
 /**
  * @typedef GovernedPublicFacetMethods
- * @property {() => StoredSubscription<GovernanceSubscriptionState>} getSubscription
+ * @property {(path?: any) => StoredSubscription<GovernanceSubscriptionState>} getSubscription
  * @property {() => Instance} getContractGovernor
- * @property {() => ParamStateRecord} getGovernedParams - get descriptions of
+ * @property {(path?: any) => ParamStateRecord} getGovernedParams - get descriptions of
  *   all the governed parameters
- * @property {(name: string) => Amount} getAmount
- * @property {(name: string) => Brand} getBrand
- * @property {(name: string) => Instance} getInstance
- * @property {(name: string) => Installation} getInstallation
- * @property {(name: string) => Amount} getInvitationAmount
- * @property {(name: string) => bigint} getNat
- * @property {(name: string) => Ratio} getRatio
- * @property {(name: string) => string} getString
- * @property {(name: string) => any} getUnknown
+// FIXME these accessors are onerous for the contract. A facade for them can be made from getGovernedParams()
+//  property {(name: string) => Amount} getAmount
+//  property {(name: string) => Brand} getBrand
+//  property {(name: string) => Instance} getInstance
+//  property {(name: string) => Installation} getInstallation
+//  property {(name: string) => Amount} getInvitationAmount
+//  property {(name: string) => bigint} getNat
+//  property {(name: string) => Ratio} getRatio
+//  property {(name: string) => string} getString
+//  property {(name: string) => any} getUnknown
  */
 
 /**
@@ -633,7 +634,7 @@
 
 /**
  * @typedef {object} ParamManagerRetriever
- * @property {(paramKey?: ParamKey) => AnyParamManager} get
+ * @property {(paramKey: unknown) => AnyParamManager} get
  */
 
 /**
@@ -681,16 +682,6 @@
  * @property {CreatedQuestion} createdFilterQuestion
  */
 
-/**
- * @callback SetupGovernance
- * @param {ERef<ZoeService>} zoe
- * @param {ERef<ParamManagerRetriever>} paramManagerRetriever
- * @param {Instance} contractInstance
- * @param {import('@agoric/time/src/types').TimerService} timer
- * @param {() => Promise<PoserFacet>} getUpdatedPoserFacet
- * @returns {ParamGovernor}
- */
-
 /**
  * @callback CreatedQuestion
  *   Was this question created by this ContractGovernor?

packages/governance/test/unitTests/test-paramGovernance.js

@@ -76,6 +76,14 @@ const setUpGovernedContract = async (zoe, electorateTerms, timer) => {
     installBundle(zoe, voteCounterBundle),
     installBundle(zoe, governedBundle),
   ]);
+  /**
+   * @type {{
+   * governor: Installation<import('../../src/contractGovernor.js').start>,
+   * electorate: Installation<import('../../src/noActionElectorate.js').start>,
+   * counter: Installation<import('../../src/binaryVoteCounter.js').start>,
+   * governed: Installation<import('../swingsetTests/contractGovernor/governedContract.js').start>,
+   * }}
+   */
   const installs = { governor, electorate, counter, governed };
 
   const { creatorFacet: committeeCreator } = await E(zoe).startInstance(