@agoric/inter-protocol 0.16.2-dev-5dc325b.0 → 0.16.2-getting-started-dev-d127d1d.0

package/src/interest.js

@@ -12,7 +12,6 @@ import { TimeMath } from '@agoric/time';
 
 /**
  * @typedef {import('@agoric/time/src/types').Timestamp} Timestamp
- *
  * @typedef {import('@agoric/time/src/types').RelativeTime} RelativeTime
  */
 
@@ -21,7 +20,9 @@ const BASIS_POINTS = 10000;
 // single digit APR is less than a basis point per day.
 const LARGE_DENOMINATOR = BASIS_POINTS * BASIS_POINTS;
 
-/** Number chosen from 6 digits for a basis point, doubled for multiplication. */
+/**
+ * Number chosen from 6 digits for a basis point, doubled for multiplication.
+ */
 const COMPOUNDED_INTEREST_DENOMINATOR = 10n ** 20n;
 
 /**
@@ -146,27 +147,20 @@ const validatedBrand = (mint, debt) => {
  * Charge interest accrued between `latestInterestUpdate` and `accruedUntil`.
  *
  * @param {{
- *   mint: ZCFMint<'nat'>;
- *   mintAndTransferWithFee: MintAndTransfer;
- *   poolIncrementSeat: ZCFSeat;
- *   seatAllocationKeyword: Keyword;
- * }} powers
+ *  mint: ZCFMint<'nat'>,
+ *  mintAndTransferWithFee: MintAndTransfer,
+ *  poolIncrementSeat: ZCFSeat,
+ *  seatAllocationKeyword: Keyword }} powers
  * @param {{
- *   interestRate: Ratio;
- *   chargingPeriod: RelativeTime;
- *   recordingPeriod: RelativeTime;
- * }} params
+ *  interestRate: Ratio,
+ *  chargingPeriod: RelativeTime,
+ *  recordingPeriod: RelativeTime}} params
  * @param {{
- *   latestInterestUpdate: Timestamp;
- *   compoundedInterest: Ratio;
- *   totalDebt: Amount<'nat'>;
- * }} prior
+ *  latestInterestUpdate: Timestamp,
+ *  compoundedInterest: Ratio,
+ *  totalDebt: Amount<'nat'>}} prior
  * @param {Timestamp} accruedUntil
- * @returns {{
- *   compoundedInterest: Ratio;
- *   latestInterestUpdate: Timestamp;
- *   totalDebt: Amount<'nat'>;
- * }}
+ * @returns {{compoundedInterest: Ratio, latestInterestUpdate: Timestamp, totalDebt: Amount<'nat'> }}
  */
 export const chargeInterest = (powers, params, prior, accruedUntil) => {
   const brand = validatedBrand(powers.mint, prior.totalDebt);

package/src/price/README.md

@@ -4,19 +4,6 @@ This directory contains the `fluxAggregatorKit.js` contract which takes prices a
 input and outputs a best known price. There are multiple ways to get the price,
 including a PriceAuthority interface.
 
-## Design
-
-The authorities are hierarchical. Many authorities can be registered in the priceAuthorityRegistry.
-
-For oracles, there must be two: the negotiable brand and the _oracle_ brand (an inert one).
-
-The intended flow is that:
-1. a negotiable brand is created (e.g. ATOM)
-2. a price provider says “i can give you quotes for that” and runs price-feed-proposal. That makes “oracleBrands” (which are inert and have a separate identity so that they don’t have the authority to say they’re the real quote for it).
-3. Some higher authority (eg EC, Stakers) decides that should be the quote source for negotiable brand so it registers it under the real brand identity in the registry (with a new instance of a scaledPriceAuthority ).
-
-In practice we do these all in one core proposal. And each vault manager is started with a limit on minting to the EC has another way to gate transactions.
-
 ## Usage
 
 See the [Smart Wallet integration test](/packages/inter-protocol/test/smartWallet/test-oracle-integration.js) for how it's used.

package/src/price/fluxAggregatorContract.js

@@ -1,6 +1,10 @@
 // @jessie-check
 
-import { prepareIssuerKit } from '@agoric/ertp';
+import {
+  hasIssuer,
+  makeDurableIssuerKit,
+  prepareIssuerKit,
+} from '@agoric/ertp';
 import { handleParamGovernance } from '@agoric/governance';
 import { makeTracer, StorageNodeShape } from '@agoric/internal';
 import { prepareDurablePublishKit } from '@agoric/notifier';
@@ -14,67 +18,55 @@ import { prepareFluxAggregatorKit } from './fluxAggregatorKit.js';
 const trace = makeTracer('FluxAgg', false);
 /**
  * @typedef {import('@agoric/vat-data').Baggage} Baggage
- *
  * @typedef {import('@agoric/time/src/types').TimerService} TimerService
  */
 
-/** @type {ContractMeta} */
-export const meta = {
-  privateArgsShape: M.splitRecord(
-    {
-      storageNode: StorageNodeShape,
-      marshaller: M.eref(M.remotable('marshaller')),
-      namesByAddressAdmin: M.any(),
-    },
-    {
-      // 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'),
-    },
-  ),
-  upgradability: 'canUpgrade',
-};
-harden(meta);
+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
+ * 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 {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;
+ * 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 start = async (zcf, privateArgs, 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 = prepareIssuerKit(
-    baggage,
-    'quote',
-    'set',
-    undefined,
-    undefined,
-  );
+  const quoteIssuerKit = hasIssuer(baggage)
+    ? prepareIssuerKit(baggage)
+    : makeDurableIssuerKit(baggage, 'quote', 'set');
 
   const {
     highPrioritySendersManager,
@@ -139,8 +131,10 @@ export const start = async (zcf, privateArgs, baggage) => {
       addr,
       [invitation],
     );
-    await (highPrioritySendersManager &&
-      E(highPrioritySendersManager).add(description, addr));
+    if (highPrioritySendersManager) {
+      // eslint-disable-next-line @jessie.js/no-nested-await -- after another await
+      await E(highPrioritySendersManager).add(description, addr);
+    }
     return `added ${addr}`;
   };
 
@@ -152,29 +146,29 @@ export const start = async (zcf, privateArgs, baggage) => {
   const removeOracle = async addr => {
     trace('removeOracle', addr);
     await E(faKit.creator).removeOracle(addr);
-    await (highPrioritySendersManager &&
-      E(highPrioritySendersManager).remove(description, 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.
+     * Add the specified oracles. May partially fail, such that some oracles are added and others aren't.
      *
      * @param {string[]} addrs
-     * @returns {Promise<PromiseSettledResult<string>[]>}
+     * @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
+     * 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<PromiseSettledResult<string>[]>}
+     * @returns {Promise<Array<PromiseSettledResult<string>>>}
      */
     removeOracles: addrs => {
       return Promise.allSettled(addrs.map(removeOracle));
@@ -193,4 +187,4 @@ export const start = async (zcf, privateArgs, baggage) => {
     publicFacet: faKit.public,
   });
 };
-harden(start);
+harden(prepare);

package/src/price/fluxAggregatorKit.js

@@ -1,7 +1,7 @@
 /**
- * @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?)
+ * @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';
@@ -24,14 +24,10 @@ 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').RelativeTime} RelativeTime
+ * // TODO: use RelativeTime, not RelativeTimeValue
  * @typedef {import('@agoric/time/src/types').RelativeTimeValue} RelativeTimeValue
- *
  * @typedef {import('@agoric/time/src/types').TimerService} TimerService
  */
 
@@ -53,35 +49,30 @@ const priceDescriptionFromQuote = quote => quote.quoteAmount.value[0];
  * @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
+ * @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.
+ * 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
+ * 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 {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
@@ -137,10 +128,7 @@ export const prepareFluxAggregatorKit = async (
   // 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`
-     */
+    /** 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: () =>
@@ -154,11 +142,9 @@ export const prepareFluxAggregatorKit = async (
       E.when(E(storageNode).makeChildNode('latestRound'), node =>
         makeRecorderKit(
           node,
-          /**
-           * @type {import('@agoric/zoe/src/contractSupport/recorder.js').TypedMatcher<
-           *     import('./roundsManager.js').LatestRound
-           *   >}
-           */ (M.any()),
+          /** @type {import('@agoric/zoe/src/contractSupport/recorder.js').TypedMatcher<import('./roundsManager.js').LatestRound>} */ (
+            M.any()
+          ),
         ),
       ),
   });
@@ -237,9 +223,9 @@ export const prepareFluxAggregatorKit = async (
          * 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.
+         * 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
          */
@@ -249,13 +235,12 @@ export const prepareFluxAggregatorKit = async (
           /**
            * 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.
+           * `shiftValueOut` that should be adapted as part of the priceAuthority's
+           * reported data.
            *
            * @param {ZCFSeat} seat
            */
           const offerHandler = async seat => {
-            seat.exit();
             const { oracle } = await facets.creator.initOracle(oracleId);
             const invitationMakers = Far('invitation makers', {
               /** @param {import('./roundsManager.js').PriceRound} result */
@@ -270,6 +255,7 @@ export const prepareFluxAggregatorKit = async (
                 );
               },
             });
+            seat.exit();
 
             return harden({
               invitationMakers,
@@ -313,9 +299,8 @@ export const prepareFluxAggregatorKit = async (
         },
 
         /**
-         * 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.
+         * 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

package/src/price/priceOracleKit.js

@@ -8,17 +8,14 @@ export const INVITATION_MAKERS_DESC = 'oracle invitation';
 
 /**
  * @typedef {{
- *   oracleId: string;
- *   roundPowers: {
- *     handlePush: (
- *       status: OracleStatus,
- *       result: import('./roundsManager.js').PriceRound,
- *     ) => Promise<OracleStatus>;
- *   };
+ *   oracleId: string,
+ *   roundPowers: { handlePush: (status: OracleStatus, result: import('./roundsManager.js').PriceRound) => Promise<OracleStatus> }
  * }} HeldParams
  */
 
-/** @typedef {{ roundId: number | undefined; unitPrice: NatValue }} PriceDatum */
+/**
+ * @typedef {{ roundId: number | undefined, unitPrice: NatValue }} PriceDatum
+ */
 
 /**
  * @typedef {object} OracleStatus
@@ -29,9 +26,11 @@ export const INVITATION_MAKERS_DESC = 'oracle invitation';
  * @property {string} oracleId
  */
 /**
- * @typedef {Readonly<HeldParams & {}>} ImmutableState
+ * @typedef {Readonly<HeldParams & {
+ * }>} ImmutableState
  *
- * @typedef {OracleStatus & {}} MutableState
+ * @typedef {OracleStatus & {
+ * }} MutableState
  */
 /** @typedef {ImmutableState & MutableState} State */
 
@@ -107,7 +106,10 @@ export const prepareOracleAdminKit = baggage =>
           state.lastStartedRound = result.lastStartedRound;
           state.latestSubmission = result.latestSubmission;
         },
-        /** @returns {OracleStatus} */
+        /**
+         *
+         * @returns {OracleStatus}
+         */
         getStatus() {
           const { state } = this;
           return {