@agoric/fast-usdc 0.1.1-dev-02967de.0

package/src/exos/status-manager.js

@@ -0,0 +1,176 @@
+import { M } from '@endo/patterns';
+import { makeError, q } from '@endo/errors';
+
+import { appendToStoredArray } from '@agoric/store/src/stores/store-utils.js';
+import { CctpTxEvidenceShape, PendingTxShape } from '../type-guards.js';
+import { PendingTxStatus } from '../constants.js';
+
+/**
+ * @import {MapStore, SetStore} from '@agoric/store';
+ * @import {Zone} from '@agoric/zone';
+ * @import {CctpTxEvidence, NobleAddress, SeenTxKey, PendingTxKey, PendingTx} from '../types.js';
+ */
+
+/**
+ * Create the key for the pendingTxs MapStore.
+ *
+ * The key is a composite of `txHash` and `chainId` and not meant to be
+ * parsable.
+ *
+ * @param {NobleAddress} addr
+ * @param {bigint} amount
+ * @returns {PendingTxKey}
+ */
+const makePendingTxKey = (addr, amount) =>
+  `pendingTx:${JSON.stringify([addr, String(amount)])}`;
+
+/**
+ * Get the key for the pendingTxs MapStore.
+ *
+ * @param {CctpTxEvidence} evidence
+ * @returns {PendingTxKey}
+ */
+const pendingTxKeyOf = evidence => {
+  const { amount, forwardingAddress } = evidence.tx;
+  return makePendingTxKey(forwardingAddress, amount);
+};
+
+/**
+ * Get the key for the seenTxs SetStore.
+ *
+ * The key is a composite of `NobleAddress` and transaction `amount` and not
+ * meant to be parsable.
+ *
+ * @param {CctpTxEvidence} evidence
+ * @returns {SeenTxKey}
+ */
+const seenTxKeyOf = evidence => {
+  const { txHash, chainId } = evidence;
+  return `seenTx:${JSON.stringify([txHash, chainId])}`;
+};
+
+/**
+ * The `StatusManager` keeps track of Pending and Seen Transactions
+ * via {@link PendingTxStatus} states, aiding in coordination between the `Advancer`
+ * and `Settler`.
+ *
+ * XXX consider separate facets for `Advancing` and `Settling` capabilities.
+ *
+ * @param {Zone} zone
+ */
+export const prepareStatusManager = zone => {
+  /** @type {MapStore<PendingTxKey, PendingTx[]>} */
+  const pendingTxs = zone.mapStore('PendingTxs', {
+    keyShape: M.string(),
+    valueShape: M.arrayOf(PendingTxShape),
+  });
+
+  /** @type {SetStore<SeenTxKey>} */
+  const seenTxs = zone.setStore('SeenTxs', {
+    keyShape: M.string(),
+  });
+
+  /**
+   * Ensures that `txHash+chainId` has not been processed
+   * and adds entry to `seenTxs` set.
+   *
+   * Also records the CctpTxEvidence and status in `pendingTxs`.
+   *
+   * @param {CctpTxEvidence} evidence
+   * @param {PendingTxStatus} status
+   */
+  const recordPendingTx = (evidence, status) => {
+    const seenKey = seenTxKeyOf(evidence);
+    if (seenTxs.has(seenKey)) {
+      throw makeError(`Transaction already seen: ${q(seenKey)}`);
+    }
+    seenTxs.add(seenKey);
+
+    appendToStoredArray(
+      pendingTxs,
+      pendingTxKeyOf(evidence),
+      harden({ ...evidence, status }),
+    );
+  };
+
+  return zone.exo(
+    'Fast USDC Status Manager',
+    M.interface('StatusManagerI', {
+      advance: M.call(CctpTxEvidenceShape).returns(M.undefined()),
+      observe: M.call(CctpTxEvidenceShape).returns(M.undefined()),
+      hasPendingSettlement: M.call(M.string(), M.bigint()).returns(M.boolean()),
+      settle: M.call(M.string(), M.bigint()).returns(M.undefined()),
+      lookupPending: M.call(M.string(), M.bigint()).returns(
+        M.arrayOf(PendingTxShape),
+      ),
+    }),
+    {
+      /**
+       * Add a new transaction with ADVANCED status
+       * @param {CctpTxEvidence} evidence
+       */
+      advance(evidence) {
+        recordPendingTx(evidence, PendingTxStatus.Advanced);
+      },
+
+      /**
+       * Add a new transaction with OBSERVED status
+       * @param {CctpTxEvidence} evidence
+       */
+      observe(evidence) {
+        recordPendingTx(evidence, PendingTxStatus.Observed);
+      },
+
+      /**
+       * Find an `ADVANCED` or `OBSERVED` tx waiting to be `SETTLED`
+       *
+       * @param {NobleAddress} address
+       * @param {bigint} amount
+       * @returns {boolean}
+       */
+      hasPendingSettlement(address, amount) {
+        const key = makePendingTxKey(address, amount);
+        const pending = pendingTxs.get(key);
+        return !!pending.length;
+      },
+
+      /**
+       * Mark an `ADVANCED` or `OBSERVED` transaction as `SETTLED` and remove it
+       *
+       * @param {NobleAddress} address
+       * @param {bigint} amount
+       */
+      settle(address, amount) {
+        const key = makePendingTxKey(address, amount);
+        const pending = pendingTxs.get(key);
+
+        if (!pending.length) {
+          throw makeError(`No unsettled entry for ${q(key)}`);
+        }
+
+        const pendingCopy = [...pending];
+        pendingCopy.shift();
+        // TODO, vstorage update for `TxStatus.Settled`
+        pendingTxs.set(key, harden(pendingCopy));
+      },
+
+      /**
+       * Lookup all pending entries for a given address and amount
+       *
+       * @param {NobleAddress} address
+       * @param {bigint} amount
+       * @returns {PendingTx[]}
+       */
+      lookupPending(address, amount) {
+        const key = makePendingTxKey(address, amount);
+        if (!pendingTxs.has(key)) {
+          throw makeError(`Key ${q(key)} not yet observed`);
+        }
+        return pendingTxs.get(key);
+      },
+    },
+  );
+};
+harden(prepareStatusManager);
+
+/** @typedef {ReturnType<typeof prepareStatusManager>} StatusManager */

