@agoric/fast-usdc 0.1.1-dev-8fd731c.0 → 0.1.1-dev-aa11d5c.0

package/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
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/fast-usdc",
-  "version": "0.1.1-dev-8fd731c.0+8fd731c",
+  "version": "0.1.1-dev-aa11d5c.0+aa11d5c",
   "description": "CLI and library for Fast USDC product",
   "type": "module",
   "files": [
@@ -21,9 +21,9 @@
     "lint:eslint": "eslint ."
   },
   "devDependencies": {
-    "@agoric/swingset-liveslots": "0.10.3-dev-8fd731c.0+8fd731c",
-    "@agoric/vats": "0.15.2-dev-8fd731c.0+8fd731c",
-    "@agoric/zone": "0.2.3-dev-8fd731c.0+8fd731c",
+    "@agoric/swingset-liveslots": "0.10.3-dev-aa11d5c.0+aa11d5c",
+    "@agoric/vats": "0.15.2-dev-aa11d5c.0+aa11d5c",
+    "@agoric/zone": "0.2.3-dev-aa11d5c.0+aa11d5c",
     "@fast-check/ava": "^2.0.1",
     "ava": "^5.3.0",
     "c8": "^10.1.2",
@@ -31,15 +31,15 @@
     "ts-blank-space": "^0.4.1"
   },
   "dependencies": {
-    "@agoric/client-utils": "0.1.1-dev-8fd731c.0+8fd731c",
-    "@agoric/ertp": "0.16.3-dev-8fd731c.0+8fd731c",
-    "@agoric/internal": "0.3.3-dev-8fd731c.0+8fd731c",
-    "@agoric/notifier": "0.6.3-dev-8fd731c.0+8fd731c",
-    "@agoric/orchestration": "0.1.1-dev-8fd731c.0+8fd731c",
-    "@agoric/store": "0.9.3-dev-8fd731c.0+8fd731c",
-    "@agoric/vat-data": "0.5.3-dev-8fd731c.0+8fd731c",
-    "@agoric/vow": "0.1.1-dev-8fd731c.0+8fd731c",
-    "@agoric/zoe": "0.26.3-dev-8fd731c.0+8fd731c",
+    "@agoric/client-utils": "0.1.1-dev-aa11d5c.0+aa11d5c",
+    "@agoric/ertp": "0.16.3-dev-aa11d5c.0+aa11d5c",
+    "@agoric/internal": "0.3.3-dev-aa11d5c.0+aa11d5c",
+    "@agoric/notifier": "0.6.3-dev-aa11d5c.0+aa11d5c",
+    "@agoric/orchestration": "0.1.1-dev-aa11d5c.0+aa11d5c",
+    "@agoric/store": "0.9.3-dev-aa11d5c.0+aa11d5c",
+    "@agoric/vat-data": "0.5.3-dev-aa11d5c.0+aa11d5c",
+    "@agoric/vow": "0.1.1-dev-aa11d5c.0+aa11d5c",
+    "@agoric/zoe": "0.26.3-dev-aa11d5c.0+aa11d5c",
     "@cosmjs/proto-signing": "^0.32.4",
     "@cosmjs/stargate": "^0.32.4",
     "@endo/base64": "^1.0.9",
@@ -78,5 +78,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "8fd731ce457512f3ad1b7d8e936b935e0f8d3b9b"
+  "gitHead": "aa11d5c2482ac47f1a6ab8ac5e67a9678e2946f7"
 }

package/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);

package/src/exos/advancer.js

@@ -6,12 +6,14 @@ 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';
@@ -19,7 +21,7 @@ const { isGTE } = AmountMath;
  * @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,12 +48,16 @@ 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', {
