feat(transaction-pay-controller): store no-op quotes for direct routes (MetaMask#9484)

## Explanation

`TransactionPayController` stores an empty quotes array both when no
conversion is needed and when a quote could not be fetched, so at
publish time the two cases cannot be told apart.

This PR makes the distinction explicit:

- Store a no-op quote (`TransactionPayStrategy.None`) when a payment
token is selected but the route needs no conversion. The no-op quote is
built inside `getQuotes` when there are no quote requests, and is
skipped when `isQuoteRequired` is set, since an empty request list then
means source amounts could not be calculated.
- No-op quotes are not routable: the quote refresher skips them, they
are excluded from totals and the external-sign flag, and
`TransactionPayPublishHook` filters them out before selecting a
strategy.
- Clients can rely on `quotes.length > 0` whenever MetaMask Pay is
engaged, and enforce quote presence at publish time on their side.

## References

- Mobile adoption: MetaMask/metamask-mobile#33194

## Checklist

- [x] I've updated the test suite for new or updated code as appropriate
- [x] I've updated documentation (JSDoc, Markdown, etc.) for new or
updated code as appropriate
- [x] I've communicated my changes to consumers by [updating changelogs
for packages I've
changed](https://github.com/MetaMask/core/tree/main/docs/processes/updating-changelogs.md)
- [x] I've introduced [breaking
changes](https://github.com/MetaMask/core/tree/main/docs/processes/breaking-changes.md)
in this PR and have prepared draft pull requests for clients and
consumer packages to resolve them

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes quote shape and publish-time behavior (breaking for quote
consumers) in the transaction pay path, but logic is guarded with
filters and broad tests rather than touching auth or funds directly.
> 
> **Overview**
> Direct MetaMask Pay routes (payment token selected, no conversion) now
persist a **no-op quote** with strategy `none` instead of an empty
`quotes` array, so **“no conversion needed”** is distinguishable from
**“quote still missing.”**
> 
> `getQuotes` builds that marker via `buildNoOpQuote` when there are no
quote requests and `isQuoteRequired` is false; fiat-only empty cases and
quote-required flows still clear or omit it.
**`TransactionPayStrategy.None` is not
routable**—`isTransactionPayStrategy` excludes it, the publish hook
skips execution, quote refresh/polling ignores only-no-op state, and fee
totals / `hasQuotes` sync use **executable** quotes only.
> 
> **Breaking:** downstream clients that treat any entry in `quotes` as a
real pay quote must ignore or handle `strategy: 'none'`.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
30646eb. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: dan437

packages/transaction-pay-controller/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Store a no-op quote (`TransactionPayStrategy.None`) when a payment token is selected but the route needs no conversion, so clients can tell "no conversion needed" apart from "quote missing" ([#9484](https://github.com/MetaMask/core/pull/9484))
+- Add `None` value to `TransactionPayStrategy` enum ([#9484](https://github.com/MetaMask/core/pull/9484))
+
+### Changed
+
+- **BREAKING:** Quotes stored in `transactionData` can now contain a single no-op quote with the `none` strategy; clients that read quotes for display, metrics, or publish validation must ignore or handle no-op quotes ([#9484](https://github.com/MetaMask/core/pull/9484))
+
 ## [24.1.0]
 
 ### Added

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

@@ -72,14 +72,24 @@ export enum PaymentOverride {
 export enum TransactionPayStrategy {
   Across = 'across',
   Fiat = 'fiat',
+  /**
+   * Internal marker for no-op quotes generated when the controller determines
+   * that no conversion is needed. Not a routable strategy.
+   */
+  None = 'none',
   Relay = 'relay',
   Server = 'server',
 }
 
-const VALID_STRATEGIES = new Set(Object.values(TransactionPayStrategy));
+const VALID_STRATEGIES = new Set(
+  Object.values(TransactionPayStrategy).filter(
+    (strategy) => strategy !== TransactionPayStrategy.None,
+  ),
+);
 
 /**
- * Checks if a value is a valid transaction pay strategy.
+ * Checks if a value is a valid, routable transaction pay strategy.
+ * The internal no-op marker is not routable.
  *
  * @param strategy - Candidate strategy value.
  * @returns True if the value is a valid strategy.

packages/transaction-pay-controller/src/helpers/QuoteRefresher.test.ts

@@ -80,6 +80,31 @@ describe('QuoteRefresher', () => {
     expect(refreshQuotesMock).not.toHaveBeenCalled();
   });
 
+  it('does not poll if only no-op quotes in state', async () => {
+    new QuoteRefresher({
+      getStrategies: jest.fn().mockReturnValue([TransactionPayStrategy.Relay]),
+      messenger,
+      updateTransactionData: jest.fn(),
+    });
+
+    publish(
+      'TransactionPayController:stateChange',
+      {
+        transactionData: {
+          '123': {
+            quotes: [{ strategy: TransactionPayStrategy.None }],
+          } as TransactionData,
+        },
+      },
+      [],
+    );
+
+    jest.runAllTimers();
+    await flushPromises();
+
+    expect(refreshQuotesMock).not.toHaveBeenCalled();
+  });
+
   it('polls again after interval', async () => {
     new QuoteRefresher({
       getStrategies: jest.fn().mockReturnValue([TransactionPayStrategy.Relay]),

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

@@ -106,8 +106,11 @@ export class QuoteRefresher {
   }
 
   #onStateChange(state: TransactionPayControllerState): void {
+    // No-op quotes never refresh, so they don't need the refresh loop.
     const hasQuotes = Object.values(state.transactionData).some((transaction) =>
-      Boolean(transaction.quotes?.length),
+      transaction.quotes?.some(
+        (quote) => quote.strategy !== TransactionPayStrategy.None,
+      ),
     );
 
     if (hasQuotes && !this.#isRunning) {

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

@@ -115,6 +115,43 @@ describe('TransactionPayPublishHook', () => {
     expect(executeMock).not.toHaveBeenCalled();
   });
 
+  it('does nothing if transaction data has no quotes', async () => {
+    getControllerStateMock.mockReturnValue({
+      transactionData: {
+        [TRANSACTION_META_MOCK.id]: {
+          isLoading: false,
+          paymentToken: { address: '0x123' },
+          tokens: [],
+        },
+      },
+    } as unknown as TransactionPayControllerState);
+
+    const result = await runHook();
+
+    expect(result).toStrictEqual({ transactionHash: undefined });
+    expect(executeMock).not.toHaveBeenCalled();
+    expect(updateTransactionMock).not.toHaveBeenCalled();
+  });
+
+  it('does nothing if only a no-op quote is present', async () => {
+    getControllerStateMock.mockReturnValue({
+      transactionData: {
+        [TRANSACTION_META_MOCK.id]: {
+          isLoading: false,
+          paymentToken: { address: '0x123' },
+          quotes: [{ strategy: TransactionPayStrategy.None }],
+          tokens: [],
+        },
+      },
+    } as unknown as TransactionPayControllerState);
+
+    const result = await runHook();
+
+    expect(result).toStrictEqual({ transactionHash: undefined });
+    expect(executeMock).not.toHaveBeenCalled();
+    expect(updateTransactionMock).not.toHaveBeenCalled();
+  });
+
   it('throws if fiat payment is selected but no quotes are in state', async () => {
     getControllerStateMock.mockReturnValue({
       transactionData: {

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

@@ -4,6 +4,7 @@ import type { PublishHookResult } from '@metamask/transaction-controller';
 import type { Hex } from '@metamask/utils';
 import { createModuleLogger } from '@metamask/utils';
 
+import { TransactionPayStrategy } from '../constants';
 import { projectLogger } from '../logger';
 import type {
   TransactionPayControllerMessenger,
@@ -64,18 +65,23 @@ export class TransactionPayPublishHook {
     );
 
     const transactionData = controllerState.transactionData?.[transactionId];
-    const quotes =
-      (transactionData?.quotes as TransactionPayQuote<unknown>[]) ?? [];
+
+    // No-op quotes mark direct routes and cannot be executed by any strategy.
+    const quotes = (
+      (transactionData?.quotes as TransactionPayQuote<unknown>[]) ?? []
+    ).filter((quote) => quote.strategy !== TransactionPayStrategy.None);
+
     const isFiatSelected = Boolean(
       transactionData?.fiatPayment?.selectedPaymentMethodId,
     );
 
-    if (!quotes?.length) {
+    if (!quotes.length) {
       if (isFiatSelected) {
         throw new Error('Fiat: Missing quote');
       }
 
-      log('Skipping as no quotes found');
+      log('Skipping as no executable quotes found', { transactionId });
+
       return EMPTY_RESULT;
     }
 

packages/transaction-pay-controller/src/utils/no-op-quote.test.ts

@@ -0,0 +1,63 @@
+import type { Hex } from '@metamask/utils';
+
+import { TransactionPayStrategy } from '../constants';
+import type { TransactionPaymentToken } from '../types';
+import { buildNoOpQuote } from './no-op-quote';
+
+const FROM_MOCK = '0xabc' as Hex;
+
+const PAYMENT_TOKEN_MOCK = {
+  address: '0x123' as Hex,
+  balanceRaw: '2000000',
+  chainId: '0x89' as Hex,
+  decimals: 6,
+  symbol: 'pUSD',
+} as TransactionPaymentToken;
+
+describe('No-Op Quote Utils', () => {
+  describe('buildNoOpQuote', () => {
+    it('builds quote with none strategy', () => {
+      const quote = buildNoOpQuote(FROM_MOCK, PAYMENT_TOKEN_MOCK);
+
+      expect(quote.strategy).toBe(TransactionPayStrategy.None);
+    });
+
+    it('builds quote with zero fees and amounts', () => {
+      const quote = buildNoOpQuote(FROM_MOCK, PAYMENT_TOKEN_MOCK);
+
+      expect(quote.estimatedDuration).toBe(0);
+      expect(quote.dust).toStrictEqual({ fiat: '0', usd: '0' });
+      expect(quote.targetAmount).toStrictEqual({ fiat: '0', usd: '0' });
+      expect(quote.sourceAmount).toStrictEqual({
+        fiat: '0',
+        usd: '0',
+        human: '0',
+        raw: '0',
+      });
+      expect(quote.fees).toStrictEqual({
+        metaMask: { fiat: '0', usd: '0' },
+        provider: { fiat: '0', usd: '0' },
+        sourceNetwork: {
+          estimate: { fiat: '0', usd: '0', human: '0', raw: '0' },
+          max: { fiat: '0', usd: '0', human: '0', raw: '0' },
+        },
+        targetNetwork: { fiat: '0', usd: '0' },
+      });
+    });
+
+    it('builds request targeting the payment token', () => {
+      const quote = buildNoOpQuote(FROM_MOCK, PAYMENT_TOKEN_MOCK);
+
+      expect(quote.request).toStrictEqual({
+        from: FROM_MOCK,
+        sourceBalanceRaw: PAYMENT_TOKEN_MOCK.balanceRaw,
+        sourceChainId: PAYMENT_TOKEN_MOCK.chainId,
+        sourceTokenAddress: PAYMENT_TOKEN_MOCK.address,
+        sourceTokenAmount: '0',
+        targetAmountMinimum: '0',
+        targetChainId: PAYMENT_TOKEN_MOCK.chainId,
+        targetTokenAddress: PAYMENT_TOKEN_MOCK.address,
+      });
+    });
+  });
+});

packages/transaction-pay-controller/src/utils/no-op-quote.ts

@@ -0,0 +1,64 @@
+import type { Hex, Json } from '@metamask/utils';
+
+import { TransactionPayStrategy } from '../constants';
+import type {
+  Amount,
+  FiatValue,
+  TransactionPaymentToken,
+  TransactionPayQuote,
+} from '../types';
+
+function zeroFiat(): FiatValue {
+  return { fiat: '0', usd: '0' };
+}
+
+function zeroAmount(): Amount {
+  return { ...zeroFiat(), human: '0', raw: '0' };
+}
+
+/**
+ * Build a no-op quote for a transaction that needs no conversion.
+ *
+ * Stored instead of an empty quotes array when a payment token is selected
+ * but the route is direct (e.g. same token and chain, or sufficient balance).
+ * This gives clients and the publish hook an explicit marker to distinguish
+ * "no quote needed" from "quote needed but missing". No-op quotes use the
+ * `TransactionPayStrategy.None` strategy, cannot be executed, and must be
+ * ignored by fee totals and quote refreshes.
+ *
+ * @param from - Resolved wallet address for the transaction.
+ * @param paymentToken - Selected payment token.
+ * @returns The no-op quote.
+ */
+export function buildNoOpQuote(
+  from: Hex,
+  paymentToken: TransactionPaymentToken,
+): TransactionPayQuote<Json> {
+  return {
+    dust: zeroFiat(),
+    estimatedDuration: 0,
+    fees: {
+      metaMask: zeroFiat(),
+      provider: zeroFiat(),
+      sourceNetwork: {
+        estimate: zeroAmount(),
+        max: zeroAmount(),
+      },
+      targetNetwork: zeroFiat(),
+    },
+    original: null,
+    request: {
+      from,
+      sourceBalanceRaw: paymentToken.balanceRaw,
+      sourceChainId: paymentToken.chainId,
+      sourceTokenAddress: paymentToken.address,
+      sourceTokenAmount: '0',
+      targetAmountMinimum: '0',
+      targetChainId: paymentToken.chainId,
+      targetTokenAddress: paymentToken.address,
+    },
+    sourceAmount: zeroAmount(),
+    strategy: TransactionPayStrategy.None,
+    targetAmount: zeroFiat(),
+  };
+}