feat(perps): core resolver — providerCredentials, builder fee injection, env var centralization (MetaMask#27899)

## **Description**

Resolves several core-parity and architecture concerns for the perps
controller:

### 1. Backport core-only changes (existing)
- **`stopEligibilityMonitoring()`** — Disables geo-blocking eligibility
checks when `useExternalServices` is toggled off.
- **Dynamic MYX import** — `await import()` → `.then()/.catch()` to
avoid bundling heavy MYX dependencies in extension.

### 2. Nested `providerCredentials` on `PerpsControllerConfig`
- Restructures flat MYX config fields (`myxAppIdTestnet`,
`myxProviderEnabled`, etc.) into `providerCredentials.myx.*`.
- Adds `providerCredentials.hyperliquid.*` for builder fee wallet
addresses.
- New types: `PerpsProviderCredentials`, `HyperLiquidCredentials`,
`MYXCredentials`.

### 3. Builder fee address injection
- `HyperLiquidProvider` accepts optional
`builderAddressTestnet`/`builderAddressMainnet` via constructor.
- Falls back to hardcoded `BUILDER_FEE_CONFIG` defaults when env vars
are empty.
- New env vars in `.js.env.example`:
`MM_PERPS_HL_BUILDER_ADDRESS_TESTNET`,
`MM_PERPS_HL_BUILDER_ADDRESS_MAINNET`.

### 4. Env var centralization in mobile adapter
- New `createMobileClientConfig()` in `mobileInfrastructure.ts` — all
`process.env.*` reads in one place.
- Engine init (`perps-controller/index.ts`) reduced from ~73 to ~37
lines — pure controller wiring, no env var reads.

### 5. MYX dynamic import race condition fix
- `await import()` inside non-async `#createProviders(): void` →
`.then()/.catch()` chain.
- Removes `@ts-expect-error` suppression. Fixes provider setup race
condition flagged by bugbot.

## **Changelog**

CHANGELOG entry: null

## **Related issues**

Fixes: N/A — architecture cleanup + core parity

## **Manual testing steps**

```gherkin
Feature: Provider credentials and builder fee injection

  Scenario: HyperLiquid uses env-var builder address when set
    Given MM_PERPS_HL_BUILDER_ADDRESS_TESTNET is set in .js.env
    When a trade is placed on testnet
    Then the builder fee uses the env-var address (not hardcoded default)

  Scenario: HyperLiquid falls back to default when env var is empty
    Given MM_PERPS_HL_BUILDER_ADDRESS_TESTNET is empty
    When a trade is placed on testnet
    Then the builder fee uses BUILDER_FEE_CONFIG.TestnetBuilder

  Scenario: MYX provider registers via dynamic import
    Given MYX provider is enabled
    When PerpsController initializes
    Then MYX registers asynchronously via .then()/.catch()
    And initialization completes without waiting for MYX

  Scenario: Engine init uses adapter for config
    Given the app starts
    When PerpsController is initialized
    Then clientConfig comes from createMobileClientConfig()
    And no process.env reads exist in the Engine init file
```

## **Screenshots/Recordings**

N/A — no UI changes

## **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
- [x] 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.

## **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**
> Touches Perps provider initialization/selection and geo-eligibility
monitoring, which can impact trading availability and protocol routing
if misconfigured. Changes are largely additive but include
async/dynamic-import ordering and new config wiring that should be
validated across networks/providers.
> 
> **Overview**
> **Refactors Perps controller configuration to use a nested
`providerCredentials` structure** and centralizes all Perps
`process.env` reads into `createMobileClientConfig()`, simplifying
`perpsControllerInit` to pure wiring.
> 
> **Adds HyperLiquid builder-fee address injection** via new env vars
and passes these through `PerpsController` into `HyperLiquidProvider`,
falling back to hardcoded defaults when env values are empty.
> 
> **Hardens MYX provider registration and eligibility controls** by
switching MYX to a dynamic `import()` flow with explicit error
handling/awaiting during initialization, adding
`stopEligibilityMonitoring()` (and messenger action typing) to defer
geolocation checks, and extending tests to cover these behaviors.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
30f6e0a. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: abretonc7s

.js.env.example

@@ -197,6 +197,9 @@ export MM_PERPS_MYX_BROKER_ADDRESS_TESTNET=""
 export MM_PERPS_MYX_APP_ID_MAINNET=""
 export MM_PERPS_MYX_API_SECRET_MAINNET=""
 export MM_PERPS_MYX_BROKER_ADDRESS_MAINNET=""
+# HyperLiquid builder fee wallet addresses (empty = uses hardcoded defaults)
+export MM_PERPS_HL_BUILDER_ADDRESS_TESTNET=""
+export MM_PERPS_HL_BUILDER_ADDRESS_MAINNET=""
 # HIP-3 Feature Flags (remote override with local fallback)
 export MM_PERPS_HIP3_ENABLED="true"
 export MM_PERPS_HIP3_ALLOWLIST_MARKETS=""  # Allowlist: Empty = enable all markets. Examples: "xyz:XYZ100,xyz:TSLA" or "xyz:*,abc:TSLA"

app/components/UI/Perps/adapters/mobileInfrastructure.test.ts

@@ -3,7 +3,10 @@ import { AnalyticsEventBuilder } from '../../../../util/analytics/AnalyticsEvent
 import { analytics } from '../../../../util/analytics/analytics';
 import Logger from '../../../../util/Logger';
 import type { PerpsAnalyticsEvent } from '@metamask/perps-controller';
-import { createMobileInfrastructure } from './mobileInfrastructure';
+import {
+  createMobileInfrastructure,
+  createMobileClientConfig,
+} from './mobileInfrastructure';
 import Engine from '../../../../core/Engine';
 
 jest.mock('../../../../util/analytics/analytics', () => ({
@@ -212,3 +215,62 @@ describe('createMobileInfrastructure', () => {
     });
   });
 });
