@agoric/fast-usdc 0.1.1-other-dev-3eb1a1d.0 → 0.2.0-u18.0

package/src/exos/status-manager.js

@@ -1,28 +1,39 @@
-import { M } from '@endo/patterns';
-import { makeError, q } from '@endo/errors';
-
+import { makeTracer } from '@agoric/internal';
 import { appendToStoredArray } from '@agoric/store/src/stores/store-utils.js';
-import { CctpTxEvidenceShape, PendingTxShape } from '../type-guards.js';
-import { PendingTxStatus } from '../constants.js';
+import { AmountKeywordRecordShape } from '@agoric/zoe/src/typeGuards.js';
+import { Fail, makeError, q } from '@endo/errors';
+import { E } from '@endo/eventual-send';
+import { M } from '@endo/patterns';
+import { PendingTxStatus, TerminalTxStatus, TxStatus } from '../constants.js';
+import {
+  CctpTxEvidenceShape,
+  EvmHashShape,
+  PendingTxShape,
+} from '../type-guards.js';
 
 /**
  * @import {MapStore, SetStore} from '@agoric/store';
  * @import {Zone} from '@agoric/zone';
- * @import {CctpTxEvidence, NobleAddress, SeenTxKey, PendingTxKey, PendingTx} from '../types.js';
+ * @import {CctpTxEvidence, NobleAddress, PendingTx, EvmHash, LogFn, TransactionRecord, EvidenceWithRisk, RiskAssessment} from '../types.js';
+ */
+
+/**
+ * @typedef {`pendingTx:${bigint}:${NobleAddress}`} PendingTxKey
+ * The string template is for developer visibility but not meant to ever be parsed.
  */
 
 /**
  * Create the key for the pendingTxs MapStore.
  *
- * The key is a composite of `txHash` and `chainId` and not meant to be
- * parsable.
+ * The key is a composite but not meant to be parsable.
  *
- * @param {NobleAddress} addr
+ * @param {NobleAddress} nfa Noble Forwarding Account (implies EUD)
  * @param {bigint} amount
  * @returns {PendingTxKey}
  */
-const makePendingTxKey = (addr, amount) =>
-  `pendingTx:${JSON.stringify([addr, String(amount)])}`;
+const makePendingTxKey = (nfa, amount) =>
+  // amount can't contain colon
+  `pendingTx:${amount}:${nfa}`;
 
 /**
  * Get the key for the pendingTxs MapStore.
@@ -36,18 +47,11 @@ const pendingTxKeyOf = evidence => {
 };
 
 /**
- * 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}
+ * @typedef {{
+ *  log?: LogFn;
+ *  marshaller: ERef<Marshaller>;
+ * }} StatusManagerPowers
  */
-const seenTxKeyOf = evidence => {
-  const { txHash, chainId } = evidence;
-  return `seenTx:${JSON.stringify([txHash, chainId])}`;
-};
 
 /**
  * The `StatusManager` keeps track of Pending and Seen Transactions
@@ -57,19 +61,83 @@ const seenTxKeyOf = evidence => {
  * XXX consider separate facets for `Advancing` and `Settling` capabilities.
  *
  * @param {Zone} zone
+ * @param {ERef<StorageNode>} txnsNode
+ * @param {StatusManagerPowers} caps
  */
