feat: Implement max amount with gas station fallback by OGPoyraz · Pull Request #7927 · MetaMask/core

OGPoyraz · 2026-02-13T09:52:51Z

Explanation

This PR introduces a dedicated max-amount gas-station fallback flow for Relay, extracted into a focused helper and wired into quote orchestration. The goal was fixing max-amount mUSD conversion failures caused by gas-fee-token estimation dead-ends but in fact it fixes for any kind of intent.

The helper (getMaxAmountQuoteWithGasStationFallback) now implements a clear two-phase flow with explicit fallback points:

Phase-1 quote (full max amount)

Request quote using original max source amount.

Early-return guards (return phase-1 immediately)

If source gas fee token is not used and native balance already covers gas.
If maxGaslessEnabled is false.
If gas station is disabled/unsupported for source chain.

Gas-cost estimation strategy

First try direct estimation from quote/gas-station params.
If that fails, request a probe quote with smaller source amount (PROBE_AMOUNT_PERCENTAGE = 0.25) to discover gas fee token + amount.
Uses TransactionController:getGasFeeTokens and calculateGasFeeTokenCost to normalize source-token gas fee amount.

Phase-2 quote (adjusted max)

Compute adjusted amount as: adjusted = sourceAmount - estimatedGasCost.
Request phase-2 quote with adjusted source amount.

Validation before accepting phase-2

Re-estimate gas on phase-2 quote.
Require affordability: adjusted + validationGasCost <= originalSourceAmount.
If valid, mark twoPhaseQuoteForMaxAmount = true and return phase-2.
Otherwise fallback to phase-1.

References

Fixes: Enable gasless mUSD conversions for max amount transactions metamask-mobile#25466

gasless.max.mov

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 Relay quote selection for isMaxAmount requests and introduces new gas-cost estimation/validation paths; while heavily tested, errors could affect max-amount pricing or fallback behavior in production.

Overview
Adds a dedicated two-phase max-amount quoting path for the Relay strategy that can fall back to gas-station-derived gas costs (and optionally a smaller “probe” quote) to produce an adjusted max quote when the initial max quote can’t be priced safely in source-token gas units.

Refactors Relay quote gas-fee-token handling by extracting getGasStationEligibility/getGasStationCostInSourceTokenRaw (including multi-item gas normalization and support for decimal simulation fields), wires the new max-amount flow into getRelayQuotes, and tags successful phase-2 quotes via original.metamask.isMaxGasStation (type extended accordingly). Test coverage is expanded significantly, including post-quote normalization and ensuring max-gas-station submissions keep the existing gasFeeToken-only behavior.

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

packages/transaction-pay-controller/src/strategy/relay/relay-max-gas-station.ts

packages/transaction-pay-controller/src/strategy/relay/max-amount-with-gas-station-fallback.ts

packages/transaction-pay-controller/src/strategy/relay/relay-max-gas-station.ts

packages/transaction-pay-controller/src/strategy/relay/max-amount-with-gas-station-fallback.ts

matthewwalsh0 · 2026-02-16T12:37:23Z

packages/transaction-pay-controller/src/strategy/relay/max-amount-with-gas-station-fallback.ts

