Skip to content

refactor: drop legacy RPC endpoint failoverUrls - #38801

Merged
cryptodev-2s merged 14 commits into
mainfrom
refactor/drop-legacy-rpc-failover-urls
Nov 11, 2026
Merged

cryptodev-2s merged 14 commits into
mainfrom
refactor/drop-legacy-rpc-failover-urls

Conversation

@cryptodev-2s

@cryptodev-2s cryptodev-2s commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Description

MetaMask/core#11266 removes the per endpoint failoverUrls property from @metamask/network-controller (v38). Failover URLs now come only from the controller's failoverUrls constructor option (chain ID to URLs), and core applies them only to *.infura.io endpoints.

This PR adapts mobile to that:

  • Builds the constructor option from one chain keyed map in customNetworks.tsx, and stops writing failoverUrls on endpoints (popular networks, config registry, swap deeplink, card and bridge hooks).
  • Adds migration 162 to strip failoverUrls from persisted NetworkController state. Migrations 72 and 83 no longer write the field (needed to type check).
  • Network details UI reads failover from the chain map and shows the Failover tag only for Infura hosted endpoints, matching what core does.
  • Adds Robinhood (0x1237) to the map. Its only failover source used to be the endpoint state value.

The v38 bump also changes failover behavior beyond the failoverUrls removal:

  • RPC failover mode now defaults to enabled. Before, a missing or malformed corePlatformRpcFailoverMode flag was read as disabled. Now it is skipped, so the default applies. A valid value (disabled, enabled, forced) is still honored.
  • The Failover tag follows corePlatformRpcFailoverMode (on unless disabled), matching the controller. The retired walletFrameworkRpcFailoverEnabled flag is no longer referenced, and the feature flag registry is updated.

Changelog

CHANGELOG entry: null

Related issues

Refs: MetaMask/core#11266

Manual testing steps

Before testing, set a failover URL for Ethereum Mainnet in .js.env. Without it the chain has no failover configured and the tag never shows:

export QUICKNODE_MAINNET_URL="https://example.quiknode.pro/test"

Then restart Metro with yarn watch:clean (the value is baked into the bundle, so a plain reload is not enough) and reload the app. Any URL works for checking the display.

Feature: RPC failover display

  Scenario: Infura endpoint shows failover
    Given Ethereum Mainnet with its Infura RPC selected and QUICKNODE_MAINNET_URL set

    When user opens the network details
    Then the Failover tag and read only failover URL are shown

  Scenario: custom endpoint does not show failover
    Given the same chain with a custom RPC that is not Infura selected

    When user opens the network details
    Then no Failover tag or failover URL is shown

  Scenario: upgrading from a build of main
    Given a wallet created on a build of main

    When user installs this branch on top and opens the app
    Then the wallet loads, networks still work, and persisted NetworkController state has no `failoverUrls` on any RPC endpoint

Screenshots/Recordings

Screen.Recording.iPhone.18.Pro.10-11-2026.at.15.47.54.mp4

Pre-merge author checklist

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.

Note

Medium Risk
Touches core RPC configuration, a persistence migration, and a major network-controller bump; failover gating and defaults change when remote flags are missing, but scope is largely aligned with upstream core behavior.

Overview
Upgrades @metamask/network-controller to v38 and removes the legacy failoverUrls field on RPC endpoints everywhere the app adds or edits networks (PopularList, bridge/card hooks, swap deeplinks, config registry, network form state).

Failover is now chain-level only: customNetworks.tsx exposes getFailoverUrlsByChainId() (including Robinhood chain 0x1237), passed into NetworkController via wallet init options. The network details UI and RPC list use getFailoverUrlsForEndpoint(chainId, rpcUrl) so the Failover tag and read-only URL appear only for *.infura.io endpoints when failover is enabled—matching core behavior.

Migration 162 strips persisted per-endpoint failoverUrls from networkConfigurationsByChainId. Older migrations and fixtures stop writing the field.

Feature flags: selectIsRpcFailoverEnabled now keys off corePlatformRpcFailoverMode (off only when disabled; absent flag defaults to on), replacing walletFrameworkRpcFailoverEnabled.

Reviewed by Cursor Bugbot for commit 25c1ebe. Bugbot is set up for automated code reviews on this repo. Configure here.

@cryptodev-2s cryptodev-2s self-assigned this Nov 3, 2026
@github-actions

