feat(transaction-controller): support saved gas fee levels - #8993
Merged
Conversation
pedronfigueiredo
force-pushed
the
pnf/save-custom-gas-settings
branch
2 times, most recently
from
June 3, 2026 16:45
83cc6ba to
ba63c2b
Compare
7 tasks
pedronfigueiredo
marked this pull request as ready for review
June 8, 2026 13:23
pedronfigueiredo
temporarily deployed
to
default-branch
June 8, 2026 13:24 — with 
GitHub Actions
Inactive
GitHub Actions
Inactive
vinistevam
previously approved these changes
Jun 9, 2026
github-merge-queue
Bot
removed this pull request from the merge queue due to failed status checks
Jun 9, 2026
github-merge-queue
Bot
removed this pull request from the merge queue due to failed status checks
Jun 11, 2026
github-merge-queue
Bot
removed this pull request from the merge queue due to failed status checks
Jun 11, 2026
pedronfigueiredo
force-pushed
the
pnf/save-custom-gas-settings
branch
from
June 11, 2026 09:11
ba63c2b to
b620f8f
Compare
Contributor
Author
|
@metamaskbot publish-preview |
Contributor
|
Preview builds have been published. Learn how to use preview builds in other projects. Expand for full list of packages and versions. |
pedronfigueiredo
force-pushed
the
pnf/save-custom-gas-settings
branch
from
June 11, 2026 11:50
b620f8f to
a8ca11c
Compare
Contributor
Author
|
@metamaskbot publish-preview |
Contributor
|
Preview builds have been published. Learn how to use preview builds in other projects. Expand for full list of packages and versions. |
pedronfigueiredo
force-pushed
the
pnf/save-custom-gas-settings
branch
from
June 11, 2026 12:12
a8ca11c to
1a8241c
Compare
Contributor
Author
|
@metamaskbot publish-preview |
Contributor
|
Preview builds have been published. Learn how to use preview builds in other projects. Expand for full list of packages and versions. |
pedronfigueiredo
force-pushed
the
pnf/save-custom-gas-settings
branch
from
June 12, 2026 16:48
1a8241c to
69d8cef
Compare
pedronfigueiredo
added
team-transactions
dan437
previously approved these changes
Jun 15, 2026
pedronfigueiredo
force-pushed
the
pnf/save-custom-gas-settings
branch
from
July 3, 2026 10:49
69d8cef to
2ecedf3
Compare
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
pedronfigueiredo
force-pushed
the
pnf/save-custom-gas-settings
branch
from
July 7, 2026 12:49
7c33a6f to
0d8540e
Compare
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 0d8540e. Configure here.
dan437
previously approved these changes
Jul 9, 2026
…even when a level is set Revert an unrelated edit to the already-released 68.0.0 changelog entry that crept in from a prior rebase, and fix getUserFeeLevel to return CUSTOM whenever savedGasFees includes an explicit maxBaseFee, priorityFee, or gasPrice override, even if a level is also present. Without this, GasFeePoller would treat the transaction as fully level-tracked and silently overwrite the custom override on the next automatic gas fee update. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…eeLevel when actually applied Cursor Bugbot flagged that a saved gas fee level (e.g. 'high') could be reflected in txMeta.userFeeLevel even when the resolved fee wasn't actually derived from that level - specifically when the gas fee flow returns a flat eth_gasPrice-type estimate, or when the flow throws and a raw eth_gasPrice RPC fallback is used. In both cases there are no per-level values to select from, so labelling userFeeLevel with the saved level was misleading. Track whether the suggested fee was actually derived from a per-level lookup and only preserve the saved level in userFeeLevel when it was; otherwise fall back to CUSTOM.
pedronfigueiredo
force-pushed
the
pnf/save-custom-gas-settings
branch
from
July 10, 2026 12:52
ccbd85a to
7435162
Compare
dan437
previously approved these changes
Jul 10, 2026
…eased 68.3.0 section to Unreleased The rebase auto-merge placed our saved-gas-fee-levels changelog entry under the already-released [68.3.0] section instead of [Unreleased], since that's where the surrounding context lines used to live before 68.3.0 was cut. Move it back to [Unreleased].
pedronfigueiredo
enabled auto-merge
July 10, 2026 13:08
dan437
approved these changes
Jul 10, 2026
DDDDDanica
pushed a commit
to MetaMask/metamask-extension
that referenced
this pull request
Jul 14, 2026
## **Description** Re-introduces saved gas fee preferences for confirmations. Users can save low, medium, high, or custom gas settings from the gas edit modal and reuse that preference for future send or dapp transactions on the same account and chain. Dapp-proposed fees still take precedence when present, and MM Pay/Swaps flows are excluded. Related PRs: - MetaMask/core#8993 - MetaMask/metamask-mobile#31649 ## **Changelog** CHANGELOG entry: Added the ability to save gas fee preferences per account and network. ## **Related issues** Fixes: ## **Manual testing steps** 1. Start a send transaction on account 1 and network A. 2. Open the gas edit modal and select low, medium, high, or custom. 3. Save the preference and open another transaction on account 1 and network A. 4. Confirm the saved gas preference is presented by default. 5. Switch to another account or network and confirm the saved preference is not reused. 6. Open a dapp transaction with proposed gas fees and confirm the dapp-proposed fees take precedence. <!-- ## **Screenshots/Recordings** ### **Before** ### **After** --> ## **Pre-merge author checklist** - [x] I've followed [MetaMask Contributor Docs](https://github.com/MetaMask/contributor-docs) and [MetaMask Extension Coding Standards](https://github.com/MetaMask/metamask-extension/blob/main/.github/guidelines/CODING_GUIDELINES.md). - [x] I've completed the PR template to the best of my ability - [x] I’ve included tests if applicable - [x] I’ve documented my code using [JSDoc](https://jsdoc.app/) format if applicable - [ ] I’ve applied the right labels on the PR (see [labeling guidelines](https://github.com/MetaMask/metamask-extension/blob/main/.github/guidelines/LABELING_GUIDELINES.md)). Not required for external contributors. ## **Pre-merge reviewer checklist** - [ ] I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed). - [ ] I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots. <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Medium Risk** > Changes persisted preference shape and transaction default gas behavior; migration clears legacy chain-scoped fees, which can reset saved settings for some users. > > **Overview** > Reintroduces **saved gas fee preferences** scoped by **account and chain**, so confirmations can default to the user’s last low/medium/high/custom choice for that sender on that network. > > **Preferences and persistence:** `advancedGasFee` moves from chain-only to **chain → account →** `AdvancedGasFeePreferences` (including `userFeeLevel`). `setAdvancedGasFee` requires `account`, normalizes addresses, supports per-account clear when `gasFeePreferences` is omitted, and typed prefs replace loose string maps. UI adds `usePersistGasFeePreference` and wires save/select paths in gas modals and estimate hooks; `getAdvancedGasFeeValues` reads the **selected account** on the current chain. > > **Transaction wiring:** `getSavedGasFees` takes full `TransactionMeta`, looks up prefs by `from` + `chainId`, maps to `SavedGasFees`, and returns nothing for **MetaMask Pay** transactions. Bumps `@metamask/transaction-controller` to **^69.0.0** and `@metamask/wallet` to **^7.0.1**. > > **Migration 218:** Converts or drops legacy chain-scoped fee blobs; keeps valid account-scoped data (lowercase keys); clears unmigratable legacy/malformed entries. Fixtures and mock state move to version **218**. > > **Metrics:** Gas metrics add `gas_fee_presented` from default estimates and share `dappSuggested` → `dapp_proposed` normalization for selected vs presented levels. > > LavaMoat policy updates are dependency graph alignment for nested `transaction-controller` copies. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 9310301. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup> <!-- /CURSOR_SUMMARY --> --------- Co-authored-by: MetaMask Bot <metamaskbot@users.noreply.github.com>
pull Bot
pushed a commit
to Reality2byte/metamask-extension
that referenced
this pull request
Jul 14, 2026
## **Description** Re-introduces saved gas fee preferences for confirmations. Users can save low, medium, high, or custom gas settings from the gas edit modal and reuse that preference for future send or dapp transactions on the same account and chain. Dapp-proposed fees still take precedence when present, and MM Pay/Swaps flows are excluded. Related PRs: - MetaMask/core#8993 - MetaMask/metamask-mobile#31649 ## **Changelog** CHANGELOG entry: Added the ability to save gas fee preferences per account and network. ## **Related issues** Fixes: ## **Manual testing steps** 1. Start a send transaction on account 1 and network A. 2. Open the gas edit modal and select low, medium, high, or custom. 3. Save the preference and open another transaction on account 1 and network A. 4. Confirm the saved gas preference is presented by default. 5. Switch to another account or network and confirm the saved preference is not reused. 6. Open a dapp transaction with proposed gas fees and confirm the dapp-proposed fees take precedence. <!-- ## **Screenshots/Recordings** ### **Before** ### **After** --> ## **Pre-merge author checklist** - [x] I've followed [MetaMask Contributor Docs](https://github.com/MetaMask/contributor-docs) and [MetaMask Extension Coding Standards](https://github.com/MetaMask/metamask-extension/blob/main/.github/guidelines/CODING_GUIDELINES.md). - [x] I've completed the PR template to the best of my ability - [x] I’ve included tests if applicable - [x] I’ve documented my code using [JSDoc](https://jsdoc.app/) format if applicable - [ ] I’ve applied the right labels on the PR (see [labeling guidelines](https://github.com/MetaMask/metamask-extension/blob/main/.github/guidelines/LABELING_GUIDELINES.md)). Not required for external contributors. ## **Pre-merge reviewer checklist** - [ ] I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed). - [ ] I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots. <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Medium Risk** > Changes persisted preference shape and transaction default gas behavior; migration clears legacy chain-scoped fees, which can reset saved settings for some users. > > **Overview** > Reintroduces **saved gas fee preferences** scoped by **account and chain**, so confirmations can default to the user’s last low/medium/high/custom choice for that sender on that network. > > **Preferences and persistence:** `advancedGasFee` moves from chain-only to **chain → account →** `AdvancedGasFeePreferences` (including `userFeeLevel`). `setAdvancedGasFee` requires `account`, normalizes addresses, supports per-account clear when `gasFeePreferences` is omitted, and typed prefs replace loose string maps. UI adds `usePersistGasFeePreference` and wires save/select paths in gas modals and estimate hooks; `getAdvancedGasFeeValues` reads the **selected account** on the current chain. > > **Transaction wiring:** `getSavedGasFees` takes full `TransactionMeta`, looks up prefs by `from` + `chainId`, maps to `SavedGasFees`, and returns nothing for **MetaMask Pay** transactions. Bumps `@metamask/transaction-controller` to **^69.0.0** and `@metamask/wallet` to **^7.0.1**. > > **Migration 218:** Converts or drops legacy chain-scoped fee blobs; keeps valid account-scoped data (lowercase keys); clears unmigratable legacy/malformed entries. Fixtures and mock state move to version **218**. > > **Metrics:** Gas metrics add `gas_fee_presented` from default estimates and share `dappSuggested` → `dapp_proposed` normalization for selected vs presented levels. > > LavaMoat policy updates are dependency graph alignment for nested `transaction-controller` copies. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 9310301. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup> <!-- /CURSOR_SUMMARY --> --------- Co-authored-by: MetaMask Bot <metamaskbot@users.noreply.github.com>
pull Bot
pushed a commit
to Reality2byte/metamask-mobile
that referenced
this pull request
Jul 14, 2026
## Summary - Persist custom gas fee settings from the advanced gas modals. - Read saved gas preferences when building fee options for send confirmations. - Wire mobile PreferencesController and TransactionController integration for saved gas fee preferences. ## Related PRs - MetaMask/metamask-extension#43317 - MetaMask/core#8993 ## Testing - `yarn jest app/components/Views/confirmations/components/modals/advanced-eip1559-modal/advanced-eip1559-modal.test.tsx app/components/Views/confirmations/components/modals/advanced-gas-price-modal/advanced-gas-price-modal.test.tsx app/components/Views/confirmations/hooks/gas/useGasFeeEstimateLevelOptions.test.ts app/components/Views/confirmations/hooks/gas/useGasPriceEstimateOption.test.ts app/components/Views/confirmations/hooks/gas/usePersistGasFeePreference.test.ts app/core/Engine/controllers/preferences-controller-init.test.ts app/core/Engine/controllers/transaction-controller/metrics_properties/gas.test.ts app/core/Engine/controllers/transaction-controller/transaction-controller-init.test.ts` (8 suites, 78 tests). <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Medium Risk** > Changes how default and custom gas fees are stored and applied for sends; incorrect lookup or validation could affect fee defaults, though saves are gated on complete custom values and covered by new tests. > > **Overview** > Adds **per-account, per-chain persistence** for gas choices so confirmations can reuse the user’s last fee level or custom values. > > On save, confirmation gas flows call **`usePersistGasFeePreference`**, which writes to **`PreferencesController.setAdvancedGasFee`** (`advancedGasFee` is persisted state). Advanced EIP-1559 and legacy gas price modals share **`useAdvancedGasFeeModal`**, which blocks save when custom fees are incomplete and persists mapped preferences (e.g. max base / priority fee). Preset estimate levels and gas-price estimate options persist the selected **`userFeeLevel`** as well. > > **`TransactionController`** is upgraded to **69.0.0** and receives a **`getSavedGasFees`** hook that reads those preferences for the transaction’s `from` address and chain. Gas metrics now report **`dapp_proposed`** when **`UserFeeLevel.DAPP_SUGGESTED`** is selected. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 3041ea6. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup> <!-- /CURSOR_SUMMARY -->
This was referenced Jul 30, 2026
pull Bot
pushed a commit
to dmrazzy/core
that referenced
this pull request
Aug 4, 2026
…sted estimates (MetaMask#9704) ## Explanation Underpriced gas fees — a `maxFeePerGas` below (or barely above) the current base fee — produce transactions that are very unlikely to be included before fee conditions change further. They typically end up stuck as pending until eventually marked as failed (e.g. `Transaction not found on network after timeout`), with no actionable feedback to the user. Telemetry shows this is a meaningful contributor to dropped/timed-out transactions. Two fee sources can produce such values, and nothing in the client validates either against current network conditions. This PR adds a feature-flag-gated staleness gate for both, at transaction creation time — the last point where fees can still be changed before signing. ### 1. Dapp-suggested fees (`replaceUnderpricedDappGasFees` flag) Currently: - `updateGasFees` uses `initialParams.maxFeePerGas` as-is. - Gas estimation deliberately strips fee fields before calling the RPC node, so the node's own fee-cap validation never runs. - `GasFeePoller` only refreshes fees for preset levels, so `dappSuggested` fees stay frozen while the confirmation is open. A dapp that computes fees from stale data can therefore produce a signed transaction that cannot mine. With the flag enabled: - A new `shouldIgnoreDappGasFees` check fires when the dapp-suggested `maxFeePerGas` (or a legacy `gasPrice` used as `maxFeePerGas` on EIP-1559 networks) is below the current **low** estimate. The low estimate is the floor rather than the raw base fee, since fees between the base fee and the low estimate have near-zero effective priority fee and no headroom for base fee movement, so they share the same failure mode. - When it fires, the transaction falls through to the existing suggested (medium) fee logic for both `maxFeePerGas` and `maxPriorityFeePerGas`. - `userFeeLevel` is set to `medium` instead of `dappSuggested`, which also opts the transaction into `GasFeePoller` refresh while unapproved. - The original values remain available via `dappSuggestedGasFees` on the transaction metadata, so UIs can still display the site suggestion and users can revert via the edit modal. Note: for transactions with complete dapp-suggested fees, `getSuggestedGasFees` previously skipped fetching estimates entirely. When the flag is enabled, estimates are now fetched for these transactions so the comparison can run — one additional gas fee estimate call per dapp transaction on enabled chains. ### 2. Saved (advanced) gas fee preferences (`replaceUnderpricedSavedGasFees` flag) A saved *custom* preference is a static `maxBaseFee` captured at some point in the past; once the base fee rises past it, every transaction priced from it strands. Nothing else guards this source: the dapp gate deliberately excludes `savedGasFees`, and `hasInitialGasFeeParams` only protects transactions carrying explicit fee params — saved fees apply precisely when they don't. This is increasingly relevant as clients expand saved-preference usage (per-account custom gas settings persisted from the confirmation flow, and MetaMask#9682 extending saved fees to wallet-initiated transfers). With the flag enabled: - After suggested fees are fetched, if the saved preference has a custom `maxBaseFee` below the current low estimate, the saved preference is ignored for this transaction and the suggested (medium) values are used instead. - **Level-based saved preferences (`low`/`medium`/`high`) are never touched** — they track current estimates by construction. - `userFeeLevel` becomes `medium` instead of `custom`, with the same `GasFeePoller` refresh benefit. - No fetch-path changes needed: transactions eligible for saved fees carry no fee params, so estimates are already fetched. ### Guards / fail-open behavior (both gates) Fees are kept unchanged when: the respective feature flag is not enabled for the chain (both default to disabled; per-chain rollout via `perChainConfig` with `default` fallback, mirroring `timeoutAttempts`); the transaction is internal (dapp gate; swaps/bridges are priced by the aggregator/relay); the fee is at or above the low estimate; or estimates are unavailable / not fee-market type. ### The product decision (saved-fees gate) Overriding a value the *user* saved is a stronger intervention than overriding a dapp's computed value. Three defensible behaviors when the saved-fees gate fires: (1) silently use suggested fees (this PR's behavior), (2) use suggested fees + surface an alert ("your saved gas setting is below current network fees"), (3) keep the saved value + warn only. The flag ships disabled, so this can be settled before enablement. An argument for intervening (1 or 2) rather than deferring entirely to the saved value: **saved preferences already do not grant full autonomy.** The controller already ignores them for swaps and bridges (`SAVED_GAS_FEES_IGNORED_TRANSACTION_TYPES`, MetaMask#9401/MetaMask#9682) — explicitly because a saved fee could underprice aggregator-priced transactions — and already yields them to explicit fee params (`hasInitialGasFeeParams`, MetaMask#8993). The established principle is that saved preferences apply *where they can work* and yield *where they would predictably break the transaction*. A custom `maxBaseFee` below the current low estimate is the clearest instance of the latter — this extends existing precedent rather than setting new one. ## References - Prior art for saved-fee exclusions: MetaMask#9401, MetaMask#9682, MetaMask#8993 - Known edge case (fee bump vs. dapp max-spend arithmetic) and proposed balance-clamp refinement: see PR comment below — it applies to both gates. ## 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) - [ ] 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 pre-sign gas selection for dapp and saved-fee paths when flags are enabled; behavior is gated and fail-open, but wrong thresholds or rollout could surprise users or sites. > > **Overview** > Adds **opt-in, per-chain** gates in `updateGasFees` so transactions are less likely to be priced below current network conditions before approval. > > When **`replaceUnderpricedDappGasFees`** is enabled, dapp-suggested EIP-1559 fees whose effective `maxFeePerGas` (including legacy `gasPrice` used as max fee) is **below the wallet’s low estimate** are replaced with **suggested medium** `maxFeePerGas` / `maxPriorityFeePerGas`. **`userFeeLevel`** becomes **`medium`** instead of **`dappSuggested`**, so fees can keep updating while unapproved; originals stay on **`dappSuggestedGasFees`**. Complete dapp fee params no longer skip estimate fetch when this flag is on (needed for the comparison; fail-open if estimates are missing). > > When **`replaceUnderpricedSavedGasFees`** is enabled, saved **custom** `maxBaseFee` below the low estimate is **dropped** for that tx so medium suggestions apply; **level-based** saved prefs are unchanged. **`userFeeLevel`** becomes **`medium`** instead of **`custom`**. > > New remote feature-flag helpers and types mirror existing per-chain `default` / `perChainConfig` patterns; both flags default to **disabled**. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 95e622d. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup> <!-- /CURSOR_SUMMARY -->
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Explanation
This expands transaction-controller saved gas fee handling so clients can resolve saved preferences with full transaction metadata instead of only a chain ID. That lets consumers key saved gas settings by both chain and account while keeping the controller API responsible for applying saved fees.
The saved gas payload now supports gas fee estimate levels (
low,medium,high) and legacy customgasPricevalues in addition to EIP-1559 custom fee values. Saved estimate levels reuse the current gas fee flow estimate for the saved level; custom values override only the specific saved fields.Transactions that already include gas fee params continue to use those initial params, so dapp-proposed fees keep precedence over saved preferences. Swap transaction types continue to skip saved gas fees.
References
Related PRs:
Checklist
Note
Medium Risk
Breaking callback signature and changed gas-fee precedence logic can misprice dApp txs or break extension/mobile until consumers update; changes are confined to gas fee application paths with substantial test coverage.
Overview
Breaking change:
getSavedGasFeesnow receives fullTransactionMetainstead of chain ID so clients can key saved preferences by chain and account. TheSavedGasFeesshape adds optional estimatelevel, legacygasPrice, and makes EIP-1559 fields optional.Gas fee application in
updateGasFeesnow skips saved lookup when the tx already has initial gas params (dapp fees win), still skips internal txs, and can pick low/medium/high from the current gas fee flow when only a level is saved. CustommaxBaseFee/priorityFee/gasPriceoverride specific fields;userFeeLevelstays on the saved level only when pricing is truly level-derived (otherwisecustom).Deprecated incoming transaction constructor options and restored no-op
startIncomingTransactionPolling/stopIncomingTransactionPollingfor backward compatibility, with tests.Reviewed by Cursor Bugbot for commit a173b00. Bugbot is set up for automated code reviews on this repo. Configure here.