feat(fast-usdc): settler disburses or forwards funds (#10530)

closes: #10391

## Description

 - feat(fast-usdc): settler disburses or forwards funds

Discussion of what to do if the minted USDC shows up at each state led to some refinement of states.
So the scope of this PR expanded somewhat:

 - chore(fast-usdc): status manager: split out Advancing state
 - chore(fast-usdc): advancer: split ADVANCING state


### Security Considerations

In addition to the normal case where funds are repaid to the pool and fees are distributed, the settler is responsible to forward funds in case they were not advanced.

### Scaling Considerations

nothing novel

### Documentation Considerations

Readers are assumed to be familiar with design docs.

### Testing Considerations

Getting the tests to pass requires:

 - [ ] #10553

It's included in this PR for now but is expected to land separately

DRAFT until
 - [x] test "Settlement for unknown transaction" case

### Upgrade Considerations

This is a new component.

Author: mergify[bot]

packages/fast-usdc/README.md

@@ -56,3 +56,44 @@ sequenceDiagram
 
     A->>TF: notify(evidence)
 ```
+
+# Status Manager
+
+### Pending Advance State Diagram
+
+*Transactions are qualified by the OCW and EventFeed before arriving 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
+```
+
+### Complete state diagram (starting from Transaction Feed into Advancer)
+
+```mermaid
+stateDiagram-v2
+  Observed --> Advancing
+  Observed --> Forwarding:Minted
+  Forwarding --> Forwarded
+  Advancing --> Advanced
+  Advanced --> Disbursed
+  AdvanceFailed --> Forwarding
+  Advancing --> AdvanceFailed
+  Forwarding --> ForwardFailed
+```

packages/fast-usdc/src/constants.js

@@ -7,12 +7,22 @@ export const TxStatus = /** @type {const} */ ({
   /** tx was observed but not advanced */
   Observed: 'OBSERVED',
   /** IBC transfer is initiated */
+  Advancing: 'ADVANCING',
+  /** IBC transfer is complete */
   Advanced: 'ADVANCED',
-  /** settlement for matching advance received and funds dispersed */
-  Settled: 'SETTLED',
+  /** IBC transfer failed (timed out) */
+  AdvanceFailed: 'ADVANCE_FAILED',
+  /** settlement for matching advance received and funds disbursed */
+  Disbursed: 'DISBURSED',
+  /** fallback: do not collect fees */
+  Forwarded: 'FORWARDED',
+  /** failed to forward to EUD */
+  ForwardFailed: 'FORWARD_FAILED',
 });
 harden(TxStatus);
 
+// TODO: define valid state transitions
+
 /**
  * Status values for the StatusManager.
  *
@@ -22,6 +32,10 @@ export const PendingTxStatus = /** @type {const} */ ({
   /** tx was observed but not advanced */
   Observed: 'OBSERVED',
   /** IBC transfer is initiated */
+  Advancing: 'ADVANCING',
+  /** IBC transfer failed (timed out) */
+  AdvanceFailed: 'ADVANCE_FAILED',
+  /** IBC transfer is complete */
   Advanced: 'ADVANCED',
 });
 harden(PendingTxStatus);

packages/fast-usdc/src/exos/README.md

@@ -6,20 +6,22 @@ import { VowShape } from '@agoric/vow';
 import { q } from '@endo/errors';
 import { E } from '@endo/far';
 import { M } from '@endo/patterns';
-import { CctpTxEvidenceShape, EudParamShape } from '../type-guards.js';
+import {
+  CctpTxEvidenceShape,
+  EudParamShape,
+  EvmHashShape,
+} from '../type-guards.js';
 import { addressTools } from '../utils/address.js';
 import { makeFeeTools } from '../utils/fees.js';
 
-const { isGTE } = AmountMath;
-
 /**
  * @import {HostInterface} from '@agoric/async-flow';
  * @import {NatAmount} from '@agoric/ertp';
  * @import {ChainAddress, ChainHub, Denom, OrchestrationAccount} from '@agoric/orchestration';
  * @import {ZoeTools} from '@agoric/orchestration/src/utils/zoe-tools.js';
  * @import {VowTools} from '@agoric/vow';
  * @import {Zone} from '@agoric/zone';
- * @import {CctpTxEvidence, FeeConfig, LogFn} from '../types.js';
+ * @import {CctpTxEvidence, EvmHash, FeeConfig, LogFn, NobleAddress} from '../types.js';
  * @import {StatusManager} from './status-manager.js';
  * @import {LiquidityPoolKit} from './liquidity-pool.js';
  */
@@ -46,27 +48,44 @@ const AdvancerKitI = harden({
     onFulfilled: M.call(M.undefined(), {
       amount: AmountShape,
       destination: ChainAddressShape,
+      forwardingAddress: M.string(),
       tmpSeat: M.remotable(),
+      txHash: EvmHashShape,
     }).returns(VowShape),
     onRejected: M.call(M.error(), {
       amount: AmountShape,
       destination: ChainAddressShape,
+      forwardingAddress: M.string(),
       tmpSeat: M.remotable(),
+      txHash: EvmHashShape,
     }).returns(),
   }),
   transferHandler: M.interface('TransferHandlerI', {
     // TODO confirm undefined, and not bigint (sequence)
     onFulfilled: M.call(M.undefined(), {
       amount: AmountShape,
       destination: ChainAddressShape,
+      forwardingAddress: M.string(),
+      txHash: EvmHashShape,
     }).returns(M.undefined()),
     onRejected: M.call(M.error(), {
       amount: AmountShape,
       destination: ChainAddressShape,
+      forwardingAddress: M.string(),
+      txHash: EvmHashShape,
     }).returns(M.undefined()),
   }),
 });
 