+
+describe('createMobileClientConfig', () => {
+  it('returns default config with empty strings and arrays when no env vars are set', () => {
+    // Arrange — ensure relevant env vars are absent
+    const envVars = [
+      'MM_PERPS_BLOCKED_REGIONS',
+      'MM_PERPS_HIP3_ENABLED',
+      'MM_PERPS_HIP3_ALLOWLIST_MARKETS',
+      'MM_PERPS_HIP3_BLOCKLIST_MARKETS',
+      'MM_PERPS_HL_BUILDER_ADDRESS_TESTNET',
+      'MM_PERPS_HL_BUILDER_ADDRESS_MAINNET',
+      'MM_PERPS_MYX_PROVIDER_ENABLED',
+      'MM_PERPS_MYX_APP_ID_TESTNET',
+      'MM_PERPS_MYX_API_SECRET_TESTNET',
+      'MM_PERPS_MYX_BROKER_ADDRESS_TESTNET',
+      'MM_PERPS_MYX_APP_ID_MAINNET',
+      'MM_PERPS_MYX_API_SECRET_MAINNET',
+      'MM_PERPS_MYX_BROKER_ADDRESS_MAINNET',
+    ];
+    const saved: Record<string, string | undefined> = {};
+    for (const key of envVars) {
+      saved[key] = process.env[key];
+      delete process.env[key];
+    }
+
+    // Act
+    const config = createMobileClientConfig();
+
+    // Assert
+    expect(config).toEqual({
+      fallbackBlockedRegions: [],
+      fallbackHip3Enabled: false,
+      fallbackHip3AllowlistMarkets: [],
+      fallbackHip3BlocklistMarkets: [],
+      providerCredentials: {
+        hyperliquid: {
+          builderAddressTestnet: '',
+          builderAddressMainnet: '',
+        },
+        myx: {
+          enabled: false,
+          appIdTestnet: '',
+          apiSecretTestnet: '',
+          brokerAddressTestnet: '',
+          appIdMainnet: '',
+          apiSecretMainnet: '',
+          brokerAddressMainnet: '',
+        },
+      },
+    });
+
+    // Restore
+    for (const key of envVars) {
+      if (saved[key] !== undefined) {
+        process.env[key] = saved[key];
+      }
+    }
+  });
+});

