@agoric/fast-usdc 0.1.1-other-dev-3eb1a1d.0 → 0.1.1-upgrade-19-dev-c605745.0

package/src/distribute-fees.core.js

@@ -0,0 +1,93 @@
+/** @file core eval module to collect fees. */
+import { AmountMath } from '@agoric/ertp';
+import { floorMultiplyBy } from '@agoric/zoe/src/contractSupport/index.js';
+import { E } from '@endo/far';
+import { makeTracer } from '@agoric/internal';
+import { fromExternalConfig } from './utils/config-marshal.js';
+
+/**
+ * @import {DepositFacet} from '@agoric/ertp';
+ * @import {FastUSDCCorePowers} from '@agoric/fast-usdc/src/start-fast-usdc.core.js';
+ * @import {CopyRecord} from '@endo/pass-style'
+ * @import {BootstrapManifestPermit} from '@agoric/vats/src/core/lib-boot.js'
+ * @import {LegibleCapData} from './utils/config-marshal.js'
+ */
+
+/**
+ * @typedef {{ destinationAddress: string } &
+ *  ({ feePortion: Ratio} | {fixedFees: Amount<'nat'>}) &
+ *  CopyRecord
+ * } FeeDistributionTerms
+ */
+
+const kwUSDC = 'USDC'; // keyword in AmountKeywordRecord
+const issUSDC = 'USDC'; // issuer name
+
+const trace = makeTracer('FUCF', true);
+
+/**
+ * @param {BootstrapPowers & FastUSDCCorePowers } permittedPowers
+ * @param {{ options: LegibleCapData<{ feeTerms: FeeDistributionTerms}> }} config
+ */
+export const distributeFees = async (permittedPowers, config) => {
+  trace('distributeFees...', config.options);
+
+  const { agoricNames, namesByAddress, zoe } = permittedPowers.consume;
+  /** @type {Brand<'nat'>} */
+  const usdcBrand = await E(agoricNames).lookup('brand', issUSDC);
+  /** @type {{ feeTerms: FeeDistributionTerms}} */
+  const { feeTerms: terms } = fromExternalConfig(config.options, {
+    USDC: usdcBrand,
+  });
+
+  const { creatorFacet } = await permittedPowers.consume.fastUsdcKit;
+  const want = {
+    [kwUSDC]: await ('fixedFees' in terms
+      ? terms.fixedFees
+      : E(creatorFacet)
+          .getContractFeeBalance()
+          .then(balance => floorMultiplyBy(balance, terms.feePortion))),
+  };
+  const proposal = harden({ want });
+
+  /** @type {DepositFacet} */
+  const depositFacet = await E(namesByAddress).lookup(
+    terms.destinationAddress,
+    'depositFacet',
+  );
+  trace('to:', terms.destinationAddress, depositFacet);
+
+  const toWithdraw = await E(creatorFacet).makeWithdrawFeesInvitation();
+  trace('invitation:', toWithdraw, 'proposal:', proposal);
+  const seat = E(zoe).offer(toWithdraw, proposal);
+  const result = await E(seat).getOfferResult();
+  trace('offer result', result);
+  const payout = await E(seat).getPayout(kwUSDC);
+  /** @type {Amount<'nat'>} */
+  // @ts-expect-error USDC is a nat brand
+  const rxd = await E(depositFacet).receive(payout);
+  trace('received', rxd);
+  if (!AmountMath.isGTE(rxd, proposal.want[kwUSDC])) {
+    trace('🚨 expected', proposal.want[kwUSDC], 'got', rxd);
+  }
+  trace('done');
+};
+harden(distributeFees);
+
+/** @satisfies {BootstrapManifestPermit} */
+const permit = {
+  consume: {
+    fastUsdcKit: true,
+    agoricNames: true,
+    namesByAddress: true,
+    zoe: true,
+  },
+};
+
+/**
+ * @param {unknown} _utils
+ * @param {Parameters<typeof distributeFees>[1]} config
+ */
+export const getManifestForDistributeFees = (_utils, { options }) => {
+  return { manifest: { [distributeFees.name]: permit }, options };
+};