package/src/exos/transaction-feed.js

@@ -0,0 +1,180 @@
+import { makeTracer } from '@agoric/internal';
+import { prepareDurablePublishKit } from '@agoric/notifier';
+import { M } from '@endo/patterns';
+import { CctpTxEvidenceShape } from '../type-guards.js';
+import { defineInertInvitation } from '../utils/zoe.js';
+import { prepareOperatorKit } from './operator-kit.js';
+
+/**
+ * @import {Zone} from '@agoric/zone';
+ * @import {OperatorKit} from './operator-kit.js';
+ * @import {CctpTxEvidence} from '../types.js';
+ */
+
+const trace = makeTracer('TxFeed', true);
+
+/** Name in the invitation purse (keyed also by this contract instance) */
+export const INVITATION_MAKERS_DESC = 'oracle operator invitation';
+
+const TransactionFeedKitI = harden({
+  operatorPowers: M.interface('Transaction Feed Admin', {
+    submitEvidence: M.call(CctpTxEvidenceShape, M.any()).returns(),
+  }),
+  creator: M.interface('Transaction Feed Creator', {
+    // TODO narrow the return shape to OperatorKit
+    initOperator: M.call(M.string()).returns(M.record()),
+    makeOperatorInvitation: M.call(M.string()).returns(M.promise()),
+    removeOperator: M.call(M.string()).returns(),
+  }),
+  public: M.interface('Transaction Feed Public', {
+    getEvidenceSubscriber: M.call().returns(M.remotable()),
+  }),
+});
+
+/**
+ * @param {Zone} zone
+ * @param {ZCF} zcf
+ */
+export const prepareTransactionFeedKit = (zone, zcf) => {
+  const kinds = zone.mapStore('Kinds');
+  const makeDurablePublishKit = prepareDurablePublishKit(
+    kinds,
+    'Transaction Feed',
+  );
+  /** @type {PublishKit<CctpTxEvidence>} */
+  const { publisher, subscriber } = makeDurablePublishKit();
+
+  const makeInertInvitation = defineInertInvitation(zcf, 'submitting evidence');
+
+  const makeOperatorKit = prepareOperatorKit(zone, {
+    makeInertInvitation,
+  });
+
+  return zone.exoClassKit(
+    'Fast USDC Feed',
+    TransactionFeedKitI,
+    () => {
+      /** @type {MapStore<string, OperatorKit>} */
+      const operators = zone.mapStore('operators', {
+        durable: true,
+      });
+      /** @type {MapStore<string, MapStore<string, CctpTxEvidence>>} */
+      const pending = zone.mapStore('pending', {
+        durable: true,
+      });
+      return { operators, pending };
+    },
+    {
+      creator: {
+        /**
+         * An "operator invitation" is an invitation to be an operator in the
+         * oracle netowrk, with the able to submit data to submit evidence of
+         * CCTP transactions.
+         *
+         * @param {string} operatorId unique per contract instance
+         * @returns {Promise<Invitation<OperatorKit>>}
+         */
+        makeOperatorInvitation(operatorId) {
+          const { creator } = this.facets;
+          trace('makeOperatorInvitation', operatorId);
+
+          return zcf.makeInvitation(
+            /** @type {OfferHandler<OperatorKit>} */
+            seat => {
+              seat.exit();
+              return creator.initOperator(operatorId);
+            },
+            INVITATION_MAKERS_DESC,
+          );
+        },
+        /** @param {string} operatorId */
+        initOperator(operatorId) {
+          const { operators, pending } = this.state;
+          trace('initOperator', operatorId);
+
+          const operatorKit = makeOperatorKit(
+            operatorId,
+            this.facets.operatorPowers,
+          );
+          operators.init(operatorId, operatorKit);
+          pending.init(
+            operatorId,
+            zone.detached().mapStore('pending evidence'),
+          );
+
+          return operatorKit;
+        },
+
+        /** @param {string} operatorId */
+        async removeOperator(operatorId) {
+          const { operators } = this.state;
+          trace('removeOperator', operatorId);
+          const operatorKit = operators.get(operatorId);
+          operatorKit.admin.disable();
+          operators.delete(operatorId);
+        },
+      },
+      operatorPowers: {
+        /**
+         * Add evidence from an operator.
+         *
+         * @param {CctpTxEvidence} evidence
+         * @param {OperatorKit} operatorKit
+         */
+        submitEvidence(evidence, operatorKit) {
+          const { pending } = this.state;
+          trace(
+            'submitEvidence',
+            operatorKit.operator.getStatus().operatorId,
+            evidence,
+          );
+          const { operatorId } = operatorKit.operator.getStatus();
+
+          // TODO should this verify that the operator is one made by this exo?
+          // This doesn't work...
+          // operatorKit === operators.get(operatorId) ||
+          //   Fail`operatorKit mismatch`;
+
+          // TODO validate that it's a valid for Fast USDC before accepting
+          // E.g. that the `recipientAddress` is the FU settlement account and that
+          // the EUD is a chain supported by FU.
+          const { txHash } = evidence;
+
+          // accept the evidence
+          {
+            const pendingStore = pending.get(operatorId);
+            if (pendingStore.has(txHash)) {
+              trace(`operator ${operatorId} already reported ${txHash}`);
+            } else {
+              pendingStore.init(txHash, evidence);
+            }
+          }
+
+          // check agreement
+          const found = [...pending.values()].filter(store =>
+            store.has(txHash),
+          );
+          // TODO determine the real policy for checking agreement
+          if (found.length < pending.getSize()) {
+            // not all have seen it
+            return;
+          }
+
+          // TODO verify that all found deep equal
+
+          // all agree, so remove from pending and publish
+          for (const pendingStore of pending.values()) {
+            pendingStore.delete(txHash);
+          }
+          publisher.publish(evidence);
+        },
+      },
+      public: {
+        getEvidenceSubscriber: () => subscriber,
+      },
+    },
+  );
+};
+harden(prepareTransactionFeedKit);
+
+/** @typedef {ReturnType<ReturnType<typeof prepareTransactionFeedKit>>} TransactionFeedKit */

