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
Introduces new control flow for Relay max-amount quoting and changes how gas-fee-token costs are estimated/normalized, which can affect quote correctness and max-amount execution paths across supported chains.

Overview
Implements a dedicated max-amount “gas station” fallback for Relay quotes: when isMaxAmount is set, the strategy now may request an initial quote, estimate gas cost in the source token (via quote values, Gas Station estimation, or a probe quote), then re-request an adjusted quote and validate affordability before returning it.

Extracts Gas Station logic into a new gas-station helper (eligibility + source-token gas cost with multi-item normalization and support for decimal/hex simulation fields) and wires it into existing post-quote/source-network fee calculation to reuse the same normalization behavior.

Adds metamask.isMaxGasStation to Relay quote types and adjusts Relay submission behavior to keep max-gas-station executions on the existing gasFeeToken-only path (no gasFeeTokenAmount), with extensive new unit test coverage and changelog entry.

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

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

matthewwalsh0 · 2026-02-16T12:18:15Z

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

+
+const log = createModuleLogger(
+  projectLogger,
+  'max-amount-with-gas-station-fallback',


relay-max-gas-station? Maybe the file also?

matthewwalsh0 · 2026-02-16T12:19:53Z

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

+  };
+}
+
+function getGasStationEligibility(


Minor, some duplication with the existing relay-quotes, so probably worth some gas-station utils not specific to any pay strategy in future.

Good call, addressed it by extracting shared Relay gas-station logic into gas-station-utils.ts and reusing it from both quote paths.

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

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

+): Promise<GasCostEstimate | undefined> {
+  const gasCost = quote.fees.sourceNetwork.max;
+
+  if (quote.fees.isSourceGasFeeToken) {


To clarify, this shouldn't be possible with max amount since there would always be no balance left?

matthewwalsh0 · 2026-02-16T12:25:57Z

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

+  };
+}
+
+async function getGasStationCostInSourceTokenRaw(


This is a big duplication with the existing logic in relay-quotes, could we make some gas-station utils that are Relay specific for now within strategy/relay?

Maybe a getGasStationCost(quote) for example?

I extracted the duplicated Relay gas-station logic into gas-station.ts and now reuse it in both relay-quotes and relay-max-gas-station.

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

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

+  return phase1Quote;
+}
+
+function isAdjustedAmountPositive(adjustedSourceAmount: BigNumber): boolean {


For greater readability, should we avoid these tiny utils that are only used once?

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.

matthewwalsh0 · 2026-02-16T12:38:00Z

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

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


isMaxGasStation?

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

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

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


Should we force isSourceGasFeeToken here and also set the fees and amount for sourceNetwork using our original value from the probe quote?

matthewwalsh0 · 2026-02-16T12:44:21Z

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


  const slippage = featureFlags.slippage ?? DEFAULT_SLIPPAGE;

+  const maxGaslessEnabled =


Is this needed since currently the user just gets an error so there is no risk to functionality?

Removed it, as it fallbacks and shows error. It rarely happens but still shows error on re-quoting so I assume we are safe

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?

cursor

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

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

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


		markQuoteAsTwoPhaseForMaxAmount(phase2Quote);

		return phase2Quote;


		const slippage = featureFlags.slippage ?? DEFAULT_SLIPPAGE;

		const maxGaslessEnabled =

Uh oh!

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!

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!

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!

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

OGPoyraz commented Feb 13, 2026 •

edited by cursor bot

Loading