package/src/exos/advancer.js

@@ -1,25 +1,29 @@
-import { AmountMath, AmountShape } from '@agoric/ertp';
+import { decodeAddressHook } from '@agoric/cosmic-proto/address-hooks.js';
+import { AmountMath } from '@agoric/ertp';
 import { assertAllDefined, makeTracer } from '@agoric/internal';
-import { ChainAddressShape } from '@agoric/orchestration';
+import { AnyNatAmountShape, ChainAddressShape } from '@agoric/orchestration';
 import { pickFacet } from '@agoric/vat-data';
 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 { addressTools } from '../utils/address.js';
+import { M, mustMatch } from '@endo/patterns';
+import { Fail, q } from '@endo/errors';
+import {
+  AddressHookShape,
+  EvmHashShape,
+  EvidenceWithRiskShape,
+} from '../type-guards.js';
 import { makeFeeTools } from '../utils/fees.js';
 
-const { isGTE } = AmountMath;
-
 /**
  * @import {HostInterface} from '@agoric/async-flow';
+ * @import {Amount, Brand} from '@agoric/ertp';
+ * @import {TypedPattern} from '@agoric/internal'
  * @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 {AddressHook, EvmHash, FeeConfig, LogFn, NobleAddress, EvidenceWithRisk} from '../types.js';
  * @import {StatusManager} from './status-manager.js';
  * @import {LiquidityPoolKit} from './liquidity-pool.js';
  */
@@ -28,45 +32,73 @@ const { isGTE } = AmountMath;
  * @typedef {{
  *  chainHub: ChainHub;
  *  feeConfig: FeeConfig;
- *  localTransfer: ZoeTools['localTransfer'];
  *  log?: LogFn;
  *  statusManager: StatusManager;
  *  usdc: { brand: Brand<'nat'>; denom: Denom; };
  *  vowTools: VowTools;
  *  zcf: ZCF;
+ *  zoeTools: ZoeTools;
  * }} AdvancerKitPowers
  */
 
+/** @type {TypedPattern<AdvancerVowCtx>} */
+const AdvancerVowCtxShape = M.splitRecord(
+  {
+    fullAmount: AnyNatAmountShape,
+    advanceAmount: AnyNatAmountShape,
+    destination: ChainAddressShape,
+    forwardingAddress: M.string(),
+    txHash: EvmHashShape,
+  },
+  { tmpSeat: M.remotable() },
+);
+
 /** type guards internal to the AdvancerKit */
 const AdvancerKitI = harden({
   advancer: M.interface('AdvancerI', {
-    handleTransactionEvent: M.callWhen(CctpTxEvidenceShape).returns(),
+    handleTransactionEvent: M.callWhen(EvidenceWithRiskShape).returns(),
+    setIntermediateRecipient: M.call(ChainAddressShape).returns(),
   }),
   depositHandler: M.interface('DepositHandlerI', {
-    onFulfilled: M.call(M.undefined(), {
-      amount: AmountShape,
-      destination: ChainAddressShape,
-      tmpSeat: M.remotable(),
-    }).returns(VowShape),
-    onRejected: M.call(M.error(), {
-      amount: AmountShape,
-      destination: ChainAddressShape,
-      tmpSeat: M.remotable(),
-    }).returns(),
+    onFulfilled: M.call(M.undefined(), AdvancerVowCtxShape).returns(VowShape),
+    onRejected: M.call(M.error(), AdvancerVowCtxShape).returns(),
   }),
   transferHandler: M.interface('TransferHandlerI', {
-    // TODO confirm undefined, and not bigint (sequence)
+    onFulfilled: M.call(M.undefined(), AdvancerVowCtxShape).returns(
+      M.undefined(),
+    ),
+    onRejected: M.call(M.error(), AdvancerVowCtxShape).returns(M.undefined()),
+  }),
+  withdrawHandler: M.interface('WithdrawHandlerI', {
     onFulfilled: M.call(M.undefined(), {
-      amount: AmountShape,
-      destination: ChainAddressShape,
+      advanceAmount: AnyNatAmountShape,
+      tmpReturnSeat: M.remotable(),
     }).returns(M.undefined()),
     onRejected: M.call(M.error(), {
-      amount: AmountShape,
-      destination: ChainAddressShape,
+      advanceAmount: AnyNatAmountShape,
+      tmpReturnSeat: M.remotable(),
     }).returns(M.undefined()),
   }),
 });
 