package/src/fast-usdc.contract.js

@@ -0,0 +1,216 @@
+import { AssetKind } from '@agoric/ertp';
+import {
+  assertAllDefined,
+  deeplyFulfilledObject,
+  makeTracer,
+} from '@agoric/internal';
+import { observeIteration, subscribeEach } from '@agoric/notifier';
+import {
+  OrchestrationPowersShape,
+  withOrchestration,
+} from '@agoric/orchestration';
+import { provideSingleton } from '@agoric/zoe/src/contractSupport/durability.js';
+import { prepareRecorderKitMakers } from '@agoric/zoe/src/contractSupport/recorder.js';
+import { E } from '@endo/far';
+import { M, objectMap } from '@endo/patterns';
+import { depositToSeat } from '@agoric/zoe/src/contractSupport/zoeHelpers.js';
+import { prepareAdvancer } from './exos/advancer.js';
+import { prepareLiquidityPoolKit } from './exos/liquidity-pool.js';
+import { prepareSettler } from './exos/settler.js';
+import { prepareStatusManager } from './exos/status-manager.js';
+import { prepareTransactionFeedKit } from './exos/transaction-feed.js';
+import { defineInertInvitation } from './utils/zoe.js';
+import { FastUSDCTermsShape, FeeConfigShape } from './type-guards.js';
+
+const trace = makeTracer('FastUsdc');
+
+/**
+ * @import {Denom} from '@agoric/orchestration';
+ * @import {OrchestrationPowers, OrchestrationTools} from '@agoric/orchestration/src/utils/start-helper.js';
+ * @import {Zone} from '@agoric/zone';
+ * @import {OperatorKit} from './exos/operator-kit.js';
+ * @import {CctpTxEvidence, FeeConfig} from './types.js';
+ * @import {RepayAmountKWR, RepayPaymentKWR} from './exos/liquidity-pool.js';
+ */
+
+/**
+ * @typedef {{
+ *   usdcDenom: Denom;
+ * }} FastUsdcTerms
+ */
+
+/** @type {ContractMeta<typeof start>} */
+export const meta = {
+  // @ts-expect-error TypedPattern not recognized as record
+  customTermsShape: FastUSDCTermsShape,
+  privateArgsShape: {
+    // @ts-expect-error TypedPattern not recognized as record
+    ...OrchestrationPowersShape,
+    feeConfig: FeeConfigShape,
+    marshaller: M.remotable(),
+  },
+};
+harden(meta);
+
+/**
+ * @param {ZCF<FastUsdcTerms>} zcf
+ * @param {OrchestrationPowers & {
+ *   marshaller: Marshaller;
+ *   feeConfig: FeeConfig;
+ * }} privateArgs
+ * @param {Zone} zone
+ * @param {OrchestrationTools} tools
+ */
+export const contract = async (zcf, privateArgs, zone, tools) => {
+  assert(tools, 'no tools');
+  const terms = zcf.getTerms();
+  assert('USDC' in terms.brands, 'no USDC brand');
+  assert('usdcDenom' in terms, 'no usdcDenom');
+  const { feeConfig, marshaller } = privateArgs;
+  const { makeRecorderKit } = prepareRecorderKitMakers(
+    zone.mapStore('vstorage'),
+    marshaller,
+  );
+  const statusManager = prepareStatusManager(zone);
+  const makeSettler = prepareSettler(zone, { statusManager });
+  const { chainHub, vowTools } = tools;
+  const makeAdvancer = prepareAdvancer(zone, {
+    chainHub,
+    feeConfig,
+    log: trace,
+    usdc: harden({
+      brand: terms.brands.USDC,
+      denom: terms.usdcDenom,
+    }),
+    statusManager,
+    vowTools,
+  });
+  const makeFeedKit = prepareTransactionFeedKit(zone, zcf);
+  assertAllDefined({ makeFeedKit, makeAdvancer, makeSettler, statusManager });
+  const feedKit = makeFeedKit();
+  const advancer = makeAdvancer(
+    // @ts-expect-error FIXME
+    {},
+  );
+  // Connect evidence stream to advancer
+  void observeIteration(subscribeEach(feedKit.public.getEvidenceSubscriber()), {
+    updateState(evidence) {
+      try {
+        void advancer.handleTransactionEvent(evidence);
+      } catch (err) {
+        trace('🚨 Error handling transaction event', err);
+      }
+    },
+  });
+  const makeLiquidityPoolKit = prepareLiquidityPoolKit(
+    zone,
+    zcf,
+    terms.brands.USDC,
+    { makeRecorderKit },
+  );
+
+  const makeTestInvitation = defineInertInvitation(
+    zcf,
+    'test of forcing evidence',
+  );
+
+  const creatorFacet = zone.exo('Fast USDC Creator', undefined, {
+    /** @type {(operatorId: string) => Promise<Invitation<OperatorKit>>} */
+    async makeOperatorInvitation(operatorId) {
+      return feedKit.creator.makeOperatorInvitation(operatorId);
+    },
+    /**
+     * @param {{ USDC: Amount<'nat'>}} amounts
+     */
+    testBorrow(amounts) {
+      console.log('🚧🚧 UNTIL: borrow is integrated 🚧🚧', amounts);
+      const { zcfSeat: tmpAssetManagerSeat } = zcf.makeEmptySeatKit();
+      // eslint-disable-next-line no-use-before-define
+      poolKit.borrower.borrow(tmpAssetManagerSeat, amounts);
+      return tmpAssetManagerSeat.getCurrentAllocation();
+    },
+    /**
+     *
+     * @param {RepayAmountKWR} amounts
+     * @param {RepayPaymentKWR} payments
+     * @returns {Promise<AmountKeywordRecord>}
+     */
+    async testRepay(amounts, payments) {
+      console.log('🚧🚧 UNTIL: repay is integrated 🚧🚧', amounts);
+      const { zcfSeat: tmpAssetManagerSeat } = zcf.makeEmptySeatKit();
+      await depositToSeat(
+        zcf,
+        tmpAssetManagerSeat,
+        await deeplyFulfilledObject(
+          objectMap(payments, pmt => E(terms.issuers.USDC).getAmountOf(pmt)),
+        ),
+        payments,
+      );
+      // eslint-disable-next-line no-use-before-define
+      poolKit.repayer.repay(tmpAssetManagerSeat, amounts);
+      return tmpAssetManagerSeat.getCurrentAllocation();
+    },
+  });
+
+  const publicFacet = zone.exo('Fast USDC Public', undefined, {
+    // XXX to be removed before production
+    /**
+     * NB: Any caller with access to this invitation maker has the ability to
+     * force handling of evidence.
+     *
+     * Provide an API call in the form of an invitation maker, so that the
+     * capability is available in the smart-wallet bridge during UI testing.
+     *
+     * @param {CctpTxEvidence} evidence
+     */
+    makeTestPushInvitation(evidence) {
+      void advancer.handleTransactionEvent(evidence);
+      return makeTestInvitation();
+    },
+    makeDepositInvitation() {
+      // eslint-disable-next-line no-use-before-define
+      return poolKit.public.makeDepositInvitation();
+    },
+    makeWithdrawInvitation() {
+      // eslint-disable-next-line no-use-before-define
+      return poolKit.public.makeWithdrawInvitation();
+    },
+    getPublicTopics() {
+      // eslint-disable-next-line no-use-before-define
+      return poolKit.public.getPublicTopics();
+    },
+  });
+
+  // ^^^ Define all kinds above this line. Keep remote calls below. vvv
+
+  // NOTE: Using a ZCFMint is helpful for the usual reasons (
+  // synchronous mint/burn, keeping assets out of contract vats, ...).
+  // And there's just one pool, which suggests building it with zone.exo().
+  //
+  // But zone.exo() defines a kind and
+  // all kinds have to be defined before any remote calls,
+  // such as the one to the zoe vat as part of making a ZCFMint.
+  //
+  // So we use zone.exoClassKit above to define the liquidity pool kind
+  // and pass the shareMint into the maker / init function.
+
+  const shareMint = await provideSingleton(
+    zone.mapStore('mint'),
+    'PoolShare',
+    () =>
+      zcf.makeZCFMint('PoolShares', AssetKind.NAT, {
+        decimalPlaces: 6,
+      }),
+  );
+
+  const poolKit = zone.makeOnce('Liquidity Pool kit', () =>
+    makeLiquidityPoolKit(shareMint, privateArgs.storageNode),
+  );
+
+  return harden({ creatorFacet, publicFacet });
+};
+harden(contract);
+
+export const start = withOrchestration(contract);
+harden(start);
+/** @typedef {typeof start} FastUsdcSF */