@agoric/inter-protocol 0.13.4-pismo-dev-0d5327f.0 → 0.14.0

package/src/price/fluxAggregatorContract.js

@@ -0,0 +1,190 @@
+// @jessie-check
+
+import {
+  hasIssuer,
+  makeDurableIssuerKit,
+  prepareIssuerKit,
+} from '@agoric/ertp';
+import { handleParamGovernance } from '@agoric/governance';
+import { makeTracer, StorageNodeShape } from '@agoric/internal';
+import { prepareDurablePublishKit } from '@agoric/notifier';
+import { M } from '@agoric/store';
+import { provideAll } from '@agoric/zoe/src/contractSupport/durability.js';
+import { prepareRecorder } from '@agoric/zoe/src/contractSupport/recorder.js';
+import { E } from '@endo/eventual-send';
+import { reserveThenDeposit } from '../proposals/utils.js';
+import { prepareFluxAggregatorKit } from './fluxAggregatorKit.js';
+
+const trace = makeTracer('FluxAgg');
+/**
+ * @typedef {import('@agoric/vat-data').Baggage} Baggage
+ * @typedef {import('@agoric/time/src/types').TimerService} TimerService
+ */
+
+export const privateArgsShape = M.splitRecord(
+  harden({
+    storageNode: StorageNodeShape,
+    marshaller: M.eref(M.remotable('marshaller')),
+    namesByAddressAdmin: M.any(),
+  }),
+  harden({
+    // always optional. XXX some code is including the key, set to null
+    highPrioritySendersManager: M.or(
+      M.remotable('prioritySenders manager'),
+      M.null(),
+    ),
+    // only necessary on first invocation, not subsequent
+    initialPoserInvitation: M.remotable('Invitation'),
+  }),
+);
+
+/**
+ * PriceAuthority for their median. Unlike the simpler `priceAggregator.js`, this approximates
+ * the *Node Operator Aggregation* logic of [Chainlink price
+ * feeds](https://blog.chain.link/levels-of-data-aggregation-in-chainlink-price-feeds/).
+ *
+ * @param {ZCF<import('./fluxAggregatorKit.js').ChainlinkConfig & {
+ * timer: TimerService,
+ * brandIn: Brand<'nat'>,
+ * brandOut: Brand<'nat'>,
+ * description: string,
+ * unitAmountIn?: Amount<'nat'>,
+ * }>} zcf
+ * @param {{
+ * highPrioritySendersManager?: import('@agoric/internal/src/priority-senders.js').PrioritySendersManager,
+ * initialPoserInvitation: Invitation,
+ * marshaller: ERef<Marshaller>,
+ * namesByAddressAdmin: ERef<import('@agoric/vats').NameAdmin>,
+ * storageNode: StorageNode,
+ * }} privateArgs
+ * @param {Baggage} baggage
+ */
+export const prepare = async (zcf, privateArgs, baggage) => {
+  trace('prepare with baggage keys', [...baggage.keys()]);
+
+  // xxx uses contract baggage as issuerBagage, assumes one issuer in this contract
+  /** @type {import('./roundsManager.js').QuoteKit} */
+  const quoteIssuerKit = hasIssuer(baggage)
+    ? prepareIssuerKit(baggage)
+    : makeDurableIssuerKit(baggage, 'quote', 'set');
+
+  const {
+    highPrioritySendersManager,
+    initialPoserInvitation,
+    marshaller,
+    namesByAddressAdmin,
+    storageNode,
+  } = privateArgs;
+
+  const { description, timer } = zcf.getTerms();
+
+  trace('awaited args');
+
+  const makeDurablePublishKit = prepareDurablePublishKit(
+    baggage,
+    'Price Aggregator publish kit',
+  );
+  const makeRecorder = prepareRecorder(baggage, marshaller);
+
+  const makeFluxAggregatorKit = await prepareFluxAggregatorKit(
+    baggage,
+    zcf,
+    timer,
+    quoteIssuerKit,
+    storageNode,
+    makeDurablePublishKit,
+    makeRecorder,
+  );
+
+  const { faKit } = await provideAll(baggage, {
+    faKit: () => makeFluxAggregatorKit(),
+  });
+  trace('got faKit', faKit);
+
+  // cannot be stored in baggage because not durable
+  // UNTIL https://github.com/Agoric/agoric-sdk/issues/4343
+  const { makeDurableGovernorFacet } = handleParamGovernance(
+    // @ts-expect-error FIXME include Governance params
+    zcf,
+    initialPoserInvitation,
+    {
+      // No governed parameters. Governance just for API methods.
+    },
+    storageNode,
+    marshaller,
+  );
+
+  trace('got makeDurableGovernorFacet', makeDurableGovernorFacet);
+
+  /**
+   * Initialize a new oracle and send an invitation to control it.
+   *
+   * @param {string} addr
+   */
+  const addOracle = async addr => {
+    trace('addOracle', addr);
+    const invitation = await E(faKit.creator).makeOracleInvitation(addr);
+    // XXX imported from 'proposals' path
+    await reserveThenDeposit(
+      `fluxAggregator oracle ${addr}`,
+      namesByAddressAdmin,
+      addr,
+      [invitation],
+    );
+    if (highPrioritySendersManager) {
+      // eslint-disable-next-line @jessie.js/no-nested-await -- after another await
+      await E(highPrioritySendersManager).add(description, addr);
+    }
+    return `added ${addr}`;
+  };
+
+  /**
+   * Remove an oracle from aggregation and disable its facet.
+   *
+   * @param {string} addr
+   */
+  const removeOracle = async addr => {
+    trace('removeOracle', addr);
+    await E(faKit.creator).removeOracle(addr);
+    if (highPrioritySendersManager) {
+      // eslint-disable-next-line @jessie.js/no-nested-await -- after another await
+      await E(highPrioritySendersManager).remove(description, addr);
+    }
+    return `removed ${addr}`;
+  };
+
+  const governedApis = {
+    /**
+     * Add the specified oracles. May partially fail, such that some oracles are added and others aren't.
+     *
+     * @param {string[]} addrs
+     * @returns {Promise<Array<PromiseSettledResult<string>>>}
+     */
+    addOracles: addrs => {
+      return Promise.allSettled(addrs.map(addOracle));
+    },
+    /**
+     * Remove the specified oracles. May partially fail, such that some oracles are removed and others aren't.
+     * If the oracle was never part of the set that's a PromiseRejectedResult
+     *
+     * @param {string[]} addrs
+     * @returns {Promise<Array<PromiseSettledResult<string>>>}
+     */
+    removeOracles: addrs => {
+      return Promise.allSettled(addrs.map(removeOracle));
+    },
+  };
+
+  const { governorFacet } = makeDurableGovernorFacet(
+    baggage,
+    faKit.creator,
+    governedApis,
+  );
+  trace('made governorFacet', governorFacet);
+
+  return harden({
+    creatorFacet: governorFacet,
+    publicFacet: faKit.public,
+  });
+};
+harden(prepare);