+  if (
+    !isAdjustedAmountAffordable(
+      adjustedSourceAmount,
+      validationGasEstimate.amount,


We don't care about the new amount do we, as we calculated the old one to be exactly what is remaining of the balance, so do we want to use that to avoid dust?

I think we shouldn't blindly trust the new amount, but we also avoid forcing the original estimate when quote internals shift slightly. This keeps max safety and minimizes dust risk without introducing a new submit API in this PR.

Makes sense as MVP I think, but avoiding dust wherever possible is a good goal, we can circle back later.

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

packages/transaction-pay-controller/src/strategy/relay/relay-max-gas-station.ts

packages/transaction-pay-controller/src/utils/feature-flags.ts

matthewwalsh0 · 2026-02-16T12:46:52Z

packages/transaction-pay-controller/src/strategy/relay/relay-max-gas-station.ts

+
+  markQuoteAsTwoPhaseForMaxAmount(phase2Quote);
+
+  return phase2Quote;


Potentially a separate PR, but are the gas fee tokens consistent in your testing?

Or should we also update relay-submit to specify a new gasFeeTokenAmount property to the TransactionController to avoid any dust?

Discussed in other comments, no new submit API for now for simplicity, at the cost of minor dust 👍

cursor

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

packages/transaction-pay-controller/src/strategy/relay/relay-quotes.ts

matthewwalsh0 · 2026-02-24T21:14:08Z

packages/transaction-pay-controller/src/strategy/relay/gas-station.ts

+
+function parseGasValue(value: string): BigNumber {
+  if (value.toLowerCase().startsWith('0x')) {
+    return new BigNumber(value.slice(2), 16);


Minor, BigNumber should handle 0x automatically, even without the base argument.

Done, removed

matthewwalsh0 · 2026-02-24T21:17:45Z

packages/transaction-pay-controller/src/strategy/relay/max-amount-with-gas-station-fallback.ts

+  if (
+    !isAdjustedAmountAffordable(
+      adjustedSourceAmount,
+      validationGasEstimate.amount,


Makes sense as MVP I think, but avoiding dust wherever possible is a good goal, we can circle back later.

matthewwalsh0 · 2026-02-24T21:18:58Z

packages/transaction-pay-controller/src/strategy/relay/relay-max-gas-station.ts

+
+  markQuoteAsTwoPhaseForMaxAmount(phase2Quote);
+
+  return phase2Quote;


Discussed in other comments, no new submit API for now for simplicity, at the cost of minor dust 👍

matthewwalsh0 · 2026-02-24T21:27:57Z

packages/transaction-pay-controller/src/strategy/relay/relay-max-gas-station.ts

+    request,
+  };
+
+  const { relayDisabledGasStationChains } = getFeatureFlags(messenger);


Minor, could we encapsulate this within getGasStationEligibility since we pass the messenger also?

Good call, relocated in getGasStationEligibility

matthewwalsh0 · 2026-02-24T21:40:15Z

packages/transaction-pay-controller/src/strategy/relay/relay-max-gas-station.ts

+  request: QuoteRequest;
+};
+
+export async function getRelayMaxGasStationQuote(


Minor, could we get a high level summary of the algorithm here in JSDoc?

Added JSDoc

matthewwalsh0 · 2026-02-24T21:47:04Z

packages/transaction-pay-controller/src/strategy/relay/relay-max-gas-station.ts

+  );
+
+  if (
+    !isAdjustedAmountAffordable(


Is this another benefit of the future add transaction API changes, since we can guarantee we can still afford the original value since we subtracted it from our balance?

But this new one may have gone up.

Yes, that’s right, subtraction used an earlier estimate, and the phase2 gas cost can come back higher.

A future submit API change (explicit gasFeeTokenAmount) would help execution time determinism/dust, but it does not fully replace this quote-time affordability guard. We still need to validate that adjusted + latestGasCost <= originalBalance before accepting phase2.

matthewwalsh0 · 2026-02-24T21:51:03Z

packages/transaction-pay-controller/src/strategy/relay/relay-max-gas-station.ts

+    return primaryEstimate;
+  }
+
+  const probeCost = await getProbeGasCostInSourceTokenRaw(context);


How can the above fail?

If no gas fee tokens are returned from the original quote, then should we not just fallback at that point?

Why would it help to try get another quote with a smaller amount?

From testing, at full max, fee-token estimation/simulation can return no usable gas-fee-token result (or no match) because the transaction is too tight at the balance boundary.

With a smaller probe amount, the same route often becomes estimable and returns either:
isSourceGasFeeToken directly, or a usable getGasFeeTokens result we can normalize.

So this is a recovery path, not a bypass. It lets us rescue cases that would otherwise unnecessarily fall back.

matthewwalsh0 · 2026-02-24T21:52:55Z

packages/transaction-pay-controller/src/strategy/relay/relay-max-gas-station.ts

+    return undefined;
+  }
+
+  if (probeQuote.fees.isSourceGasFeeToken) {


Is everything below a duplication of getGasCostFromQuoteOrGasStation?

Good call, removed below by re-using getGasCostFromQuoteOrGasStation

matthewwalsh0 · 2026-02-24T21:59:06Z

packages/transaction-pay-controller/src/strategy/relay/relay-quotes.ts

+      sourceTokenAddress,
+    },
+    totalGasEstimate,
+    totalItemCount: Math.max(relayParams.length, gasLimits.length),


I can see this was part of the old code, but I can't see how we could have multiple gas limits with a single relay params.

Isn't that comes from post-quote handling? If it's a post-quote with an original transaction, in non-7702 path prepends original transaction gas (gasLimits = [originalTxGas, ...gasLimits])

matthewwalsh0 · 2026-02-24T22:00:22Z

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

  };
  metamask: {
    gasLimits: number[];
+    isMaxGasStation?: boolean;


Is this purely for future use if we change the submission flow to use the exact gas fee token amount?

Should we omit now if not used?

This is purely for metric purposes, so we can track if 2 phase quoting successfully initiated and quote replaced then we will flag metrics it on client.

OGPoyraz force-pushed the ogp/25466 branch from 49395d8 to 45eabcb Compare February 16, 2026 10:20

OGPoyraz added 11 commits February 16, 2026 12:02

Implement max amount with gas station fallback

ccb0b35

Add case for native gas pay

3e6be7d

Temp

cbc8692

Temp2

4d90d56

Temp3

8b2cb73

Finalise tests

0c03369

Fix ff tests

12596e5

Remove unused constant

7dc561c

Update

6f02404

Add changelog

ed5df8a

Update tests

dc11cf7

OGPoyraz force-pushed the ogp/25466 branch from d5ee7ec to dc11cf7 Compare February 16, 2026 11:02

OGPoyraz marked this pull request as ready for review February 16, 2026 11:04

OGPoyraz requested review from a team as code owners February 16, 2026 11:04

cursor bot reviewed Feb 16, 2026

View reviewed changes

packages/transaction-pay-controller/src/strategy/relay/relay-max-gas-station.ts Show resolved Hide resolved

Update name of constant

36e5dea

matthewwalsh0 requested changes Feb 16, 2026

View reviewed changes

Update

12c7b29

cursor bot reviewed Feb 17, 2026

View reviewed changes

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

OGPoyraz added 3 commits February 17, 2026 14:12

Update bugbot comment

829953b

Update changelog

b1ec14e

Rename gas-station-util

11d1a85

matthewwalsh0 requested changes Feb 24, 2026

View reviewed changes

OGPoyraz added 4 commits February 25, 2026 10:17

Merge branch 'main' into ogp/25466

7ca6a55

Address comments

32d5741

Update changelog

697dd9a

Fix lint

7a5d8d4


		markQuoteAsTwoPhaseForMaxAmount(phase2Quote);

		return phase2Quote;

Uh oh!

Comments

Conversation

OGPoyraz commented Feb 13, 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!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

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!

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!

Choose a reason for hiding this comment

Uh oh!

OGPoyraz Feb 25, 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!

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!

OGPoyraz Feb 25, 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

OGPoyraz commented Feb 13, 2026 •

edited by cursor bot

Loading

OGPoyraz Feb 25, 2026 •

edited

Loading

OGPoyraz Feb 25, 2026 •

edited

Loading