fix(perps): add spotMeta caching to reduce API calls on HIP-3 markets

[abretonc7s]

Description

fix(perps): add spotMeta caching to reduce API calls on HIP-3 markets

This PR adds session-based caching for HyperLiquid's global spotMeta endpoint to avoid redundant API calls during HIP-3 operations.

Context

Following the rate limiting incident where excessive API calls triggered HyperLiquid's rate limits (2000 msg/min), this is a defensive improvement to reduce unnecessary network requests.

Problem

The spotMeta API (which returns token metadata like USDC/USDH indices) was being called multiple times per trading session:

• getUsdcTokenId() - called during transfers
• isUsdhCollateralDex() - called to check collateral type
• swapUsdcToUsdh() - called during HIP-3 USDH swaps

Each call was making a fresh API request, even though the data (token indices) doesn't change during a session.

Solution

• Added cachedSpotMeta property for session-based caching (no TTL - token indices are stable)
• Added getCachedSpotMeta() method that returns cached data or fetches once
• Pre-fetch spotMeta in ensureReadyForTrading() when HIP-3 is enabled (non-blocking)
• Cache invalidated on disconnect() to ensure fresh state on reconnect/account switch

Design Decisions

• Global cache (not per-DEX): spotMeta is a global endpoint returning all tokens
• Session-based (no TTL): Token indices don't change during a session
• Graceful fallback: If pre-fetch fails, methods fetch on-demand
• Follows existing patterns: getCachedMeta(), getCachedPerpDexs()

Changelog

CHANGELOG entry: Fixed excessive API calls on HIP-3 markets by caching spot metadata

Related issues

Fixes: add spotMeta caching to reduce API calls on HIP-3 markets

Manual testing steps

Feature: SpotMeta caching for HIP-3 operations

  Scenario: User places order on HIP-3 DEX (SILVER)
    Given user has connected wallet with USDC balance
    And user is on a HIP-3 enabled DEX (e.g., SILVER)

    When user places an order
    Then order should succeed
    And spotMeta API should only be called once per session (check debug logs)

  Scenario: User disconnects and reconnects
    Given user has placed orders (spotMeta is cached)

    When user disconnects wallet
    And user reconnects wallet
    Then spotMeta cache should be cleared
    And next HIP-3 operation should fetch fresh spotMeta

Screenshots/Recordings

N/A - Internal optimization, no UI changes

Before

Multiple spotMeta API calls per session (one per HIP-3 operation)

After

Single spotMeta API call per session, cached for subsequent operations

Pre-merge author checklist

• I've followed MetaMask Contributor Docs and MetaMask Mobile Coding Standards.
• I've completed the PR template to the best of my ability
• I've included tests if applicable
• I've documented my code using JSDoc format if applicable
• I've applied the right labels on the PR (see labeling guidelines). 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.

---

Note

Medium Risk
Touches perps trading setup and HIP-3 order/transfer paths by introducing session caching and prefetching of spotMeta; bugs here could affect order placement after reconnect or when token metadata is unexpectedly stale.

Overview
Reduces HyperLiquid API traffic during HIP-3 trading by introducing a session cache for spotMeta (via getCachedSpotMeta()), prefetching it in ensureReadyForTrading(), and reusing it in getUsdcTokenId(), isUsdhCollateralDex(), and swapUsdcToUsdh(); the cache is cleared on disconnect().

Improves error reporting by updating ensureError() to convert null/undefined into a consistent descriptive Error, and updates provider tests/mocks to match the SpotMetaResponse shape (token index and universe).

^{Written by Cursor Bugbot for commit a7d00a0. This will update automatically on new commits. Configure here.}

[github-actions]

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]

🔍 Smart E2E Test Selection

• Selected E2E tags: SmokePerps
• Selected Performance tags: @PerformancePreps
• Risk Level: medium
• AI Confidence: 90%

click to see 🤖 AI reasoning details

E2E Test Selection:
The changes are focused on the Perps (perpetuals trading) functionality:

1. HyperLiquidProvider.ts - Core trading provider changes:

   • Added session-based caching for spotMeta (spot metadata for USDC/USDH token info)
   • Pre-fetches spotMeta in ensureReadyForTrading() for HIP-3 operations
   • Replaces direct API calls with cached data in multiple methods
   • This is a defensive improvement to prevent rate limiting during heavy trading

2. HyperLiquidProvider.test.ts - Test updates to match new caching behavior with updated mock data

3. hyperliquid-types.ts - Added SpotMetaResponse type export

4. errorUtils.ts - Improved error handling for undefined/null errors (provides better Sentry context)

5. Documentation - Two postmortem documents explaining the incident and fixes

The changes are isolated to the Perps module. The errorUtils.ts change is backward-compatible and only affects error message formatting. The SmokePerps tag is the appropriate test suite as it covers:

• Add Funds flow to deposit USDC into Perps trading account
• Balance verification after deposits
• Perps interface functionality

No other test tags are needed as the changes don't affect other wallet features like accounts, confirmations, swaps, network management, etc.

Performance Test Selection:
The changes to HyperLiquidProvider.ts introduce caching for spotMeta which could impact the performance of Perps trading operations. The caching is designed to reduce API calls and improve performance during order placement, especially for HIP-3 assets. Running the @PerformancePreps tests will validate that the caching improvements don't negatively impact perps market loading, position management, add funds flow, and order execution times.

View GitHub Actions results

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

[cursor]

Test names use prohibited "should" prefix

Low Severity

The modified test names at lines 26 and 33 use 'should convert null to Error with descriptive message' and 'should convert undefined to Error with descriptive message', which violates the unit testing guideline: "NEVER use 'should' in test names - this is a hard rule with zero exceptions." The test names were actively modified in this PR and had an opportunity to be fixed.

Additional Locations (1)

• app/util/errorUtils.test.ts#L32-L33