@agoric/fast-usdc 0.1.1-dev-02967de.0

package/src/cli/transfer.js

@@ -0,0 +1,91 @@
+/* global globalThis */
+
+import { makeVStorage } from '@agoric/client-utils';
+import { depositForBurn, makeProvider } from '../util/cctp.js';
+import {
+  makeSigner,
+  queryForwardingAccount,
+  registerFwdAccount,
+} from '../util/noble.js';
+import { queryFastUSDCLocalChainAccount } from '../util/agoric.js';
+
+/** @import { file } from '../util/file' */
+/** @import { VStorage } from '@agoric/client-utils' */
+/** @import { SigningStargateClient } from '@cosmjs/stargate' */
+/** @import { JsonRpcProvider as ethProvider } from 'ethers' */
+
+const transfer = async (
+  /** @type {file} */ configFile,
+  /** @type {string} */ amount,
+  /** @type {string} */ destination,
+  out = console,
+  fetch = globalThis.fetch,
+  /** @type {VStorage | undefined} */ vstorage,
+  /** @type {{signer: SigningStargateClient, address: string} | undefined} */ nobleSigner,
+  /** @type {ethProvider | undefined} */ ethProvider,
+) => {
+  const execute = async (
+    /** @type {import('./config').ConfigOpts} */ config,
+  ) => {
+    vstorage ||= makeVStorage(
+      { fetch },
+      { chainName: 'agoric', rpcAddrs: [config.agoricRpc] },
+    );
+    const agoricAddr = await queryFastUSDCLocalChainAccount(vstorage, out);
+    const appendedAddr = `${agoricAddr}?EUD=${destination}`;
+    out.log(`forwarding destination ${appendedAddr}`);
+
+    const { exists, address } = await queryForwardingAccount(
+      config.nobleApi,
+      config.nobleToAgoricChannel,
+      appendedAddr,
+      out,
+      fetch,
+    );
+
+    if (!exists) {
+      nobleSigner ||= await makeSigner(config.nobleSeed, config.nobleRpc, out);
+      const { address: signerAddress, signer } = nobleSigner;
+      try {
+        const res = await registerFwdAccount(
+          signer,
+          signerAddress,
+          config.nobleToAgoricChannel,
+          appendedAddr,
+          out,
+        );
+        out.log(res);
+      } catch (e) {
+        out.error(
+          `Error registering noble forwarding account for ${appendedAddr} on channel ${config.nobleToAgoricChannel}`,
+        );
+        throw e;
+      }
+    }
+
+    ethProvider ||= makeProvider(config.ethRpc);
+    await depositForBurn(
+      ethProvider,
+      config.ethSeed,
+      config.tokenMessengerAddress,
+      config.tokenAddress,
+      address,
+      amount,
+      out,
+    );
+  };
+
+  let config;
+  await null;
+  try {
+    config = JSON.parse(await configFile.read());
+  } catch {
+    out.error(
+      `No config found at ${configFile.path}. Use "config init" to create one, or "--home" to specify config location.`,
+    );
+    throw new Error();
+  }
+  await execute(config);
+};
+
+export default { transfer };

package/src/constants.js

@@ -0,0 +1,27 @@
+/**
+ * Status values for FastUSDC.
+ *
+ * @enum {(typeof TxStatus)[keyof typeof TxStatus]}
+ */
+export const TxStatus = /** @type {const} */ ({
+  /** tx was observed but not advanced */
+  Observed: 'OBSERVED',
+  /** IBC transfer is initiated */
+  Advanced: 'ADVANCED',
+  /** settlement for matching advance received and funds dispersed */
+  Settled: 'SETTLED',
+});
+harden(TxStatus);
+
+/**
+ * Status values for the StatusManager.
+ *
+ * @enum {(typeof PendingTxStatus)[keyof typeof PendingTxStatus]}
+ */
+export const PendingTxStatus = /** @type {const} */ ({
+  /** tx was observed but not advanced */
+  Observed: 'OBSERVED',
+  /** IBC transfer is initiated */
+  Advanced: 'ADVANCED',
+});
+harden(PendingTxStatus);

package/src/exos/README.md