github-actions Bot commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

CLA Signature Action: All authors have signed the CLA. You may need to manually re-run the blocking PR check if it doesn't pass in a few minutes.

@github-actions github-actions Bot added the size-L label Nov 3, 2026
@metamask-ci metamask-ci Bot added the team-core-platform Core Platform team label Nov 3, 2026
@metamask-ci

metamask-ci Bot commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

PR template — items to address before "Ready for review"

Warnings — informational, address before merging:

  • Pre-merge author checklist has only 5 of the required 8 items. Every checklist row must be present and consciously checked — do not delete rows.

See docs/readme/ready-for-review.md for the full Definition of Ready for Review.

@github-actions

github-actions Bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Smart E2E Test Selection

Selected E2E tags: ALL

AI Confidence: 100

E2E reasoning

Expand to read

The hard-rule seed (controller-version-update) selects ALL, and the diffs support keeping it. @metamask/network-controller goes from ^37.1.1 to ^38.0.0, a major bump, in both dependencies and resolutions. The Engine instance options for the network controller were refactored: the per-chain failover URL map is replaced by getFailoverUrlsByChainId() in customNetworks.tsx. That change also removes failoverRpcUrls from every entry in PopularList, which affects the add-popular-network flow. A new state migration (162) is registered in migrations/index.ts, and migrations 072 and 083 are modified, so persisted state is touched at startup. Shared fixtures (default-fixture.json, initial-background-state.json) and the feature-flag registry also change. The network controller underlies transactions, swaps and bridges, dApp permissions, multichain and Solana, Card and Earn, and onboarding. Every smoke tag therefore runs, which includes the dependent tags (Confirmations, Swap, Stake, Perps, Predictions, MultiChainAPI, NetworkExpansion and others).

View run

Naz-Ovh pushed a commit to 0x-fork/metamask-core that referenced this pull request Nov 7, 2026
MetaMask#11266)

## Explanation

`NetworkController` has two places to define RPC failover URLs: the
`failoverUrls` constructor option (keyed by chain ID) and a legacy
`failoverUrls` property on each RPC endpoint in state. The state
property was only a fallback for chains missing from the constructor
option, and both clients now pass that option.

This PR removes the legacy property:

- `failoverUrls` is gone from `InfuraRpcEndpoint` and
`CustomRpcEndpoint`, so `addNetwork` and `updateNetwork` no longer
accept it.
- Network clients use `failoverUrls?.[chainId] ?? []`, so
`configuration.failoverRpcUrls` keeps its shape.

## References

- Extension Work:
MetaMask/metamask-extension#47594
- Mobile Work: MetaMask/metamask-mobile#38801

## 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]
> **High Risk**
> Breaking API and behavior change to RPC failover sourcing in core
network infrastructure; clients relying on per-endpoint persisted
failover URLs will lose failover unless they migrate to the constructor
option.
> 
> **Overview**
> **Breaking change:** `failoverUrls` is removed from
`InfuraRpcEndpoint` and `CustomRpcEndpoint`, so persisted RPC endpoints
and `addNetwork` / `updateNetwork` payloads must no longer include it.
Default and custom network templates in `NetworkController` stop
emitting empty `failoverUrls` arrays on each endpoint.
> 
> RPC failover is now **only** supplied via the `NetworkController`
constructor option `failoverUrls` (keyed by chain ID). When building
network clients, `failoverRpcUrls` is set to `failoverUrls?.[chainId] ??
[]` with no fallback to values that used to live on individual
endpoints—chains without a constructor entry get no failover URLs.
> 
> Tests and fixtures across `network-controller`, `assets-controller`,
`assets-controllers`, `multichain-network-controller`, and
`selected-network-controller` are updated accordingly (provider failover
tests now pass chain-level `failoverUrls`). The changelog documents
client migration (stop writing endpoint `failoverUrls`, optionally strip
them from persisted state).
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
76a9a4b. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
@cryptodev-2s
cryptodev-2s marked this pull request as ready for review November 9, 2026 16:21
@cryptodev-2s
cryptodev-2s requested review from a team as code owners November 9, 2026 16:21

@cursor cursor Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Stale Bugbot comment from a previous run.

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

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 using default effort and found 1 potential issue.

Fix All in Cursor

❌ 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 61e196b. Configure here.

…rpc-failover-urls

