Internal JSDoc for fastUSDC and state transition diagram

packages/fast-usdc/README.md

@@ -59,43 +59,39 @@ sequenceDiagram
 
 # Status Manager
 
-### Pending Advance State Diagram
+### State Diagram
 
-*Transactions are qualified by the OCW and EventFeed before arriving to the Advancer.*
+*Transactions are qualified by the OCW and TransactionFeed before being
+delivered to the Advancer.*
 
-```mermaid
-stateDiagram-v2
-  [*] --> Observed: observe()
-  [*] --> Advancing: advancing()
-
-  Advancing --> Advanced: advanceOutcome(...true)
-  Advancing --> AdvanceFailed: advanceOutcome(...false)
-
-  Observed --> [*]: dequeueStatus()
-  Advanced --> [*]: dequeueStatus()
-  AdvanceFailed --> [*]: dequeueStatus()
-
-  note right of [*]
-    After dequeueStatus():
-    Transaction is removed 
-    from pendingTxs store.
-    Settler will .disburse()
-    or .forward()
-  end note
-```
+The transactionFeed receives attestations from Oracles, records their
+evidence, and when enough oracles agree, (if no risks are identified)
+it publishes the results for the advancer to act on.
+
+The Advancer subscribes (via `handleTransactionEvent`) to events published by
+the transactionFeed. When notified of an appropriate opportunity, it is
+responsible for advancing funds to fastUSDC payees.
 
