Comments

feat: Implement max amount with gas station fallback#7927

Open

OGPoyraz wants to merge 16 commits intomain from

ogp/25466

Open

feat: Implement max amount with gas station fallback #7927
OGPoyraz wants to merge 16 commits intomain from
ogp/25466

Conversation

@OGPoyraz

Copy link

Member

@OGPoyraz OGPoyraz commented Feb 13, 2026 •

edited by cursor bot

Loading

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.}

@OGPoyraz 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

@OGPoyraz


 Implement max amount with gas station fallback

ccb0b35

@OGPoyraz


 Add case for native gas pay

3e6be7d

@OGPoyraz


 Temp

cbc8692

@OGPoyraz


 Temp2

4d90d56

@OGPoyraz


 Temp3

8b2cb73

@OGPoyraz


 Finalise tests

0c03369

@OGPoyraz


 Fix ff tests

12596e5

@OGPoyraz


 Remove unused constant

7dc561c

@OGPoyraz


 Update

6f02404

@OGPoyraz


 Add changelog

ed5df8a

@OGPoyraz


 Update tests

dc11cf7

@OGPoyraz OGPoyraz force-pushed the ogp/25466 branch from d5ee7ec to dc11cf7 Compare

February 16, 2026 11:02

@OGPoyraz OGPoyraz marked this pull request as ready for review

February 16, 2026 11:04

@OGPoyraz OGPoyraz requested review from a team as code owners

February 16, 2026 11:04

cursor[bot]

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

@OGPoyraz


 Update name of constant

36e5dea

matthewwalsh0

matthewwalsh0 requested changes

Feb 16, 2026

View reviewed changes

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

const log = createModuleLogger(

projectLogger,

'max-amount-with-gas-station-fallback',

Copy link

Member

@matthewwalsh0 matthewwalsh0 Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link

Member Author

@OGPoyraz OGPoyraz Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done

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

};

}

function getGasStationEligibility(

Copy link

Member

@matthewwalsh0 matthewwalsh0 Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link

Member Author

@OGPoyraz OGPoyraz Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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) {

Copy link

Member

@matthewwalsh0 matthewwalsh0 Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

};

}

async function getGasStationCostInSourceTokenRaw(

Copy link

Member

@matthewwalsh0 matthewwalsh0 Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link

Member Author

@OGPoyraz OGPoyraz Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

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

return phase1Quote;

}

function isAdjustedAmountPositive(adjustedSourceAmount: BigNumber): boolean {

Copy link

Member

@matthewwalsh0 matthewwalsh0 Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link

Member Author

@OGPoyraz OGPoyraz Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done

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

if (

!isAdjustedAmountAffordable(

adjustedSourceAmount,

validationGasEstimate.amount,

Copy link

Member

@matthewwalsh0 matthewwalsh0 Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link

Member Author

@OGPoyraz OGPoyraz Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

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

};

metamask: {

gasLimits: number[];

twoPhaseQuoteForMaxAmount?: boolean;

Copy link

Member

@matthewwalsh0 matthewwalsh0 Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

isMaxGasStation?

Copy link

Member Author

@OGPoyraz OGPoyraz Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done

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

markQuoteAsTwoPhaseForMaxAmount(phase2Quote);

return phase2Quote;

Copy link

Member

@matthewwalsh0 matthewwalsh0 Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

const slippage = featureFlags.slippage ?? DEFAULT_SLIPPAGE;

const maxGaslessEnabled =

Copy link

Member

@matthewwalsh0 matthewwalsh0 Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link

Member Author

@OGPoyraz OGPoyraz Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

markQuoteAsTwoPhaseForMaxAmount(phase2Quote);

return phase2Quote;

Copy link

Member

@matthewwalsh0 matthewwalsh0 Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

@OGPoyraz


 Update

12c7b29

cursor[bot]

cursor bot reviewed

Feb 17, 2026

View reviewed changes

Copy link

@cursor cursor bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

OGPoyraz added 3 commits

February 17, 2026 14:12

@OGPoyraz


 Update bugbot comment

829953b

@OGPoyraz


 Update changelog

b1ec14e

@OGPoyraz


 Rename gas-station-util

11d1a85

Labels

None yet

2 participants

@OGPoyraz @matthewwalsh0

Uh oh!

Comments

Conversation

@OGPoyraz 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!

@matthewwalsh0 matthewwalsh0 Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

@OGPoyraz OGPoyraz Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

@matthewwalsh0 matthewwalsh0 Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

@OGPoyraz OGPoyraz Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

@matthewwalsh0 matthewwalsh0 Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

@matthewwalsh0 matthewwalsh0 Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

@OGPoyraz OGPoyraz Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

@matthewwalsh0 matthewwalsh0 Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

@OGPoyraz OGPoyraz Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

@matthewwalsh0 matthewwalsh0 Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

@OGPoyraz OGPoyraz Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

@matthewwalsh0 matthewwalsh0 Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

@OGPoyraz OGPoyraz Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

@matthewwalsh0 matthewwalsh0 Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

@matthewwalsh0 matthewwalsh0 Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

@OGPoyraz OGPoyraz Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

@matthewwalsh0 matthewwalsh0 Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

@cursor 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 OGPoyraz commented Feb 13, 2026 •

edited by cursor bot

Loading