feat(transaction-pay): add ordered strategy fallback orchestration #7868

pedronfigueiredo · 2026-02-09T10:59:10Z

Explanation

As per preemptive validation on #7806

Adds ordered strategy retrieval via TransactionPayController:getStrategies while preserving existing getStrategy behavior.
Adds compatibility filtering (supports(...)) during strategy selection.
Implements quote fallback orchestration:
- try next strategy when quote retrieval fails
- try next strategy when quote list is empty
- skip unsupported strategies
Implements publish-hook fallback orchestration:
- execute primary strategy from existing quote strategy
- on execution failure, rebuild quote requests and try next compatible strategy
- throw original primary error if all fallback attempts fail

References

Addresses https://github.com/MetaMask/MetaMask-planning/issues/6992

Checklist

I've updated the test suite for new or updated code as appropriate
I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
I've communicated my changes to consumers by updating changelogs for packages I've changed
I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

Note

Medium Risk
Changes core quote-selection and execution routing logic; incorrect ordering/fallback behavior could lead to missing quotes or executing the wrong pay path, though guarded by defaults/tests and fallback-to-default strategy order.

Overview
Implements ordered PayStrategy orchestration for quote retrieval: TransactionPayController now accepts getStrategies (with feature-flag default ordering) and updateQuotes iterates strategies in order, applying optional supports(...) checks and falling back on errors or empty quotes/batch transactions.

Publish-time execution is aligned with quote selection by executing via the strategy recorded on the quote (quotes[0].strategy) rather than re-resolving strategy from the transaction. Adds a new confirmations_pay.strategyOrder feature flag with validation/deduping, updates quote refresh plumbing to pass strategy ordering through, and updates docs/tests accordingly.

^{Written by Cursor Bugbot for commit eeca0ed. This will update automatically on new commits. Configure here.}

packages/transaction-pay-controller/src/utils/quotes.ts

packages/transaction-pay-controller/src/utils/strategy.ts

packages/transaction-pay-controller/src/types.ts

packages/transaction-pay-controller/src/helpers/TransactionPayPublishHook.ts

packages/transaction-pay-controller/src/TransactionPayController.ts

packages/transaction-pay-controller/src/utils/strategy.ts

matthewwalsh0 · 2026-02-11T09:59:55Z

packages/transaction-pay-controller/ARCHITECTURE.md


+`TransactionPayController` provides an ordered strategy list via `getStrategies`.
+The quote flow iterates strategies in order, applies `supports(...)` compatibility checks when present, and falls back to the next compatible strategy if quote retrieval fails or returns no quotes.
+The publish hook uses the same ordered fallback approach if execution fails for the primary quote strategy.


As mentioned in the previous PR, I don't think quote execution fallback is possible since we have no opportunity to present the new fee to the user, which may be higher, or have an alternate network fee, or require gas station etc.

matthewwalsh0 · 2026-02-11T10:09:22Z

packages/transaction-pay-controller/src/types.ts

 };

