fix: migrate Sei explorer from Seitrace to Seiscan (#29221)

## **Description**

Seitrace (`https://seitrace.com`), the current Sei Mainnet block
explorer, is being decommissioned. This PR swaps every hardcoded
reference to `seiscan.io` and adds migration **134** to rewrite existing
users' persisted `NetworkController` state on upgrade.

Hardcoded URL swaps:

- `app/util/networks/customNetworks.tsx` — Sei Mainnet
`blockExplorerUrl`
- `tests/resources/networks.e2e.js` — e2e resource
- `tests/api-mocking/mock-responses/tx-sentinel-networks-map.ts` — mock
`explorer`

Migration 134 rewrites

`engine.backgroundState.NetworkController.networkConfigurationsByChainId['0x531'].blockExplorerUrls`
from `seitrace.com` to `seiscan.io` for existing installs. It only
touches entries still pointing at `seitrace.com` — a user who customized
their Sei block explorer (e.g. to `seistream.app`) is left alone. The
migration follows mobile's current pattern (sync arrow function with
in-place `state` mutation), and is registered in
`app/store/migrations/index.ts`. Cross-repo reference for this family
of block-explorer-URL migrations is

[`metamask-extension/app/scripts/migrations/197.ts`](https://github.com/MetaMask/metamask-extension/blob/main/app/scripts/migrations/197.ts).

The `@metamask/controller-utils` bump is deliberately deferred until
the sibling PR in `MetaMask/core` releases; this PR stands alone.

## **Changelog**

CHANGELOG entry: Fixed Sei Mainnet: replaced deprecated Seitrace
explorer with Seiscan (`https://seiscan.io`). Existing installs are
migrated via migration 134.

## **Related issues**

Fixes:

Companion PRs:
- [`MetaMask/core#8545`](MetaMask/core#8545) —
default `BlockExplorerUrl[SeiMainnet]`
-
[`MetaMask/metafi-sdk#525`](MetaMask/metafi-sdk#525)
— shared SDK `SEI_EXPLORER`
-
[`MetaMask/metamask-extension#42064`](MetaMask/metamask-extension#42064)
— extension migration 207

## **Manual testing steps**

```gherkin
Feature: Sei Mainnet block explorer URL

  Scenario: fresh install uses Seiscan
    Given a fresh install of MetaMask Mobile
    When the user adds the Sei Mainnet network
    Then the network's block-explorer URL is "https://seiscan.io/"
    And tapping a Sei transaction's "View on block explorer" opens "https://seiscan.io/tx/<hash>"

  Scenario: existing user with Seitrace URL is migrated
    Given a build prior to this change with Sei Mainnet added
    And the stored "blockExplorerUrls" is ["https://seitrace.com"]
    When the user upgrades to this build
    Then migration 134 runs
    And the stored "blockExplorerUrls" for Sei Mainnet is ["https://seiscan.io"]

  Scenario: user-customized URL is preserved
    Given a build prior to this change with Sei Mainnet added
    And the user has customized "blockExplorerUrls" to ["https://seistream.app"]
    When the user upgrades to this build
    Then migration 134 is a no-op for this entry
    And the stored "blockExplorerUrls" for Sei Mainnet remains ["https://seistream.app"]
```

## **Screenshots/Recordings**

<!-- If applicable, add screenshots and/or recordings to visualize the
before and after of your change. -->

### **Before**

<!-- [screenshots/recordings] -->

### **After**

<!-- [screenshots/recordings] -->

## **Pre-merge author checklist**

- [x] I've followed [MetaMask Contributor
Docs](https://github.com/MetaMask/contributor-docs) and [MetaMask Mobile
Coding
Standards](https://github.com/MetaMask/metamask-mobile/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-mobile/blob/main/.github/guidelines/LABELING_GUIDELINES.md)).
Not required for external contributors.

#### Performance checks (if applicable)

- [ ] I've tested on Android
- [ ] I've tested with a power user scenario
- [ ] I've instrumented key operations with Sentry traces for production
performance metrics

## **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**
> Adds a new persisted-state migration that mutates `NetworkController`
network configs for Sei Mainnet; while narrowly scoped, migrations run
on upgrade and can affect existing user state if bugs slip through.
> 
> **Overview**
> Updates Sei Mainnet’s default block explorer from **Seitrace** to
**Seiscan** across the in-app popular network config and test fixtures.
> 
> Adds migration `134` (registered in `app/store/migrations/index.ts`)
to rewrite persisted Sei Mainnet `blockExplorerUrls` entries whose URL
hostname is exactly `seitrace.com` to `seiscan.io`, while leaving
missing/invalid controller state and user-customized/lookalike URLs
untouched; includes unit tests covering the rewrite and no-op cases.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
68e91bc. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: jeremytsng

app/store/migrations/134.test.ts

@@ -0,0 +1,168 @@
+import { captureException } from '@sentry/react-native';
+import migrate, { migrationVersion } from './134';
+import { ensureValidState } from './util';
+
+jest.mock('@sentry/react-native', () => ({
+  captureException: jest.fn(),
+}));
+
+jest.mock('./util', () => ({
+  ensureValidState: jest.fn(),
+}));
+
+const mockedEnsureValidState = jest.mocked(ensureValidState);
+const mockedCaptureException = jest.mocked(captureException);
+
+const SEI_MAINNET_CHAIN_ID = '0x531';
+
+interface SeiNetworkConfiguration {
+  blockExplorerUrls: string[];
+  chainId: string;
+  defaultBlockExplorerUrlIndex?: number;
+  defaultRpcEndpointIndex: number;
+  name: string;
+  nativeCurrency: string;
+  rpcEndpoints: {
+    networkClientId: string;
+    url: string;
+    type: string;
+    failoverUrls?: string[];
+  }[];
+}
+
+interface TestState {
+  engine: {
+    backgroundState: {
+      NetworkController?: {
+        networkConfigurationsByChainId?: Record<
+          string,
+          SeiNetworkConfiguration
+        >;
+        selectedNetworkClientId?: string;
+        [key: string]: unknown;
+      };
+      [key: string]: unknown;
+    };
+  };
+  [key: string]: unknown;
+}
+
+function buildSeiConfig(blockExplorerUrls: string[]): SeiNetworkConfiguration {
+  return {
+    blockExplorerUrls,
+    chainId: SEI_MAINNET_CHAIN_ID,
+    defaultBlockExplorerUrlIndex: 0,
+    defaultRpcEndpointIndex: 0,
+    name: 'Sei',
+    nativeCurrency: 'SEI',
+    rpcEndpoints: [
+      {
+        networkClientId: 'sei-mainnet',
+        url: 'https://sei-mainnet.infura.io/v3/fake',
+        type: 'custom',
+      },
+    ],
+  };
+}
+
+function buildState(seiConfig?: SeiNetworkConfiguration): TestState {
+  return {
+    engine: {
+      backgroundState: {
+        NetworkController: {
+          networkConfigurationsByChainId: seiConfig
+            ? { [SEI_MAINNET_CHAIN_ID]: seiConfig }
+            : {},
+          selectedNetworkClientId: 'mainnet',
+        },
+      },
+    },
+  };
+}
+
+describe(`Migration ${migrationVersion}: Replace Seitrace with Seiscan for Sei Mainnet`, () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockedEnsureValidState.mockReturnValue(true);
+  });
+
+  it('reports the expected migration version', () => {
+    expect(migrationVersion).toBe(134);
+  });
+
+  it('rewrites Seitrace block explorer URL to Seiscan for Sei Mainnet', () => {
+    const state = buildState(buildSeiConfig(['https://seitrace.com']));
+
+    const result = migrate(state) as TestState;
+
+    const seiConfig =
+      result.engine.backgroundState.NetworkController
+        ?.networkConfigurationsByChainId?.[SEI_MAINNET_CHAIN_ID];
+    expect(seiConfig?.blockExplorerUrls).toStrictEqual(['https://seiscan.io/']);
+    expect(mockedCaptureException).not.toHaveBeenCalled();
+  });
+
+  it('leaves state unchanged when Sei Mainnet is not configured', () => {
+    const state: TestState = {
+      engine: {
+        backgroundState: {
+          NetworkController: {
+            networkConfigurationsByChainId: {
+              '0x1': buildSeiConfig(['https://etherscan.io']),
+            },
+            selectedNetworkClientId: 'mainnet',
+          },
+        },
+      },
+    };
+    const snapshotBefore = JSON.stringify(state);
+
+    const result = migrate(state);
+
+    expect(JSON.stringify(result)).toBe(snapshotBefore);
+    expect(mockedCaptureException).not.toHaveBeenCalled();
+  });
+
+  it('silently skips when NetworkController is missing (upgrade-from-old-version)', () => {
+    const state = {
+      engine: {
+        backgroundState: {
+          SomeOtherController: { foo: 'bar' },
+        },
+      },
+    };
+    const snapshotBefore = JSON.stringify(state);
+
+    const result = migrate(state);
+
+    expect(JSON.stringify(result)).toBe(snapshotBefore);
+    expect(mockedCaptureException).not.toHaveBeenCalled();
+  });
+
+  it('does not touch user-customized block explorer URLs', () => {
+    const state = buildState(buildSeiConfig(['https://seistream.app']));
+
+    const result = migrate(state) as TestState;
+
+    const seiConfig =
+      result.engine.backgroundState.NetworkController
+        ?.networkConfigurationsByChainId?.[SEI_MAINNET_CHAIN_ID];
+    expect(seiConfig?.blockExplorerUrls).toStrictEqual([
+      'https://seistream.app',
+    ]);
+    expect(mockedCaptureException).not.toHaveBeenCalled();
+  });
+
+  it('does not rewrite a URL whose host only starts with seitrace.com', () => {
+    const lookalike = 'https://seitrace.com.attacker.example/path';
+    const state = buildState(buildSeiConfig([lookalike]));
+
+    const result = migrate(state) as TestState;
+
+    const seiConfig =
+      result.engine.backgroundState.NetworkController
+        ?.networkConfigurationsByChainId?.[SEI_MAINNET_CHAIN_ID];
+    expect(seiConfig?.blockExplorerUrls).toStrictEqual([lookalike]);
+    expect(mockedCaptureException).not.toHaveBeenCalled();
+  });
+});

app/store/migrations/134.ts

@@ -0,0 +1,176 @@
+import { captureException } from '@sentry/react-native';
+import {
+  getErrorMessage,
+  hasProperty,
+  Hex,
+  isHexString,
+  isObject,
+} from '@metamask/utils';
+
+import { ensureValidState } from './util';
+
+/**
+ * Migration 134: replace the deprecated Seitrace block explorer URL
+ * (`seitrace.com`, being decommissioned) with its replacement Seiscan
+ * (`seiscan.io`) for Sei Mainnet on existing user installs.
+ *
+ * Users without Sei Mainnet configured: no-op (silent).
+ * Users who customized the explorer URL away from Seitrace: no-op
+ * (only entries that still point at `seitrace.com` are rewritten).
+ * Users missing `NetworkController` entirely: no-op (silent) — expected
+ * during upgrade-from-old-version.
+ */
+export const migrationVersion = 134;
+
+const SEI_MAINNET_CHAIN_ID: Hex = '0x531'; // 1329
+const OLD_HOSTNAME = 'seitrace.com';
+const NEW_HOSTNAME = 'seiscan.io';
+
+interface RpcEndpoint {
+  failoverUrls?: string[];
+  name?: string;
+  networkClientId: string;
+  url: string;
+  type: string;
+}
+
+interface NetworkConfiguration {
+  blockExplorerUrls: string[];
+  chainId: Hex;
+  defaultBlockExplorerUrlIndex?: number;
+  defaultRpcEndpointIndex: number;
+  name: string;
+  nativeCurrency: string;
+  rpcEndpoints: RpcEndpoint[];
+}
+
+const migration = (state: unknown): unknown => {
+  if (!ensureValidState(state, migrationVersion)) {
+    return state;
+  }
+
+  try {
+    const networkControllerState = validateNetworkController(state);
+    if (networkControllerState === undefined) {
+      return state;
+    }
+
+    const { networkConfigurationsByChainId } = networkControllerState;
+    if (!hasProperty(networkConfigurationsByChainId, SEI_MAINNET_CHAIN_ID)) {
+      return state;
+    }
+
+    const seiConfig = networkConfigurationsByChainId[SEI_MAINNET_CHAIN_ID];
+    if (!isValidNetworkConfiguration(seiConfig)) {
+      return state;
+    }
+
+    const rewritten = seiConfig.blockExplorerUrls.map((url) => {
+      try {
+        const parsed = new URL(url);
+        if (parsed.hostname === OLD_HOSTNAME) {
+          parsed.hostname = NEW_HOSTNAME;
+          return parsed.toString();
+        }
+      } catch {
+        // not a valid URL, leave as-is
+      }
+      return url;
+    });
+    const didChange = rewritten.some(
+      (url, index) => url !== seiConfig.blockExplorerUrls[index],
+    );
+
+    if (didChange) {
+      seiConfig.blockExplorerUrls = rewritten;
+    }
+  } catch (error) {
+    captureException(
+      new Error(
+        `Migration ${migrationVersion}: Failed to rewrite Sei Mainnet block explorer URL: ${getErrorMessage(
+          error,
+        )}`,
+      ),
+    );
+  }
+
+  return state;
+};
+
+export default migration;
+
+// Sentry logging is intentionally omitted — expected-missing states
+// (NetworkController absent, Sei not configured) are not errors.
+function validateNetworkController(state: {
+  engine: { backgroundState: Record<string, unknown> };
+}):
+  | {
+      networkConfigurationsByChainId: Record<Hex, unknown>;
+      selectedNetworkClientId: string;
+    }
+  | undefined {
+  if (!hasProperty(state.engine.backgroundState, 'NetworkController')) {
+    // Expected during upgrade-from-old-version — don't log.
+    return undefined;
+  }
+
+  const networkControllerState = state.engine.backgroundState.NetworkController;
+
+  if (!isValidNetworkControllerState(networkControllerState)) {
+    return undefined;
+  }
+
+  return networkControllerState;
+}
+
+function isValidNetworkControllerState(value: unknown): value is {
+  networkConfigurationsByChainId: Record<Hex, unknown>;
+  selectedNetworkClientId: string;
+} {
+  if (!isObject(value)) {
+    return false;
+  }
+
+  if (
+    !hasProperty(value, 'networkConfigurationsByChainId') ||
+    !isValidNetworkConfigurationsByChainId(value.networkConfigurationsByChainId)
+  ) {
+    return false;
+  }
+
+  if (
+    !hasProperty(value, 'selectedNetworkClientId') ||
+    typeof value.selectedNetworkClientId !== 'string'
+  ) {
+    return false;
+  }
+
+  return true;
+}
+
+function isValidNetworkConfigurationsByChainId(
+  value: unknown,
+): value is Record<Hex, unknown> {
+  return (
+    isObject(value) &&
+    Object.entries(value).every(
+      ([chainId]) => typeof chainId === 'string' && isHexString(chainId),
+    )
+  );
+}
+
+// Minimal validator — only chainId + blockExplorerUrls need to be sound
+// for this migration.
+function isValidNetworkConfiguration(
+  object: unknown,
+): object is NetworkConfiguration {
+  return (
+    isObject(object) &&
+    hasProperty(object, 'chainId') &&
+    typeof object.chainId === 'string' &&
+    isHexString(object.chainId) &&
+    hasProperty(object, 'blockExplorerUrls') &&
+    Array.isArray(object.blockExplorerUrls) &&
+    object.blockExplorerUrls.every((url) => typeof url === 'string')
+  );
+}

app/store/migrations/index.ts

@@ -134,6 +134,7 @@ import migration130 from './130';
 import migration131 from './131';
 import migration132 from './132';
 import migration133 from './133';
+import migration134 from './134';
 
 // Add migrations above this line
 import { ControllerStorage } from '../persistConfig';
@@ -287,6 +288,7 @@ export const migrationList: MigrationsList = {
   131: migration131,
   132: migration132,
   133: migration133,
+  134: migration134,
 };
 
 // Enable both synchronous and asynchronous migrations

app/util/networks/customNetworks.tsx

@@ -159,7 +159,7 @@ export const PopularList = [
     ticker: 'SEI',
     warning: true,
     rpcPrefs: {
-      blockExplorerUrl: 'https://seitrace.com/',
+      blockExplorerUrl: 'https://seiscan.io/',
       imageUrl: 'SEI',
       imageSource: require('../../images/sei.png'),
     },

tests/api-mocking/mock-responses/tx-sentinel-networks-map.ts

@@ -64,7 +64,7 @@ export const TX_SENTINEL_NETWORKS_MAP = {
       decimals: 18,
     },
     network: 'sei-mainnet',
-    explorer: 'https://seitrace.com',
+    explorer: 'https://seiscan.io',
     confirmations: true,
     smartTransactions: false,
     relayTransactions: false,

tests/resources/networks.e2e.js

@@ -192,7 +192,7 @@ const CustomNetworks = {
       rpcUrl: 'https://sei-mainnet.infura.io',
       nickname: 'Sei Testnet',
       ticker: 'SEI',
-      BlockExplorerUrl: 'https://seitrace.com/',
+      BlockExplorerUrl: 'https://seiscan.io/',
     },
   },
 };