feat: settle against batched mints #11369

0xpatrickdev · 2025-05-09T21:08:23Z

closes: https://github.com/Agoric/agoric-private/issues/312

Description

These changes allow FUSDC to settle multiple advances against a single CCTP mint. To facilitate this change:

pendingSettleTxs is no longer keyed by NFA + amount, just NFA, to facilitate the new matching algorithm. The value type and guard remain the same, PendingTx[] and M.arrayOf(PendingTxShape), but is now sorted descending by tx.amount
dequeueStatus was renamed to matchAndDequeueSettlement, and now returns an array of PendingTxs instead of a single PendingTx or undefined. If no matches are found, an empty array is returned
matchAndDequeueSettlement attempts to find an exact match (hot path) and will fall back to a greedy depth-first search that matches the largest settlements first.

Security Considerations

The greedy‐match algorithm used in matchAndDequeueSettlement limits recursion via MAX_MATCH_DEPTH to avoid denial-of-service risks from extremely large pending sets.

Scaling Considerations

appendToSortedStoredArray uses a linear scan for insertion; this is efficient for the expected small lists (dozens of elements at most).

The settlement‐matching algorithm employs memoization and a depth cap (MAX_MATCH_DEPTH = 25) to prevent exponential blowup. Typical match depth is 2–3.

Documentation Considerations

None

Testing Considerations

Includes and fixes a test.failing case where one mint should settle multiple advances.

Includes unit tests for appendToSortedStoredArray and matchAndDequeueSettlement with a wide range of scenarios.

Upgrade Considerations

Includes migratePendingSettleStore which will handle the MapStore migration the next time the contract starts.

cloudflare-workers-and-pages · 2025-05-09T21:09:53Z

Deploying agoric-sdk with Cloudflare Pages

Latest commit:	`c9a4ecd`
Status:	✅ Deploy successful!
Preview URL:	https://c12d3892.agoric-sdk.pages.dev
Branch Preview URL:	https://312-batched-settle.agoric-sdk.pages.dev

View logs

- like `appendToStoredArray`, but keep it sorted

Implement a new module that provides efficient transaction matching for USDC settlements. The system maintains a sorted queue of pending transactions and uses a two-phase matching strategy: 1. Exact-amount lookup for direct matches 2. Greedy combination algorithm for multi-transaction settlements (largest to smallest)

- migrate store to shape expected by `matchAndDequeueSettlement` in `packages/fast-usdc-contract/src/utils/settlement-matching.ts`

- replaces `dequeueStatus` in favor of `matchAndDequeueSettlement` which is able to match multiple pending settlement transactions with a single mint

turadg · 2025-05-12T17:30:03Z

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

