refactor: forwardFunds flow

Author: turadg

packages/fast-usdc-contract/src/exos/settler.ts

@@ -49,20 +49,14 @@ import type { WithdrawToSeat } from '@agoric/orchestration/src/utils/zoe-tools.j
 import { mustMatch, type MapStore } from '@agoric/store';
 import type { IBCChannelID, IBCPacket, VTransferIBCEvent } from '@agoric/vats';
 import type { TargetRegistration } from '@agoric/vats/src/bridge-target.js';
-import type { VowTools } from '@agoric/vow';
+import type { Vow, VowTools } from '@agoric/vow';
 import type { ZCF } from '@agoric/zoe/src/zoeService/zoe.js';
 import type { Zone } from '@agoric/zone';
 import { makeSupportsCctp } from '../utils/cctp.ts';
 import { asMultiset } from '../utils/store.ts';
 import type { LiquidityPoolKit } from './liquidity-pool.js';
 import type { StatusManager } from './status-manager.js';
 
-const FORWARD_TIMEOUT = {
-  sec: 10n * 60n,
-  p: '10m',
-} as const;
-harden(FORWARD_TIMEOUT);
-
 const decodeEventPacket = (
   { data }: IBCPacket,
   remoteDenom: string,
@@ -148,9 +142,9 @@ export const stateShape = harden({
 export const prepareSettler = (
   zone: Zone,
   {
-    currentChainReference,
     chainHub,
     feeConfig,
+    forwardFunds,
     getNobleICA,
     log = makeTracer('Settler', true),
     statusManager,
@@ -159,10 +153,14 @@ export const prepareSettler = (
     withdrawToSeat,
     zcf,
   }: {
-    /** e.g., `agoric-3` */
-    currentChainReference: string;
     chainHub: Pick<ChainHub, 'resolveAccountId'>;
     feeConfig: FeeConfig;
+    forwardFunds: (tx: {
+      txHash: EvmHash;
+      amount: NatAmount;
+      destination: AccountId;
+      fundsInNobleIca?: boolean;
+    }) => Vow<void>;
     getNobleICA: () => OrchestrationAccount<{ chainId: 'noble-1' }>;
     log?: LogFn;
     statusManager: StatusManager;
@@ -176,8 +174,6 @@ export const prepareSettler = (
 
   const UsdcAmountShape = makeNatAmountShape(USDC);
 
-  const supportsCctp = makeSupportsCctp(chainHub);
-
   return zone.exoClassKit(
     'Fast USDC Settler',
     {
@@ -203,6 +199,10 @@ export const prepareSettler = (
         ),
         forward: M.call(EvmHashShape, UsdcAmountShape, M.string()).returns(),
       }),
+      // XXX the following handlers are from before refactoring to an async flow for `forwardFunds`.
+      // They must remain implemented for as long as any vow might settle and need their behavior.
+      // Once all possible such vows are settled, the methods could be removed but the handler
+      // facets must remain to satisfy the kind definition backward compatibility checker.
       transferHandler: M.interface('SettlerTransferI', {
         onFulfilled: M.call(M.undefined(), M.string()).returns(),
         onRejected: M.call(M.error(), M.string()).returns(),
@@ -427,7 +427,6 @@ export const prepareSettler = (
           fullValue: NatAmount,
           EUD: AccountId | Bech32Address,
         ) {
-          const { settlementAccount } = this.state;
           log('forwarding', fullValue.value, 'to', EUD, 'for', txHash);
 
           const dest: AccountId | null = (() => {
@@ -446,44 +445,8 @@ export const prepareSettler = (
           })();
           if (!dest) return;
 
-          const { namespace, reference } = parseAccountId(dest);
-
-          const intermediateRecipient = getNobleICA().getAddress();
-
-          if (namespace === 'cosmos') {
-            const transferOrSendV =
-              reference === currentChainReference
-                ? E(settlementAccount).send(dest, fullValue)
-                : E(settlementAccount).transfer(dest, fullValue, {
-                    timeoutRelativeSeconds: FORWARD_TIMEOUT.sec,
-                    forwardOpts: {
-                      intermediateRecipient,
-                      timeout: FORWARD_TIMEOUT.p,
-                    },
-                  });
-            void vowTools.watch(
-              transferOrSendV,
-              this.facets.transferHandler,
-              txHash,
-            );
-          } else if (supportsCctp(dest)) {
-            // send to Noble then call `.depositForBurn(dest, fullValue)`
-            void vowTools.watch(
-              E(settlementAccount).transfer(intermediateRecipient, fullValue, {
-                timeoutRelativeSeconds: FORWARD_TIMEOUT.sec,
-              }),
-              this.facets.intermediateTransferHandler,
-              { amt: fullValue, dest, txHash },
-            );
-          } else {
-            log(
-              '🚨 forward not attempted!',
-              'unsupported destination',
-              txHash,
-              dest,
-            );
-            statusManager.forwardSkipped(txHash);
-          }
+          // This synchronous function returns a Vow that does its own error handling.
+          void forwardFunds({ txHash, amount: fullValue, destination: dest });
         },
       },
       transferHandler: {

packages/fast-usdc-contract/src/fast-usdc.contract.ts

@@ -20,6 +20,7 @@ import {
   type OrchestrationPowers,
   type OrchestrationTools,
 } from '@agoric/orchestration';
+import type { HostForGuest } from '@agoric/orchestration/src/facade.js';
 import { makeZoeTools } from '@agoric/orchestration/src/utils/zoe-tools.js';
 import { provideSingleton } from '@agoric/zoe/src/contractSupport/durability.js';
 import { prepareRecorderKitMakers } from '@agoric/zoe/src/contractSupport/recorder.js';
@@ -48,6 +49,7 @@ import { prepareStatusManager } from './exos/status-manager.ts';
 import type { OperatorOfferResult } from './exos/transaction-feed.ts';
 import { prepareTransactionFeedKit } from './exos/transaction-feed.ts';
 import * as flows from './fast-usdc.flows.ts';
+import { makeSupportsCctp } from './utils/cctp.ts';
 
 const trace = makeTracer('FastUsdc');
 
@@ -133,17 +135,60 @@ export const contract = async (
   const getNobleICA = (): OrchestrationAccount<{ chainId: 'noble-1' }> =>
     baggage.get(NOBLE_ICA_BAGGAGE_KEY);
 
+  /** Chain, connection, and asset info can only be registered once */
+  const firstIncarnationKey = 'firstIncarnationKey';
+  // Perform this before makeLocalAccount() is called or it will cause
+  // `agoric` chain info to be pulled from agoricNames.
+  // UNTIL https://github.com/Agoric/agoric-sdk/issues/10602
+  if (!baggage.has(firstIncarnationKey)) {
+    baggage.init(firstIncarnationKey, true);
+    registerChainsAndAssets(
+      chainHub,
+      terms.brands,
+      privateArgs.chainInfo,
+      privateArgs.assetInfo,
+    );
+  }
+
+  const supportsCctp = makeSupportsCctp(chainHub);
+
+  const { makeLocalAccount, makeNobleAccount } = orchestrateAll(
+    {
+      // TODO flow picker for orchestrateAll with different contexts or ordering
+      makeLocalAccount: flows.makeLocalAccount,
+      makeNobleAccount: flows.makeNobleAccount,
+    },
+    {},
+  );
+
+  const poolAccountV = zone.makeOnce('PoolAccount', () => makeLocalAccount());
+  const settleAccountV = zone.makeOnce('SettleAccount', () =>
+    makeLocalAccount(),
+  );
+  const { forwardFunds } = orchestrateAll(
+    // @ts-expect-error flow membrance type debt
+    { forwardFunds: flows.forwardFunds },
+    {
+      currentChainReference: privateArgs.chainInfo.agoric.chainId,
+      getNobleICA,
+      log: makeTracer('ForwardFunds'),
+      settlementAccount: settleAccountV,
+      supportsCctp,
+      statusManager,
+    },
+  ) as { forwardFunds: HostForGuest<typeof flows.forwardFunds> };
+
   const makeSettler = prepareSettler(zone, {
     statusManager,
     USDC,
     withdrawToSeat,
     feeConfig,
+    forwardFunds,
     getNobleICA,
     vowTools: tools.vowTools,
     zcf,
     // UNTIL we have an generic way to attenuate an Exo https://github.com/Agoric/agoric-sdk/issues/11309
     chainHub: { resolveAccountId: chainHub.resolveAccountId.bind(chainHub) },
-    currentChainReference: privateArgs.chainInfo.agoric.chainId,
   });
 
   const zoeTools = makeZoeTools(zcf, vowTools);
@@ -170,8 +215,6 @@ export const contract = async (
     { makeRecorderKit },
   );
 
-  const { makeLocalAccount, makeNobleAccount } = orchestrateAll(flows, {});
-
   const creatorFacet = zone.exo('Fast USDC Creator', undefined, {
     async makeOperatorInvitation(
       operatorId: string,
@@ -294,24 +337,8 @@ export const contract = async (
     makeLiquidityPoolKit(shareMint, privateArgs.poolMetricsNode),
   );
 
-  /** Chain, connection, and asset info can only be registered once */
-  const firstIncarnationKey = 'firstIncarnationKey';
-  if (!baggage.has(firstIncarnationKey)) {
-    baggage.init(firstIncarnationKey, true);
-    registerChainsAndAssets(
-      chainHub,
-      terms.brands,
-      privateArgs.chainInfo,
-      privateArgs.assetInfo,
-    );
-  }
-
   const feedKit = zone.makeOnce('Feed Kit', () => makeFeedKit());
 
-  const poolAccountV = zone.makeOnce('PoolAccount', () => makeLocalAccount());
-  const settleAccountV = zone.makeOnce('SettleAccount', () =>
-    makeLocalAccount(),
-  );
   // when() is OK here since this clearly resolves promptly.
   const [poolAccount, settlementAccount] = (await vowTools.when(
     vowTools.all([poolAccountV, settleAccountV]),

packages/fast-usdc-contract/src/fast-usdc.flows.ts

@@ -1,4 +1,30 @@
-import type { OrchestrationFlow, Orchestrator } from '@agoric/orchestration';
+import type { NatAmount } from '@agoric/ertp';
+import type { EvmHash } from '@agoric/fast-usdc/src/types.ts';
+import type {
+  AccountId,
+  OrchestrationAccount,
+  OrchestrationFlow,
+  Orchestrator,
+} from '@agoric/orchestration';
+import { parseAccountId } from '@agoric/orchestration/src/utils/address.js';
+import { assertAllDefined } from '@agoric/internal';
+import type { StatusManager } from './exos/status-manager.ts';
+
+const FORWARD_TIMEOUT = {
+  sec: 10n * 60n,
+  p: '10m',
+} as const;
+harden(FORWARD_TIMEOUT);
+
+export interface Context {
+  /** e.g., `agoric-3` */
+  currentChainReference: string;
+  supportsCctp: (destination: AccountId) => boolean;
+  log: Console['log'];
+  statusManager: StatusManager;
+  getNobleICA: () => OrchestrationAccount<{ chainId: 'noble-1' }>;
+  settlementAccount: Promise<OrchestrationAccount<{ chainId: 'agoric-any' }>>;
+}
 
 export const makeLocalAccount = (async (orch: Orchestrator) => {
   const agoricChain = await orch.getChain('agoric');
@@ -11,3 +37,98 @@ export const makeNobleAccount = (async (orch: Orchestrator) => {
   return nobleChain.makeAccount();
 }) satisfies OrchestrationFlow;
 harden(makeNobleAccount);
+
+export const forwardFunds = async (
+  orch: Orchestrator,
+  {
+    currentChainReference,
+    supportsCctp,
+    log,
+    getNobleICA,
+    settlementAccount,
+    statusManager,
+  }: Context,
+  tx: {
+    txHash: EvmHash;
+    amount: NatAmount;
+    destination: AccountId;
+  },
+) => {
+  await null;
+  assertAllDefined({
+    currentChainReference,
+    supportsCctp,
+    log,
+    getNobleICA,
+    settlementAccount,
+    statusManager,
+    tx,
+  });
+  const { amount, destination, txHash } = tx;
+  log('trying forward for', amount, 'to', destination, 'for', txHash);
+
+  const { namespace, reference } = parseAccountId(destination);
+
+  const settlement = await settlementAccount;
+  const intermediateRecipient = getNobleICA().getAddress();
+
+  if (namespace === 'cosmos') {
+    const completion =
+      reference === currentChainReference
+        ? settlement.send(destination, amount)
+        : settlement.transfer(destination, amount, {
+            timeoutRelativeSeconds: FORWARD_TIMEOUT.sec,
+            forwardOpts: {
+              intermediateRecipient,
+              timeout: FORWARD_TIMEOUT.p,
+            },
+          });
+    try {
+      await completion;
+      log('forward successful for', txHash);
+      statusManager.forwarded(tx.txHash);
+    } catch (reason) {
+      // funds remain in `settlementAccount` and must be recovered via a
+      // contract upgrade
+      log('🚨 forward transfer rejected!', reason, txHash);
+      // update status manager, flagging a terminal state that needs to be
+      // manual intervention or a code update to remediate
+      statusManager.forwardFailed(txHash);
+    }
+  } else if (supportsCctp(destination)) {
+    try {
+      await settlement.transfer(intermediateRecipient, amount, {
+        timeoutRelativeSeconds: FORWARD_TIMEOUT.sec,
+      });
+    } catch (reason) {
+      // funds remain in `settlementAccount` and must be recovered via a
+      // contract upgrade
+      log('🚨 forward intermediate transfer rejected!', reason, txHash);
+      // update status manager, flagging a terminal state that needs manual
+      // intervention or a code update to remediate
+      statusManager.forwardFailed(txHash);
+    }
+
+    try {
+      await getNobleICA().depositForBurn(destination, amount);
+      log('forward transfer and depositForBurn successful for', txHash);
+      statusManager.forwarded(tx.txHash);
+    } catch (reason) {
+      // funds remain in `nobleAccount` and must be recovered via a
+      // contract upgrade
+      log('🚨 forward depositForBurn rejected!', reason, txHash);
+      // update status manager, flagging a terminal state that needs manual
+      // intervention or a code update to remediate
+      statusManager.forwardFailed(txHash);
+    }
+  } else {
+    log(
+      '⚠️ forward not attempted',
+      'unsupported destination',
+      txHash,
+      destination,
+    );
+    statusManager.forwardSkipped(txHash);
+  }
+};
+harden(forwardFunds);