-export const prepareStatusManager = zone => {
-  /** @type {MapStore<PendingTxKey, PendingTx[]>} */
+export const prepareStatusManager = (
+  zone,
+  txnsNode,
+  {
+    marshaller,
+    log = makeTracer('Advancer', true),
+  } = /** @type {StatusManagerPowers} */ ({}),
+) => {
+  /**
+   * Keyed by a tuple of the Noble Forwarding Account and amount.
+   * @type {MapStore<PendingTxKey, PendingTx[]>}
+   */
   const pendingTxs = zone.mapStore('PendingTxs', {
     keyShape: M.string(),
     valueShape: M.arrayOf(PendingTxShape),
   });
 
-  /** @type {SetStore<SeenTxKey>} */
+  /**
+   * Transactions seen *ever* by the contract.
+   *
+   * Note that like all durable stores, this SetStore is stored in IAVL. It
+   * grows without bound (though the amount of growth per incoming message to
+   * the contract is bounded). At some point in the future we may want to prune.
+   * @type {SetStore<EvmHash>}
+   */
   const seenTxs = zone.setStore('SeenTxs', {
     keyShape: M.string(),
   });
 
+  /**
+   * Transactions that have completed, but are still in vstorage.
+   *
+   * @type {SetStore<EvmHash>}
+   */
+  const storedCompletedTxs = zone.setStore('StoredCompletedTxs', {
+    keyShape: M.string(),
+  });
+
+  /**
+   * @param {EvmHash} txId
+   * @param {TransactionRecord} record
+   * @returns {Promise<void>}
+   */
+  const publishTxnRecord = async (txId, record) => {
+    const txNode = E(txnsNode).makeChildNode(txId, {
+      sequence: true, // avoid overwriting other output in the block
+    });
+
+    // XXX awkward for publish* to update a store, but it's temporary
+    if (record.status && TerminalTxStatus[record.status]) {
+      // UNTIL https://github.com/Agoric/agoric-sdk/issues/7405
+      // Queue it for deletion later because if we deleted it now the earlier
+      // writes in this block would be wiped. For now we keep track of what to
+      // delete when we know it'll be another block.
+      storedCompletedTxs.add(txId);
+    }
+
+    const capData = await E(marshaller).toCapData(record);
+
+    await E(txNode).setValue(JSON.stringify(capData));
+  };
+
+  /**
+   * @param {CctpTxEvidence['txHash']} hash
+   * @param {CctpTxEvidence} evidence
+   */
+  const publishEvidence = (hash, evidence) => {
+    // Don't await, just writing to vstorage.
+    void publishTxnRecord(
+      hash,
+      harden({ evidence, status: TxStatus.Observed }),
+    );
+  };
+
   /**
    * Ensures that `txHash+chainId` has not been processed
    * and adds entry to `seenTxs` set.
@@ -78,39 +146,130 @@ export const prepareStatusManager = zone => {
    *
    * @param {CctpTxEvidence} evidence
    * @param {PendingTxStatus} status
+   * @param {string[]} [risksIdentified]
    */
-  const recordPendingTx = (evidence, status) => {
-    const seenKey = seenTxKeyOf(evidence);
-    if (seenTxs.has(seenKey)) {
-      throw makeError(`Transaction already seen: ${q(seenKey)}`);
+  const initPendingTx = (evidence, status, risksIdentified) => {
+    const { txHash } = evidence;
+    if (seenTxs.has(txHash)) {
+      throw makeError(`Transaction already seen: ${q(txHash)}`);
     }
-    seenTxs.add(seenKey);
+    seenTxs.add(txHash);
 
     appendToStoredArray(
       pendingTxs,
       pendingTxKeyOf(evidence),
       harden({ ...evidence, status }),
     );
+    publishEvidence(txHash, evidence);
+    if (status === PendingTxStatus.AdvanceSkipped) {
+      void publishTxnRecord(txHash, harden({ status, risksIdentified }));
+    } else if (status !== PendingTxStatus.Observed) {
+      // publishEvidence publishes Observed
+      void publishTxnRecord(txHash, harden({ status }));
+    }
   };
 
+  /**
+   * Update the pending transaction status.
+   *
+   * @param {{nfa: NobleAddress, amount: bigint}} keyParts
+   * @param {PendingTxStatus} status
+   */
+  function setPendingTxStatus({ nfa, amount }, status) {
+    const key = makePendingTxKey(nfa, amount);
+    pendingTxs.has(key) || Fail`no advancing tx with ${{ nfa, amount }}`;
+    const pending = pendingTxs.get(key);
+    const ix = pending.findIndex(tx => tx.status === PendingTxStatus.Advancing);
+    ix >= 0 || Fail`no advancing tx with ${{ nfa, amount }}`;
+    const [prefix, tx, suffix] = [
+      pending.slice(0, ix),
+      pending[ix],
+      pending.slice(ix + 1),
+    ];
+    const txpost = { ...tx, status };
+    pendingTxs.set(key, harden([...prefix, txpost, ...suffix]));
+    void publishTxnRecord(tx.txHash, harden({ status }));
+  }
+
   return zone.exo(
     'Fast USDC Status Manager',
     M.interface('StatusManagerI', {
+      // TODO: naming scheme for transition events
       advance: M.call(CctpTxEvidenceShape).returns(M.undefined()),
+      advanceOutcome: M.call(M.string(), M.nat(), M.boolean()).returns(),
+      skipAdvance: M.call(CctpTxEvidenceShape, M.arrayOf(M.string())).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()),
+      hasBeenObserved: M.call(CctpTxEvidenceShape).returns(M.boolean()),
+      deleteCompletedTxs: M.call().returns(M.undefined()),
+      dequeueStatus: M.call(M.string(), M.bigint()).returns(
+        M.or(
+          {
+            txHash: EvmHashShape,
+            status: M.or(
+              PendingTxStatus.Advanced,
+              PendingTxStatus.AdvanceSkipped,
+              PendingTxStatus.AdvanceFailed,
+              PendingTxStatus.Observed,
+            ),
+          },
+          M.undefined(),
+        ),
+      ),
+      disbursed: M.call(EvmHashShape, AmountKeywordRecordShape).returns(
+        M.undefined(),
+      ),
+      forwarded: M.call(M.opt(EvmHashShape), M.string(), M.nat()).returns(
+        M.undefined(),
+      ),
       lookupPending: M.call(M.string(), M.bigint()).returns(
         M.arrayOf(PendingTxShape),
       ),
     }),
     {
       /**
-       * Add a new transaction with ADVANCED status
+       * Add a new transaction with ADVANCING status
+       *
+       * NB: this acts like observe() but subsequently records an ADVANCING
+       * state
+       *
        * @param {CctpTxEvidence} evidence
        */
       advance(evidence) {
-        recordPendingTx(evidence, PendingTxStatus.Advanced);
+        initPendingTx(evidence, PendingTxStatus.Advancing);
+      },
+
+      /**
+       * Add a new transaction with ADVANCE_SKIPPED status
+       *
+       * NB: this acts like observe() but subsequently records an
+       * ADVANCE_SKIPPED state along with risks identified
+       *
+       * @param {CctpTxEvidence} evidence
+       * @param {string[]} risksIdentified
+       */
+      skipAdvance(evidence, risksIdentified) {
+        initPendingTx(
+          evidence,
+          PendingTxStatus.AdvanceSkipped,
+          risksIdentified,
+        );
+      },
+
+      /**
+       * Record result of ADVANCING
+       *
+       * @param {NobleAddress} nfa Noble Forwarding Account
+       * @param {import('@agoric/ertp').NatValue} amount
+       * @param {boolean} success - Advanced vs. AdvanceFailed
+       * @throws {Error} if nothing to advance
+       */
+      advanceOutcome(nfa, amount, success) {
+        setPendingTxStatus(
+          { nfa, amount },
+          success ? PendingTxStatus.Advanced : PendingTxStatus.AdvanceFailed,
+        );
       },
 
       /**
@@ -118,53 +277,107 @@ export const prepareStatusManager = zone => {
        * @param {CctpTxEvidence} evidence
        */
       observe(evidence) {
-        recordPendingTx(evidence, PendingTxStatus.Observed);
+        initPendingTx(evidence, PendingTxStatus.Observed);
       },
 
       /**
-       * Find an `ADVANCED` or `OBSERVED` tx waiting to be `SETTLED`
+       * Note: ADVANCING state implies tx has been OBSERVED
        *
-       * @param {NobleAddress} address
-       * @param {bigint} amount
-       * @returns {boolean}
+       * @param {CctpTxEvidence} evidence
        */
-      hasPendingSettlement(address, amount) {
-        const key = makePendingTxKey(address, amount);
-        const pending = pendingTxs.get(key);
-        return !!pending.length;
+      hasBeenObserved(evidence) {
+        return seenTxs.has(evidence.txHash);
+      },
+
+      // UNTIL https://github.com/Agoric/agoric-sdk/issues/7405
+      deleteCompletedTxs() {
+        for (const txHash of storedCompletedTxs.values()) {
+          // As of now, setValue('') on a non-sequence node will delete it
+          const txNode = E(txnsNode).makeChildNode(txHash, {
+            sequence: false,
+          });
+          void E(txNode)
+            .setValue('')
+            .then(() => storedCompletedTxs.delete(txHash));
+        }
       },
 
       /**
-       * Mark an `ADVANCED` or `OBSERVED` transaction as `SETTLED` and remove it
+       * Remove and return an `ADVANCED` or `OBSERVED` tx waiting to be `SETTLED`.
        *
-       * @param {NobleAddress} address
+       * @param {NobleAddress} nfa
        * @param {bigint} amount
+       * @returns {Pick<PendingTx, 'status' | 'txHash'> | undefined} undefined if nothing
+       *   with this address and amount has been marked pending.
        */
-      settle(address, amount) {
-        const key = makePendingTxKey(address, amount);
+      dequeueStatus(nfa, amount) {
+        const key = makePendingTxKey(nfa, amount);
+        if (!pendingTxs.has(key)) return undefined;
         const pending = pendingTxs.get(key);
 
-        if (!pending.length) {
-          throw makeError(`No unsettled entry for ${q(key)}`);
+        const dequeueIdx = pending.findIndex(
+          x => x.status !== PendingTxStatus.Advancing,
+        );
+        if (dequeueIdx < 0) return undefined;
+
+        if (pending.length > 1) {
+          const pendingCopy = [...pending];
+          pendingCopy.splice(dequeueIdx, 1);
+          pendingTxs.set(key, harden(pendingCopy));
+        } else {
+          pendingTxs.delete(key);
         }
 
-        const pendingCopy = [...pending];
-        pendingCopy.shift();
-        // TODO, vstorage update for `TxStatus.Settled`
-        pendingTxs.set(key, harden(pendingCopy));
+        const { status, txHash } = pending[dequeueIdx];
+        // TODO: store txHash -> evidence for txs pending settlement?
+        // If necessary for vstorage writes in `forwarded` and `settled`
+        return harden({ status, txHash });
+      },
+
+      /**
+       * Mark a transaction as `DISBURSED`
+       *
+       * @param {EvmHash} txHash
+       * @param {import('./liquidity-pool.js').RepayAmountKWR} split
+       */
+      disbursed(txHash, split) {
+        void publishTxnRecord(
+          txHash,
+          harden({ split, status: TxStatus.Disbursed }),
+        );
+      },
+
+      /**
+       * Mark a transaction as `FORWARDED`
+       *
+       * @param {EvmHash | undefined} txHash - undefined in case mint before observed
+       * @param {NobleAddress} nfa
+       * @param {bigint} amount
+       */
+      forwarded(txHash, nfa, amount) {
+        if (txHash) {
+          void publishTxnRecord(txHash, harden({ status: TxStatus.Forwarded }));
+        } else {
+          // TODO store (early) `Minted` transactions to check against incoming evidence
+          log(
+            `⚠️ Forwarded minted amount ${amount} from account ${nfa} before it was observed.`,
+          );
+        }
       },
 
       /**
        * Lookup all pending entries for a given address and amount
        *
-       * @param {NobleAddress} address
+       * XXX only used in tests. should we remove?
+       *
+       * @param {NobleAddress} nfa
        * @param {bigint} amount
        * @returns {PendingTx[]}
        */
-      lookupPending(address, amount) {
-        const key = makePendingTxKey(address, amount);
+      lookupPending(nfa, amount) {
+        const key = makePendingTxKey(nfa, amount);
         if (!pendingTxs.has(key)) {
-          throw makeError(`Key ${q(key)} not yet observed`);
+          return harden([]);
         }
         return pendingTxs.get(key);
       },

package/src/exos/transaction-feed.js

@@ -1,14 +1,16 @@
 import { makeTracer } from '@agoric/internal';
 import { prepareDurablePublishKit } from '@agoric/notifier';
-import { M } from '@endo/patterns';
-import { CctpTxEvidenceShape } from '../type-guards.js';
+import { keyEQ, M } from '@endo/patterns';
+import { Fail } from '@endo/errors';
+import { CctpTxEvidenceShape, RiskAssessmentShape } from '../type-guards.js';
 import { defineInertInvitation } from '../utils/zoe.js';
 import { prepareOperatorKit } from './operator-kit.js';
 
 /**
  * @import {Zone} from '@agoric/zone';
+ * @import {MapStore} from '@agoric/store';
  * @import {OperatorKit} from './operator-kit.js';
- * @import {CctpTxEvidence} from '../types.js';
+ * @import {CctpTxEvidence, EvidenceWithRisk, RiskAssessment} from '../types.js';
  */
 
 const trace = makeTracer('TxFeed', true);
@@ -18,7 +20,11 @@ export const INVITATION_MAKERS_DESC = 'oracle operator invitation';
 
 const TransactionFeedKitI = harden({
   operatorPowers: M.interface('Transaction Feed Admin', {
-    submitEvidence: M.call(CctpTxEvidenceShape, M.any()).returns(),
+    attest: M.call(
+      CctpTxEvidenceShape,
+      RiskAssessmentShape,
+      M.string(),
+    ).returns(),
   }),
   creator: M.interface('Transaction Feed Creator', {
     // TODO narrow the return shape to OperatorKit
@@ -31,6 +37,22 @@ const TransactionFeedKitI = harden({
   }),
 });
 
+/**
+ * @param {MapStore<string, RiskAssessment>[]} riskStores
+ * @param {string} txHash
+ */
+const allRisksIdentified = (riskStores, txHash) => {
+  /**  @type {Set<string>} */
+  const setOfRisks = new Set();
+  for (const store of riskStores) {
+    const next = store.get(txHash);
+    for (const risk of next.risksIdentified ?? []) {
+      setOfRisks.add(risk);
+    }
+  }
+  return [...setOfRisks.values()].sort();
+};
+
 /**
  * @param {Zone} zone
  * @param {ZCF} zcf
@@ -41,7 +63,7 @@ export const prepareTransactionFeedKit = (zone, zcf) => {
     kinds,
     'Transaction Feed',
   );
-  /** @type {PublishKit<CctpTxEvidence>} */
+  /** @type {PublishKit<EvidenceWithRisk>} */
   const { publisher, subscriber } = makeDurablePublishKit();
 
   const makeInertInvitation = defineInertInvitation(zcf, 'submitting evidence');
@@ -55,14 +77,12 @@ export const prepareTransactionFeedKit = (zone, zcf) => {
     TransactionFeedKitI,
     () => {
       /** @type {MapStore<string, OperatorKit>} */
-      const operators = zone.mapStore('operators', {
-        durable: true,
-      });
+      const operators = zone.mapStore('operators');
       /** @type {MapStore<string, MapStore<string, CctpTxEvidence>>} */
-      const pending = zone.mapStore('pending', {
-        durable: true,
-      });
-      return { operators, pending };
+      const pending = zone.mapStore('pending');
+      /** @type {MapStore<string, MapStore<string, RiskAssessment>>} */
+      const risks = zone.mapStore('risks');
+      return { operators, pending, risks };
     },
     {
       creator: {
@@ -89,7 +109,7 @@ export const prepareTransactionFeedKit = (zone, zcf) => {
         },
         /** @param {string} operatorId */
         initOperator(operatorId) {
-          const { operators, pending } = this.state;
+          const { operators, pending, risks } = this.state;
           trace('initOperator', operatorId);
 
           const operatorKit = makeOperatorKit(
@@ -101,6 +121,7 @@ export const prepareTransactionFeedKit = (zone, zcf) => {
             operatorId,
             zone.detached().mapStore('pending evidence'),
           );
+          risks.init(operatorId, zone.detached().mapStore('risk assessments'));
 
           return operatorKit;
         },
@@ -118,23 +139,17 @@ export const prepareTransactionFeedKit = (zone, zcf) => {
         /**
          * Add evidence from an operator.
          *
+         * NB: the operatorKit is responsible for
+         *
          * @param {CctpTxEvidence} evidence
-         * @param {OperatorKit} operatorKit
+         * @param {RiskAssessment} riskAssessment
+         * @param {string} operatorId
          */
-        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`;
+        attest(evidence, riskAssessment, operatorId) {
+          const { operators, pending, risks } = this.state;
+          trace('attest', operatorId, evidence);
 
+          // TODO https://github.com/Agoric/agoric-sdk/pull/10720
           // 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.
@@ -147,6 +162,9 @@ export const prepareTransactionFeedKit = (zone, zcf) => {
               trace(`operator ${operatorId} already reported ${txHash}`);
             } else {
               pendingStore.init(txHash, evidence);
+              // accept the risk assessment as well
+              const riskStore = risks.get(operatorId);
+              riskStore.init(txHash, riskAssessment);
             }
           }
 
@@ -154,19 +172,59 @@ export const prepareTransactionFeedKit = (zone, zcf) => {
           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
+          const minAttestations = Math.ceil(operators.getSize() / 2);
+          trace(
+            'transaction',
+            txHash,
+            'has',
+            found.length,
+            'of',
+            minAttestations,
+            'necessary attestations',
+          );
+          if (found.length < minAttestations) {
             return;
           }
 
-          // TODO verify that all found deep equal
+          let lastEvidence;
+          for (const store of found) {
+            const next = store.get(txHash);
+            if (lastEvidence) {
+              if (keyEQ(lastEvidence, next)) {
+                lastEvidence = next;
+              } else {
+                trace(
+                  '🚨 conflicting evidence for',
+                  txHash,
+                  ':',
+                  lastEvidence,
+                  '!=',
+                  next,
+                );
+                Fail`conflicting evidence for ${txHash}`;
+              }
+            }
+            lastEvidence = next;
+          }
 
-          // all agree, so remove from pending and publish
-          for (const pendingStore of pending.values()) {
-            pendingStore.delete(txHash);
+          const riskStores = [...risks.values()].filter(store =>
+            store.has(txHash),
+          );
+          // take the union of risks identified from all operators
+          const risksIdentified = allRisksIdentified(riskStores, txHash);
+
+          // sufficient agreement, so remove from pending risks, then publish
+          for (const store of found) {
+            store.delete(txHash);
           }
-          publisher.publish(evidence);
+          for (const store of riskStores) {
+            store.delete(txHash);
+          }
+          trace('publishing evidence', evidence, risksIdentified);
+          publisher.publish({
+            evidence,
+            risk: { risksIdentified },
+          });
         },
       },
       public: {