+/**
+ * @typedef {{
+ *  amount: NatAmount;
+ *  destination: ChainAddress;
+ *  forwardingAddress: NobleAddress;
+ *  txHash: EvmHash;
+ * }} AdvancerVowCtx
+ */
+
 /**
  * @param {Zone} zone
  * @param {AdvancerKitPowers} caps
@@ -100,6 +119,7 @@ export const prepareAdvancerKit = (
     AdvancerKitI,
     /**
      * @param {{
+     *   notifyFacet: import('./settler.js').SettlerKit['notify'];
      *   borrowerFacet: LiquidityPoolKit['borrower'];
      *   poolAccount: HostInterface<OrchestrationAccount<{chainId: 'agoric'}>>;
      * }} config
@@ -120,51 +140,32 @@ export const prepareAdvancerKit = (
         async handleTransactionEvent(evidence) {
           await null;
           try {
+            if (statusManager.hasBeenObserved(evidence)) {
+              log('txHash already seen:', evidence.txHash);
+              return;
+            }
+
             const { borrowerFacet, poolAccount } = this.state;
             const { recipientAddress } = evidence.aux;
+            // throws if EUD is not found
             const { EUD } = addressTools.getQueryParams(
               recipientAddress,
               EudParamShape,
             );
-
-            // this will throw if the bech32 prefix is not found, but is handled by the catch
+            // throws if the bech32 prefix is not found
             const destination = chainHub.makeChainAddress(EUD);
+
             const requestedAmount = toAmount(evidence.tx.amount);
+            // throws if requested does not exceed fees
             const advanceAmount = feeTools.calculateAdvance(requestedAmount);
 
-            // TODO: consider skipping and using `borrow()`s internal balance check
-            const poolBalance = borrowerFacet.getBalance();
-            if (!isGTE(poolBalance, requestedAmount)) {
-              log(
-                `Insufficient pool funds`,
-                `Requested ${q(advanceAmount)} but only have ${q(poolBalance)}`,
-              );
-              statusManager.observe(evidence);
-              return;
-            }
-
-            try {
-              // Mark as Advanced since `transferV` initiates the advance.
-              // Will throw if we've already .skipped or .advanced this evidence.
-              statusManager.advance(evidence);
-            } catch (e) {
-              // Only anticipated error is `assertNotSeen`, so intercept the
-              // catch so we don't call .skip which also performs this check
-              log('Advancer error:', q(e).toString());
-              return;
-            }
-
             const { zcfSeat: tmpSeat } = zcf.makeEmptySeatKit();
             const amountKWR = harden({ USDC: advanceAmount });
-            try {
-              borrowerFacet.borrow(tmpSeat, amountKWR);
-            } catch (e) {
-              // We do not expect this to fail since there are no turn boundaries
-              // between .getBalance() and .borrow().
-              // We catch to report outside of the normal error flow since this is
-              // not expected.
-              log('🚨 advance borrow failed', q(e).toString());
-            }
+            // throws if the pool has insufficient funds
+            borrowerFacet.borrow(tmpSeat, amountKWR);
+
+            // this cannot throw since `.isSeen()` is called in the same turn
+            statusManager.advance(evidence);
 
             const depositV = localTransfer(
               tmpSeat,
@@ -175,7 +176,9 @@ export const prepareAdvancerKit = (
             void watch(depositV, this.facets.depositHandler, {
               amount: advanceAmount,
               destination,
+              forwardingAddress: evidence.tx.forwardingAddress,
               tmpSeat,
+              txHash: evidence.txHash,
             });
           } catch (e) {
             log('Advancer error:', q(e).toString());
@@ -186,22 +189,25 @@ export const prepareAdvancerKit = (
       depositHandler: {
         /**
          * @param {undefined} result
-         * @param {{ amount: Amount<'nat'>; destination: ChainAddress; tmpSeat: ZCFSeat }} ctx
+         * @param {AdvancerVowCtx & { tmpSeat: ZCFSeat }} ctx
          */
