Description

This PR optimizes the token details page by implementing a lightweight way to display open perps positions without requiring full PerpsController initialization, and adds one-click Long/Short trading buttons that navigate directly to the order confirmation flow.

Problem: Previously, checking if a user had an open position on a token required initializing the entire PerpsController with WebSocket subscriptions, causing slow page loads. Additionally, cached position data could become stale when users closed positions in the perps environment. There was also no way to initiate a perps trade directly from the token details page.

Solution: Added a readOnly mode pattern that allows querying perps data (positions, account state, markets) via lightweight HTTP API calls without WebSocket, wallet, or full controller initialization. Combined with a PerpsCacheInvalidator service that ensures cached data is refreshed when positions change. Added Long/Short buttons on token details that navigate through a new PerpsOrderRedirect screen to handle WebSocket initialization and order creation seamlessly.

Key Changes

New Hook:

• usePerpsPositionForAsset - Fetches position data via single HTTP API call with 30-second client-side cache, subscribes to cache invalidation events

ReadOnly Mode (Controller/Provider):

• getPositions({ readOnly: true, userAddress }) - Query positions without full init
• getAccountState({ readOnly: true, userAddress }) - Query account state without full init
• Uses createStandaloneInfoClient for lightweight HTTP-only queries

Cache Invalidation Service:

• PerpsCacheInvalidator - Singleton service for loosely-coupled cache invalidation
• Hooks subscribe to invalidation events (positions, accountState)
• Services (TradingService, AccountService) call invalidate() after successful operations
• Ensures position display is always accurate even after user actions in perps

One-Click Trade from Token Details:

• New PerpsOrderRedirect screen - a redirect/loader that initializes the WebSocket connection inside the Perps stack, calls depositWithOrder(), then navigates to the confirmation screen
• usePerpsActions hook - provides handlePerpsAction(direction) callback for Long/Short buttons, navigates to PerpsOrderRedirect with direction and asset params
• AssetOverviewContent integrates Long/Short buttons via usePerpsActions when a perps market exists for the token

Dynamic Button Layout:

• Token details action buttons (Buy, Sell, Swap, Bridge, etc.) now include Long/Short when a perps market exists
• Buttons dynamically overflow into a "More" menu when there are too many actions

Documentation:

• Added "ReadOnly Mode (Lightweight Queries)" section to docs/perps/perps-architecture.md
• Added "Cache Invalidation" subsection documenting the pattern

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    PerpsCacheInvalidator                        │
│  (Singleton service)                                            │
├─────────────────────────────────────────────────────────────────┤
│  - invalidate('positions')    → notifies position subscribers   │
│  - invalidate('accountState') → notifies account subscribers    │
│  - subscribe(type, callback)  → returns unsubscribe function    │
└─────────────────────────────────────────────────────────────────┘
          ▲                                    ▲
          │ subscribe                          │ invalidate
          │                                    │
┌─────────┴─────────┐              ┌──────────┴──────────┐
│ usePerpsPosition  │              │   TradingService    │
│   ForAsset        │              │  (closePosition,    │
│                   │              │   placeOrder)       │
│ (30s cache +      │              │                     │
│  invalidation)    │              │   AccountService    │
└───────────────────┘              │  (withdraw)         │
                                   └─────────────────────┘

Order Redirect Flow (Long/Short buttons):
┌────────────────┐    navigate     ┌──────────────────┐   WS ready    ┌─────────────────┐
│  Token Details │ ──────────────→ │PerpsOrderRedirect│ ────────────→ │  Confirmation   │
│  (Long/Short)  │                 │  (Perps stack)   │  depositWith  │    Screen       │
│                │                 │  - init WebSocket │  Order()      │                 │
└────────────────┘                 │  - show loader    │               └─────────────────┘
                                   └──────────────────┘
                                          │ on error
                                          ▼
                                   goBack() + toast

Changelog

CHANGELOG entry: Added lightweight position display and one-click Long/Short trading on token details page for perps-enabled assets

Related issues

Fixes: TAT-2427

Manual testing steps

Feature: Perps position display on token details

  Scenario: User views token with open perps position
    Given user has an open perps position for ETH
    And user is on the wallet home screen

    When user navigates to ETH token details page
    Then user should see their open position displayed
    And the page should load quickly without full perps initialization

  Scenario: User taps on position to view details
    Given user is viewing token details with an open position displayed

    When user taps on the position card
    Then user should be navigated to the perps market detail page
    And the full perps environment should load

  Scenario: User with no perps position
    Given user does not have any perps positions

    When user navigates to any token details page
    Then no perps position card should be displayed
    And no perps API calls should be made (if user is not eligible)

  Scenario: Position display updates after closing position
    Given user has an open perps position for ETH
    And user is viewing the ETH token details page
    And user sees their open position displayed

    When user navigates to perps and closes their ETH position
    And user navigates back to the ETH token details page
    Then the position card should no longer be displayed
    And the cache should have been invalidated automatically

  Scenario: User taps Long button on token with perps market
    Given user is viewing ETH token details
    And ETH has a perps market available

    When user taps the "Long" button
    Then a loader screen should appear ("Preparing order...")
    And the WebSocket connection should initialize
    And depositWithOrder should be called
    And user should be navigated to the order confirmation screen

  Scenario: User taps Short button on token with perps market
    Given user is viewing ETH token details
    And ETH has a perps market available

    When user taps the "Short" button
    Then a loader screen should appear ("Preparing order...")
    And the WebSocket connection should initialize
    And depositWithOrder should be called
    And user should be navigated to the order confirmation screen

  Scenario: Long/Short buttons not shown for token without perps market
    Given user is viewing a token details page for a token without a perps market (e.g. USDC)

    Then no Long or Short buttons should be displayed in the action bar

  Scenario: Order redirect handles error gracefully
    Given user taps Long or Short on a perps-enabled token
    And the depositWithOrder call fails

    Then user should see an error toast notification
    And user should be navigated back to the token details page

Screenshots/Recordings

Before

After

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.