package/src/price/fluxAggregatorKit.js

@@ -0,0 +1,375 @@
+/**
+ * @file
+ * Adaptation of Chainlink algorithm to the Agoric platform.
+ * Modeled on https://github.com/smartcontractkit/chainlink/blob/master/contracts/src/v0.6/FluxAggregator.sol (version?)
+ */
+import { AmountMath } from '@agoric/ertp';
+import { assertAllDefined, makeTracer } from '@agoric/internal';
+import {
+  makeNotifierFromSubscriber,
+  observeNotifier,
+  SubscriberShape,
+} from '@agoric/notifier';
+import { M, makeScalarBigMapStore, prepareExoClassKit } from '@agoric/vat-data';
+import {
+  defineRecorderKit,
+  makeOnewayPriceAuthorityKit,
+  makeRecorderTopic,
+  provideAll,
+} from '@agoric/zoe/src/contractSupport/index.js';
+import { E } from '@endo/eventual-send';
+import { Far } from '@endo/marshal';
+import { prepareOracleAdminKit } from './priceOracleKit.js';
+import { prepareRoundsManagerKit } from './roundsManager.js';
+
+const trace = makeTracer('FlxAgg', true);
+
+export const INVITATION_MAKERS_DESC = 'oracle invitation';
+
+/**
+ * @typedef {import('@agoric/vat-data').Baggage} Baggage
+ * @typedef {import('@agoric/time/src/types').Timestamp} Timestamp
+ * @typedef {import('@agoric/time/src/types').RelativeTime} RelativeTime
+ * // TODO: use RelativeTime, not RelativeTimeValue
+ * @typedef {import('@agoric/time/src/types').RelativeTimeValue} RelativeTimeValue
+ * @typedef {import('@agoric/time/src/types').TimerService} TimerService
+ */
+
+/** @type {(quote: PriceQuote) => PriceDescription} */
+const priceDescriptionFromQuote = quote => quote.quoteAmount.value[0];
+
+/**
+ * @typedef {object} RoundState
+ * @property {boolean} eligibleForSpecificRound
+ * @property {bigint} queriedRoundId
+ * @property {bigint} latestSubmission
+ * @property {Timestamp} startedAt
+ * @property {number} roundTimeout
+ * @property {number} oracleCount
+ */
+
+// Partly documented at https://github.com/smartcontractkit/chainlink/blob/b045416ebca769aa69bde2da23b5109abe07a8b5/contracts/src/v0.6/FluxAggregator.sol#L153
+/**
+ * @typedef {object} ChainlinkConfig
+ * @property {number} maxSubmissionCount
+ * @property {number} minSubmissionCount
+ * @property {bigint} restartDelay the number of rounds an Oracle has to wait before they can initiate a round
+ * @property {number} minSubmissionValue an immutable check for a lower bound of what
+ * submission values are accepted from an oracle
+ * @property {number} maxSubmissionValue an immutable check for an upper bound of what
+ * submission values are accepted from an oracle
+ * @property {number} timeout the number of seconds after the previous round that
+ * allowed to lapse before allowing an oracle to skip an unfinished round
+ */
+
+/**
+ * Returns a maker for a single durable FluxAggregatorKit, closed over the prepare() arguments.
+ *
+ * The kit aggregates price inputs to produce a PriceAuthority. Unlike the
+ * simpler `priceAggregator.js`, this approximates the *Node Operator
+ * Aggregation* logic of [Chainlink price
+ * feeds](https://blog.chain.link/levels-of-data-aggregation-in-chainlink-price-feeds/).
+ *
+ * @param {Baggage} baggage
+ * @param {ZCF<ChainlinkConfig & {
+ * timer: TimerService,
+ * brandIn: Brand<'nat'>,
+ * brandOut: Brand<'nat'>,
+ * unitAmountIn?: Amount<'nat'>,
+ * }>} zcf
+ * @param {TimerService} timerPresence
+ * @param {import('./roundsManager.js').QuoteKit} quoteKit
+ * @param {StorageNode} storageNode
+ * @param {() => PublishKit<any>} makeDurablePublishKit
+ * @param {import('@agoric/zoe/src/contractSupport/recorder.js').MakeRecorder} makeRecorder
+ */
+export const prepareFluxAggregatorKit = async (
+  baggage,
+  zcf,
+  timerPresence,
+  quoteKit,
+  storageNode,
+  makeDurablePublishKit,
+  makeRecorder,
+) => {
+  // brands come from named terms instead of `brands` key because the latter is
+  // a StandardTerm that Zoe creates from the `issuerKeywordRecord` argument and
+  // Oracle brands are inert (without issuers or mints).
+  const {
+    brandIn,
+    brandOut,
+    maxSubmissionCount,
+    maxSubmissionValue,
+    minSubmissionCount,
+    minSubmissionValue,
+    restartDelay,
+    timeout,
+
+    unitAmountIn = AmountMath.make(brandIn, 1n),
+  } = zcf.getTerms();
+
+  assertAllDefined({
+    brandIn,
+    brandOut,
+    maxSubmissionCount,
+    maxSubmissionValue,
+    minSubmissionCount,
+    minSubmissionValue,
+    restartDelay,
+    timeout,
+    unitAmountIn,
+  });
+
+  const makeRoundsManagerKit = prepareRoundsManagerKit(baggage);
+  const makeOracleAdminKit = prepareOracleAdminKit(baggage);
+
+  const makeRecorderKit = defineRecorderKit({
+    // @ts-expect-error XXX
+    makeDurablePublishKit,
+    makeRecorder,
+  });
+
+  // end of maker definitions /////////////////////////////////
+
+  const { answerKit, latestRoundKit, priceKit } = await provideAll(baggage, {
+    /** This is just a signal that there's a new answer, which is read from `lastValueOutForUnitIn` */
+    answerKit: () => makeDurablePublishKit(),
+    /** For publishing priceAuthority values to off-chain storage */
+    priceKit: () =>
+      makeRecorderKit(
+        storageNode,
+        /** @type {import('@agoric/zoe/src/contractSupport/recorder.js').TypedMatcher<PriceDescription>} */ (
+          M.any()
+        ),
+      ),
+    latestRoundKit: () =>
+      E.when(E(storageNode).makeChildNode('latestRound'), node =>
+        makeRecorderKit(
+          node,
+          /** @type {import('@agoric/zoe/src/contractSupport/recorder.js').TypedMatcher<import('./roundsManager.js').LatestRound>} */ (
+            M.any()
+          ),
+        ),
+      ),
+  });
+
+  const { roundsManagerKit } = await provideAll(baggage, {
+    roundsManagerKit: () =>
+      makeRoundsManagerKit(
+        harden({
+          answerPublisher: answerKit.publisher,
+          brandIn,
+          brandOut,
+          latestRoundPublisher: latestRoundKit.recorder,
+          minSubmissionCount,
+          maxSubmissionCount,
+          minSubmissionValue,
+          maxSubmissionValue,
+          quoteKit,
+          restartDelay,
+          timerPresence,
+          timeout,
+          unitAmountIn,
+        }),
+      ),
+  });
+
+  // not durable, held in closure and remade in every call of enclosing
+  const { priceAuthority } = makeOnewayPriceAuthorityKit({
+    createQuote: roundsManagerKit.contract.makeCreateQuote(),
+    notifier: makeNotifierFromSubscriber(answerKit.subscriber),
+    quoteIssuer: quoteKit.issuer,
+    timer: timerPresence,
+    actualBrandIn: brandIn,
+    actualBrandOut: brandOut,
+  });
+
+  // for each new quote from the priceAuthority, publish it to off-chain storage
+  void observeNotifier(
+    priceAuthority.makeQuoteNotifier(unitAmountIn, brandOut),
+    {
+      updateState: quote => {
+        void priceKit.recorder.write(priceDescriptionFromQuote(quote));
+      },
+      fail: reason => {
+        throw Error(`priceAuthority observer failed: ${reason}`);
+      },
+      finish: done => {
+        throw Error(`priceAuthority observer died: ${done}`);
+      },
+    },
+  );
+
+  const makeFluxAggregatorKit = prepareExoClassKit(
+    baggage,
+    'fluxAggregator',
+    {
+      creator: M.interface('fluxAggregator creatorFacet', {}, { sloppy: true }),
+      public: M.interface('fluxAggregator publicFacet', {
+        getPriceAuthority: M.call().returns(M.any()),
+        getSubscriber: M.call().returns(SubscriberShape),
+        getRoundStartNotifier: M.call().returns(SubscriberShape),
+        getPublicTopics: M.call().returns({
+          quotes: M.any(),
+          latestRound: M.any(),
+        }),
+      }),
+    },
+    () => {
+      /** @type {MapStore<string, import('./priceOracleKit.js').OracleKit>} */
+      const oracles = makeScalarBigMapStore('oracles', {
+        durable: true,
+      });
+      return { oracles };
+    },
+    {
+      creator: {
+        /**
+         * An "oracle invitation" is an invitation to be able to submit data to
+         * include in the priceAggregator's results.
+         *
+         * The offer result from this invitation is a OracleAdmin, which can be used
+         * directly to manage the price submissions as well as to terminate the
+         * relationship.
+         *
+         * @param {string} oracleId unique per contract instance
+         */
+        async makeOracleInvitation(oracleId) {
+          const { facets } = this;
+          trace('makeOracleInvitation', oracleId);
+          /**
+           * If custom arguments are supplied to the `zoe.offer` call, they can
+           * indicate an OraclePriceSubmission notifier and a corresponding
+           * `shiftValueOut` that should be adapted as part of the priceAuthority's
+           * reported data.
+           *
+           * @param {ZCFSeat} seat
+           */
+          const offerHandler = async seat => {
+            const { oracle } = await facets.creator.initOracle(oracleId);
+            const invitationMakers = Far('invitation makers', {
+              /** @param {import('./roundsManager.js').PriceRound} result */
+              PushPrice(result) {
+                return zcf.makeInvitation(
+                  /** @param {ZCFSeat} cSeat */
+                  async cSeat => {
+                    cSeat.exit();
+                    await oracle.pushPrice(result);
+                  },
+                  'PushPrice',
+                );
+              },
+            });
+            seat.exit();
+
+            return harden({
+              invitationMakers,
+              oracle,
+            });
+          };
+
+          return zcf.makeInvitation(offerHandler, INVITATION_MAKERS_DESC);
+        },
+        /** @param {string} oracleId */
+        async removeOracle(oracleId) {
+          const { oracles } = this.state;
+          trace('deleteOracle', oracleId);
+          const kit = oracles.get(oracleId);
+          kit.admin.disable();
+          oracles.delete(oracleId);
+        },
+
+        getRoundData: roundIdRaw => {
+          return roundsManagerKit.contract.getRoundData(roundIdRaw);
+        },
+
+        /** @param {string} oracleId */
+        async initOracle(oracleId) {
+          const { oracles } = this.state;
+          trace('initOracle', oracleId);
+          assert.typeof(oracleId, 'string');
+
+          const oracleKit = makeOracleAdminKit(
+            harden({
+              minSubmissionValue,
+              maxSubmissionValue,
+              oracleId, // must be unique per vat
+              roundPowers: roundsManagerKit.oracle,
+              timer: timerPresence,
+            }),
+          );
+          oracles.init(oracleId, oracleKit);
+
+          return oracleKit;
+        },
+
+        /**
+         * a method to provide all current info oracleStatuses need. Intended only
+         * only to be callable by oracleStatuses. Not for use by contracts to read state.
+         *
+         * @param {string} oracleId
+         * @param {bigint} queriedRoundId
+         * @returns {Promise<RoundState>}
+         */
+        async oracleRoundState(oracleId, queriedRoundId) {
+          const { oracles } = this.state;
+          const blockTimestamp = await E(timerPresence).getCurrentTimestamp();
+          const status = await E(oracles.get(oracleId).oracle).getStatus();
+
+          const oracleCount = oracles.getSize();
+
+          const { contract } = roundsManagerKit;
+          if (queriedRoundId > 0) {
+            const roundStatus = contract.getRoundStatus(queriedRoundId);
+            return {
+              eligibleForSpecificRound: contract.eligibleForSpecificRound(
+                status,
+                queriedRoundId,
+                blockTimestamp,
+              ),
+              queriedRoundId,
+              latestSubmission: status.latestSubmission,
+              startedAt: roundStatus.startedAt,
+              roundTimeout: roundStatus.roundTimeout,
+              oracleCount,
+            };
+          } else {
+            return {
+              ...contract.oracleRoundStateSuggestRound(status, blockTimestamp),
+              oracleCount,
+            };
+          }
+        },
+      },
+      public: {
+        getPriceAuthority() {
+          return priceAuthority;
+        },
+        /** @deprecated use getPublicTopics */
+        getSubscriber: () => {
+          return priceKit.subscriber;
+        },
+        /** @deprecated use getPublicTopics */
+        getRoundStartNotifier() {
+          return latestRoundKit.subscriber;
+        },
+        getPublicTopics() {
+          return {
+            quotes: makeRecorderTopic(
+              'Quotes from this price aggregator',
+              priceKit,
+            ),
+            latestRound: makeRecorderTopic(
+              'Notification of each round',
+              latestRoundKit,
+            ),
+          };
+        },
+      },
+    },
+  );
+
+  return makeFluxAggregatorKit;
+};
+harden(prepareFluxAggregatorKit);
+/** @typedef {ReturnType<Awaited<ReturnType<typeof prepareFluxAggregatorKit>>>} FluxAggregatorKit */

