docs: document fastUSDC's processing plan and state transitions

packages/fast-usdc/README.md

@@ -59,43 +59,50 @@ 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.
 
-### Complete state diagram (starting from Transaction Feed into Advancer)
+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.
+
+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
-  Observed --> AdvanceSkipped : Risks identified
-  Observed --> Advancing : No risks, can advance
-  Observed --> Forwarding : No risks, Mint deposited before advance
-  Forwarding --> Forwarded
-  Advancing --> Advanced
-  Advanced --> Disbursed
-  AdvanceSkipped --> Forwarding : Mint deposited
-  AdvanceFailed --> Forwarding : Mint deposited
-  Advancing --> AdvanceFailed
-  Forwarding --> ForwardFailed
-```
+  [*] --> AdvanceSkipped : Risks identified
+  [*] --> Advancing : No risks, can advance
+  [*] --> Forwarding* : No risks, Mint deposited before advance
+
+  state Advancer  {
+    Advanced
+    AdvanceFailed
+    AdvanceSkipped
+    Advancing
+  }
+  state Settler {
+    Forwarded
+    ForwardFailed
+    Disbursed
+  }
+
+  Forwarding* --> Forwarded : settler.forward() succeeds
+  Advancing --> Advanced : advancer's transferHandler detects success
+  Advanced --> Disbursed : settler.disburse()
+  AdvanceSkipped --> Forwarding* : Mint deposited
+  AdvanceFailed --> Forwarding* : Mint deposited
+  Advancing --> AdvanceFailed : advancer's transferHandler detects failure
+  Forwarding* --> ForwardFailed : settler.forward() fails
+ ```
+
+* There is no actual state for **Forwarding**. It is used here to represent the
+transition from Advancer to Settler

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

@@ -17,6 +17,12 @@ import {
 } from '../type-guards.js';
 import { makeFeeTools } from '../utils/fees.js';
 
+/**
+ * @file Advancer subscribes (handleTransactionEvent) to events published by the
+ * transaction feed. When notified of an appropriate opportunity, it is
+ * responsible for advancing funds to fastUSDC payees.
+ */
+
 /**
  * @import {HostInterface} from '@agoric/async-flow';
  * @import {Amount, Brand} from '@agoric/ertp';

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

@@ -14,6 +14,13 @@ import {
   makeNatAmountShape,
 } from '../type-guards.js';
 
+/**
+ * @file Settler is responsible for monitoring (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).
+ */
+
 /**
  * @import {FungibleTokenPacketData} from '@agoric/cosmic-proto/ibc/applications/transfer/v2/packet.js';
  * @import {Amount, Brand, NatValue, Payment} from '@agoric/ertp';
@@ -300,6 +307,9 @@ export const prepareSettler = (
       },
       self: {
         /**
+         * The intended payee received an advance from the pool. When the funds
+         * are minted disburse them to the pool.
+         *
          * @param {EvmHash} txHash
          * @param {NatValue} fullValue
          */
@@ -333,6 +343,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

@@ -315,7 +315,10 @@ export const prepareStatusManager = (
       },
 
       /**
-       * Add a new transaction with OBSERVED status
+       * Add a new transaction with OBSERVED status.
+       *
+       * This message isn't currently being sent.
+       *
        * @param {CctpTxEvidence} evidence
        */
       observe(evidence) {

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

@@ -6,6 +6,12 @@ import { CctpTxEvidenceShape, RiskAssessmentShape } from '../type-guards.js';
 import { defineInertInvitation } from '../utils/zoe.js';
 import { prepareOperatorKit } from './operator-kit.js';
 
+/**
+ * @file transaction-feed receives attestations from Oracles, records their
+ * evidence, and when enough oracles agree, (if no risks are identified)
+ * publishes the results for the advancer to act on.
+ */
+
 /**
  * @import {Zone} from '@agoric/zone';
  * @import {MapStore} from '@agoric/store';