Description

This PR delivers two related pieces of work for the Predict crypto up/down details screen:

1. A reusable usePredictOrderbook hook that streams live Polymarket orderbook depth into the existing LivelineChart so the chart shows real bid/ask activity overlaid on the price line. The hook is plumbed through the existing controller / provider / WebSocket stack — no new APIs needed at the engine layer.

   The data flow:

   flowchart LR
     Hook["usePredictOrderbook(tokenId)"] --> Controller["PredictController.subscribeToOrderbook"]
     Controller --> Provider["PolymarketProvider.subscribeToOrderbook"]
     Provider --> WSManager["WebSocketManager.subscribeToOrderbook"]
     Provider --> REST["getOrderBook (utils.ts)"]
     REST -->|"seed first snapshot"| WSManager
     WS["Polymarket market WS"] --> WSManager
     Hook --> Chart["LivelineChart orderbook prop"]
   

   Loading

   The WebSocket manager handles per-token reference counting, a 250 ms emit throttle to protect the RN↔WebView bridge, book event ingestion, and opportunistic top-of-book pruning on price_change events. The REST bootstrap runs at the provider layer (where the active CLOB protocol is known) and seeds the cache before the first WS event arrives.

2. Chart UX/UI polish to match the Figma reference for BTC Up or Down:

   • Removed the oversized green/red price pill (badge) — only the orange dot remains.
   • Removed the 36 px dead space above the chart (padding.top: 48 → 12).
   • Made the chart line extend closer to the y-axis labels (padding.right: 80 → 64).
   • Pushed time-axis labels above the WebView's bottom clip zone so they actually render (padding.bottom: 48 → 80).
   • Dropped trailing .00 from the y-axis price labels per design (whole-dollar formatter).
   • Added a compact 12-hour h:mm:ss formatTime so the time-axis labels fit the live 30s window without overlap-culling.
   • Extracted CRYPTO_UP_DOWN_FORMAT_VALUE and CRYPTO_UP_DOWN_FORMAT_TIME as named exports so the WebView-bridged formatter bodies can be regression-tested with it.each.

The PR also includes a self-review pass that fixed:

• Stale orderbook state surviving WebSocket reconnects (cleared orderbookState + throttle timers in disconnectMarket).
• Dead error field on the orderbook hook's public type.
• Empty-string tokenId slipping past the subscribe guard.
• Misleading comment vs. implementation for applyTopOfBook (it prunes, doesn't splice).
• Vague "with correct props" test name renamed per the repo's unit-testing guidelines.
• Dead createMockChartRef helper + 19 unused chartRef locals + 2 orphaned appendPoint assertions in useCryptoUpDownChartData.test.ts (the hook signature dropped its chartRef arg upstream).
• Magic-number documentation for chart padding and chart-height bounds.

Deferred to follow-ups (intentional)

• patch-package on liveline for: (a) orderbook depth fade threshold (currently fades only in the top 45% — design wants midpoint), (b) time-axis edge-fade reduction, (c) palette opacity bumps. All require modifying node_modules/liveline/dist/index.js and rebundling via yarn build:liveline-webview; tracked separately because they coordinate with chart-team work.
• Imperative setOrderbook on LivelineChartRef to skip a full SET_PROPS round-trip on every depth tick (perf optimization that needs upstream liveline cooperation).
• i18n keys for Price to beat / Current price / Target (no predict.crypto_up_down namespace exists yet — broader Predict-feature concern).

Changelog

CHANGELOG entry: Added live orderbook depth visualization and refined the chart layout for Crypto Up/Down markets.

Related issues

Refs:

Manual testing steps

Feature: Crypto Up/Down details screen — live chart with orderbook depth

  Scenario: user opens a live Crypto Up/Down market and sees the redesigned chart
    Given the user has the Predict feature flag enabled
    And the user has navigated to a live "BTC Up or Down" market

    When the details screen finishes loading

    Then the chart line renders with the orange dot at the current price
    And no green or red price pill appears next to the dot
    And the y-axis price labels render to the right of the chart without trailing ".00"
    And there is no large empty band between the "Price to beat" header and the chart line
    And time labels in "h:mm:ss" format render along the bottom of the chart, above the action buttons
    And the dashed "Target" reference line renders at the target price

  Scenario: user observes live orderbook depth on the chart
    Given the user is on a live Crypto Up/Down market with active liquidity

    When the user watches the chart for a few seconds

    Then small green ($) labels for bids and red ($) labels for asks animate upward from the bottom-left of the chart
    And the labels update within ~250 ms of new orderbook events
    And on reconnect (e.g. toggle airplane mode briefly) the orderbook re-bootstraps without showing stale prices

  Scenario: user navigates away and the chart cleans up
    Given the chart is rendering with active orderbook depth

    When the user taps the back button

    Then the chart unmounts and the orderbook subscription is released
    And no further WebSocket traffic for that token is observed in the network log

Screenshots/Recordings

Before

After

Uploading upDown.mov…

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
  • usePredictOrderbook.test.ts (new) — subscribe/unsubscribe lifecycle, snapshot mapping, mount/unmount safety, connection polling.
  • WebSocketManager.test.ts — extended with positive coverage for book events, REST seed, reference counting, reconnect, throttle, opportunistic TOB prune.
  • PolymarketProvider.test.ts — subscribeToOrderbook REST bootstrap success/failure.
  • PredictController.test.ts — passthrough + MESSENGER_EXPOSED_METHODS registration.
  • PredictCryptoUpDownChart.test.tsx — orderbook wiring, prop forwarding, CRYPTO_UP_DOWN_FORMAT_VALUE and CRYPTO_UP_DOWN_FORMAT_TIME it.each regression suites.
• I've documented my code using JSDoc format if applicable
  • JSDoc on usePredictOrderbook, CRYPTO_UP_DOWN_FORMAT_VALUE, CRYPTO_UP_DOWN_FORMAT_TIME, CHART_HEIGHT_VIEWPORT_FRACTION, and the new WebSocketManager orderbook methods.
• I've applied the right labels on the PR (see labeling guidelines). Not required for external contributors.
  • Apply at PR creation time: team-predict (or the appropriate Predict team label), area-predict. Add needs-qa if the on-device cadence of orderbook depth needs review.

Performance checks (if applicable)

• I've tested on Android
  • Pending — primary development was iOS; should be smoke-tested on an Android mid-range device because the WebView bridge cadence differs.
• I've tested with a power user scenario
  • Not applicable to the orderbook layer specifically; the chart is sized for a single market view.
• I've instrumented key operations with Sentry traces for production performance metrics
  • Not added in this PR. The WebSocketManager already logs orderbook lifecycle events via DevLogger. If Sentry traces are desired on subscribeToOrderbook REST + WS handshake timing, can add in a follow-up.

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.

Appendix — quality gate

Appendix — files touched (high level)

• New: app/components/UI/Predict/hooks/usePredictOrderbook.ts (+ test)
• Modified: WebSocketManager.ts (orderbook subscription map, throttle, lifecycle), PolymarketProvider.ts (passthrough + REST seed), PredictController.ts (passthrough + MESSENGER_EXPOSED_METHODS), types/index.ts (OrderbookLevel/Snapshot/Callback), providers/types.ts (optional method in interface).
• Chart UX: PredictCryptoUpDownChart.tsx (+ test), PredictCryptoUpDownDetails.tsx, useCryptoUpDownChartData.ts (+ test).