-        onFulfilled(result, { amount, destination }) {
+        onFulfilled(result, ctx) {
           const { poolAccount } = this.state;
+          const { amount, destination, forwardingAddress, txHash } = ctx;
           const transferV = E(poolAccount).transfer(destination, {
             denom: usdc.denom,
             value: amount.value,
           });
           return watch(transferV, this.facets.transferHandler, {
             destination,
             amount,
+            forwardingAddress,
+            txHash,
           });
         },
         /**
          * @param {Error} error
-         * @param {{ amount: Amount<'nat'>; destination: ChainAddress; tmpSeat: ZCFSeat }} ctx
+         * @param {AdvancerVowCtx & { tmpSeat: ZCFSeat }} ctx
          */
         onRejected(error, { tmpSeat }) {
           // TODO return seat allocation from ctx to LP?
@@ -217,25 +223,44 @@ export const prepareAdvancerKit = (
       transferHandler: {
         /**
          * @param {undefined} result TODO confirm this is not a bigint (sequence)
-         * @param {{ destination: ChainAddress; amount: NatAmount; }} ctx
+         * @param {AdvancerVowCtx} ctx
          */
-        onFulfilled(result, { destination, amount }) {
-          // TODO vstorage update? We don't currently have a status for
-          // Advanced + transferV settled
+        onFulfilled(result, ctx) {
+          const { notifyFacet } = this.state;
+          const { amount, destination, forwardingAddress, txHash } = ctx;
           log(
             'Advance transfer fulfilled',
             q({ amount, destination, result }).toString(),
           );
+          notifyFacet.notifyAdvancingResult(
+            txHash,
+            forwardingAddress,
+            amount.value,
+            destination.value,
+            true,
+          );
         },
-        onRejected(error) {
-          // TODO #10510 (comprehensive error testing) determine
-          // course of action here. This might fail due to timeout.
+        /**
+         * @param {Error} error
+         * @param {AdvancerVowCtx} ctx
+         */
+        onRejected(error, ctx) {
+          const { notifyFacet } = this.state;
+          const { amount, destination, forwardingAddress, txHash } = ctx;
           log('Advance transfer rejected', q(error).toString());
+          notifyFacet.notifyAdvancingResult(
+            txHash,
+            forwardingAddress,
+            amount.value,
+            destination.value,
+            false,
+          );
         },
       },
     },
     {
       stateShape: harden({
+        notifyFacet: M.remotable(),
         borrowerFacet: M.remotable(),
         poolAccount: M.remotable(),
       }),

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

@@ -1,4 +1,4 @@
-import { AmountMath, AmountShape } from '@agoric/ertp';
+import { AmountMath } from '@agoric/ertp';
 import {
   makeRecorderTopic,
   TopicsRecordShape,
@@ -84,7 +84,6 @@ export const prepareLiquidityPoolKit = (zone, zcf, USDC, tools) => {
     'Liquidity Pool',
     {
       borrower: M.interface('borrower', {
-        getBalance: M.call().returns(AmountShape),
         borrow: M.call(
           SeatShape,
           harden({ USDC: makeNatAmountShape(USDC, 1n) }),
@@ -152,10 +151,6 @@ export const prepareLiquidityPoolKit = (zone, zcf, USDC, tools) => {
     },
     {
       borrower: {
-        getBalance() {
-          const { poolSeat } = this.state;
-          return poolSeat.getAmountAllocated('USDC', USDC);
-        },
         /**
          * @param {ZCFSeat} toSeat
          * @param {{ USDC: Amount<'nat'>}} amountKWR