+/** Action to get the ordered pay strategies for a transaction. */
+export type TransactionPayControllerGetStrategiesAction = {


If we remove the execution fallback, we shouldn't need a new messenger action, as we only need to identify the strategy based on the quote in the state.

Though in retrospect, we should probably do that via the strategy property on the quote itself, which would mean we also would no longer need the getStrategy action either.

I kept getStrategy for now, as this would be a breaking change to the client. I'm keeping track of this on a ticket, however, so we can clean that up later.

matthewwalsh0 · 2026-02-11T10:10:04Z

packages/transaction-pay-controller/src/utils/quotes.ts

 * @returns Array of quote requests.
 */
-function buildQuoteRequests({
+export function buildQuoteRequests({


This shouldn't need to be exported if we remove fallback execution.

matthewwalsh0 · 2026-02-11T10:10:24Z

packages/transaction-pay-controller/src/utils/quotes.ts

+
+  for (const strategy of strategies) {
+    try {
+      if (strategy.supports && !strategy.supports(request)) {


Worth a log to confirm when a strategy doesn't support a request?

matthewwalsh0 · 2026-02-11T10:10:43Z

packages/transaction-pay-controller/src/utils/quotes.ts

+      )) as TransactionPayQuote<Json>[];
+
+      if (!quotes.length) {
+        continue;


Worth a log to confirm a single strategy found no quotes?

matthewwalsh0 · 2026-02-11T10:11:58Z

packages/transaction-pay-controller/src/helpers/TransactionPayPublishHook.ts

    const quotes =
-      (controllerState.transactionData?.[transactionId]
-        ?.quotes as TransactionPayQuote<unknown>[]) ?? [];
+      (transactionData?.quotes as TransactionPayQuote<unknown>[]) ?? [];


As mentioned, all we should do here is identify the strategy from the saved quotes using the strategy property, and execute them. We shouldn't fallback here given fee implications.

matthewwalsh0 · 2026-02-11T10:12:27Z

packages/transaction-pay-controller/src/utils/quotes.ts

-  } catch (error) {
-    log('Error fetching quotes', { error, transactionId });
+  if (!requests?.length) {
+    return {


Worth a log to help debug all these branches?

matthewwalsh0 · 2026-02-11T10:13:23Z

packages/transaction-pay-controller/src/TransactionPayController.ts

+      strategies = [this.#getStrategy(transaction)];
+    }
+
+    return strategies.length ? strategies : [TransactionPayStrategy.Relay];


Are we not adding the feature flag fallback order in this PR, or are we letting the client own the order?

matthewwalsh0 · 2026-02-11T10:15:28Z

packages/transaction-pay-controller/src/utils/quotes.ts

  const { id: transactionId } = transaction;
-  const strategy = getStrategy(messenger as never, transaction);
-  let quotes: TransactionPayQuote<Json>[] | undefined = [];
+  const strategies = getStrategies(messenger as never, transaction);


If we remove both messenger actions for getting strategies, we could just get this via another callback such as getStrategies in the UpdateQuotesRequest.

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

packages/transaction-pay-controller/src/types.ts

pedronfigueiredo self-assigned this Feb 9, 2026

pedronfigueiredo requested review from a team as code owners February 9, 2026 10:59

pedronfigueiredo added the team-confirmations label Feb 9, 2026

cursor bot reviewed Feb 9, 2026

View reviewed changes

packages/transaction-pay-controller/src/utils/quotes.ts Outdated Show resolved Hide resolved

packages/transaction-pay-controller/src/utils/strategy.ts Outdated Show resolved Hide resolved

pedronfigueiredo force-pushed the cor-6992-extract-fallback-mechanism branch 6 times, most recently from 23573ac to 55549a1 Compare February 9, 2026 11:34

cursor bot reviewed Feb 9, 2026

View reviewed changes

packages/transaction-pay-controller/src/types.ts Outdated Show resolved Hide resolved

pedronfigueiredo force-pushed the cor-6992-extract-fallback-mechanism branch from 55549a1 to e2818b3 Compare February 9, 2026 13:32

cursor bot reviewed Feb 9, 2026

View reviewed changes

packages/transaction-pay-controller/src/helpers/TransactionPayPublishHook.ts Outdated Show resolved Hide resolved

pedronfigueiredo force-pushed the cor-6992-extract-fallback-mechanism branch from e2818b3 to 5158351 Compare February 9, 2026 13:48

cursor bot reviewed Feb 9, 2026

View reviewed changes

packages/transaction-pay-controller/src/TransactionPayController.ts Outdated Show resolved Hide resolved

packages/transaction-pay-controller/src/utils/strategy.ts Outdated Show resolved Hide resolved

pedronfigueiredo force-pushed the cor-6992-extract-fallback-mechanism branch 3 times, most recently from c450bc6 to 782bc16 Compare February 9, 2026 14:27

pedronfigueiredo requested a review from matthewwalsh0 February 10, 2026 10:16

matthewwalsh0 requested changes Feb 11, 2026

View reviewed changes

feat(transaction-pay): add ordered strategy fallback orchestration

af4c60f

pedronfigueiredo force-pushed the cor-6992-extract-fallback-mechanism branch from 9b2de51 to 44ee983 Compare February 12, 2026 11:02

cursor bot reviewed Feb 12, 2026

View reviewed changes

packages/transaction-pay-controller/src/types.ts Outdated Show resolved Hide resolved

refactor(transaction-pay): align strategy fallback with review feedback

eeca0ed

pedronfigueiredo force-pushed the cor-6992-extract-fallback-mechanism branch from 44ee983 to eeca0ed Compare February 12, 2026 13:47

pedronfigueiredo requested a review from matthewwalsh0 February 12, 2026 13:53

Uh oh!

feat(transaction-pay): add ordered strategy fallback orchestration #7868

Are you sure you want to change the base?

feat(transaction-pay): add ordered strategy fallback orchestration #7868

Uh oh!

Conversation

pedronfigueiredo commented Feb 9, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Explanation

References

Checklist

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matthewwalsh0 Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matthewwalsh0 Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

pedronfigueiredo commented Feb 9, 2026 •

edited by cursor bot

Loading

matthewwalsh0 Feb 11, 2026 •

edited

Loading

matthewwalsh0 Feb 11, 2026 •

edited

Loading