@@ -59,14 +65,27 @@ const AdvancerKitI = harden({
     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,10 +189,11 @@ 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,
@@ -197,11 +201,13 @@ export const prepareAdvancerKit = (
           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(),
       }),

package/src/exos/liquidity-pool.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

package/src/exos/settler.js

@@ -1,97 +1,291 @@
-import { assertAllDefined } from '@agoric/internal';
+import { AmountMath } from '@agoric/ertp';
+import { assertAllDefined, makeTracer } from '@agoric/internal';
 import { atob } from '@endo/base64';
-import { makeError, q } from '@endo/errors';
+import { E } from '@endo/far';
 import { M } from '@endo/patterns';
 
+import { PendingTxStatus } from '../constants.js';
 import { addressTools } from '../utils/address.js';
+import { makeFeeTools } from '../utils/fees.js';
+import { EvmHashShape } from '../type-guards.js';
 
 /**
  * @import {FungibleTokenPacketData} from '@agoric/cosmic-proto/ibc/applications/transfer/v2/packet.js';
- * @import {Denom} from '@agoric/orchestration';
+ * @import {Denom, OrchestrationAccount, ChainHub} from '@agoric/orchestration';
+ * @import {WithdrawToSeat} from '@agoric/orchestration/src/utils/zoe-tools'
  * @import {IBCChannelID, VTransferIBCEvent} from '@agoric/vats';
  * @import {Zone} from '@agoric/zone';
- * @import {NobleAddress} from '../types.js';
+ * @import {HostOf, HostInterface} from '@agoric/async-flow';
+ * @import {TargetRegistration} from '@agoric/vats/src/bridge-target.js';
+ * @import {NobleAddress, LiquidityPoolKit, FeeConfig, EvmHash} from '../types.js';
  * @import {StatusManager} from './status-manager.js';
  */
 
+const trace = makeTracer('Settler');
+
+/**
+ * NOTE: not meant to be parsable.
+ *
+ * @param {NobleAddress} addr
+ * @param {bigint} amount
+ */
+const makeMintedEarlyKey = (addr, amount) =>
+  `pendingTx:${JSON.stringify([addr, String(amount)])}`;
+
 /**
  * @param {Zone} zone
  * @param {object} caps
  * @param {StatusManager} caps.statusManager
+ * @param {Brand<'nat'>} caps.USDC
+ * @param {Pick<ZCF, 'makeEmptySeatKit' | 'atomicRearrange'>} caps.zcf
+ * @param {FeeConfig} caps.feeConfig
+ * @param {HostOf<WithdrawToSeat>} caps.withdrawToSeat
+ * @param {import('@agoric/vow').VowTools} caps.vowTools
+ * @param {ChainHub} caps.chainHub
  */
-export const prepareSettler = (zone, { statusManager }) => {
+export const prepareSettler = (
+  zone,
+  { statusManager, USDC, zcf, feeConfig, withdrawToSeat, vowTools, chainHub },
+) => {
   assertAllDefined({ statusManager });
-  return zone.exoClass(
+  return zone.exoClassKit(
     'Fast USDC Settler',
-    M.interface('SettlerI', {
-      receiveUpcall: M.call(M.record()).returns(M.promise()),
-    }),
+    {
+      creator: M.interface('SettlerCreatorI', {
+        monitorMintingDeposits: M.callWhen().returns(M.any()),
+      }),
+      tap: M.interface('SettlerTapI', {
+        receiveUpcall: M.call(M.record()).returns(M.promise()),
+      }),
+      notify: M.interface('SettlerNotifyI', {
+        notifyAdvancingResult: M.call(
+          M.string(),
+          M.nat(),
+          M.boolean(),
+        ).returns(),
+      }),
+      self: M.interface('SettlerSelfI', {
+        disburse: M.call(EvmHashShape, M.string(), M.nat()).returns(
+          M.promise(),
+        ),
+        forward: M.call(
+          M.opt(EvmHashShape),
+          M.string(),
+          M.nat(),
+          M.string(),
+        ).returns(),
+      }),
+      transferHandler: M.interface('SettlerTransferI', {
+        onFulfilled: M.call(M.any(), M.record()).returns(),
+        onRejected: M.call(M.any(), M.record()).returns(),
+      }),
+    },
     /**
-     *
      * @param {{
      *   sourceChannel: IBCChannelID;
-     *   remoteDenom: Denom
+     *   remoteDenom: Denom;
+     *   repayer: LiquidityPoolKit['repayer'];
+     *   settlementAccount: HostInterface<OrchestrationAccount<{ chainId: 'agoric' }>>
      * }} config
      */
-    config => harden(config),
+    config => {
+      return {
+        ...config,
+        /** @type {HostInterface<TargetRegistration>|undefined} */
+        registration: undefined,
+        /** @type {SetStore<ReturnType<typeof makeMintedEarlyKey>>} */
+        mintedEarly: zone.detached().setStore('mintedEarly'),
+      };
+    },
     {
-      /** @param {VTransferIBCEvent} event */
-      async receiveUpcall(event) {
-        if (event.packet.source_channel !== this.state.sourceChannel) {
-          // TODO #10390 log all early returns
-          // only interested in packets from the issuing chain
-          return;
-        }
-        const tx = /** @type {FungibleTokenPacketData} */ (
-          JSON.parse(atob(event.packet.data))
-        );
-        if (tx.denom !== this.state.remoteDenom) {
-          // only interested in uusdc
-          return;
-        }
-
-        if (!addressTools.hasQueryParams(tx.receiver)) {
-          // only interested in receivers with query params
-          return;
-        }
-
-        const { EUD } = addressTools.getQueryParams(tx.receiver);
-        if (!EUD) {
-          // only interested in receivers with EUD parameter
-          return;
-        }
-
-        // TODO discern between SETTLED and OBSERVED; each has different fees/destinations
-        const hasPendingSettlement = statusManager.hasPendingSettlement(
+      creator: {
+        async monitorMintingDeposits() {
+          const { settlementAccount } = this.state;
+          const registration = await vowTools.when(
+            settlementAccount.monitorTransfers(this.facets.tap),
+          );
+          assert.typeof(registration, 'object');
+          this.state.registration = registration;
+        },
+      },
+      tap: {
+        /** @param {VTransferIBCEvent} event */
+        async receiveUpcall(event) {
+          const { sourceChannel, remoteDenom } = this.state;
+          const { packet } = event;
+          if (packet.source_channel !== sourceChannel) {
+            const { source_channel: actual } = packet;
+            trace('unexpected channel', { actual, expected: sourceChannel });
+            return;
+          }
+
+          // TODO: why is it safe to cast this without a runtime check?
+          const tx = /** @type {FungibleTokenPacketData} */ (
+            JSON.parse(atob(packet.data))
+          );
+
           // given the sourceChannel check, we can be certain of this cast
-          /** @type {NobleAddress} */ (tx.sender),
-          BigInt(tx.amount),
-        );
-        if (!hasPendingSettlement) {
-          // TODO FAILURE PATH -> put money in recovery account or .transfer to receiver
-          // TODO should we have an ORPHANED TxStatus for this?
-          throw makeError(
-            `🚨 No pending settlement found for ${q(tx.sender)} ${q(tx.amount)}`,
+          const sender = /** @type {NobleAddress} */ (tx.sender);
+
+          if (tx.denom !== remoteDenom) {
+            const { denom: actual } = tx;
+            trace('unexpected denom', { actual, expected: remoteDenom });
+            return;
+          }
+
+          if (!addressTools.hasQueryParams(tx.receiver)) {
+            console.log('not query params', tx.receiver);
+            return;
+          }
+
+          const { EUD } = addressTools.getQueryParams(tx.receiver);
+          if (!EUD) {
+            console.log('no EUD parameter', tx.receiver);
+            return;
+          }
+
+          const amount = BigInt(tx.amount); // TODO: what if this throws?
+
+          const { self } = this.facets;
+          const found = statusManager.dequeueStatus(sender, amount);
+          trace('dequeued', found, 'for', sender, amount);
+          switch (found?.status) {
+            case PendingTxStatus.Advanced:
+              return self.disburse(found.txHash, sender, amount);
+
+            case PendingTxStatus.Advancing:
+              this.state.mintedEarly.add(makeMintedEarlyKey(sender, amount));
+              return;
+
+            case undefined:
+            case PendingTxStatus.Observed:
+            case PendingTxStatus.AdvanceFailed:
+            default:
+              return self.forward(found?.txHash, sender, amount, EUD);
+          }
+        },
+      },
+      notify: {
+        /**
+         * @param {EvmHash} txHash
+         * @param {NobleAddress} sender
+         * @param {NatValue} amount
+         * @param {string} EUD
+         * @param {boolean} success
+         * @returns {void}
+         */
+        notifyAdvancingResult(txHash, sender, amount, EUD, success) {
+          const { mintedEarly } = this.state;
+          const key = makeMintedEarlyKey(sender, amount);
+          if (mintedEarly.has(key)) {
+            mintedEarly.delete(key);
+            if (success) {
+              void this.facets.self.disburse(txHash, sender, amount);
+            } else {
+              void this.facets.self.forward(txHash, sender, amount, EUD);
+            }
+          } else {
+            statusManager.advanceOutcome(sender, amount, success);
+          }
+        },
+      },
+      self: {
+        /**
+         * @param {EvmHash} txHash
+         * @param {NobleAddress} sender
+         * @param {NatValue} amount
+         */
+        async disburse(txHash, sender, amount) {
+          const { repayer, settlementAccount } = this.state;
+          const received = AmountMath.make(USDC, amount);
+          const { zcfSeat: settlingSeat } = zcf.makeEmptySeatKit();
+          const { calculateSplit } = makeFeeTools(feeConfig);
+          const split = calculateSplit(received);
+          trace('disbursing', split);
+
+          // TODO: what if this throws?
+          // arguably, it cannot. Even if deposits
+          // and notifications get out of order,
+          // we don't ever withdraw more than has been deposited.
+          await vowTools.when(
+            withdrawToSeat(
+              // @ts-expect-error Vow vs. Promise stuff. TODO: is this OK???
+              settlementAccount,
+              settlingSeat,
+              harden({ In: received }),
+            ),
+          );
+          zcf.atomicRearrange(
+            harden([[settlingSeat, settlingSeat, { In: received }, split]]),
           );
-        }
+          repayer.repay(settlingSeat, split);
 
-        // TODO disperse funds
-        // ~1. fee to contractFeeAccount
-        // ~2. remainder in poolAccount
+          // update status manager, marking tx `SETTLED`
+          statusManager.disbursed(txHash, sender, amount);
+        },
+        /**
+         * @param {EvmHash | undefined} txHash
+         * @param {NobleAddress} sender
+         * @param {NatValue} amount
+         * @param {string} EUD
+         */
+        forward(txHash, sender, amount, EUD) {
+          const { settlementAccount } = this.state;
 
-        // update status manager, marking tx `SETTLED`
-        statusManager.settle(
-          /** @type {NobleAddress} */ (tx.sender),
-          BigInt(tx.amount),
-        );
+          const dest = chainHub.makeChainAddress(EUD);
+
+          // TODO? statusManager.forwarding(txHash, sender, amount);
+          const txfrV = E(settlementAccount).transfer(
+            dest,
+            AmountMath.make(USDC, amount),
+          );
+          void vowTools.watch(txfrV, this.facets.transferHandler, {
+            txHash,
+            sender,
+            amount,
+          });
+        },
+      },
+      transferHandler: {
+        /**
+         * @param {unknown} result
+         * @param {SettlerTransferCtx} ctx
+         *
+         * @typedef {{
+         *   txHash: EvmHash;
+         *   sender: NobleAddress;
+         *   amount: NatValue;
+         * }} SettlerTransferCtx
+         */
+        onFulfilled(result, ctx) {
+          const { txHash, sender, amount } = ctx;
+          statusManager.forwarded(txHash, sender, amount);
+        },
+        /**
+         * @param {unknown} _result
+         * @param {SettlerTransferCtx} _ctx
+         */
+        onRejected(_result, _ctx) {
+          // const { txHash, sender, amount } = ctx;
+          // TODO: statusManager.forwardFailed(txHash, sender, amount);
+        },
       },
     },
     {
       stateShape: harden({
+        repayer: M.remotable('Repayer'),
+        settlementAccount: M.remotable('Account'),
+        registration: M.or(M.undefined(), M.remotable('Registration')),
         sourceChannel: M.string(),
         remoteDenom: M.string(),
+        mintedEarly: M.remotable('mintedEarly'),
       }),
     },
   );
 };
 harden(prepareSettler);
+
+/**
+ * XXX consider using pickFacet (do we have pickFacets?)
+ * @typedef {ReturnType<ReturnType<typeof prepareSettler>>} SettlerKit
+ */

package/src/exos/status-manager.js

@@ -1,14 +1,18 @@
 import { M } from '@endo/patterns';
-import { makeError, q } from '@endo/errors';
+import { Fail, makeError, q } from '@endo/errors';
 
 import { appendToStoredArray } from '@agoric/store/src/stores/store-utils.js';
-import { CctpTxEvidenceShape, PendingTxShape } from '../type-guards.js';
+import {
+  CctpTxEvidenceShape,
+  EvmHashShape,
+  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';
+ * @import {CctpTxEvidence, NobleAddress, SeenTxKey, PendingTxKey, PendingTx, EvmHash} from '../types.js';
  */
 
 /**
@@ -96,21 +100,69 @@ export const prepareStatusManager = zone => {
   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(),
       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()),
+      dequeueStatus: M.call(M.string(), M.bigint()).returns(
+        M.or(
+          {
+            txHash: EvmHashShape,
+            status: M.or(
+              PendingTxStatus.Advanced,
+              PendingTxStatus.AdvanceFailed,
+              PendingTxStatus.Observed,
+            ),
+          },
+          M.undefined(),
+        ),
+      ),
+      disbursed: M.call(EvmHashShape, M.string(), M.nat()).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
        * @param {CctpTxEvidence} evidence
        */
       advance(evidence) {
-        recordPendingTx(evidence, PendingTxStatus.Advanced);
+        recordPendingTx(evidence, PendingTxStatus.Advancing);
+      },
+
+      /**
+       * Record result of ADVANCING
+       *
+       * @param {NobleAddress} sender
+       * @param {import('@agoric/ertp').NatValue} amount
+       * @param {boolean} success - Advanced vs. AdvanceFailed
+       * @throws {Error} if nothing to advance
+       */
+      advanceOutcome(sender, amount, success) {
+        const key = makePendingTxKey(sender, amount);
+        pendingTxs.has(key) || Fail`no advancing tx with ${{ sender, amount }}`;
+        const pending = pendingTxs.get(key);
+        const ix = pending.findIndex(
+          tx => tx.status === PendingTxStatus.Advancing,
+        );
+        ix >= 0 || Fail`no advancing tx with ${{ sender, amount }}`;
+        const [prefix, tx, suffix] = [
+          pending.slice(0, ix),
+          pending[ix],
+          pending.slice(ix + 1),
+        ];
+        const status = success
+          ? PendingTxStatus.Advanced
+          : PendingTxStatus.AdvanceFailed;
+        const txpost = { ...tx, status };
+        pendingTxs.set(key, harden([...prefix, txpost, ...suffix]));
       },
 
       /**
@@ -122,41 +174,76 @@ export const prepareStatusManager = zone => {
       },
 
       /**
-       * 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) {
+        const seenKey = seenTxKeyOf(evidence);
+        return seenTxs.has(seenKey);
       },
 
       /**
-       * 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 {bigint} amount
+       * @returns {Pick<PendingTx, 'status' | 'txHash'> | undefined} undefined if nothing
+       *   with this address and amount has been marked pending.
        */
-      settle(address, amount) {
+      dequeueStatus(address, amount) {
         const key = makePendingTxKey(address, 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 {NobleAddress} address
+       * @param {bigint} amount
+       */
+      disbursed(txHash, address, amount) {
+        // TODO: store txHash -> evidence for txs pending settlement?
+        console.log('TODO: vstorage update', { txHash, address, amount });
+      },
+
+      /**
+       * Mark a transaction as `FORWARDED`
+       *
+       * @param {EvmHash | undefined} txHash - undefined in case mint before observed
+       * @param {NobleAddress} address
+       * @param {bigint} amount
+       */
+      forwarded(txHash, address, amount) {
+        // TODO: store txHash -> evidence for txs pending settlement?
+        console.log('TODO: vstorage update', { txHash, address, amount });
       },
 
       /**
        * Lookup all pending entries for a given address and amount
        *
+       * XXX only used in tests. should we remove?
+       *
        * @param {NobleAddress} address
        * @param {bigint} amount
        * @returns {PendingTx[]}
@@ -164,7 +251,7 @@ export const prepareStatusManager = zone => {
       lookupPending(address, amount) {
         const key = makePendingTxKey(address, amount);
         if (!pendingTxs.has(key)) {
-          throw makeError(`Key ${q(key)} not yet observed`);
+          return harden([]);
         }
         return pendingTxs.get(key);
       },

package/src/fast-usdc.contract.js

@@ -71,14 +71,28 @@ export const contract = async (zcf, privateArgs, zone, 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 { USDC } = terms.brands;
+  const { withdrawToSeat } = tools.zoeTools;
   const { chainHub, orchestrateAll, vowTools } = tools;
+  const makeSettler = prepareSettler(zone, {
+    statusManager,
+    USDC,
+    withdrawToSeat,
+    feeConfig,
+    vowTools: tools.vowTools,
+    zcf,
+    chainHub,
+  });
+
   const { localTransfer } = makeZoeTools(zcf, vowTools);
   const makeAdvancer = prepareAdvancer(zone, {
     chainHub,
@@ -92,8 +106,10 @@ export const contract = async (zcf, privateArgs, zone, tools) => {
     vowTools,
     zcf,
   });
+
   const makeFeedKit = prepareTransactionFeedKit(zone, zcf);
   assertAllDefined({ makeFeedKit, makeAdvancer, makeSettler, statusManager });
+
   const makeLiquidityPoolKit = prepareLiquidityPoolKit(
     zone,
     zcf,
@@ -111,7 +127,6 @@ export const contract = async (zcf, privateArgs, zone, tools) => {
   const creatorFacet = zone.exo('Fast USDC Creator', undefined, {
     /** @type {(operatorId: string) => Promise<Invitation<OperatorKit>>} */
     async makeOperatorInvitation(operatorId) {
-      // eslint-disable-next-line no-use-before-define
       return feedKit.creator.makeOperatorInvitation(operatorId);
     },
     /**
@@ -157,7 +172,6 @@ export const contract = async (zcf, privateArgs, zone, tools) => {
      * @param {CctpTxEvidence} evidence
      */
     makeTestPushInvitation(evidence) {
-      // eslint-disable-next-line no-use-before-define
       void advancer.handleTransactionEvent(evidence);
       return makeTestInvitation();
     },
@@ -200,18 +214,27 @@ export const contract = async (zcf, privateArgs, zone, tools) => {
 
   const feedKit = zone.makeOnce('Feed Kit', () => makeFeedKit());
 
-  const poolAccountV =
-    // cast to HostInterface
-    /** @type { Vow<HostInterface<OrchestrationAccount<{chainId: 'agoric';}>>>} */ (
-      /** @type {unknown}*/ (
-        zone.makeOnce('Pool Local Orch Account', () => makeLocalAccount())
-      )
-    );
-  const poolAccount = await vowTools.when(poolAccountV);
+  const poolAccountV = zone.makeOnce('PoolAccount', () => makeLocalAccount());
+  const settleAccountV = zone.makeOnce('SettleAccount', () =>
+    makeLocalAccount(),
+  );
+  // when() is OK here since this clearly resolves promptly.
+  /** @type {HostInterface<OrchestrationAccount<{chainId: 'agoric';}>>[]} */
+  const [poolAccount, settlementAccount] = await vowTools.when(
+    vowTools.all([poolAccountV, settleAccountV]),
+  );
+
+  const settlerKit = makeSettler({
+    repayer: poolKit.repayer,
+    sourceChannel: 'channel-1234', // TODO: fix this as soon as testing needs it',
+    remoteDenom: 'uusdc',
+    settlementAccount,
+  });
 
   const advancer = zone.makeOnce('Advancer', () =>
     makeAdvancer({
       borrowerFacet: poolKit.borrower,
+      notifyFacet: settlerKit.notify,
       poolAccount,
     }),
   );
@@ -226,6 +249,8 @@ export const contract = async (zcf, privateArgs, zone, tools) => {
     },
   });
 
+  await settlerKit.creator.monitorMintingDeposits();
+
   return harden({ creatorFacet, publicFacet });
 };
 harden(contract);

package/src/types.ts

@@ -73,3 +73,4 @@ export interface FeedPolicy {
 }
 
 export type * from './constants.js';
+export type { LiquidityPoolKit } from './exos/liquidity-pool.js';

package/src/exos/README.md

@@ -1,26 +0,0 @@
-##   **StatusManager** state diagram, showing different transitions
-
-
-### Contract state diagram
-
-*Transactions are qualified by the OCW and EventFeed before arriving to the Advancer.*
-
-```mermaid
-stateDiagram-v2
-  [*] --> Advanced: Advancer .advance()
-  Advanced --> Settled: Settler .settle() after fees
-  [*] --> Observed: Advancer .observed()
-  Observed --> Settled: Settler .settle() sans fees
-  Settled --> [*]
-```
-
-### Complete state diagram (starting from OCW)
-
-```mermaid
-stateDiagram-v2
-  Observed --> Qualified
-  Observed --> Unqualified
-  Qualified --> Advanced
-  Advanced --> Settled
-  Qualified --> Settled
-```