+
+/**
+ * Append `item` to the array held at `key`, keeping it **sorted** according
+ * to `compare`.  Uses a simple linear scan – clearer than a binary search and


agreed, thanks for capturing

turadg · 2025-05-12T17:33:52Z

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

+  mapStore: MapStore<K, V[]>,
+  key: K,
+  item: V,
+  compare: (a: V, b: V) => number = defaultCompareDesc as any,


I think the any is hiding that V requires this same constraint, bigint | number | string, as defaultCompareDesc has or the default isn't valid.

I see the one use of this is to compare transactions, which takes a comparator. So please remove this default one to make it sound.

turadg · 2025-05-12T17:40:04Z

packages/fast-usdc-contract/src/utils/settlement-matching.ts

+const comparePendingTxDesc = (a: PendingTx, b: PendingTx): number => {
+  if (a.tx.amount < b.tx.amount) return 1;
+  if (a.tx.amount > b.tx.amount) return -1;
+  return 0;
+};


consider this idiom for scalars,

Suggested change

const comparePendingTxDesc = (a: PendingTx, b: PendingTx): number => {

if (a.tx.amount < b.tx.amount) return 1;

if (a.tx.amount > b.tx.amount) return -1;

return 0;

};

const comparePendingTxDesc = (a: PendingTx, b: PendingTx): number => Number(b.tx.amount - a.tx.amount));

turadg · 2025-05-12T17:40:36Z

packages/fast-usdc-contract/src/utils/settlement-matching.ts

+
+  const dfs = (index: number, sum: bigint): boolean => {
+    if (sum === target) return true;
+    if (sum > target) return false; // unreachable with current continue‑on‑overshoot logic


why include?

I was on the fence, but leaned towards defensiveness (against infinite recursion) and clear documentation. Happy to remove, but the cost seems low.

turadg · 2025-05-12T17:41:03Z

packages/fast-usdc-contract/src/utils/settlement-matching.ts

+  const dfs = (index: number, sum: bigint): boolean => {
+    if (sum === target) return true;
+    if (sum > target) return false; // unreachable with current continue‑on‑overshoot logic
+    if (path.length >= MAX_MATCH_DEPTH) return false;


very unexpected to reach this depth. throw instead?

Agree, much better idea.

turadg · 2025-05-12T17:46:00Z

packages/fast-usdc-contract/test/mocks.ts

@@ -127,7 +127,7 @@ export const makeTestLogger = (logger: LogFn) => {
    logger(args);
  };
  const inspectLogs = (index?: number) =>


consider typing the return type, which is conditioned on index being provided.

turadg · 2025-05-12T17:47:34Z

packages/fast-usdc-contract/src/exos/status-manager.ts

+   * Uses `zone.makeOnce` as a cheap abstraction for "only do this once".
+   */
+  zone.makeOnce('migratePendingSettleStore', () => {
+    const current = [...pendingSettleTxs.values()]; // XXX copy necessary?


Oh I see, the iterator might have nothing after .clear() is called. I think that's correct. Please do verify and then document decisively

turadg · 2025-05-12T17:48:16Z

packages/fast-usdc-contract/src/exos/status-manager.ts

   */
-  const pendingSettleTxs: MapStore<PendingTxKey, PendingTx[]> = zone.mapStore(
+  const pendingSettleTxs: MapStore<NobleAddress, PendingTx[]> = zone.mapStore(


I see that until migratePendingSettleStore the key is still PendingTxKey but statically the code should assume NobleAddress.

turadg · 2025-05-12T17:49:26Z

packages/fast-usdc-contract/src/exos/status-manager.ts

+        if (!pendingSettleTxs.has(nfa)) return undefined;
+        const allPending = pendingSettleTxs.get(nfa);
+        const idx = allPending.findIndex(tx => tx.tx.amount === amount);
+        if (idx < 0) {
          return undefined;
        }
        // extract first item


this is extracting the leading range now, yes?

Yes, the changes to dequeueStatus had a short shelf life in this PR. "extract first item" is stale

turadg · 2025-05-12T17:50:58Z

packages/fast-usdc-contract/test/batching.test.ts

@@ -40,7 +40,7 @@ test.before(async t => {
  sync.lp.resolve({ lp500 });
 });

-test.serial.failing('multiple advance amounts settled by one mint', async t => {


love to see it

turadg mentioned this pull request May 10, 2025

remediate errant batch settlements #11370

Open

turadg and others added 4 commits May 11, 2025 13:49

test: batched disbursement

5316c5c

feat: appendToSortedStoredArray

75ec8e0

- like `appendToStoredArray`, but keep it sorted

fix(test): inspectLogs returns pure data, not a reference

c678918

0xpatrickdev force-pushed the 312-batched-settle branch from 716ef26 to 10a27ec Compare May 11, 2025 17:50

0xpatrickdev added 4 commits May 12, 2025 10:21

feat: pendingSettleTxs schema supports batch matching

572f6cf

- migrate store to shape expected by `matchAndDequeueSettlement` in `packages/fast-usdc-contract/src/utils/settlement-matching.ts`

feat: match a mint to multiple txs

6c0badd

- replaces `dequeueStatus` in favor of `matchAndDequeueSettlement` which is able to match multiple pending settlement transactions with a single mint

fix(test): bobFulfills condition

1cc4bca

chore: document pre-forwardFunds future dead code removal

1ce6478

0xpatrickdev force-pushed the 312-batched-settle branch from 10a27ec to 1ce6478 Compare May 12, 2025 14:23

0xpatrickdev marked this pull request as ready for review May 12, 2025 14:23

0xpatrickdev requested a review from a team as a code owner May 12, 2025 14:23

0xpatrickdev requested review from AgoricTriage, turadg, dckc and gibson042 May 12, 2025 14:23

turadg reviewed May 12, 2025

View reviewed changes

0xpatrickdev added 3 commits May 12, 2025 17:35

fixup! feat: appendToSortedStoredArray

ed1c2d3

fixup! feat: add settlement-matching utilities for USDC transactions

9d0ff71

fixup! feat: pendingSettleTxs schema supports batch matching

e8d7de6

turadg approved these changes May 12, 2025

View reviewed changes

fixup! feat: add settlement-matching utilities for USDC transactions

c9a4ecd

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: settle against batched mints #11369

feat: settle against batched mints #11369

0xpatrickdev commented May 9, 2025 •

edited

Loading

cloudflare-workers-and-pages bot commented May 9, 2025 •

edited

Loading

turadg May 12, 2025

turadg May 12, 2025

turadg May 12, 2025

turadg May 12, 2025

0xpatrickdev May 12, 2025

turadg May 12, 2025

0xpatrickdev May 12, 2025

turadg May 12, 2025

turadg May 12, 2025

turadg May 12, 2025

turadg May 12, 2025

0xpatrickdev May 12, 2025 •

edited

Loading

turadg May 12, 2025

feat: settle against batched mints #11369

Are you sure you want to change the base?

feat: settle against batched mints #11369

Conversation

0xpatrickdev commented May 9, 2025 • edited Loading

Description

Security Considerations

Scaling Considerations

Documentation Considerations

Testing Considerations

Upgrade Considerations

cloudflare-workers-and-pages bot commented May 9, 2025 • edited Loading

Deploying agoric-sdk with Cloudflare Pages

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

0xpatrickdev May 12, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

0xpatrickdev commented May 9, 2025 •

edited

Loading

cloudflare-workers-and-pages bot commented May 9, 2025 •

edited

Loading

0xpatrickdev May 12, 2025 •

edited

Loading