Description

Second part of Perps connection optimizations building on PR #20918. This PR delivers performance improvements, reliability fixes, and architectural cleanup for the Perps connection system.

Performance (TAT-1576): Faster HyperLiquid Connection

Replaced blocking getAccountState() API calls with lightweight WebSocket health checks:

• Initial connection: Removed blocking HTTP call + stale connection check
• Account switches: Removed redundant API call after provider reinitialization
• New validation: Added provider.ping() WebSocket health check (5s timeout) instead of full API calls

Account data is now efficiently fetched via WebSocket subscriptions during preload, eliminating blocking HTTP requests and retry logic.

Reliability Improvements

Connection timeout protection (TAT-1576):

• Added 30-second timeout for connection attempts with new CONNECTION_TIMEOUT error code
• Prevents indefinite hanging on network issues
• Clear user feedback when connection fails

Background reconnection fix (TAT-1559):

• Added 300ms stabilization delay when app returns from background to prevent race conditions
• Eliminates "Perps is temporarily offline" errors on app wake-up

Architecture: Error Logging & Code Consolidation

• Standardized error logging: Added getErrorContext() helper and comprehensive Sentry logging to 20+ catch blocks with consistent context (feature, context, provider, network)
• Performance metrics refactoring: Changed naming from perps_x_y to perps.x.y for hierarchical grouping and easier filtering in Sentry dashboards
• Removed code duplication: Eliminated Controller.reconnectWithNewContext() - Manager calls initializeProviders() directly
• Fixed retry button: Now uses reconnectWithNewContext({ force: true }) for proper WebSocket disconnect
• Cleaner API: Extracted usePerpsConnection hook to separate file, added ReconnectOptions interface
• Comprehensive docs: Created PERPS_CONNECTION_ARCHITECTURE.md with Mermaid diagrams explaining connection lifecycle and race condition handling

Impact:

• ⚡ Faster: Connection and reconnection complete faster by eliminating blocking HTTP calls
• 🛡️ Reliable: Background reconnection works consistently; timeout protection prevents hanging
• 🐛 Debuggable: Standardized error logging with consistent context helps diagnose production issues in Sentry
• 🧹 Maintainable: Cleaner code with reduced duplication and clearer separation of concerns

Changelog

CHANGELOG entry: null

Related issues

Depends on: #20918
Fixes: TAT-1576, TAT-1559

Manual testing steps

Feature: Perps connection performance and reliability

  Scenario: faster initial connection
    Given Perps has never been connected in this session

    When user opens Perps tab
    Then connection establishes without blocking HTTP calls
    And loading time is noticeably faster than before
    And positions/orders appear without delay

  Scenario: faster account switching
    Given user is connected to Perps with Account A
    And user has positions open

    When user switches to Account B
    Then reconnection completes faster without getAccountState() call
    And Account B's positions load via WebSocket subscriptions
    And no Account A data leaks through

  Scenario: retry button performs full reconnection
    Given Perps fails to connect with error message

    When user taps "Retry Connection" button
    Then connection fully reinitializes including WebSocket disconnect
    And error is logged to Sentry with proper context

  Scenario: rapid account switches are serialized
    Given user is connected to Perps with Account A

    When user switches to Account B
    And immediately switches to Account C before B connection completes
    Then reconnections are serialized (no race conditions)
    And final connection uses Account C's address

  Scenario: app wake-up after inactivity (TAT-1559)
    Given app has been in background for extended period
    And user had Perps connected before backgrounding

    When user returns to app and opens Perps tab
    Then connection establishes after 300ms stabilization delay
    And "Perps is temporarily offline" error does not appear
    And positions/orders load successfully

Screenshots/Recordings

Before

• Initial connection: ~3 blocking operations (stale check + HTTP API call + provider init)
• Account switches: Provider init + HTTP API call with retry logic
• No timeout protection (could hang indefinitely)
• Background reconnection failures on app wake-up

After

• Initial connection: 1 operation (provider init + WebSocket ping health check)
• Account switches: 1 operation (provider init + WebSocket ping health check)
• 30-second connection timeout with user feedback
• Reliable background reconnection with 300ms stabilization delay
• Account data fetched via WebSocket subscriptions during preload

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.

Notes for Reviewers

Key Changes

Performance (TAT-1576):

• PerpsConnectionManager.ts: Removed blocking getAccountState() HTTP calls and retry logic
• Replaced with provider.ping() WebSocket health check (5s timeout)
• Account data now fetched via streamManager.account.prewarm() during preload subscriptions

Reliability:

• Added connection timeout protection: 30-second limit with CONNECTION_TIMEOUT error code
• Background reconnection delay: 300ms stabilization period when app returns from background (fixes TAT-1559)
• All WebSocket operations now have timeout protection

Error Logging:

• New getErrorContext() helper for consistent Sentry context across 20+ catch blocks
• Performance metric names refactored to perps.{category}.{metric} format for better Sentry dashboards
• Example: perps_websocket_connection → perps.websocket.connection_establishment

Architecture:

• NEW: hooks/usePerpsConnection.ts - Extracted hook from provider
• NEW: docs/perps/PERPS_CONNECTION_ARCHITECTURE.md - Architecture guide with Mermaid diagrams
• NEW: types/index.ts - Added ReconnectOptions interface
• REMOVED: Controller.reconnectWithNewContext() - Manager now calls initializeProviders() directly
• UPDATED: Retry button now uses reconnectWithNewContext({ force: true })

Testing Focus Areas

1. Connection speed: Initial Perps tab open should be noticeably faster without blocking HTTP calls
2. Account switching: Rapid switches (3+ accounts) should serialize correctly without data leaks
3. Background reconnection: App wake-up after extended background time should not show "temporarily offline" error
4. Connection timeout: Simulate network issues - should timeout after 30s with clear error message
5. Retry button: Should perform full reconnection with WebSocket disconnect