package/src/price/priceOracleKit.js

@@ -0,0 +1,127 @@
+import { Fail } from '@agoric/assert';
+import { makeTracer } from '@agoric/internal';
+import { M, prepareExoClassKit } from '@agoric/vat-data';
+
+const trace = makeTracer('OrKit', true);
+
+export const INVITATION_MAKERS_DESC = 'oracle invitation';
+
+/**
+ * @typedef {{
+ *   oracleId: string,
+ *   roundPowers: { handlePush: (status: OracleStatus, result: import('./roundsManager.js').PriceRound) => Promise<OracleStatus> }
+ * }} HeldParams
+ */
+
+/**
+ * @typedef {{ roundId: number | undefined, unitPrice: NatValue }} PriceDatum
+ */
+
+/**
+ * @typedef {object} OracleStatus
+ * @property {boolean} [disabled]
+ * @property {bigint} lastReportedRound
+ * @property {bigint} lastStartedRound
+ * @property {bigint} latestSubmission
+ * @property {string} oracleId
+ */
+/**
+ * @typedef {Readonly<HeldParams & {
+ * }>} ImmutableState
+ *
+ * @typedef {OracleStatus & {
+ * }} MutableState
+ */
+/** @typedef {ImmutableState & MutableState} State */
+
+/**
+ * @param {HeldParams} heldParams
+ * @returns {State}
+ */
+const initState = ({ oracleId, roundPowers }) => {
+  return {
+    oracleId,
+    roundPowers,
+    disabled: false,
+    lastReportedRound: 0n,
+    lastStartedRound: 0n,
+    latestSubmission: 0n,
+  };
+};
+
+const AdminI = M.interface('OracleKitAdmin', {
+  disable: M.call().returns(),
+});
+
+const OracleI = M.interface('Oracle', {
+  pushPrice: M.call(
+    M.splitRecord(
+      { unitPrice: M.bigint() },
+      { roundId: M.or(M.bigint(), M.number()) },
+    ),
+  ).returns(M.promise()),
+  getStatus: M.call().returns(M.record()),
+});
+
+export const prepareOracleAdminKit = baggage =>
+  prepareExoClassKit(
+    baggage,
+    'OracleKit',
+    { admin: AdminI, oracle: OracleI },
+    initState,
+    {
+      admin: {
+        disable() {
+          trace(`oracle ${this.state.oracleId} disabled`);
+          this.state.disabled = true;
+        },
+      },
+      oracle: {
+        /**
+         * push a unitPrice result from this oracle
+         *
+         * @param {PriceDatum} datum
+         */
+        async pushPrice({
+          roundId: roundIdRaw = undefined,
+          unitPrice: valueRaw,
+        }) {
+          const { state } = this;
+          !state.disabled || Fail`pushPrice for disabled oracle`;
+          const { roundPowers } = state;
+          const result = await roundPowers.handlePush(
+            {
+              oracleId: state.oracleId,
+              lastReportedRound: state.lastReportedRound,
+              lastStartedRound: state.lastStartedRound,
+              latestSubmission: state.latestSubmission,
+            },
+            {
+              roundId: roundIdRaw,
+              unitPrice: valueRaw,
+            },
+          );
+
+          state.lastReportedRound = result.lastReportedRound;
+          state.lastStartedRound = result.lastStartedRound;
+          state.latestSubmission = result.latestSubmission;
+        },
+        /**
+         *
+         * @returns {OracleStatus}
+         */
+        getStatus() {
+          const { state } = this;
+          return {
+            oracleId: state.oracleId,
+            disabled: state.disabled,
+            lastReportedRound: state.lastReportedRound,
+            lastStartedRound: state.lastStartedRound,
+            latestSubmission: state.latestSubmission,
+          };
+        },
+      },
+    },
+  );
+
+/** @typedef {ReturnType<ReturnType<typeof prepareOracleAdminKit>>} OracleKit */