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

package/src/econCommitteeCharter.js

@@ -1,102 +1,186 @@
-// @ts-check
+// @jessie-check
 
-import '@agoric/governance/src/exported.js';
+import '@agoric/governance/exported.js';
+import { M, mustMatch } from '@agoric/store';
+import { TimestampShape } from '@agoric/time';
+import { prepareExo, provideDurableMapStore } from '@agoric/vat-data';
 import '@agoric/zoe/exported.js';
 import '@agoric/zoe/src/contracts/exported.js';
-
-import { E, Far } from '@endo/far';
+import {
+  InstallationShape,
+  InstanceHandleShape,
+} from '@agoric/zoe/src/typeGuards.js';
+import { E } from '@endo/far';
 
 /**
  * @file
  *
- * This extremely quick and dirty contract simplifies the process of
- * calling for votes on changes to the economy by gathering the governor creator
- * facets in one place and invokes `voteOnParamChanges` and
- * `voteOnApiInvocation` on each when requested. A cleaner version would
- * validate parameters, constrain deadlines and probably split the ability to
- * call for vote into separate capabilities for finer grain encapsulation.
+ * This contract makes it possible for those who govern contracts to call for
+ * votes on changes. A more complete implementation would validate parameters,
+ * constrain deadlines and possibly split the ability to call for votes into
+ * separate capabilities for finer grain encapsulation.
+ */
+
+export const INVITATION_MAKERS_DESC = 'charter member invitation';
+
+/**
+ * @typedef {object} ParamChangesOfferArgs
+ * @property {bigint} deadline
+ * @property {Instance} instance
+ * @property {Record<string, unknown>} params
+ * @property {{paramPath: { key: string }}} [path]
  */
+const ParamChangesOfferArgsShape = M.splitRecord(
+  {
+    deadline: TimestampShape,
+    instance: InstanceHandleShape,
+    params: M.recordOf(M.string(), M.any()),
+  },
+  {
+    path: { paramPath: { key: M.any() } },
+  },
+);
 
 /**
- * @param {ZCF<{binaryVoteCounterInstallation:Installation}>} zcf
- * @param {{reserve:GovernedContractFacetAccess<{},{}>, amm:GovernedCreatorFacet<{}>, vaults:GovernedCreatorFacet<{}>}} privateArgs
+ * A pattern for Zoe to check custom terms before `start()`ing the contract.
  */