app/components/UI/Perps/adapters/mobileInfrastructure.ts

@@ -21,7 +21,9 @@ import { getStreamManagerInstance } from '../providers/PerpsStreamManager';
 import Engine from '../../../../core/Engine';
 import {
   PERPS_CONSTANTS,
+  parseCommaSeparatedString,
   type PerpsPlatformDependencies,
+  type PerpsControllerConfig,
   type PerpsMetrics,
   type PerpsTraceName,
   type PerpsTraceValue,
@@ -155,6 +157,44 @@ function createCacheInvalidatorAdapter() {
   };
 }
 
+/**
+ * Creates mobile-specific client config from environment variables.
+ * Centralizes all process.env reads so the Engine init file stays pure wiring.
+ */
+export function createMobileClientConfig(): PerpsControllerConfig {
+  return {
+    fallbackBlockedRegions: parseCommaSeparatedString(
+      process.env.MM_PERPS_BLOCKED_REGIONS ?? '',
+    ),
+    fallbackHip3Enabled: process.env.MM_PERPS_HIP3_ENABLED === 'true',
+    fallbackHip3AllowlistMarkets: parseCommaSeparatedString(
+      process.env.MM_PERPS_HIP3_ALLOWLIST_MARKETS ?? '',
+    ),
+    fallbackHip3BlocklistMarkets: parseCommaSeparatedString(
+      process.env.MM_PERPS_HIP3_BLOCKLIST_MARKETS ?? '',
+    ),
+    providerCredentials: {
+      hyperliquid: {
+        builderAddressTestnet:
+          process.env.MM_PERPS_HL_BUILDER_ADDRESS_TESTNET ?? '',
+        builderAddressMainnet:
+          process.env.MM_PERPS_HL_BUILDER_ADDRESS_MAINNET ?? '',
+      },
+      myx: {
+        enabled: process.env.MM_PERPS_MYX_PROVIDER_ENABLED === 'true',
+        appIdTestnet: process.env.MM_PERPS_MYX_APP_ID_TESTNET ?? '',
+        apiSecretTestnet: process.env.MM_PERPS_MYX_API_SECRET_TESTNET ?? '',
+        brokerAddressTestnet:
+          process.env.MM_PERPS_MYX_BROKER_ADDRESS_TESTNET ?? '',
+        appIdMainnet: process.env.MM_PERPS_MYX_APP_ID_MAINNET ?? '',
+        apiSecretMainnet: process.env.MM_PERPS_MYX_API_SECRET_MAINNET ?? '',
+        brokerAddressMainnet:
+          process.env.MM_PERPS_MYX_BROKER_ADDRESS_MAINNET ?? '',
+      },
+    },
+  };
+}
+
 /**
  * Creates mobile-specific platform dependencies for PerpsController.
  * Controller access uses messenger pattern (messenger.call()).

app/controllers/perps/PerpsController-method-action-types.ts

@@ -175,6 +175,11 @@ export type PerpsControllerStartEligibilityMonitoringAction = {
   handler: PerpsController['startEligibilityMonitoring'];
 };
 
+export type PerpsControllerStopEligibilityMonitoringAction = {
+  type: 'PerpsController:stopEligibilityMonitoring';
+  handler: PerpsController['stopEligibilityMonitoring'];
+};
+
 export type PerpsControllerMethodActions =
   | PerpsControllerPlaceOrderAction
   | PerpsControllerEditOrderAction
@@ -210,4 +215,5 @@ export type PerpsControllerMethodActions =
   | PerpsControllerSaveOrderBookGroupingAction
   | PerpsControllerSetSelectedPaymentTokenAction
   | PerpsControllerResetSelectedPaymentTokenAction
-  | PerpsControllerStartEligibilityMonitoringAction;
+  | PerpsControllerStartEligibilityMonitoringAction
+  | PerpsControllerStopEligibilityMonitoringAction;

app/controllers/perps/PerpsController.test.ts

@@ -24,6 +24,8 @@ import {
   PerpsController,
   getDefaultPerpsControllerState,
   InitializationState,
+  firstNonEmpty,
+  resolveMyxAuthConfig,
 } from './PerpsController';
 import type { PerpsControllerState } from './PerpsController';
 import { PERPS_ERROR_CODES } from './perpsErrorCodes';
@@ -387,6 +389,16 @@ class TestablePerpsController extends PerpsController {
   public testHasStandaloneProvider(): boolean {
     return this.hasStandaloneProvider();
   }
+
+  public testRegisterMYXProvider(
+    MYXProvider: new (opts: Record<string, unknown>) => PerpsProvider,
+  ) {
+    this.registerMYXProvider(MYXProvider as never);
+  }
+
+  public testHandleMYXImportError(error: unknown) {
+    this.handleMYXImportError(error);
+  }
 }
 
 describe('PerpsController', () => {
@@ -800,6 +812,35 @@ describe('PerpsController', () => {
         }),
       );
     });
+
+    it('stopEligibilityMonitoring defers subsequent refreshEligibility calls', async () => {
+      // Arrange — controller without deferral
+      const testMockCall = jest.fn().mockImplementation((action: string) => {
+        if (action === 'RemoteFeatureFlagController:getState') {
+          return { remoteFeatureFlags: {} };
+        }
+        if (action === 'GeolocationController:getGeolocation') {
+          return 'US';
+        }
+        return undefined;
+      });
+
+      const testController = new TestablePerpsController({
+        messenger: createMockMessenger({ call: testMockCall }),
+        state: getDefaultPerpsControllerState(),
+        infrastructure: createMockInfrastructure(),
+      });
+      testMockCall.mockClear();
+
+      // Act
+      testController.stopEligibilityMonitoring();
+      await testController.refreshEligibility();
+
+      // Assert — geolocation was never called
+      expect(testMockCall).not.toHaveBeenCalledWith(
+        'GeolocationController:getGeolocation',
+      );
+    });
   });
 
   describe('HIP-3 Configuration Integration', () => {
@@ -4551,6 +4592,17 @@ describe('PerpsController', () => {
       providers.set('myx', mockMYXProvider as any);
       myxController.testSetProviders(providers);
 
+      // Mock init on the reinit call inside switchProvider.
+      // Dynamic import() rejects in Jest (no --experimental-vm-modules),
+      // so MYX can't register via #createProviders. Mock init to
+      // simulate successful reinitialization while preserving our
+      // manually-injected MYX provider in the map.
+      jest.spyOn(myxController, 'init').mockImplementationOnce(async () => {
+        myxController.testUpdate((state) => {
+          state.initializationState = InitializationState.Initialized;
+        });
+      });
+
       const result = await myxController.switchProvider('myx');
 
       expect(result.success).toBe(true);
@@ -4643,6 +4695,59 @@ describe('PerpsController', () => {
       // The init path should detect MYX is not available and fall back
       expect(controller.state.activeProvider).toBe('hyperliquid');
     });
+
+    it('registerMYXProvider creates and registers the MYX provider', () => {
+      // Arrange
+      const mockMYXInstance = createMockHyperLiquidProvider();
+      const MockMYXConstructor = jest.fn(() => mockMYXInstance);
+
+      // Act
+      controller.testRegisterMYXProvider(
+        MockMYXConstructor as unknown as new (
+          opts: Record<string, unknown>,
+        ) => PerpsProvider,
+      );
+
+      // Assert
+      const providers = controller.testGetProviders();
+      expect(providers.get('myx')).toBe(mockMYXInstance);
+      expect(MockMYXConstructor).toHaveBeenCalledWith(
+        expect.objectContaining({ isTestnet: false }),
+      );
+    });
+
+    it('handleMYXImportError logs debug for MODULE_NOT_FOUND errors', () => {
+      // Arrange — Node sets code: 'MODULE_NOT_FOUND' on missing modules
+      const moduleError = Object.assign(
+        new Error('Cannot find module ./providers/MYXProvider'),
+        { code: 'MODULE_NOT_FOUND' },
+      );
+
+      // Act
+      controller.testHandleMYXImportError(moduleError);
+
+      // Assert
+      expect(mockInfrastructure.debugLogger.log).toHaveBeenCalledWith(
+        'PerpsController: MYX provider module not available, skipping registration',
+      );
+    });
+
+    it('handleMYXImportError routes runtime errors to logError', () => {
+      // Act — error without MODULE_NOT_FOUND code goes to Sentry
+      controller.testHandleMYXImportError(new Error('Invalid auth config'));
+
+      // Assert
+      expect(mockInfrastructure.logger.error).toHaveBeenCalledWith(
+        expect.objectContaining({ message: 'Invalid auth config' }),
+        expect.objectContaining({
+          context: expect.objectContaining({
+            data: expect.objectContaining({
+              method: 'createProviders.myx',
+            }),
+          }),
+        }),
+      );
+    });
   });
 
   describe('getOpenOrders with standalone mode', () => {
@@ -5675,3 +5780,93 @@ describe('PerpsController', () => {
     });
   });
 });
+
+describe('firstNonEmpty', () => {
+  it('returns the first non-empty string', () => {
+    expect(firstNonEmpty('', undefined, 'hello', 'world')).toBe('hello');
+  });
+
+  it('returns empty string when all values are empty or undefined', () => {
+    expect(firstNonEmpty('', undefined, '')).toBe('');
+  });
+
+  it('returns the first value if it is non-empty', () => {
+    expect(firstNonEmpty('first', 'second')).toBe('first');
+  });
+
+  it('skips empty strings and returns the fallback', () => {
+    expect(firstNonEmpty('', 'fallback')).toBe('fallback');
+  });
+});
+
+describe('resolveMyxAuthConfig', () => {
+  it('uses testnet credentials on testnet', () => {
+    // Arrange
+    const myx = {
+      appIdTestnet: 'test-app',
+      apiSecretTestnet: 'test-secret',
+      brokerAddressTestnet: '0xTestBroker',
+      appIdMainnet: 'main-app',
+      apiSecretMainnet: 'main-secret',
+      brokerAddressMainnet: '0xMainBroker',
+    };
+
+    // Act
+    const result = resolveMyxAuthConfig(myx, true);
+
+    // Assert
+    expect(result.appId).toBe('test-app');
+    expect(result.apiSecret).toBe('test-secret');
+    expect(result.brokerAddress).toBe('0xTestBroker');
+  });
+
+  it('uses mainnet credentials on mainnet', () => {
+    // Arrange
+    const myx = {
+      appIdTestnet: 'test-app',
+      apiSecretTestnet: 'test-secret',
+      brokerAddressTestnet: '0xTestBroker',
+      appIdMainnet: 'main-app',
+      apiSecretMainnet: 'main-secret',
+      brokerAddressMainnet: '0xMainBroker',
+    };
+
+    // Act
+    const result = resolveMyxAuthConfig(myx, false);
+
+    // Assert
+    expect(result.appId).toBe('main-app');
+    expect(result.apiSecret).toBe('main-secret');
+    expect(result.brokerAddress).toBe('0xMainBroker');
+  });
+
+  it('falls back to testnet credentials when mainnet are empty', () => {
+    // Arrange
+    const myx = {
+      appIdTestnet: 'test-app',
+      apiSecretTestnet: 'test-secret',
+      brokerAddressTestnet: '0xTestBroker',
+      appIdMainnet: '',
+      apiSecretMainnet: '',
+      brokerAddressMainnet: '',
+    };
+
+    // Act
+    const result = resolveMyxAuthConfig(myx, false);
+
+    // Assert
+    expect(result.appId).toBe('test-app');
+    expect(result.apiSecret).toBe('test-secret');
+    expect(result.brokerAddress).toBe('0xTestBroker');
+  });
+
+  it('returns empty strings when no credentials are set', () => {
+    // Act
+    const result = resolveMyxAuthConfig({}, true);
+
+    // Assert
+    expect(result.appId).toBe('');
+    expect(result.apiSecret).toBe('');
+    expect(result.brokerAddress).toBe('');
+  });
+});