+/**
+ * @typedef {{
+ *  fullAmount: NatAmount;
+ *  advanceAmount: NatAmount;
+ *  destination: ChainAddress;
+ *  forwardingAddress: NobleAddress;
+ *  txHash: EvmHash;
+ * }} AdvancerVowCtx
+ */
+
+export const stateShape = harden({
+  notifier: M.remotable(),
+  borrower: M.remotable(),
+  poolAccount: M.remotable(),
+  intermediateRecipient: M.opt(ChainAddressShape),
+  settlementAddress: M.opt(ChainAddressShape),
+});
+
 /**
  * @param {Zone} zone
  * @param {AdvancerKitPowers} caps
@@ -76,13 +108,13 @@ export const prepareAdvancerKit = (
   {
     chainHub,
     feeConfig,
-    localTransfer,
     log = makeTracer('Advancer', true),
     statusManager,
     usdc,
     vowTools: { watch, when },
     zcf,
-  } = /** @type {AdvancerKitPowers} */ ({}),
+    zoeTools: { localTransfer, withdrawToSeat },
+  },
 ) => {
   assertAllDefined({
     chainHub,
@@ -100,11 +132,19 @@ export const prepareAdvancerKit = (
     AdvancerKitI,
     /**
      * @param {{
-     *   borrowerFacet: LiquidityPoolKit['borrower'];
+     *   notifier: import('./settler.js').SettlerKit['notifier'];
+     *   borrower: LiquidityPoolKit['borrower'];
      *   poolAccount: HostInterface<OrchestrationAccount<{chainId: 'agoric'}>>;
+     *   settlementAddress: ChainAddress;
+     *   intermediateRecipient?: ChainAddress;
      * }} config
      */
-    config => harden(config),
+    config =>
+      harden({
+        ...config,
+        // make sure the state record has this property, perhaps with an undefined value
+        intermediateRecipient: config.intermediateRecipient,
+      }),
     {
       advancer: {
         /**
@@ -115,130 +155,204 @@ export const prepareAdvancerKit = (
          * `StatusManager` - so we don't need to concern ourselves with
          * preserving the vow chain for callers.
          *
-         * @param {CctpTxEvidence} evidence
+         * @param {EvidenceWithRisk} evidenceWithRisk
          */
-        async handleTransactionEvent(evidence) {
+        async handleTransactionEvent({ evidence, risk }) {
           await null;
           try {
-            const { borrowerFacet, poolAccount } = this.state;
-            const { recipientAddress } = evidence.aux;
-            const { EUD } = addressTools.getQueryParams(
-              recipientAddress,
-              EudParamShape,
-            );
-
-            // this will throw if the bech32 prefix is not found, but is handled by the catch
-            const destination = chainHub.makeChainAddress(EUD);
-            const requestedAmount = toAmount(evidence.tx.amount);
-            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);
+            if (statusManager.hasBeenObserved(evidence)) {
+              log('txHash already seen:', evidence.txHash);
               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());
+            if (risk.risksIdentified?.length) {
+              log('risks identified, skipping advance');
+              statusManager.skipAdvance(evidence, risk.risksIdentified);
               return;
             }
+            const { settlementAddress } = this.state;
+            const { recipientAddress } = evidence.aux;
+            const decoded = decodeAddressHook(recipientAddress);
+            mustMatch(decoded, AddressHookShape);
+            if (decoded.baseAddress !== settlementAddress.value) {
+              throw Fail`⚠️ baseAddress of address hook ${q(decoded.baseAddress)} does not match the expected address ${q(settlementAddress.value)}`;
+            }
+            const { EUD } = /** @type {AddressHook['query']} */ (decoded.query);
+            log(`decoded EUD: ${EUD}`);
+            // throws if the bech32 prefix is not found
+            const destination = chainHub.makeChainAddress(EUD);
+
+            const fullAmount = toAmount(evidence.tx.amount);
+            const { borrower, notifier, poolAccount } = this.state;
+            // do not advance if we've already received a mint/settlement
+            const mintedEarly = notifier.checkMintedEarly(
+              evidence,
+              destination,
+            );
+            if (mintedEarly) return;
+
+            // throws if requested does not exceed fees
+            const advanceAmount = feeTools.calculateAdvance(fullAmount);
 
             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
+            borrower.borrow(tmpSeat, advanceAmount);
+
+            // this cannot throw since `.isSeen()` is called in the same turn
+            statusManager.advance(evidence);
 
             const depositV = localTransfer(
               tmpSeat,
               // @ts-expect-error LocalAccountMethods vs OrchestrationAccount
               poolAccount,
-              amountKWR,
+              harden({ USDC: advanceAmount }),
             );
             void watch(depositV, this.facets.depositHandler, {
-              amount: advanceAmount,
+              advanceAmount,
               destination,
+              forwardingAddress: evidence.tx.forwardingAddress,
+              fullAmount,
               tmpSeat,
+              txHash: evidence.txHash,
             });
-          } catch (e) {
-            log('Advancer error:', q(e).toString());
-            statusManager.observe(evidence);
+          } catch (error) {
+            log('Advancer error:', error);
+            statusManager.skipAdvance(evidence, [error.message]);
           }
         },
+        /** @param {ChainAddress} intermediateRecipient */
+        setIntermediateRecipient(intermediateRecipient) {
+          this.state.intermediateRecipient = intermediateRecipient;
+        },
       },
       depositHandler: {
         /**
          * @param {undefined} result
-         * @param {{ amount: Amount<'nat'>; destination: ChainAddress; tmpSeat: ZCFSeat }} ctx
+         * @param {AdvancerVowCtx & { tmpSeat: ZCFSeat }} ctx
          */
-        onFulfilled(result, { amount, destination }) {
-          const { poolAccount } = this.state;
-          const transferV = E(poolAccount).transfer(destination, {
+        onFulfilled(result, ctx) {
+          const { poolAccount, intermediateRecipient, settlementAddress } =
+            this.state;
+          const { destination, advanceAmount, tmpSeat, ...detail } = ctx;
+          tmpSeat.exit();
+          const amount = harden({
             denom: usdc.denom,
-            value: amount.value,
+            value: advanceAmount.value,
           });
-          return watch(transferV, this.facets.transferHandler, {
+          const transferOrSendV =
+            destination.chainId === settlementAddress.chainId
+              ? E(poolAccount).send(destination, amount)
+              : E(poolAccount).transfer(destination, amount, {
+                  forwardOpts: { intermediateRecipient },
+                });
+          return watch(transferOrSendV, this.facets.transferHandler, {
             destination,
-            amount,
+            advanceAmount,
+            ...detail,
           });
         },
         /**
+         * We do not expect this to be a common failure. it should only occur
+         * if USDC is not registered in vbank or the tmpSeat has less than
+         * `advanceAmount`.
+         *
+         * If we do hit this path, we return funds to the Liquidity Pool and
+         * notify of Advancing failure.
+         *
          * @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?
-          log('🚨 advance deposit failed', q(error).toString());
-          // TODO #10510 (comprehensive error testing) determine
-          // course of action here
+        onRejected(error, { tmpSeat, advanceAmount, ...restCtx }) {
           log(
-            'TODO live payment on seat to return to LP',
-            q(tmpSeat).toString(),
+            '⚠️ deposit to localOrchAccount failed, attempting to return payment to LP',
+            error,
           );
+          try {
+            const { borrower, notifier } = this.state;
+            notifier.notifyAdvancingResult(restCtx, false);
+            borrower.returnToPool(tmpSeat, advanceAmount);
+            tmpSeat.exit();
+          } catch (e) {
+            log('🚨 deposit to localOrchAccount failure recovery failed', e);
+          }
         },
       },
       transferHandler: {
         /**
-         * @param {undefined} result TODO confirm this is not a bigint (sequence)
-         * @param {{ destination: ChainAddress; amount: NatAmount; }} ctx
+         * @param {undefined} result
+         * @param {AdvancerVowCtx} ctx
          */
-        onFulfilled(result, { destination, amount }) {
-          // TODO vstorage update? We don't currently have a status for
-          // Advanced + transferV settled
-          log(
-            'Advance transfer fulfilled',
-            q({ amount, destination, result }).toString(),
+        onFulfilled(result, ctx) {
+          const { notifier } = this.state;
+          const { advanceAmount, destination, ...detail } = ctx;
+          log('Advance succeeded', { advanceAmount, destination });
+          // During development, due to a bug, this call threw.
+          // The failure was silent (no diagnostics) due to:
+          //  - #10576 Vows do not report unhandled rejections
+          // For now, the advancer kit relies on consistency between
+          // notify, statusManager, and callers of handleTransactionEvent().
+          // TODO: revisit #10576 during #10510
+          notifier.notifyAdvancingResult({ destination, ...detail }, true);
+        },
+        /**
+         * @param {Error} error
+         * @param {AdvancerVowCtx} ctx
+         */
+        onRejected(error, ctx) {
+          const { notifier, poolAccount } = this.state;
+          log('Advance failed', error);
+          const { advanceAmount, ...restCtx } = ctx;
+          notifier.notifyAdvancingResult(restCtx, false);
+          const { zcfSeat: tmpReturnSeat } = zcf.makeEmptySeatKit();
+          const withdrawV = withdrawToSeat(
+            // @ts-expect-error LocalAccountMethods vs OrchestrationAccount
+            poolAccount,
+            tmpReturnSeat,
+            harden({ USDC: advanceAmount }),
           );
+          void watch(withdrawV, this.facets.withdrawHandler, {
+            advanceAmount,
+            tmpReturnSeat,
+          });
+        },
+      },
+      withdrawHandler: {
+        /**
+         *
+         * @param {undefined} result
+         * @param {{ advanceAmount: Amount<'nat'>; tmpReturnSeat: ZCFSeat; }} ctx
+         */
+        onFulfilled(result, { advanceAmount, tmpReturnSeat }) {
+          const { borrower } = this.state;
+          try {
+            borrower.returnToPool(tmpReturnSeat, advanceAmount);
+          } catch (e) {
+            // If we reach here, the unused advance funds will remain in `tmpReturnSeat`
+            // and must be retrieved from recovery sets.
+            log(
+              `🚨 return ${q(advanceAmount)} to pool failed. funds remain on "tmpReturnSeat"`,
+              e,
+            );
+          }
+          tmpReturnSeat.exit();
         },
-        onRejected(error) {
-          // TODO #10510 (comprehensive error testing) determine
-          // course of action here. This might fail due to timeout.
-          log('Advance transfer rejected', q(error).toString());
+        /**
+         * @param {Error} error
+         * @param {{ advanceAmount: Amount<'nat'>; tmpReturnSeat: ZCFSeat; }} ctx
+         */
+        onRejected(error, { advanceAmount, tmpReturnSeat }) {
+          log(
+            `🚨 withdraw ${q(advanceAmount)} from "poolAccount" to return to pool failed`,
+            error,
+          );
+          // If we reach here, the unused advance funds will remain in the `poolAccount`.
+          // A contract update will be required to return them to the LiquidityPool.
+          tmpReturnSeat.exit();
         },
       },
     },
     {
-      stateShape: harden({
-        borrowerFacet: M.remotable(),
-        poolAccount: M.remotable(),
-      }),
+      stateShape,
     },
   );
 };