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

Author: pedronfigueiredo

packages/transaction-pay-controller/ARCHITECTURE.md

@@ -28,6 +28,10 @@ The mechanism by which the tokens are provided on the target chain is abstracted
 
 Each `PayStrategy` dictates how the `quotes` are retrieved, which detail the associated fees and strategy specific data, and how those quotes are actioned or "submitted".
 
+`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.
+
 ### Bridge
 
 The `BridgeStrategy` bridges tokens from the payment our source token to the target chain.
@@ -54,14 +58,15 @@ The high level interaction with the `TransactionPayController` is as follows:
 4. Controller identifies any required tokens and adds them to its state.
 5. If a client confirmation is using `MetaMask Pay`, the user selects a payment token (or it is done automatically) which invokes the `updatePaymentToken` action.
    - The below steps are also triggered if the transaction `data` is updated.
-6. Controller selects an appropriate `PayStrategy` using the `getStrategy` action.
-7. Controller requests quotes from the `PayStrategy` and persists them in state, including associated totals.
+6. Controller resolves an ordered set of `PayStrategy` implementations using the `getStrategies` action.
+7. Controller requests quotes from each compatible strategy in order until one returns quotes, then persists those quotes and associated totals.
 8. Resulting fees and totals are presented in the client transaction confirmation.
 9. If approved by the user, the target transaction is signed and published.
-10. The `TransactionPayPublishHook` is invoked and submits the relevant quotes via the same `PayStrategy`.
-11. The hook waits for any transactions and quotes to complete.
-12. Depending on the pay strategy and required tokens, the original target transaction is also published as the required funds are now in place on the user's account on the target chain.
-13. Target transaction is finalized and any related controller state is removed.
+10. The `TransactionPayPublishHook` is invoked and submits the relevant quotes via the strategy encoded in the quote.
+11. If primary execution fails, the hook rebuilds quote requests and retries using the next compatible strategy in order.
+12. The hook waits for any transactions and quotes to complete.
+13. Depending on the pay strategy and required tokens, the original target transaction is also published as the required funds are now in place on the user's account on the target chain.
+14. Target transaction is finalized and any related controller state is removed.
 
 ## State
 

packages/transaction-pay-controller/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add ordered strategy fallback mechanism for quote retrieval and publish-time execution ([#7868](https://github.com/MetaMask/core/pull/7868))
+
 ### Changed
 
 - Bump `@metamask/bridge-controller` from `^65.3.0` to `^66.0.0` ([#7862](https://github.com/MetaMask/core/pull/7862))

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

@@ -112,6 +112,51 @@ describe('TransactionPayController', () => {
         ),
       ).toBe(TransactionPayStrategy.Test);
     });
+
+    it('returns relay if getStrategies callback returns empty', async () => {
+      new TransactionPayController({
+        getDelegationTransaction: jest.fn(),
+        getStrategies: (): TransactionPayStrategy[] => [],
+        messenger,
+      });
+
+      expect(
+        messenger.call(
+          'TransactionPayController:getStrategy',
+          TRANSACTION_META_MOCK,
+        ),
+      ).toBe(TransactionPayStrategy.Relay);
+    });
+  });
+
+  describe('getStrategies Action', () => {
+    it('returns relay by default', async () => {
+      createController();
+
+      expect(
+        messenger.call(
+          'TransactionPayController:getStrategies',
+          TRANSACTION_META_MOCK,
+        ),
+      ).toStrictEqual([TransactionPayStrategy.Relay]);
+    });
+
+    it('returns callback list if provided', async () => {
+      new TransactionPayController({
+        getDelegationTransaction: jest.fn(),
+        getStrategies: (): TransactionPayStrategy[] => [
+          TransactionPayStrategy.Test,
+        ],
+        messenger,
+      });
+
+      expect(
+        messenger.call(
+          'TransactionPayController:getStrategies',
+          TRANSACTION_META_MOCK,
+        ),
+      ).toStrictEqual([TransactionPayStrategy.Test]);
+    });
   });
 
   describe('transaction data update', () => {

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

@@ -43,9 +43,14 @@ export class TransactionPayController extends BaseController<
     transaction: TransactionMeta,
   ) => TransactionPayStrategy;
 
+  readonly #getStrategies?: (
+    transaction: TransactionMeta,
+  ) => TransactionPayStrategy[];
+
   constructor({
     getDelegationTransaction,
     getStrategy,
+    getStrategies,
     messenger,
     state,
   }: TransactionPayControllerOptions) {
@@ -58,6 +63,7 @@ export class TransactionPayController extends BaseController<
 
     this.#getDelegationTransaction = getDelegationTransaction;
     this.#getStrategy = getStrategy;
+    this.#getStrategies = getStrategies;
 
     this.#registerActionHandlers();
 
@@ -141,15 +147,23 @@ export class TransactionPayController extends BaseController<
   }
 
   #registerActionHandlers(): void {
+    const getStrategies = this.#getStrategiesWithFallback.bind(this);
+
     this.messenger.registerActionHandler(
       'TransactionPayController:getDelegationTransaction',
       this.#getDelegationTransaction.bind(this),
     );
 
     this.messenger.registerActionHandler(
       'TransactionPayController:getStrategy',
-      this.#getStrategy ??
-        ((): TransactionPayStrategy => TransactionPayStrategy.Relay),
+      (transaction: TransactionMeta): TransactionPayStrategy =>
+        getStrategies(transaction)[0] ?? TransactionPayStrategy.Relay,
+    );
+
+    this.messenger.registerActionHandler(
+      'TransactionPayController:getStrategies',
+      (transaction: TransactionMeta): TransactionPayStrategy[] =>
+        getStrategies(transaction),
     );
 
     this.messenger.registerActionHandler(
@@ -162,4 +176,18 @@ export class TransactionPayController extends BaseController<
       this.updatePaymentToken.bind(this),
     );
   }
+
+  #getStrategiesWithFallback(
+    transaction: TransactionMeta,
+  ): TransactionPayStrategy[] {
+    if (this.#getStrategies) {
+      return this.#getStrategies(transaction);
+    }
+
+    if (this.#getStrategy) {
+      return [this.#getStrategy(transaction)];
+    }
+
+    return [TransactionPayStrategy.Relay];
+  }
 }