chore(runway): cherry-pick fix(perps): reduce WebSocket subscription overhead and prevent leaks cp-7.63.0 cp-7.64.0 (#25504)

- fix(perps): reduce WebSocket subscription overhead and prevent leaks
cp-7.63.0 cp-7.64.0 (#25496)

## **Description**

This PR addresses WebSocket subscription issues identified during the
rate limiting incident investigation. The fixes reduce subscription
message volume by ~75% and prevent subscription leaks.

### Root Causes Identified

1. **Subscriptions to unregistered DEXs** - System subscribed to ALL 8
DEXs from API instead of only the 2 in our allowlist (main + xyz)
2. **Duplicate DEX subscriptions from race conditions** - Concurrent
calls created 2× subscriptions per DEX
3. **Candle subscription leaks** - Cleanup failed when component
unmounted before async subscription resolved

### Fixes Implemented

#### 1. Filter DEXs by Allowlist on Mainnet (HIGH PRIORITY)
**Files:** `hyperLiquidConfig.ts`, `HyperLiquidProvider.ts`

- Added `MAINNET_HIP3_CONFIG` with `AutoDiscoverAll: false`
- DEX filtering is now dynamic - extracts DEX names from the
`allowlistMarkets` feature flag patterns
- Added `extractDexsFromAllowlist()` method that parses patterns like
`xyz:*`, `xyz:TSLA`, or `xyz`
- **Impact:** Reduces from 8 DEXs to 2 (main + xyz), ~75% reduction in
subscription messages

#### 2. Prevent Duplicate DEX Subscriptions (HIGH PRIORITY)
**File:** `HyperLiquidSubscriptionService.ts`

- Added `pendingClearinghouseSubscriptions` and
`pendingOpenOrdersSubscriptions` Maps
- Refactored `ensureClearinghouseStateSubscription()` and
`ensureOpenOrdersSubscription()` to check for pending promises
- Concurrent calls now wait for the pending promise instead of creating
duplicate subscriptions
- **Impact:** Prevents 50% redundant subscriptions from race conditions

#### 3. Fix Candle Subscription Cleanup (HIGH PRIORITY)
**File:** `HyperLiquidClientService.ts`

- Store subscription promise to enable cleanup even when pending
- Updated cleanup function to wait for pending promise and unsubscribe
- **Impact:** Prevents WebSocket subscription leaks when component
unmounts before subscription resolves

### Test Results

| Metric | Before | After | Improvement |
|--------|--------|-------|-------------|
| DEXs subscribed | 8 | 2 | 75% reduction |
| clearinghouseState subscriptions | 16 | 2 | 87% reduction |
| openOrders subscriptions | 16 | 2 | 87% reduction |
| Candle subscription leaks | Yes | No | Fixed |

## **Changelog**

CHANGELOG entry: null

## **Related issues**

Fixes: Rate limiting incident from WebSocket over-subscription

Related: [WebSocket Subscription Investigation
Report](docs/perps/perps-websocket-subscription-investigation.md)

## **Manual testing steps**

```gherkin
Feature: WebSocket subscription optimization

  Scenario: User connects to perps and only allowlisted DEXs are subscribed
    Given user has the app installed with perps feature enabled
    And WebSocket logging is enabled in dev mode

    When user navigates to Perps home screen
    Then WebSocket logs show subscriptions only for main and xyz DEXs
    And no subscriptions for flx, vntl, hyna, km, abcd, cash DEXs

  Scenario: User navigates between markets without duplicate subscriptions
    Given user is connected to perps
    And WebSocket logging is enabled

    When user navigates from Home to xyz:XYZ100 market details
    And user returns to Home
    And user navigates back to xyz:XYZ100
    Then WebSocket logs show no duplicate clearinghouseState subscriptions
    And WebSocket logs show no duplicate openOrders subscriptions

  Scenario: User views candle chart and subscriptions are properly cleaned up
    Given user is on a market details screen with chart visible

    When user quickly navigates away from the screen
    And user waits for 2 seconds
    Then candle subscriptions are properly unsubscribed
    And no orphaned candle subscriptions exist
```

## **Screenshots/Recordings**

### **Before**

WebSocket subscription breakdown (full trading flow):
- clearinghouseState: 16 subscriptions (8 DEXs × 2 duplicates)
- openOrders: 16 subscriptions (8 DEXs × 2 duplicates)
- candle: 4 subscriptions, 0 unsubscriptions (leak)

### **After**

WebSocket subscription breakdown (full trading flow):
- clearinghouseState: 2 subscriptions (main + xyz only)
- openOrders: 2 subscriptions (main + xyz only)
- candle: 2 subscriptions, 2 unsubscriptions (balanced)

**Total outgoing messages:** 44
**Total incoming messages:** 402 (down from ~750)

## **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.

---

### Subscription Breakdown
- `clearinghouseState`: 2 (main + xyz)
- `openOrders`: 2 (main + xyz)
- `userFills`: 1
- `webData3`: 1
- `allMids`: 1
- `assetCtxs`: 2 (xyz only, subscribed/unsubscribed on navigation)
- `activeAssetCtx`: 2 (xyz:XYZ100, subscribed/unsubscribed on
navigation)
- `candle`: 2 (1h + 15m intervals)
- `bbo`: 2 (subscribed/unsubscribed during order flow)

### Future Optimization Opportunity

Trading operations (order placement, cancellation, modification)
currently use **HTTP transport**:
- `ExchangeClient` is configured with `httpTransport` to avoid 429 rate
limiting
- `InfoClient` uses `wsTransport` for info queries (multiplexed over
single WS connection)

Now that subscription volume is reduced by 75%, we could consider moving
`ExchangeClient` to WebSocket transport (see follow-up investigation).

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Touches core perps WebSocket subscription logic (DEX
discovery/filtering and subscription lifecycle), so mistakes could drop
market/user updates or leave subscriptions running. Changes are targeted
and add guards against race conditions and cleanup failures.
> 
> **Overview**
> Reduces HyperLiquid HIP-3 WebSocket load by **filtering mainnet DEX
discovery** based on the `allowlistMarkets` patterns, falling back to
*main DEX only* when no HIP-3 DEXs are implied. Adds
`MAINNET_HIP3_CONFIG` and an allowlist parser
(`extractDexsFromAllowlist`) to avoid subscribing to non-allowlisted
HIP-3 DEXs.
> 
> Prevents **duplicate per-DEX subscriptions** by deduplicating
concurrent `clearinghouseState` and `openOrders` subscription attempts
via pending-promise tracking, and ensures these pending entries are
cleared during teardown.
> 
> Fixes a **candle subscription leak** by tracking the pending
subscription promise and unsubscribing even if cleanup happens before
the async subscription resolves.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
9fcf758. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude <noreply@anthropic.com>
[7a0c2a1](7a0c2a1)

Co-authored-by: abretonc7s <107169956+abretonc7s@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>

Author: 3 people

app/components/UI/Perps/constants/hyperLiquidConfig.ts

@@ -370,8 +370,6 @@ export const HIP3_ASSET_MARKET_TYPES: Record<
  * On testnet, there are many HIP-3 DEXs (test deployments from various builders).
  * Subscribing to all of them causes connection/subscription overload and instability.
  * This configuration limits which DEXs are discovered and subscribed to on testnet.
- *
- * On mainnet, full DEX discovery continues unchanged.
  */
 export const TESTNET_HIP3_CONFIG = {
   /**
@@ -388,6 +386,25 @@ export const TESTNET_HIP3_CONFIG = {
   AutoDiscoverAll: false,
 } as const;
 
+/**
+ * Mainnet-specific HIP-3 DEX configuration
+ *
+ * On mainnet, DEX filtering is dynamically determined from the allowlist markets
+ * feature flag. This avoids hardcoding DEX names and ensures consistency with
+ * the market filtering logic.
+ *
+ * When AutoDiscoverAll is false and no allowlist is provided, only the main DEX is used.
+ * When an allowlist is provided, DEXs are extracted from the allowlist patterns.
+ */
+export const MAINNET_HIP3_CONFIG = {
+  /**
+   * Set to true to enable full HIP-3 discovery on mainnet
+   * When false, DEXs are filtered based on the allowlist markets feature flag
+   * (recommended for production to reduce subscription overhead)
+   */
+  AutoDiscoverAll: false,
+} as const;
+
 /**
  * HIP-3 margin management configuration
  * Controls margin buffers and auto-rebalance behavior for HIP-3 DEXes with isolated margin

app/components/UI/Perps/controllers/providers/HyperLiquidProvider.ts

@@ -12,6 +12,7 @@ import {
   HIP3_FEE_CONFIG,
   HIP3_MARGIN_CONFIG,
   HYPERLIQUID_WITHDRAWAL_MINUTES,
+  MAINNET_HIP3_CONFIG,
   REFERRAL_CONFIG,
   TESTNET_HIP3_CONFIG,
   TRADING_DEFAULTS,
@@ -1025,9 +1026,53 @@ export class HyperLiquidProvider implements PerpsProvider {
         'HyperLiquidProvider: Testnet - AUTO_DISCOVER_ALL enabled, using all DEXs',
         { totalDexCount: availableHip3Dexs.length + 1 },
       );
+    } else {
+      // Mainnet-specific filtering: Extract allowed DEXs from the allowlist patterns
+      // This reduces WebSocket subscription overhead dynamically based on feature flags
+      const { AutoDiscoverAll } = MAINNET_HIP3_CONFIG;
+
+      if (!AutoDiscoverAll) {
+        // Extract unique DEX names from allowlist patterns
+        // Patterns like "xyz:*", "xyz:TSLA", or "xyz" all indicate DEX "xyz"
+        const allowedDexsFromAllowlist = this.extractDexsFromAllowlist();
+
+        if (allowedDexsFromAllowlist.length === 0) {
+          // No HIP-3 DEXs in allowlist - main DEX only
+          this.deps.debugLogger.log(
+            'HyperLiquidProvider: Mainnet - using main DEX only (no HIP-3 DEXs in allowlist)',
+            {
+              availableHip3Dexs: availableHip3Dexs.length,
+              allowlistMarkets: this.allowlistMarkets,
+            },
+          );
+          this.cachedValidatedDexs = [null];
+          return this.cachedValidatedDexs;
+        }
+
+        // Filter to DEXs that are both available AND in the allowlist
+        const filteredDexs = availableHip3Dexs.filter((dex) =>
+          allowedDexsFromAllowlist.includes(dex),
+        );
+        this.deps.debugLogger.log(
+          'HyperLiquidProvider: Mainnet - filtered to allowlist DEXs',
+          {
+            allowedDexsFromAllowlist,
+            filteredDexs,
+            availableHip3Dexs: availableHip3Dexs.length,
+          },
+        );
+        this.cachedValidatedDexs = [null, ...filteredDexs];
+        return this.cachedValidatedDexs;
+      }
+
+      // AUTO_DISCOVER_ALL is true - proceed with all DEXs
+      this.deps.debugLogger.log(
+        'HyperLiquidProvider: Mainnet - AUTO_DISCOVER_ALL enabled, using all DEXs',
+        { totalDexCount: availableHip3Dexs.length + 1 },
+      );
     }
 
-    // Mainnet (or testnet with AUTO_DISCOVER_ALL): Return all DEXs
+    // Fallback: Return all DEXs (when AUTO_DISCOVER_ALL is true)
     // Market filtering is applied at subscription data layer
     this.deps.debugLogger.log(
       'HyperLiquidProvider: All DEXs enabled (market filtering at data layer)',
@@ -1041,6 +1086,41 @@ export class HyperLiquidProvider implements PerpsProvider {
     return this.cachedValidatedDexs;
   }
 
+  /**
+   * Extract unique DEX names from allowlist market patterns
+   * Patterns can be: "xyz:*" (wildcard), "xyz:TSLA" (exact), or "xyz" (DEX shorthand)
+   *
+   * @returns Array of unique DEX names from the allowlist
+   */
+  private extractDexsFromAllowlist(): string[] {
+    if (this.allowlistMarkets.length === 0) {
+      return [];
+    }
+
+    const dexNames = new Set<string>();
+
+    for (const pattern of this.allowlistMarkets) {
+      // Pattern formats:
+      // - "xyz:*" -> DEX "xyz" (wildcard)
+      // - "xyz:TSLA" -> DEX "xyz" (exact match)
+      // - "xyz" -> DEX "xyz" (shorthand)
+      const colonIndex = pattern.indexOf(':');
+      if (colonIndex > 0) {
+        // Has colon - extract DEX prefix
+        const dex = pattern.substring(0, colonIndex);
+        dexNames.add(dex);
+      } else if (pattern.length > 0 && !pattern.includes('*')) {
+        // No colon and not a wildcard - could be DEX shorthand
+        // Only add if it looks like a valid DEX name (lowercase alphanumeric)
+        if (/^[a-z][a-z0-9]*$/i.test(pattern)) {
+          dexNames.add(pattern.toLowerCase());
+        }
+      }
+    }
+
+    return Array.from(dexNames);
+  }
+
   /**
    * Get cached meta response for a DEX, fetching from API if not cached
    * This helper consolidates cache logic to avoid redundant API calls across the provider

app/components/UI/Perps/services/HyperLiquidClientService.ts

@@ -526,6 +526,9 @@ export class HyperLiquidClientService {
     let currentCandleData: CandleData | null = null;
     let wsUnsubscribe: (() => void) | null = null;
     let isUnsubscribed = false;
+    // Store the subscription promise to enable cleanup even when pending
+    // This fixes a race condition where component unmounts before subscription resolves
+    let subscriptionPromise: Promise<{ unsubscribe: () => void }> | null = null;
 
     // Calculate initial fetch size dynamically based on duration and interval
     // Match main branch behavior: up to 500 candles initially
@@ -548,7 +551,8 @@ export class HyperLiquidClientService {
 
         // 2. Subscribe to WebSocket for new candles
         // HyperLiquid SDK uses 'coin' terminology
-        const subscription = subscriptionClient.candle(
+        // Store the promise so cleanup can wait for it if needed
+        subscriptionPromise = subscriptionClient.candle(
           { coin: symbol, interval }, // Map to HyperLiquid SDK's 'coin' parameter
           (candleEvent) => {
             // Don't process events if already unsubscribed
@@ -598,12 +602,12 @@ export class HyperLiquidClientService {
           },
         );
 
-        // Store cleanup function
-        subscription
+        // Store cleanup function when subscription resolves
+        subscriptionPromise
           .then((sub) => {
             wsUnsubscribe = () => sub.unsubscribe();
             // If already unsubscribed while waiting, clean up immediately
-            if (isUnsubscribed && wsUnsubscribe) {
+            if (isUnsubscribed) {
               wsUnsubscribe();
               wsUnsubscribe = null;
             }
@@ -663,8 +667,19 @@ export class HyperLiquidClientService {
     return () => {
       isUnsubscribed = true;
       if (wsUnsubscribe) {
+        // Subscription already resolved - unsubscribe directly
         wsUnsubscribe();
         wsUnsubscribe = null;
+      } else if (subscriptionPromise) {
+        // Subscription promise still pending - wait for it and clean up
+        // This prevents WebSocket subscription leaks when component unmounts
+        // before the subscription promise resolves
+        subscriptionPromise
+          .then((sub) => sub.unsubscribe())
+          .catch(() => {
+            // Ignore errors during cleanup - subscription may have failed
+          });
+        subscriptionPromise = null;
       }
     };
   }

app/components/UI/Perps/services/HyperLiquidSubscriptionService.ts

@@ -158,6 +158,18 @@ export class HyperLiquidSubscriptionService {
   >(); // Key: dex name ('' for main)
   private readonly openOrdersSubscriptions = new Map<string, ISubscription>(); // Key: dex name ('' for main)
 
+  // Pending subscription promises to prevent race conditions
+  // When multiple calls to ensure*Subscription happen concurrently, this ensures
+  // only one subscription is created per DEX (others wait for the pending promise)
+  private readonly pendingClearinghouseSubscriptions = new Map<
+    string,
+    Promise<void>
+  >();
+  private readonly pendingOpenOrdersSubscriptions = new Map<
+    string,
+    Promise<void>
+  >();
+
   // Meta cache per DEX - populated by metaAndAssetCtxs, used by createAssetCtxsSubscription
   // This avoids redundant meta() API calls since metaAndAssetCtxs already returns meta data
   private readonly dexMetaCache = new Map<
@@ -1258,15 +1270,49 @@ export class HyperLiquidSubscriptionService {
 
   /**
    * Ensure clearinghouseState subscription exists for a DEX
+   * Uses pending promise tracking to prevent race conditions where multiple
+   * concurrent calls could create duplicate subscriptions
    */
   private async ensureClearinghouseStateSubscription(
     userAddress: string,
     dexName: string,
   ): Promise<void> {
+    // Already subscribed
     if (this.clearinghouseStateSubscriptions.has(dexName)) {
-      return; // Already subscribed
+      return;
+    }
+
+    // Another call is already in progress - wait for it instead of creating duplicate
+    const pending = this.pendingClearinghouseSubscriptions.get(dexName);
+    if (pending) {
+      this.deps.debugLogger.log(
+        `[ensureClearinghouseStateSubscription] Waiting for pending subscription for DEX: ${dexName || 'main'}`,
+      );
+      return pending;
     }
 
+    // Create subscription promise and track it
+    const subscriptionPromise = this.createClearinghouseSubscription(
+      userAddress,
+      dexName,
+    );
+    this.pendingClearinghouseSubscriptions.set(dexName, subscriptionPromise);
+
+    try {
+      await subscriptionPromise;
+    } finally {
+      this.pendingClearinghouseSubscriptions.delete(dexName);
+    }
+  }
+
+  /**
+   * Create the actual clearinghouseState subscription
+   * Separated from ensureClearinghouseStateSubscription to enable promise deduplication
+   */
+  private async createClearinghouseSubscription(
+    userAddress: string,
+    dexName: string,
+  ): Promise<void> {
     const subscriptionClient = this.clientService.getSubscriptionClient();
     if (!subscriptionClient) {
       throw new Error('Subscription client not available');
@@ -1351,15 +1397,49 @@ export class HyperLiquidSubscriptionService {
 
   /**
    * Ensure openOrders subscription exists for a DEX
+   * Uses pending promise tracking to prevent race conditions where multiple
+   * concurrent calls could create duplicate subscriptions
    */
   private async ensureOpenOrdersSubscription(
     userAddress: string,
     dexName: string,
   ): Promise<void> {
+    // Already subscribed
     if (this.openOrdersSubscriptions.has(dexName)) {
-      return; // Already subscribed
+      return;
+    }
+
+    // Another call is already in progress - wait for it instead of creating duplicate
+    const pending = this.pendingOpenOrdersSubscriptions.get(dexName);
+    if (pending) {
+      this.deps.debugLogger.log(
+        `[ensureOpenOrdersSubscription] Waiting for pending subscription for DEX: ${dexName || 'main'}`,
+      );
+      return pending;
+    }
+
+    // Create subscription promise and track it
+    const subscriptionPromise = this.createOpenOrdersSubscription(
+      userAddress,
+      dexName,
+    );
+    this.pendingOpenOrdersSubscriptions.set(dexName, subscriptionPromise);
+
+    try {
+      await subscriptionPromise;
+    } finally {
+      this.pendingOpenOrdersSubscriptions.delete(dexName);
     }
+  }
 
+  /**
+   * Create the actual openOrders subscription
+   * Separated from ensureOpenOrdersSubscription to enable promise deduplication
+   */
+  private async createOpenOrdersSubscription(
+    userAddress: string,
+    dexName: string,
+  ): Promise<void> {
     const subscriptionClient = this.clientService.getSubscriptionClient();
     if (!subscriptionClient) {
       throw new Error('Subscription client not available');
@@ -1569,6 +1649,10 @@ export class HyperLiquidSubscriptionService {
         this.openOrdersSubscriptions.clear();
       }
 
+      // Clear pending subscription promises (race condition prevention)
+      this.pendingClearinghouseSubscriptions.clear();
+      this.pendingOpenOrdersSubscriptions.clear();
+
       // Clear subscriber counts
       this.positionSubscriberCount = 0;
       this.orderSubscriberCount = 0;