-### Complete state diagram (starting from Transaction Feed into Advancer)
+The Settler is responsible for monitoring (via `receiveUpcall`) deposits to the
+settlementAccount. It either `disburse`s funds to the Pool (if funds were
+`advance`d to the payee), or `forwards` funds to the payee (if pool funds
+were not `advance`d).
 
 ```mermaid
 stateDiagram-v2
+  state Forwarding <<choice>>
+  state AdvancingChoice <<choice>>
+
   Observed --> AdvanceSkipped : Risks identified
   Observed --> Advancing : No risks, can advance
   Observed --> Forwarding : No risks, Mint deposited before advance
-  Forwarding --> Forwarded
-  Advancing --> Advanced
-  Advanced --> Disbursed
+
+  Forwarding --> Forwarded : settler.forward() succeeds
+  Advancing --> AdvancingChoice
+  AdvancingChoice --> Advanced : advancer's transferHandler detects success
+  Advanced --> Disbursed : settler.disburse()
   AdvanceSkipped --> Forwarding : Mint deposited
   AdvanceFailed --> Forwarding : Mint deposited
-  Advancing --> AdvanceFailed
-  Forwarding --> ForwardFailed
-```
+  AdvancingChoice --> AdvanceFailed : advancer's transferHandler detects failure
+  Forwarding --> ForwardFailed : settler.forward() fails
+ ```

packages/fast-usdc/src/constants.js

@@ -1,5 +1,5 @@
 /**
- * Status values for FastUSDC.
+ * Status values for FastUSDC. Includes states for advancing and settling.
  *
  * @enum {(typeof TxStatus)[keyof typeof TxStatus]}
  */
@@ -31,7 +31,7 @@ export const TerminalTxStatus = {
 };
 
 /**
- * Status values for the StatusManager.
+ * Status values for the StatusManager while an advance is being processed.
  *
  * @enum {(typeof PendingTxStatus)[keyof typeof PendingTxStatus]}
  */

packages/fast-usdc/src/exos/advancer.js

@@ -1,3 +1,5 @@
+/** @file main export: @see {prepareAdvancerKit} */
+
 import { decodeAddressHook } from '@agoric/cosmic-proto/address-hooks.js';
 import { AmountMath } from '@agoric/ertp';
 import { assertAllDefined, makeTracer } from '@agoric/internal';
@@ -29,6 +31,7 @@ import { makeFeeTools } from '../utils/fees.js';
  * @import {AddressHook, EvmHash, FeeConfig, LogFn, NobleAddress, EvidenceWithRisk} from '../types.js';
  * @import {StatusManager} from './status-manager.js';
  * @import {LiquidityPoolKit} from './liquidity-pool.js';
+ * @import { TransactionFeedKit } from './transaction-feed.js';
  */
 
 /**
@@ -103,6 +106,10 @@ export const stateShape = harden({
 });
 
 /**
+ * Advancer subscribes (using handleTransactionEvent) to events published by the
+ * {@link TransactionFeedKit}. When notified of an appropriate opportunity, it
+ * is responsible for advancing funds to EUD.
+ *
  * @param {Zone} zone
  * @param {AdvancerKitPowers} caps
  */

packages/fast-usdc/src/exos/liquidity-pool.js

@@ -269,23 +269,23 @@ export const prepareLiquidityPoolKit = (zone, zcf, USDC, tools) => {
           const post = depositCalc(shareWorth, proposal);
 
           // COMMIT POINT
-          const mint = shareMint.mintGains(post.payouts);
+          const sharePayout = shareMint.mintGains(post.payouts);
           try {
             this.state.shareWorth = post.shareWorth;
             zcf.atomicRearrange(
               harden([
                 // zoe guarantees lp has proposal.give allocated
                 [lp, poolSeat, proposal.give],
-                // mintGains() above establishes that mint has post.payouts
-                [mint, lp, post.payouts],
+                // mintGains() above establishes that sharePayout has post.payouts
+                [sharePayout, lp, post.payouts],
               ]),
             );
           } catch (cause) {
             // UNTIL #10684: ability to terminate an incarnation w/o terminating the contract
             throw new Error('🚨 cannot commit deposit', { cause });
           } finally {
             lp.exit();
-            mint.exit();
+            sharePayout.exit();
           }
           external.publishPoolMetrics();
         },

packages/fast-usdc/src/exos/settler.js

@@ -1,3 +1,5 @@
+/** @file main export: @see {prepareSettler} */
+
 import { AmountMath } from '@agoric/ertp';
 import { assertAllDefined, makeTracer } from '@agoric/internal';
 import { CosmosChainAddressShape } from '@agoric/orchestration';
@@ -105,6 +107,17 @@ export const stateShape = harden({
 });
 
 /**
+ * The Settler is responsible for monitoring (using receiveUpcall) deposits to
+ * the settlementAccount. It either "disburses" funds to the Pool (if funds were
+ * "advance"d to the payee), or "forwards" funds to the payee (if pool funds
+ * were not advanced).
+ *
+ * Funds are forwarded
+ *
+ * `receivUpcall` is configured to receive notifications in
+ * `monitorMintingDeposits()`, with a call to
+ * `settlementAccount.monitorTransfers()`.
+ *
  * @param {Zone} zone
  * @param {object} caps
  * @param {StatusManager} caps.statusManager
@@ -227,7 +240,6 @@ export const prepareSettler = (
               self.addMintedEarly(nfa, amount);
               return;
 
-            case PendingTxStatus.Observed:
             case PendingTxStatus.AdvanceSkipped:
             case PendingTxStatus.AdvanceFailed:
               return self.forward(found.txHash, amount, EUD);
@@ -275,10 +287,12 @@ export const prepareSettler = (
           }
         },
         /**
+         * If the EUD received minted funds without an advance, forward the
+         * funds to the pool.
+         *
          * @param {CctpTxEvidence} evidence
          * @param {CosmosChainAddress} destination
-         * @returns {boolean}
-         * @throws {Error} if minted early, so advancer doesn't advance
+         * @returns {boolean} whether the EUD received funds without an advance
          */
         checkMintedEarly(evidence, destination) {
           const {
@@ -313,6 +327,9 @@ export const prepareSettler = (
           asMultiset(mintedEarly).add(key);
         },
         /**
+         * The intended payee received an advance from the pool. When the funds
+         * are minted, disburse them to the pool and fee seats.
+         *
          * @param {EvmHash} txHash
          * @param {NatValue} fullValue
          */
@@ -344,6 +361,8 @@ export const prepareSettler = (
           statusManager.disbursed(txHash, split);
         },
         /**
+         * Funds were not advanced. Forward proceeds to the payee directly.
+         *
          * @param {EvmHash} txHash
          * @param {NatValue} fullValue
          * @param {string} EUD

packages/fast-usdc/src/exos/status-manager.js

@@ -209,7 +209,6 @@ export const prepareStatusManager = (
       skipAdvance: M.call(CctpTxEvidenceShape, M.arrayOf(M.string())).returns(),
       advanceOutcomeForMintedEarly: M.call(EvmHashShape, M.boolean()).returns(),
       advanceOutcomeForUnknownMint: M.call(CctpTxEvidenceShape).returns(),
-      observe: M.call(CctpTxEvidenceShape).returns(),
       hasBeenObserved: M.call(CctpTxEvidenceShape).returns(M.boolean()),
       deleteCompletedTxs: M.call().returns(M.undefined()),
       dequeueStatus: M.call(M.string(), M.bigint()).returns(
@@ -311,14 +310,6 @@ export const prepareStatusManager = (
         publishEvidence(txHash, evidence);
       },
 
-      /**
-       * Add a new transaction with OBSERVED status
-       * @param {CctpTxEvidence} evidence
-       */
-      observe(evidence) {
-        initPendingTx(evidence, PendingTxStatus.Observed);
-      },
-
       /**
        * Note: ADVANCING state implies tx has been OBSERVED
        *

packages/fast-usdc/src/exos/transaction-feed.js

@@ -1,4 +1,5 @@
 /** @file Exo for @see {prepareTransactionFeedKit} */
+
 import { makeTracer } from '@agoric/internal';
 import { prepareDurablePublishKit } from '@agoric/notifier';
 import { Fail, quote } from '@endo/errors';

packages/fast-usdc/test/exos/settler.test.ts

@@ -170,18 +170,6 @@ const makeTestContext = async t => {
 
         return cctpTxEvidence;
       },
-      /**
-       * slow path - e.g. insufficient pool funds
-       * @param evidence
-       */
-      observe: (evidence?: CctpTxEvidence) => {
-        const cctpTxEvidence = makeEvidence(evidence);
-        t.log('Mock CCTP Evidence:', cctpTxEvidence);
-        t.log('Pretend we `OBSERVED` (did not advance)');
-        statusManager.observe(cctpTxEvidence);
-
-        return cctpTxEvidence;
-      },
       /**
        * mint early path. caller must simulate tap before calling
        * @param evidence
@@ -338,15 +326,7 @@ test('slow path: forward to EUD; remove pending tx', async t => {
     ...defaultSettlerParams,
   });
   const simulate = makeSimulate(settler.notifier);
-  const cctpTxEvidence = simulate.observe();
-  t.deepEqual(
-    statusManager.lookupPending(
-      cctpTxEvidence.tx.forwardingAddress,
-      cctpTxEvidence.tx.amount,
-    ),
-    [{ ...cctpTxEvidence, status: PendingTxStatus.Observed }],
-    'statusManager shows this tx is only observed',
-  );
+  const cctpTxEvidence = simulate.skipAdvance(['TOO_LARGE_AMOUNT']);
 
   t.log('Simulate incoming IBC settlement');
   void settler.tap.receiveUpcall(MockVTransferEvents.AGORIC_PLUS_OSMO());
@@ -384,6 +364,7 @@ test('slow path: forward to EUD; remove pending tx', async t => {
   await eventLoopIteration();
   t.deepEqual(storage.getDeserialized(`fun.txns.${cctpTxEvidence.txHash}`), [
     { evidence: cctpTxEvidence, status: 'OBSERVED' },
+    { risksIdentified: ['TOO_LARGE_AMOUNT'], status: 'ADVANCE_SKIPPED' },
     { status: 'FORWARDED' },
   ]);
 
@@ -628,7 +609,7 @@ test('Multiple minted early transactions with same address and amount', async t
   ]);
 
   // Simulate a third transaction and verify no more are tracked as minted early
-  simulate.observe({
+  simulate.observeLate({
     ...MockCctpTxEvidences.AGORIC_PLUS_OSMO(),
     txHash:
       '0x0000000000000000000000000000000000000000000000000000000000000001',
@@ -775,12 +756,11 @@ test('slow path, and forward fails (terminal state)', async t => {
   const {
     common,
     makeSettler,
-    statusManager,
     defaultSettlerParams,
     repayer,
     makeSimulate,
+    inspectLogs,
     accounts,
-    peekCalls,
     storage,
   } = t.context;
   const { usdc } = common.brands;
@@ -790,43 +770,32 @@ test('slow path, and forward fails (terminal state)', async t => {
     settlementAccount: accounts.settlement.account,
     ...defaultSettlerParams,
   });
-  const simulate = makeSimulate(settler.notifier);
-  const cctpTxEvidence = simulate.observe();
-  t.deepEqual(
-    statusManager.lookupPending(
-      cctpTxEvidence.tx.forwardingAddress,
-      cctpTxEvidence.tx.amount,
-    ),
-    [{ ...cctpTxEvidence, status: PendingTxStatus.Observed }],
-    'statusManager shows this tx is only observed',
-  );
+
+  t.log('simulating forward failure (e.g. unknown route)');
+  const mockE = Error('no connection info found');
+  accounts.settlement.transferVResolver.reject(mockE);
+  await eventLoopIteration();
 
   t.log('Simulate incoming IBC settlement');
   void settler.tap.receiveUpcall(MockVTransferEvents.AGORIC_PLUS_OSMO());
   await eventLoopIteration();
+  const simulate = makeSimulate(settler.notifier);
 
-  t.log('funds are forwarded; no interaction with LP');
-  t.like(accounts.settlement.callLog, [
+  const evidence = simulate.observeLate();
+
+  const rawLogs = inspectLogs();
+  const penultimateLog = rawLogs.slice(rawLogs.length - 2, rawLogs.length - 1);
+  await eventLoopIteration();
+  t.deepEqual(penultimateLog, [
     [
-      'transfer',
-      'cosmos:osmosis-1:osmo183dejcnmkka5dzcu9xw6mywq0p2m5peks28men',
-      usdc.units(150),
-      {
-        forwardOpts: {
-          intermediateRecipient: {
-            value: 'noble1test',
-          },
-        },
-      },
+      '⚠️ tap: minted before observed',
+      'noble1x0ydg69dh6fqvr27xjvp6maqmrldam6yfelqkd',
+      150000000n,
     ],
   ]);
 
-  t.log('simulating forward failure (e.g. unknown route)');
-  const mockE = Error('no connection info found');
-  accounts.settlement.transferVResolver.reject(mockE);
-  await eventLoopIteration();
-  t.deepEqual(storage.getDeserialized(`fun.txns.${cctpTxEvidence.txHash}`), [
-    { evidence: cctpTxEvidence, status: 'OBSERVED' },
+  t.deepEqual(storage.getDeserialized(`fun.txns.${evidence.txHash}`), [
+    { evidence, status: 'OBSERVED' },
     { status: 'FORWARD_FAILED' },
   ]);
 });