# Conflicts:
#	package.json
#	yarn.lock
Comment on lines +39 to +46
/**
* Failover URLs for each chain that has them configured, keyed by chain ID.
* This is the single source of truth for RPC failover: it is passed to
* `NetworkController` as the `failoverUrls` constructor option (which applies
* it to every RPC endpoint of the chain) and read by the network details UI.
*
* @returns Failover URLs keyed by chain ID.
*/

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

nitpick (non-blocking): This JSDoc says the failoverUrls constructor option "applies it to every RPC endpoint of the chain", which is broader than what v38 does. Core only attaches failover when the endpoint hostname ends with .infura.io, as the JSDoc on getFailoverUrlsForEndpoint already says. Tightening this would keep a later change from assuming failover on custom RPCs.

Suggested wording for the parenthetical:

 * `NetworkController` as the `failoverUrls` constructor option (core applies
 * those URLs only to endpoints whose hostname ends with `.infura.io`) and read
 * by the network details UI.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Done as a follow up here #39394

@vinnyhoward vinnyhoward left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

UX owned files look good

@sonarqubecloud

Copy link
Copy Markdown

@javiergarciavera javiergarciavera left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

QA review against the MetaMask mobile-testing skill (unit and test-layer placement). Please consider using that skill during development so layer choice and coverage are checked as the change is written.

The failover helpers, migration 162, and the feature-flag selector are covered at the unit layer, which is the right place for this work. The inline comment is a gap in the new RpcEndpointSection cases.

Comment on lines 221 to 268
).toBeOnTheScreen();
});

it('shows the failover tag for an endpoint with a failover', () => {
const formHook = createRpcModalFormHook({
form: { rpcUrl: 'https://mainnet.infura.io/v3/key', chainId: '0x1' },
showMultiRpcAddModal: false,
rpcModalShowForm: false,
});

const { queryByText } = render(
<RpcEndpointSection
formHook={formHook}
validation={createRpcValidation()}
onValidationSuccess={jest.fn()}
isRpcFailoverEnabled
styles={styles}
themeAppearance="light"
placeholderTextColor={placeholderTextColor}
/>,
);

expect(queryByText(strings('app_settings.failover'))).toBeOnTheScreen();
});

it('hides the failover tag for an endpoint without a failover', () => {
const formHook = createRpcModalFormHook({
form: { rpcUrl: 'https://rpc1.example.com', chainId: '0x1' },
showMultiRpcAddModal: false,
rpcModalShowForm: false,
});

const { queryByText } = render(
<RpcEndpointSection
formHook={formHook}
validation={createRpcValidation()}
onValidationSuccess={jest.fn()}
isRpcFailoverEnabled
styles={styles}
themeAppearance="light"
placeholderTextColor={placeholderTextColor}
/>,
);

expect(queryByText(strings('app_settings.failover'))).not.toBeOnTheScreen();
});

it('renders RPC selector in edit mode', () => {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

These cases check the Failover tag, but the section also renders a read-only failover URL (strings('app_settings.network_failover_rpc_url_label') and failoverRpcUrls[0]). That is the behavior called out in the PR's manual steps: the tag and URL appear for an Infura endpoint, and neither appears for a custom RPC.

Please also assert the URL field in these two tests (for mainnet Infura, the value should be https://mainnet.quicknode.example from the beforeEach env setup). And add a case with isRpcFailoverEnabled={false} on an Infura endpoint that has failover configured, so the tag and URL stay hidden when the flag is off.

@cryptodev-2s cryptodev-2s Nov 10, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

@javiergarciavera to not loose the current approvals, I have done this as a follow up on this stacked PR #39394

@Jwhiles Jwhiles left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

approving for earn

@cryptodev-2s
cryptodev-2s added this pull request to the merge queue Nov 11, 2026
Merged via the queue into main with commit 76eeade Nov 11, 2026
247 of 261 checks passed
@cryptodev-2s
cryptodev-2s deleted the refactor/drop-legacy-rpc-failover-urls branch November 11, 2026 07:57
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 11, 2026
@metamask-ci metamask-ci Bot added the release-8.21.0 Issue or pull request that will be included in release 8.21.0 label Nov 11, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

release-8.21.0 Issue or pull request that will be included in release 8.21.0 size-L team-core-platform Core Platform team

Projects

None yet

Development

Successfully merging this pull request may close these issues.

9 participants