@@ -0,0 +1,26 @@
+##   **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
+```

package/src/exos/advancer.js

@@ -0,0 +1,240 @@
+import { AmountMath, AmountShape, PaymentShape } from '@agoric/ertp';
+import { assertAllDefined } from '@agoric/internal';
+import { 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 { makeFeeTools } from '../utils/fees.js';
+
+const { isGTE } = AmountMath;
+
+/**
+ * @import {HostInterface} from '@agoric/async-flow';
+ * @import {NatAmount} from '@agoric/ertp';
+ * @import {ChainAddress, ChainHub, Denom, DenomAmount, OrchestrationAccount} from '@agoric/orchestration';
+ * @import {VowTools} from '@agoric/vow';
+ * @import {Zone} from '@agoric/zone';
+ * @import {CctpTxEvidence, FeeConfig, LogFn} from '../types.js';
+ * @import {StatusManager} from './status-manager.js';
+ */
+
+/**
+ * Expected interface from LiquidityPool
+ *
+ * @typedef {{
+ *   lookupBalance(): NatAmount;
+ *   borrow(amount: Amount<"nat">): Promise<Payment<"nat">>;
+ *   repay(payments: PaymentKeywordRecord): Promise<void>
+ * }} AssetManagerFacet
+ */
+
+/**
+ * @typedef {{
+ *  chainHub: ChainHub;
+ *  feeConfig: FeeConfig;
+ *  log: LogFn;
+ *  statusManager: StatusManager;
+ *  usdc: { brand: Brand<'nat'>; denom: Denom; };
+ *  vowTools: VowTools;
+ * }} AdvancerKitPowers
+ */
+
+/** type guards internal to the AdvancerKit */
+const AdvancerKitI = harden({
+  advancer: M.interface('AdvancerI', {
+    handleTransactionEvent: M.callWhen(CctpTxEvidenceShape).returns(),
+  }),
+  depositHandler: M.interface('DepositHandlerI', {
+    onFulfilled: M.call(AmountShape, {
+      destination: ChainAddressShape,
+      payment: PaymentShape,
+    }).returns(VowShape),
+    onRejected: M.call(M.error(), {
+      destination: ChainAddressShape,
+      payment: PaymentShape,
+    }).returns(),
+  }),
+  transferHandler: M.interface('TransferHandlerI', {
+    // TODO confirm undefined, and not bigint (sequence)
+    onFulfilled: M.call(M.undefined(), {
+      amount: AmountShape,
+      destination: ChainAddressShape,
+    }).returns(M.undefined()),
+    onRejected: M.call(M.error(), {
+      amount: AmountShape,
+      destination: ChainAddressShape,
+    }).returns(M.undefined()),
+  }),
+});
+
+/**
+ * @param {Zone} zone
+ * @param {AdvancerKitPowers} caps
+ */
+export const prepareAdvancerKit = (
+  zone,
+  { chainHub, feeConfig, log, statusManager, usdc, vowTools: { watch, when } },
+) => {
+  assertAllDefined({
+    chainHub,
+    feeConfig,
+    statusManager,
+    watch,
+    when,
+  });
+  const feeTools = makeFeeTools(feeConfig);
+  /** @param {bigint} value */
+  const toAmount = value => AmountMath.make(usdc.brand, value);
+
+  return zone.exoClassKit(
+    'Fast USDC Advancer',
+    AdvancerKitI,
+    /**
+     * @param {{
+     *   assetManagerFacet: AssetManagerFacet;
+     *   poolAccount: ERef<HostInterface<OrchestrationAccount<{chainId: 'agoric'}>>>;
+     * }} config
+     */
+    config => harden(config),
+    {
+      advancer: {
+        /**
+         * Must perform a status update for every observed transaction.
+         *
+         * We do not expect any callers to depend on the settlement of
+         * `handleTransactionEvent` - errors caught are communicated to the
+         * `StatusManager` - so we don't need to concern ourselves with
+         * preserving the vow chain for callers.
+         *
+         * @param {CctpTxEvidence} evidence
+         */
+        async handleTransactionEvent(evidence) {
+          await null;
+          try {
+            // TODO poolAccount might be a vow we need to unwrap
+            const { assetManagerFacet, 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 = assetManagerFacet.lookupBalance();
+            if (!isGTE(poolBalance, requestedAmount)) {
+              log(
+                `Insufficient pool funds`,
+                `Requested ${q(advanceAmount)} but only have ${q(poolBalance)}`,
+              );
+              // report `requestedAmount`, not `advancedAmount`... do we need to
+              // communicate net to `StatusManger` in case fees change in between?
+              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;
+            }
+
+            try {
+              const payment = await assetManagerFacet.borrow(advanceAmount);
+              const depositV = E(poolAccount).deposit(payment);
+              void watch(depositV, this.facets.depositHandler, {
+                destination,
+                payment,
+              });
+            } catch (e) {
+              // `.borrow()` might fail if the balance changes since we
+              // requested it. TODO - how to handle this? change ADVANCED -> OBSERVED?
+              // Note: `depositHandler` handles the `.deposit()` failure
+              log('🚨 advance borrow failed', q(e).toString());
+            }
+          } catch (e) {
+            log('Advancer error:', q(e).toString());
+            statusManager.observe(evidence);
+          }
+        },
+      },
+      depositHandler: {
+        /**
+         * @param {NatAmount} amount amount returned from deposit
+         * @param {{ destination: ChainAddress; payment: Payment<'nat'> }} ctx
+         */
+        onFulfilled(amount, { destination }) {
+          const { poolAccount } = this.state;
+          const transferV = E(poolAccount).transfer(
+            destination,
+            /** @type {DenomAmount} */ ({
+              denom: usdc.denom,
+              value: amount.value,
+            }),
+          );
+          return watch(transferV, this.facets.transferHandler, {
+            destination,
+            amount,
+          });
+        },
+        /**
+         * @param {Error} error
+         * @param {{ destination: ChainAddress; payment: Payment<'nat'> }} ctx
+         */
+        onRejected(error, { payment }) {
+          // TODO return live payment from ctx to LP
+          log('🚨 advance deposit failed', q(error).toString());
+          log('TODO live payment to return to LP', q(payment).toString());
+        },
+      },
+      transferHandler: {
+        /**
+         * @param {undefined} result TODO confirm this is not a bigint (sequence)
+         * @param {{ destination: ChainAddress; amount: NatAmount; }} ctx
+         */
+        onFulfilled(result, { destination, amount }) {
+          // TODO vstorage update?
+          log(
+            'Advance transfer fulfilled',
+            q({ amount, destination, result }).toString(),
+          );
+        },
+        onRejected(error) {
+          // XXX retry logic?
+          // What do we do if we fail, should we keep a Status?
+          log('Advance transfer rejected', q(error).toString());
+        },
+      },
+    },
+    {
+      stateShape: harden({
+        assetManagerFacet: M.remotable(),
+        poolAccount: M.or(VowShape, M.remotable()),
+      }),
+    },
+  );
+};
+harden(prepareAdvancerKit);
+
+/**
+ * @param {Zone} zone
+ * @param {AdvancerKitPowers} caps
+ */
+export const prepareAdvancer = (zone, caps) => {
+  const makeAdvancerKit = prepareAdvancerKit(zone, caps);
+  return pickFacet(makeAdvancerKit, 'advancer');
+};
+harden(prepareAdvancer);