@agoric/fast-usdc 0.1.1-dev-9835fb0.0 → 0.1.1-dev-bfca51a.0

package/package.json

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

package/src/cli/operator-commands.js

@@ -99,6 +99,7 @@ export const addOperatorCommands = (
     .requiredOption('--chainId <string>', 'chain id', Number)
     .requiredOption('--amount <number>', 'number', parseNat)
     .requiredOption('--forwardingAddress <string>', 'bech32 address', String)
+    .requiredOption('--sender <string>', 'Ethereum address initiating', String)
     .requiredOption('--txHash <0xhexo>', 'hex hash', parseHex)
     .option('--offerId <string>', 'Offer id', String, `operatorAttest-${now()}`)
     .action(async opts => {
@@ -109,12 +110,13 @@ export const addOperatorCommands = (
         recipientAddress,
         amount,
         forwardingAddress,
+        sender,
         ...flat
       } = opts;
 
       const evidence = harden({
         aux: { forwardingChannel, recipientAddress },
-        tx: { amount, forwardingAddress },
+        tx: { amount, forwardingAddress, sender },
         ...flat,
       });
       mustMatch(evidence, CctpTxEvidenceShape);

package/src/constants.js

@@ -21,7 +21,12 @@ export const TxStatus = /** @type {const} */ ({
 });
 harden(TxStatus);
 
-// TODO: define valid state transitions
+// According to the state diagram
+export const TerminalTxStatus = {
+  [TxStatus.Forwarded]: true,
+  [TxStatus.ForwardFailed]: true,
+  [TxStatus.Disbursed]: true,
+};
 
 /**
  * Status values for the StatusManager.

package/src/exos/settler.js

@@ -143,7 +143,7 @@ export const prepareSettler = (
           );
 
           // given the sourceChannel check, we can be certain of this cast
-          const sender = /** @type {NobleAddress} */ (tx.sender);
+          const nfa = /** @type {NobleAddress} */ (tx.sender);
 
           if (tx.denom !== remoteDenom) {
             const { denom: actual } = tx;
@@ -170,23 +170,23 @@ export const prepareSettler = (
           const amount = BigInt(tx.amount); // TODO: what if this throws?
 
           const { self } = this.facets;
-          const found = statusManager.dequeueStatus(sender, amount);
-          log('dequeued', found, 'for', sender, amount);
+          const found = statusManager.dequeueStatus(nfa, amount);
+          log('dequeued', found, 'for', nfa, amount);
           switch (found?.status) {
             case PendingTxStatus.Advanced:
-              return self.disburse(found.txHash, sender, amount);
+              return self.disburse(found.txHash, nfa, amount);
 
             case PendingTxStatus.Advancing:
-              this.state.mintedEarly.add(makeMintedEarlyKey(sender, amount));
+              this.state.mintedEarly.add(makeMintedEarlyKey(nfa, amount));
               return;
 
             case PendingTxStatus.Observed:
             case PendingTxStatus.AdvanceFailed:
-              return self.forward(found.txHash, sender, amount, EUD);
+              return self.forward(found.txHash, nfa, amount, EUD);
 
             case undefined:
             default:
-              log('⚠️ tap: no status for ', sender, amount);
+              log('⚠️ tap: no status for ', nfa, amount);
           }
         },
       },
@@ -231,10 +231,10 @@ export const prepareSettler = (
       self: {
         /**
          * @param {EvmHash} txHash
-         * @param {NobleAddress} sender
+         * @param {NobleAddress} nfa
          * @param {NatValue} fullValue
          */
-        async disburse(txHash, sender, fullValue) {
+        async disburse(txHash, nfa, fullValue) {
           const { repayer, settlementAccount } = this.state;
           const received = AmountMath.make(USDC, fullValue);
           const { zcfSeat: settlingSeat } = zcf.makeEmptySeatKit();
@@ -264,11 +264,11 @@ export const prepareSettler = (
         },
         /**
          * @param {EvmHash} txHash
-         * @param {NobleAddress} sender
+         * @param {NobleAddress} nfa
          * @param {NatValue} fullValue
          * @param {string} EUD
          */
-        forward(txHash, sender, fullValue, EUD) {
+        forward(txHash, nfa, fullValue, EUD) {
           const { settlementAccount, intermediateRecipient } = this.state;
 
           const dest = chainHub.makeChainAddress(EUD);
@@ -281,7 +281,7 @@ export const prepareSettler = (
           );
           void vowTools.watch(txfrV, this.facets.transferHandler, {
             txHash,
-            sender,
+            nfa,
             fullValue,
           });
         },
@@ -293,13 +293,13 @@ export const prepareSettler = (
          *
          * @typedef {{
          *   txHash: EvmHash;
-         *   sender: NobleAddress;
+         *   nfa: NobleAddress;
          *   fullValue: NatValue;
          * }} SettlerTransferCtx
          */
         onFulfilled(_result, ctx) {
-          const { txHash, sender, fullValue } = ctx;
-          statusManager.forwarded(txHash, sender, fullValue);
+          const { txHash, nfa, fullValue } = ctx;
+          statusManager.forwarded(txHash, nfa, fullValue);
         },
         /**
          * @param {unknown} reason
@@ -307,8 +307,8 @@ export const prepareSettler = (
          */
         onRejected(reason, ctx) {
           log('⚠️ transfer rejected!', reason, ctx);
-          // const { txHash, sender, amount } = ctx;
-          // TODO(#10510): statusManager.forwardFailed(txHash, sender, amount);
+          // const { txHash, nfa, amount } = ctx;
+          // TODO(#10510): statusManager.forwardFailed(txHash, nfa, amount);
         },
       },
     },

package/src/exos/status-manager.js

@@ -2,26 +2,23 @@ import { M } from '@endo/patterns';
 import { Fail, makeError, q } from '@endo/errors';
 import { appendToStoredArray } from '@agoric/store/src/stores/store-utils.js';
 import { E } from '@endo/eventual-send';
-import { makeTracer } from '@agoric/internal';
+import { makeTracer, pureDataMarshaller } from '@agoric/internal';
 import {
   CctpTxEvidenceShape,
   EvmHashShape,
   PendingTxShape,
 } from '../type-guards.js';
-import { PendingTxStatus, TxStatus } from '../constants.js';
+import { PendingTxStatus, TerminalTxStatus, TxStatus } from '../constants.js';
 
 /**
  * @import {MapStore, SetStore} from '@agoric/store';
  * @import {Zone} from '@agoric/zone';
- * @import {CctpTxEvidence, NobleAddress, PendingTx, EvmHash, LogFn} from '../types.js';
+ * @import {CctpTxEvidence, NobleAddress, PendingTx, EvmHash, LogFn, TransactionRecord} from '../types.js';
  */
 
 /**
  * @typedef {`pendingTx:${bigint}:${NobleAddress}`} PendingTxKey
  * The string template is for developer visibility but not meant to ever be parsed.
- *
- * @typedef {`seenTx:${string}:${EvmHash}`} SeenTxKey
- * The string template is for developer visibility but not meant to ever be parsed.
  */
 
 /**
@@ -29,13 +26,13 @@ import { PendingTxStatus, TxStatus } from '../constants.js';
  *
  * The key is a composite but not meant to be parsable.
  *
- * @param {NobleAddress} addr
+ * @param {NobleAddress} nfa Noble Forwarding Account (implies EUD)
  * @param {bigint} amount
  * @returns {PendingTxKey}
  */
-const makePendingTxKey = (addr, amount) =>
+const makePendingTxKey = (nfa, amount) =>
   // amount can't contain colon
-  `pendingTx:${amount}:${addr}`;
+  `pendingTx:${amount}:${nfa}`;
 
 /**
  * Get the key for the pendingTxs MapStore.
@@ -48,20 +45,6 @@ const pendingTxKeyOf = evidence => {
   return makePendingTxKey(forwardingAddress, amount);
 };
 
-/**
- * Get the key for the seenTxs SetStore.
- *
- * The key is a composite but not meant to be parsable.
- *
- * @param {CctpTxEvidence} evidence
- * @returns {SeenTxKey}
- */
-const seenTxKeyOf = evidence => {
-  const { txHash, chainId } = evidence;
-  // chainId can't contain colon
-  return `seenTx:${chainId}:${txHash}`;
-};
-
 /**
  * @typedef {{
  *  log?: LogFn;
@@ -76,35 +59,85 @@ const seenTxKeyOf = evidence => {
  * XXX consider separate facets for `Advancing` and `Settling` capabilities.
  *
  * @param {Zone} zone
- * @param {ERef<StorageNode>} transactionsNode
+ * @param {ERef<StorageNode>} txnsNode
  * @param {StatusManagerPowers} caps
  */
 export const prepareStatusManager = (
   zone,
-  transactionsNode,
+  txnsNode,
   {
     log = makeTracer('Advancer', true),
   } = /** @type {StatusManagerPowers} */ ({}),
 ) => {
-  /** @type {MapStore<PendingTxKey, PendingTx[]>} */
+  /**
+   * Keyed by a tuple of the Noble Forwarding Account and amount.
+   * @type {MapStore<PendingTxKey, PendingTx[]>}
+   */
   const pendingTxs = zone.mapStore('PendingTxs', {
     keyShape: M.string(),
     valueShape: M.arrayOf(PendingTxShape),
   });
 
-  /** @type {SetStore<SeenTxKey>} */
+  /**
+   * Transactions seen *ever* by the contract.
+   *
+   * Note that like all durable stores, this SetStore is stored in IAVL. It
+   * grows without bound (though the amount of growth per incoming message to
+   * the contract is bounded). At some point in the future we may want to prune.
+   * @type {SetStore<EvmHash>}
+   */
   const seenTxs = zone.setStore('SeenTxs', {
     keyShape: M.string(),
   });
 
+  /**
+   * Transactions that have completed, but are still in vstorage.
+   *
+   * @type {SetStore<EvmHash>}
+   */
+  const storedCompletedTxs = zone.setStore('StoredCompletedTxs', {
+    keyShape: M.string(),
+  });
+
+  /**
+   * @param {EvmHash} txId
+   * @param {TransactionRecord} record
+   */
+  const publishTxnRecord = (txId, record) => {
+    const txNode = E(txnsNode).makeChildNode(txId, {
+      sequence: true, // avoid overwriting other output in the block
+    });
+    void E(txNode).setValue(
+      JSON.stringify(pureDataMarshaller.toCapData(record)),
+    );
+  };
+
+  /**
+   * @param {CctpTxEvidence['txHash']} hash
+   * @param {CctpTxEvidence} evidence
+   */
+  const publishEvidence = (hash, evidence) => {
+    // Don't await, just writing to vstorage.
+    void publishTxnRecord(
+      hash,
+      harden({ evidence, status: TxStatus.Observed }),
+    );
+  };
+
   /**
    * @param {CctpTxEvidence['txHash']} hash
    * @param {TxStatus} status
    */
   const publishStatus = (hash, status) => {
-    const txnNodeP = E(transactionsNode).makeChildNode(hash);
     // Don't await, just writing to vstorage.
-    void E(txnNodeP).setValue(status);
+    void publishTxnRecord(hash, harden({ status }));
+    if (TerminalTxStatus[status]) {
+      // UNTIL https://github.com/Agoric/agoric-sdk/issues/7405
+      // Queue it for deletion later because if we deleted it now the earlier
+      // writes in this block would be wiped. For now we keep track of what to
+      // delete when we know it'll be another block.
+      storedCompletedTxs.add(hash);
+    }
   };
 
   /**
@@ -117,32 +150,36 @@ export const prepareStatusManager = (
    * @param {PendingTxStatus} status
    */
   const initPendingTx = (evidence, status) => {
-    const seenKey = seenTxKeyOf(evidence);
-    if (seenTxs.has(seenKey)) {
-      throw makeError(`Transaction already seen: ${q(seenKey)}`);
+    const { txHash } = evidence;
+    if (seenTxs.has(txHash)) {
+      throw makeError(`Transaction already seen: ${q(txHash)}`);
     }
-    seenTxs.add(seenKey);
+    seenTxs.add(txHash);
 
     appendToStoredArray(
       pendingTxs,
       pendingTxKeyOf(evidence),
       harden({ ...evidence, status }),
     );
-    publishStatus(evidence.txHash, status);
+    publishEvidence(txHash, evidence);
+    if (status !== PendingTxStatus.Observed) {
+      // publishEvidence publishes Observed
+      publishStatus(txHash, status);
+    }
   };
 
   /**
    * Update the pending transaction status.
    *
-   * @param {{sender: NobleAddress, amount: bigint}} keyParts
+   * @param {{nfa: NobleAddress, amount: bigint}} keyParts
    * @param {PendingTxStatus} status
    */
-  function setPendingTxStatus({ sender, amount }, status) {
-    const key = makePendingTxKey(sender, amount);
-    pendingTxs.has(key) || Fail`no advancing tx with ${{ sender, amount }}`;
+  function setPendingTxStatus({ nfa, amount }, status) {
+    const key = makePendingTxKey(nfa, amount);
+    pendingTxs.has(key) || Fail`no advancing tx with ${{ nfa, amount }}`;
     const pending = pendingTxs.get(key);
     const ix = pending.findIndex(tx => tx.status === PendingTxStatus.Advancing);
-    ix >= 0 || Fail`no advancing tx with ${{ sender, amount }}`;
+    ix >= 0 || Fail`no advancing tx with ${{ nfa, amount }}`;
     const [prefix, tx, suffix] = [
       pending.slice(0, ix),
       pending[ix],
@@ -161,6 +198,7 @@ export const prepareStatusManager = (
       advanceOutcome: M.call(M.string(), M.nat(), M.boolean()).returns(),
       observe: M.call(CctpTxEvidenceShape).returns(M.undefined()),
       hasBeenObserved: M.call(CctpTxEvidenceShape).returns(M.boolean()),
+      deleteCompletedTxs: M.call().returns(M.undefined()),
       dequeueStatus: M.call(M.string(), M.bigint()).returns(
         M.or(
           {
@@ -197,14 +235,14 @@ export const prepareStatusManager = (
       /**
        * Record result of ADVANCING
        *
-       * @param {NobleAddress} sender
+       * @param {NobleAddress} nfa Noble Forwarding Account
        * @param {import('@agoric/ertp').NatValue} amount
        * @param {boolean} success - Advanced vs. AdvanceFailed
        * @throws {Error} if nothing to advance
        */
-      advanceOutcome(sender, amount, success) {
+      advanceOutcome(nfa, amount, success) {
         setPendingTxStatus(
-          { sender, amount },
+          { nfa, amount },
           success ? PendingTxStatus.Advanced : PendingTxStatus.AdvanceFailed,
         );
       },
@@ -223,20 +261,32 @@ export const prepareStatusManager = (
        * @param {CctpTxEvidence} evidence
        */
       hasBeenObserved(evidence) {
-        const seenKey = seenTxKeyOf(evidence);
-        return seenTxs.has(seenKey);
+        return seenTxs.has(evidence.txHash);
+      },
+
+      // UNTIL https://github.com/Agoric/agoric-sdk/issues/7405
+      deleteCompletedTxs() {
+        for (const txHash of storedCompletedTxs.values()) {
+          // As of now, setValue('') on a non-sequence node will delete it
+          const txNode = E(txnsNode).makeChildNode(txHash, {
+            sequence: false,
+          });
+          void E(txNode)
+            .setValue('')
+            .then(() => storedCompletedTxs.delete(txHash));
+        }
       },
 
       /**
        * Remove and return an `ADVANCED` or `OBSERVED` tx waiting to be `SETTLED`.
        *
-       * @param {NobleAddress} address
+       * @param {NobleAddress} nfa
        * @param {bigint} amount
        * @returns {Pick<PendingTx, 'status' | 'txHash'> | undefined} undefined if nothing
        *   with this address and amount has been marked pending.
        */
-      dequeueStatus(address, amount) {
-        const key = makePendingTxKey(address, amount);
+      dequeueStatus(nfa, amount) {
+        const key = makePendingTxKey(nfa, amount);
         if (!pendingTxs.has(key)) return undefined;
         const pending = pendingTxs.get(key);
 
@@ -272,16 +322,16 @@ export const prepareStatusManager = (
        * Mark a transaction as `FORWARDED`
        *
        * @param {EvmHash | undefined} txHash - undefined in case mint before observed
-       * @param {NobleAddress} address
+       * @param {NobleAddress} nfa
        * @param {bigint} amount
        */
-      forwarded(txHash, address, amount) {
+      forwarded(txHash, nfa, amount) {
         if (txHash) {
           publishStatus(txHash, TxStatus.Forwarded);
         } else {
           // TODO store (early) `Minted` transactions to check against incoming evidence
           log(
-            `⚠️ Forwarded minted amount ${amount} from account ${address} before it was observed.`,
+            `⚠️ Forwarded minted amount ${amount} from account ${nfa} before it was observed.`,
           );
         }
       },
@@ -291,12 +341,12 @@ export const prepareStatusManager = (
        *
        * XXX only used in tests. should we remove?
        *
-       * @param {NobleAddress} address
+       * @param {NobleAddress} nfa
        * @param {bigint} amount
        * @returns {PendingTx[]}
        */
-      lookupPending(address, amount) {
-        const key = makePendingTxKey(address, amount);
+      lookupPending(nfa, amount) {
+        const key = makePendingTxKey(nfa, amount);
         if (!pendingTxs.has(key)) {
           return harden([]);
         }

package/src/fast-usdc.contract.js

@@ -26,7 +26,7 @@ import { defineInertInvitation } from './utils/zoe.js';
 
 const trace = makeTracer('FastUsdc');
 
-const STATUS_NODE = 'status';
+const TXNS_NODE = 'txns';
 const FEE_NODE = 'feeConfig';
 const ADDRESSES_BAGGAGE_KEY = 'addresses';
 
@@ -39,7 +39,6 @@ const ADDRESSES_BAGGAGE_KEY = 'addresses';
  * @import {Zone} from '@agoric/zone';
  * @import {OperatorKit} from './exos/operator-kit.js';
  * @import {CctpTxEvidence, FeeConfig} from './types.js';
- * @import {RepayAmountKWR, RepayPaymentKWR} from './exos/liquidity-pool.js';
  */
 
 /**
@@ -110,8 +109,10 @@ export const contract = async (zcf, privateArgs, zone, tools) => {
     marshaller,
   );
 
-  const statusNode = E(storageNode).makeChildNode(STATUS_NODE);
-  const statusManager = prepareStatusManager(zone, statusNode);
+  const statusManager = prepareStatusManager(
+    zone,
+    E(storageNode).makeChildNode(TXNS_NODE),
+  );
 
   const { USDC } = terms.brands;
   const { withdrawToSeat } = tools.zoeTools;

package/src/type-guards.js

@@ -6,7 +6,7 @@ import { PendingTxStatus } from './constants.js';
  * @import {TypedPattern} from '@agoric/internal';
  * @import {FastUsdcTerms} from './fast-usdc.contract.js';
  * @import {USDCProposalShapes} from './pool-share-math.js';
- * @import {CctpTxEvidence, FeeConfig, PendingTx, PoolMetrics, ChainPolicy, FeedPolicy, AddressHook} from './types.js';
+ * @import {CctpTxEvidence, FeeConfig, PendingTx, PoolMetrics, ChainPolicy, FeedPolicy, AddressHook, EvmAddress, EvmHash} from './types.js';
  */
 
 /**
@@ -36,7 +36,14 @@ export const FastUSDCTermsShape = harden({
   usdcDenom: M.string(),
 });
 
-/** @type {TypedPattern<string>} */
+/** @type {TypedPattern<EvmAddress>} */
+export const EvmAddressShape = M.string({
+  // 0x + 40 hex digits
+  stringLengthLimit: 42,
+});
+harden(EvmAddressShape);
+
+/** @type {TypedPattern<EvmHash>} */
 export const EvmHashShape = M.string({
   stringLengthLimit: 66,
 });
@@ -54,6 +61,7 @@ export const CctpTxEvidenceShape = {
   tx: {
     amount: M.nat(),
     forwardingAddress: M.string(),
+    sender: EvmAddressShape,
   },
   txHash: EvmHashShape,
 };

package/src/types.ts

@@ -7,10 +7,11 @@ import type {
 import type { IBCChannelID } from '@agoric/vats';
 import type { Amount } from '@agoric/ertp';
 import type { CopyRecord, Passable } from '@endo/pass-style';
-import type { PendingTxStatus } from './constants.js';
+import type { PendingTxStatus, TxStatus } from './constants.js';
 import type { FastUsdcTerms } from './fast-usdc.contract.js';
 
 export type EvmHash = `0x${string}`;
+export type EvmAddress = `0x${string & { length: 40 }}`;
 export type NobleAddress = `noble1${string}`;
 export type EvmChainID = number;
 export type EvmChainName = string;
@@ -28,10 +29,20 @@ export interface CctpTxEvidence {
   tx: {
     amount: bigint;
     forwardingAddress: NobleAddress;
+    sender: EvmAddress;
   };
   txHash: EvmHash;
 }
 
+/**
+ * 'evidence' only available when it's first observed and not in subsequent
+ * updates.
+ */
+export interface TransactionRecord extends CopyRecord {
+  evidence?: CctpTxEvidence;
+  status: TxStatus;
+}
+
 export type LogFn = (...args: unknown[]) => void;
 
 export interface PendingTx extends CctpTxEvidence {