-export const start = async (zcf, privateArgs) => {
+export const customTermsShape = harden({
+  binaryVoteCounterInstallation: InstallationShape,
+});
+
+/**
+ * @param {ZCF<{binaryVoteCounterInstallation: Installation}>} zcf
+ * @param {undefined} privateArgs
+ * @param {import('@agoric/vat-data').Baggage} baggage
+ */
+export const prepare = async (zcf, privateArgs, baggage) => {
   const { binaryVoteCounterInstallation: counter } = zcf.getTerms();
-  const { reserve, amm, vaults } = privateArgs;
+  /** @type {MapStore<Instance, GovernorCreatorFacet<any>>} */
+  const instanceToGovernor = provideDurableMapStore(
+    baggage,
+    'instanceToGovernor',
+  );
+
+  const makeParamInvitation = () => {
+    /**
+     * @param {ZCFSeat} seat
+     * @param {ParamChangesOfferArgs} args
+     */
+    const voteOnParamChanges = (seat, args) => {
+      mustMatch(args, ParamChangesOfferArgsShape);
+      seat.exit();
+
+      const {
+        params,
+        instance,
+        deadline,
+        path = { paramPath: { key: 'governedApi' } },
+      } = args;
+      const governor = instanceToGovernor.get(instance);
+      return E(governor).voteOnParamChanges(counter, deadline, {
+        ...path,
+        changes: params,
+      });
+    };
+
+    return zcf.makeInvitation(voteOnParamChanges, 'vote on param changes');
+  };
+
+  const makeOfferFilterInvitation = (instance, strings, deadline) => {
+    const voteOnOfferFilterHandler = seat => {
+      seat.exit();
+
+      const governor = instanceToGovernor.get(instance);
+      return E(governor).voteOnOfferFilter(counter, deadline, strings);
+    };
+
+    return zcf.makeInvitation(voteOnOfferFilterHandler, 'vote on offer filter');
+  };
 
   /**
-   * @param {*} target
-   * @param {Record<string, unknown>} params
-   * @param {bigint} deadline
-   * @param {{paramPath: { key: unknown }}} [path]
+   * @param {Instance} instance
+   * @param {string} methodName
+   * @param {string[]} methodArgs
+   * @param {import('@agoric/time').TimestampValue} deadline
    */
-  const voteOnParamChanges = (
-    target,
-    params,
+  const makeApiInvocationInvitation = (
+    instance,
+    methodName,
+    methodArgs,
     deadline,
-    path = { paramPath: { key: 'governedApi' } },
   ) => {
-    return E(target).voteOnParamChanges(counter, deadline, {
-      ...path,
-      changes: params,
-    });
-  };
+    const handler = seat => {
+      seat.exit();
 
-  /**
-   * @param {*} target
-   * @param {string} method
-   * @param {unknown[]} args
-   * @param {bigint} deadline
-   */
-  const voteOnApiInvocation = (target, method, args, deadline) => {
-    return E(target).voteOnApiInvocation(method, args, counter, deadline);
+      const governor = instanceToGovernor.get(instance);
+      return E(governor).voteOnApiInvocation(
+        methodName,
+        methodArgs,
+        counter,
+        deadline,
+      );
+    };
+    return zcf.makeInvitation(handler, 'vote on API invocation');
   };
 
-  const makeNullInvitation = () => {
-    return zcf.makeInvitation(() => {}, 'econCommitteeCharter noop');
+  const MakerI = M.interface('Charter InvitationMakers', {
+    VoteOnParamChange: M.call().returns(M.promise()),
+    VoteOnPauseOffers: M.call(
+      InstanceHandleShape,
+      M.arrayOf(M.string()),
+      TimestampShape,
+    ).returns(M.promise()),
+    VoteOnApiCall: M.call(
+      InstanceHandleShape,
+      M.string(),
+      M.arrayOf(M.any()),
+      TimestampShape,
+    ).returns(M.promise()),
+  });
+
+  // durable so that when this contract is upgraded this ocap held
+  // by committee members (from their invitations) stay capable
+  const invitationMakers = prepareExo(
+    baggage,
+    'Charter Invitation Makers',
+    MakerI,
+    {
+      VoteOnParamChange: makeParamInvitation,
+      VoteOnPauseOffers: makeOfferFilterInvitation,
+      VoteOnApiCall: makeApiInvocationInvitation,
+    },
+  );
+
+  const charterMemberHandler = seat => {
+    seat.exit();
+    return harden({ invitationMakers });
   };
 
-  const publicFacet = Far('votingAPI', {
-    /**
-     * @param {Record<string, unknown>} params
-     * @param {bigint} deadline
-     */
-    voteOnAmmParamChanges: (params, deadline) =>
-      voteOnParamChanges(amm, params, deadline),
-    /**
-     * @param {Record<string, unknown>} params
-     * @param {bigint} deadline
-     */
-    voteOnReserveParamChanges: (params, deadline) =>
-      voteOnParamChanges(reserve, params, deadline),
-    /**
-     * vote on param changes for a vaultManager
-     *
-     * @param {Record<string, unknown>} params
-     * @param {{collateralBrand: Brand}} brand
-     * @param {bigint} deadline
-     */
-    voteOnVaultParamChanges: (params, brand, deadline) =>
-      voteOnParamChanges(vaults, params, deadline, {
-        paramPath: { key: brand },
-      }),
-    /**
-     * vote on param changes across the vaultFactory
-     *
-     * @param {Record<string, unknown>} params
-     * @param {bigint} deadline
-     */
-    voteOnVaultFactoryParamChanges: (params, deadline) =>
-      voteOnParamChanges(vaults, params, deadline),
-    /**
-     * @param {Amount[]} amounts
-     * @param {bigint} deadline
-     */
-    voteOnReserveApiInvocation: (amounts, deadline) =>
-      voteOnApiInvocation(reserve, 'addLiquidityToAmmPool', amounts, deadline),
-    makeNullInvitation,
+  const charterCreatorI = M.interface('Charter creatorFacet', {
+    addInstance: M.call(InstanceHandleShape, M.any())
+      .optional(M.string())
+      .returns(),
+    makeCharterMemberInvitation: M.call().returns(M.promise()),
   });
 
-  return harden({ publicFacet });
+  const creatorFacet = prepareExo(
+    baggage,
+    'Charter creatorFacet',
+    charterCreatorI,
+    {
+      /**
+       * @param {Instance} governedInstance
+       * @param {GovernorCreatorFacet<any>} governorFacet
+       * @param {string} [label] for diagnostic use only
+       */
+      addInstance: (governedInstance, governorFacet, label) => {
+        console.log('charter: adding instance', label);
+        instanceToGovernor.init(governedInstance, governorFacet);
+      },
+      makeCharterMemberInvitation: () =>
+        zcf.makeInvitation(charterMemberHandler, INVITATION_MAKERS_DESC),
+    },
+  );
+
+  return harden({ creatorFacet });
 };

package/src/feeDistributor.js

@@ -1,16 +1,32 @@
-// @ts-check
-
 import { AmountMath } from '@agoric/ertp';
+import { splitMany } from '@agoric/ertp/src/legacy-payment-helpers.js';
 import { E, Far } from '@endo/far';
+import { Nat } from '@endo/nat';
 import { observeNotifier } from '@agoric/notifier';
-import { makeScalarSetStore } from '@agoric/store';
+import { mustMatch, makeScalarSetStore, M } from '@agoric/store';
+import { RelativeTimeShape } from '@agoric/time';
+import { KeywordShape } from '@agoric/zoe/src/typeGuards.js';
+
+const KeywordSharesShape = M.recordOf(KeywordShape, M.nat());
+
+/**
+ * A pattern for Zoe to check custom terms before `start()`ing the contract.
+ */
+export const customTermsShape = harden({
+  keywordShares: KeywordSharesShape,
+  timerService: M.eref(M.remotable('TimerService')),
+  collectionInterval: RelativeTimeShape,
+});
 
-const { details: X } = assert;
+/**
+ * @typedef {import('@agoric/time/src/types').RelativeTime} RelativeTime
+ * @typedef {import('@agoric/time/src/types').TimerService} TimerService
+ */
 
 /**
  * @typedef {object} FeeCollector
  *
- * @property {() => ERef<Payment>} collectFees
+ * @property {() => ERef<Payment<'nat'>>} collectFees
  */
 
 /**
@@ -22,11 +38,11 @@ const { details: X } = assert;
 
 /**
  * @typedef {object} CollectibleContractFacet
- * @property {() => Promise<Invitation>} makeCollectFeesInvitation
+ * @property {() => Promise<Invitation<string, never>>} makeCollectFeesInvitation
  */
 
 /**
- * wrapper to take the vaultFactory or AMM's creatorFacet, and make a call that
+ * wrapper to take the a creatorFacet (e.g. vaultFactory) and make a call that
  * will request an invitation and return a promise for a payment.
  *
  * @param {ERef<ZoeService>} zoe
@@ -86,15 +102,14 @@ export const startDistributing = (
  * @typedef {{ pushPayment: (payment: Payment, issuer: ERef<Issuer>) => Promise<Amount>}} FeeDestination
  *
  * @param {Record<Keyword, ERef<FeeDestination>>} [destinations]
- * @param {Record<Keyword, bigint>} [keywordShares]
+ * @param {Record<Keyword, NatValue>} [keywordShares]
  */
 export const makeShareConfig = (destinations = {}, keywordShares = {}) => {
   let totalShares = 0n;
   const shares = Object.entries(destinations)
     .filter(([_, dst]) => dst)
     .map(([kw, destination]) => {
-      const share = keywordShares[kw];
-      assert.typeof(share, 'bigint', X`${kw} must be a bigint; got ${share}`);
+      const share = Nat(keywordShares[kw]);
       totalShares += share;
       return {
         share,
@@ -109,8 +124,8 @@ export const makeShareConfig = (destinations = {}, keywordShares = {}) => {
 /**
  * Split and deposit a payment given a share configuration.
  *
- * @param {Payment} payment
- * @param {ERef<Issuer>} issuer
+ * @param {Payment<'nat'>} payment
+ * @param {ERef<Issuer<'nat'>>} issuer
  * @param {ShareConfig} shareConfig
  */
 export const sharePayment = async (
@@ -145,8 +160,25 @@ export const sharePayment = async (
     })
     .filter(([_, amt]) => !AmountMath.isEmpty(amt));
 
+  /**
+   * If the `sharedPayment[i]` payments that are sent to the fee
+   * `destination` with `pushPayment` never arrive, or never get deposited
+   * (or otherwise used up), then they remain in the recovery set of the
+   * `recoveryPurse`. The purpose of this, and of recovery sets in general,
+   * is to be able, in emergencies, to recover the assets of payments in flight
+   * that seem to be stuck. This is much like cancelling a check that may still
+   * be undeposited.
+   *
+   * TODO: However, for this to be possible, the `recoveryPurse` holding that
+   * recovery set must remain accessible to someone that should legitimately
+   * be able to recover those payments. But this `recoveryPurse` is currently
+   * dropped on the floor instead.
+   */
+  const recoveryPurse = E(issuer).makeEmptyPurse();
+
   // Split the payment, which asserts conservation of the total.
-  const sharedPayment = await E(issuer).splitMany(
+  const sharedPayment = await splitMany(
+    recoveryPurse,
     payment,
     destinedAmountEntries.map(([_dst, amt]) => amt),
   );
@@ -160,20 +192,21 @@ export const sharePayment = async (
 };
 
 /**
- * @param {ERef<Issuer>} feeIssuer
- * @param {{ keywordShares: Record<Keyword, bigint>, timerService: ERef<TimerService>, collectionInterval: RelativeTime}} terms
+ * @param {ERef<Issuer<'nat'>>} feeIssuer
+ * @param {{ keywordShares: Record<Keyword, NatValue>, timerService: ERef<TimerService>, collectionInterval: RelativeTime}} terms
  */
 export const makeFeeDistributor = (feeIssuer, terms) => {
   const { timerService, collectionInterval } = terms;
 
   /** @type {Record<string, ERef<FeeDestination>>} */
   let destinations = {};
-  let shareConfig = makeShareConfig(destinations, terms.keywordShares);
+  let { keywordShares } = terms;
+  let shareConfig = makeShareConfig(destinations, keywordShares);
 
   /** @type {SetStore<FeeCollector>} */
   const collectors = makeScalarSetStore();
 
-  /** @param {Payment} payment */
+  /** @param {Payment<'nat'>} payment */
   const distributeFees = payment =>
     sharePayment(payment, feeIssuer, shareConfig);
 
@@ -190,6 +223,7 @@ export const makeFeeDistributor = (feeIssuer, terms) => {
 
   const publicFacet = Far('feeDistributor publicFacet', {
     distributeFees,
+    getKeywordShares: () => keywordShares,
   });
 
   const creatorFacet = Far('feeDistributor creatorFacet', {
@@ -228,7 +262,7 @@ export const makeFeeDistributor = (feeIssuer, terms) => {
     },
 
     /**
-     * @param {EOnly<DepositFacet>} depositFacet
+     * @param {import('@endo/far').EOnly<DepositFacet>} depositFacet
      */
     makeDepositFacetDestination: depositFacet => {
       return Far(`DepositFacetDestination`, {
@@ -282,14 +316,20 @@ export const makeFeeDistributor = (feeIssuer, terms) => {
     },
 
     /**
-     * @param {Record<Keyword, FeeDestination>} newDestinations
+     * @param {Record<Keyword, ERef<FeeDestination>>} newDestinations
      */
     setDestinations: async newDestinations => {
       destinations = newDestinations;
-      shareConfig = makeShareConfig(destinations, terms.keywordShares);
+      shareConfig = makeShareConfig(destinations, keywordShares);
       // Run once immediately for these destinations.
       await schedulePayments();
     },
+
+    /** @param {Record<Keyword, bigint>} newShares */
+    setKeywordShares: newShares => {
+      mustMatch(newShares, KeywordSharesShape);
+      keywordShares = newShares;
+    },
   });
 
   // Start processing collections.

package/src/index.js

@@ -1 +1,3 @@
+// @jessie-check
+
 export { calculateCurrentDebt } from './interest-math.js';

package/src/interest-math.js

@@ -1,4 +1,4 @@
-// @ts-check
+// @jessie-check
 
 import {
   divideBy,
@@ -9,7 +9,6 @@ import {
 } from '@agoric/zoe/src/contractSupport/ratio.js';
 
 /**
- *
  * @param {Ratio} currentCompoundedInterest as coefficient
  * @param {Ratio} previousCompoundedInterest as coefficient
  * @returns {Ratio} additional compounding since the previous
@@ -26,7 +25,6 @@ const calculateRelativeCompounding = (
 };
 
 /**
- *
  * @param {Amount<'nat'>} debtSnapshot
  * @param {Ratio} interestSnapshot as coefficient
  * @param {Ratio} currentCompoundedInterest as coefficient
@@ -50,7 +48,6 @@ export const calculateCurrentDebt = (
 };
 
 /**
- *
  * @param {Amount<'nat'>} debt
  * @param {Ratio} interestApplied
  * @returns {Amount<'nat'>}

package/src/interest.js

@@ -1,4 +1,4 @@
-// @ts-check
+// @jessie-check
 
 import { AmountMath } from '@agoric/ertp';
 import { natSafeMath } from '@agoric/zoe/src/contractSupport/index.js';
@@ -7,8 +7,13 @@ import {
   multiplyRatios,
   quantize,
 } from '@agoric/zoe/src/contractSupport/ratio.js';
-import { assert, details as X } from '@agoric/assert';
-import { TimeMath } from '@agoric/swingset-vat/src/vats/timer/timeMath.js';
+import { Fail } from '@agoric/assert';
+import { TimeMath } from '@agoric/time';
+
+/**
+ * @typedef {import('@agoric/time/src/types').Timestamp} Timestamp
+ * @typedef {import('@agoric/time/src/types').RelativeTime} RelativeTime
+ */
 
 export const SECONDS_PER_YEAR = 60n * 60n * 24n * 365n;
 const BASIS_POINTS = 10000;
@@ -126,18 +131,15 @@ export const calculateCompoundedInterest = (
 };
 
 /**
- *
- *
- * @param {ZCFMint} mint
- * @param {Amount} debt
+ * @template {AssetKind} K
+ * @param {ZCFMint<K>} mint
+ * @param {Amount<K>} debt
  */
 const validatedBrand = (mint, debt) => {
   const { brand: debtBrand } = debt;
   const { brand: issuerBrand } = mint.getIssuerRecord();
   debtBrand === issuerBrand ||
-    assert.fail(
-      X`Debt and issuer brands differ: ${debtBrand} != ${issuerBrand}`,
-    );
+    Fail`Debt and issuer brands differ: ${debtBrand} != ${issuerBrand}`;
   return issuerBrand;
 };
 
@@ -145,8 +147,8 @@ const validatedBrand = (mint, debt) => {
  * Charge interest accrued between `latestInterestUpdate` and `accruedUntil`.
  *
  * @param {{
- *  mint: ZCFMint,
- *  mintAndReallocateWithFee: MintAndReallocate,
+ *  mint: ZCFMint<'nat'>,
+ *  mintAndTransferWithFee: MintAndTransfer,
  *  poolIncrementSeat: ZCFSeat,
  *  seatAllocationKeyword: Keyword }} powers
  * @param {{
@@ -208,7 +210,12 @@ export const chargeInterest = (powers, params, prior, accruedUntil) => {
 
   // mint that much of brand for the reward pool
   const rewarded = AmountMath.make(brand, interestAccrued);
-  powers.mintAndReallocateWithFee(rewarded, rewarded, powers.poolIncrementSeat);
+  powers.mintAndTransferWithFee(
+    powers.poolIncrementSeat,
+    rewarded,
+    rewarded,
+    [],
+  );
 
   return {
     compoundedInterest,

package/src/price/README.md

@@ -0,0 +1,57 @@
+# Price oracles
+
+This directory contains the `fluxAggregatorKit.js` contract which takes prices as
+input and outputs a best known price. There are multiple ways to get the price,
+including a PriceAuthority interface.
+
+## Usage
+
+See the [Smart Wallet integration test](/packages/inter-protocol/test/smartWallet/test-oracle-integration.js) for how it's used.
+
+Oracle operates can make PushPrice offers in the CLI. There is no GUI.
+
+### CLI
+
+See [oracle.js command file](/packages/agoric-cli/src/commands/oracle.js) and its [integration test script](/packages/agoric-cli/test/agops-oracle-smoketest.sh).
+
+```mermaid
+sequenceDiagram
+
+actor user
+
+participant cli as Oracle
+participant disk
+participant B as Cosmos / Swingset <br/> bridge
+participant C as smart-wallet<br/>contract
+participant flux as Flux Aggregator<br/>contract
+
+user ->> cli: create a PushPrice offer
+user -->> disk: write offer data
+user ->> cli: sign and send PushPrice offer
+disk -->> cli: read offer data
+cli ->> B: spending transaction
+B ->> C: unpack ocap data
+C ->> flux: route offer
+```
+
+### Reading feed
+
+Once a new price has been determined, it's published on the aggregator's public topics.
+
+```mermaid
+sequenceDiagram
+
+actor user
+
+participant cli as Oracle<br>query command
+participant flux as Flux Aggregator<br/>contract
+participant B as Cosmos / Swingset <br/> bridge
+participant RPC as validator RPC
+
+flux ->> B: publish a PriceDescription
+B ->> RPC: write into Merkle tree
+user ->> cli: query the current price
+cli ->> RPC: request head of vstorage for the feed's path
+RPC -->> cli: return the value
+cli -->> user: display pretty version
+```