feat: move perps streaming ownership to background (Phase 2 POC) by abretonc7s · Pull Request #40600 · MetaMask/metamask-extension

abretonc7s · 2026-03-04T13:01:33Z

Description

This PR implements Path 2 from the streaming architecture discussion: move WebSocket ownership from the UI to the background process, eliminating the dual-controller problem flagged in #40078.

The Problem (from #40078 review)

The current architecture creates two PerpsController instances — one in the background and one in the UI — resulting in:

Two independent WebSocket connections to HyperLiquid
Split controller authority / two state machines
Risk of race conditions and data inconsistency

Path 2: Custom JSON-RPC Notification Channel

Background subscribes to HyperLiquid WebSocket via PerpsController, then emits perpsStreamUpdate notifications over the existing outStream connection. The UI handles them alongside sendUpdate in ui/index.js.

Background PerpsController (WebSocket owner)
  → subscribeToPositions/Orders/Account/Prices/OrderBook/Candles
  → emitPerpsUpdate(channel, data) → outStream.write({ method: 'perpsStreamUpdate' })
    ↓ (only when perpsSubscriberCount > 0)
UI ui/index.js onNotification
  → getPerpsStreamManager().handleBackgroundUpdate({ channel, data })
    ↓
PerpsDataChannel.pushData() → React subscribers (direct, no Redux, no debounce)

What Changed

Area	Change
`metamask-controller.js`	Subscribe background controller to all 6 channels on connection setup; emit `perpsStreamUpdate` notifications; track per-connection subscriber count via `perpsSubscriberChange`
`ui/index.js`	Route `perpsStreamUpdate` → `PerpsStreamManager.handleBackgroundUpdate()`
`getPerpsController.ts`	Remove UI `PerpsController` instantiation entirely — no `new PerpsController()`, no messenger, no streaming controller
`createPerpsControllerFacade.ts`	Remove all streaming methods; all operations delegate to background
`PerpsStreamManager.ts`	Add `prices`/`orderBook` channels; `handleBackgroundUpdate()` for all 6 channels; initial REST `connectFn` for positions/orders/account; eager cache clear on account switch
`CandleStreamChannel.ts`	Add `pushFromBackground()`
`usePerpsLivePrices` / `usePerpsLiveOrderBook`	Migrate from direct controller subscribe → `usePerpsChannel` pattern
`usePerpsStreamManager`	Clear caches synchronously on account switch to prevent stale-data flash

Key Properties

No Redux overhead for high-frequency data (prices, orderBook, candles)
No debounce — data reaches React components directly via PerpsDataChannel.pushData()
Component-scoped: only UI connections with perpsSubscriberCount > 0 receive stream data
Single WebSocket: one connection per HyperLiquid endpoint, owned by background
Cache preserved across navigation; cleared on account switch

Tests

193 tests passing across 12 suites. All perps provider and hook tests updated to match new architecture.

Changelog

CHANGELOG entry: null

Overview
Perps streaming is moved to the background process. A new per-connection PerpsStreamBridge subscribes the background PerpsController to positions/orders/account and dynamically switches prices/orderBook/candles streams, emitting perpsStreamUpdate notifications only when the UI reports active subscribers.

The UI now routes perpsStreamUpdate in ui/index.js into PerpsStreamManager.handleBackgroundUpdate(). PerpsStreamManager, CandleStreamChannel, and stream hooks/pages are refactored to stop using a UI-side streaming controller; they instead (1) fetch initial snapshots via background RPC (perpsGetPositions, perpsGetAccountState, etc.), (2) request background streaming via perpsActivateStreaming, and (3) consume pushed updates from the manager.

Perps routing/provider wiring is adjusted to lazy-load a new PerpsLayout that wraps all Perps routes with PerpsControllerProvider, removing PerpsRouteWrapper. Misc cleanup includes removing mock-based Perps exports/usages in UI components/tests and updating affected tests/baselines.

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

Implements Path 2 streaming architecture: background PerpsController owns WebSocket connections and emits perpsStreamUpdate notifications to the UI. The UI PerpsController instance is removed entirely, eliminating dual WebSocket connections and split controller authority. Changes: - metamask-controller.js: subscribe background PerpsController to all 6 channels (positions, orders, account, prices, orderBook, candles); emit perpsStreamUpdate notifications per-connection; track subscriber count via perpsSubscriberChange to gate emission - ui/index.js: route perpsStreamUpdate notifications to PerpsStreamManager - PerpsStreamManager: add prices/orderBook channels; add handleBackgroundUpdate() for all 6 channels; add initial REST fetch connectFn for positions/orders/account; clear caches on account switch - getPerpsController: remove UI PerpsController instantiation; simplify to facade-only; add markPerpsControllerInitialized/isInitialized helpers - createPerpsControllerFacade: remove streaming methods; all operations delegate to background via submitRequestToBackground - usePerpsLivePrices/usePerpsLiveOrderBook: migrate from direct controller subscribe to usePerpsChannel pattern - CandleStreamChannel: add pushFromBackground() method - usePerpsStreamManager: clear caches eagerly on account switch to prevent stale data flash - All related tests updated (193 passing)

github-actions · 2026-03-04T13:01:45Z

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.

metamaskbotv2 · 2026-03-04T13:04:13Z

✨ Files requiring CODEOWNER review ✨

👨‍🔧 @MetaMask/perps (26 files, +1169 -1958)

📁 app/
- 📁 scripts/
  - 📁 controllers/
    - 📁 perps/
      - 📄 perps-stream-bridge.ts +120 -0
📁 ui/
- 📁 components/
  - 📁 app/
    - 📁 perps/
      - 📁 order-entry/
        
        📁 components/
        
        📁 amount-input/
        
        📄 amount-input.tsx +1 -2
        
        📄 index.ts +0 -12
      - 📁 perps-recent-activity/
        
        📄 perps-recent-activity.test.tsx +112 -99
        
        📄 perps-recent-activity.tsx +3 -3
        
        📄 perps-tab-view.tsx +1 -1
- 📁 hooks/
  - 📁 perps/
    - 📁 stream/
      - 📄 usePerpsLiveOrderBook.ts +18 -39
      - 📄 usePerpsLivePrices.ts +31 -54
      - 📄 usePerpsStreamManager.ts +17 -17
      - 📄 usePerpsTopOfBook.ts +49 -52
      - 📄 usePerpsOrderForm.ts +1 -1
- 📁 pages/
  - 📁 perps/
    - 📄 perps-layout.tsx +18 -0
    - 📄 perps-market-detail-page.tsx +22 -35
    - 📄 perps-order-entry-page.tsx +47 -64
- 📁 providers/
  - 📁 perps/
    - 📄 CandleStreamChannel.test.ts +191 -251
    - 📄 CandleStreamChannel.ts +63 -53
    - 📄 createPerpsControllerFacade.test.ts +29 -65
    - 📄 createPerpsControllerFacade.ts +16 -42
    - 📄 getPerpsController.test.ts +48 -172
    - 📄 getPerpsController.ts +49 -278
    - 📄 PerpsControllerProvider.test.tsx +3 -8
    - 📄 PerpsControllerProvider.tsx +11 -23
    - 📄 PerpsRouteWrapper.test.tsx +0 -273
    - 📄 PerpsRouteWrapper.tsx +0 -134
    - 📄 PerpsStreamManager.test.ts +168 -195
    - 📄 PerpsStreamManager.ts +151 -85

abretonc7s · 2026-03-04T13:04:14Z

I have read the CLA Document and I hereby sign the CLA

metamaskbotv2 · 2026-03-04T13:35:50Z

Builds ready [fedc086]

builds: chrome, firefox
builds (beta): chrome, firefox
builds (flask): chrome, firefox
builds (test): chrome, firefox
builds (test-flask): chrome, firefox
bundle size: Bundle Size Stats
interaction-benchmark: Interaction Stats
storybook: Storybook
typescript migration: Dashboard
all artifacts
bundle viz:
- background: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19
- common: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19
- ui: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20
- content-script: 0
- offscreen: 0

⚡ Performance Benchmarks

👆 Interaction Benchmarks
Benchmark Metric Mean (ms) Min (ms) Max (ms) Std Dev (ms) P75 (ms) P95 (ms)
Load New Account load_new_account 282 261 336 31 267 336
total 282 261 336 31 267 336
Confirm Tx confirm_tx 6048 6004 6098 39 6092 6098
total 6048 6004 6098 39 6092 6098
Bridge User Actions bridge_load_page 214 212 217 2 215 217
bridge_load_asset_picker 200 199 200 0 200 200
bridge_search_token 705 702 709 3 708 709
total 1117 1116 1120 2 1120 1120

🔌 Startup Benchmarks
Benchmark Metric Mean (ms) Min (ms) Max (ms) Std Dev (ms) P75 (ms) P95 (ms)
Standard Home uiStartup 1436 1200 1840 110 1476 1644
load 1206 1013 1503 99 1245 1395
domContentLoaded 1197 985 1453 95 1235 1383
domInteractive 29 17 114 20 25 79
firstPaint 156 72 459 87 213 345
backgroundConnect 214 194 402 23 214 246
firstReactRender 20 12 58 6 21 30
initialActions 2 0 8 2 2 4
loadScripts 1001 788 1247 94 1039 1188
setupStore 13 6 33 5 17 21
numNetworkReqs 31 22 88 19 25 82
Power User Home uiStartup 2164 1440 9494 1084 2090 4285
load 1198 1030 1649 140 1226 1533
domContentLoaded 1179 1014 1585 131 1209 1471
domInteractive 35 19 149 20 33 82
firstPaint 211 86 1578 201 261 339
backgroundConnect 503 260 3881 589 381 1669
firstReactRender 25 15 66 9 27 46
initialActions 1 0 7 1 1 3
loadScripts 965 820 1336 124 996 1249
setupStore 15 5 38 6 18 28
numNetworkReqs 71 40 146 21 81 113

🧭 User Journey Benchmarks
Benchmark Metric Mean (ms) Min (ms) Max (ms) Std Dev (ms) P75 (ms) P95 (ms)
Onboarding Import Wallet importWalletToSocialScreen 220 218 223 2 222 223
srpButtonToSrpForm 95 94 97 1 94 97
confirmSrpToPwForm 22 21 22 1 22 22
pwFormToMetricsScreen 16 15 16 0 16 16
metricsToWalletReadyScreen 17 16 17 0 17 17
doneButtonToHomeScreen 639 601 725 50 617 725
openAccountMenuToAccountListLoaded 2929 2906 2946 15 2937 2946
total 3959 3888 4068 71 4018 4068
Onboarding New Wallet createWalletToSocialScreen 218 217 219 1 219 219
srpButtonToPwForm 106 104 109 2 105 109
createPwToRecoveryScreen 8 8 8 0 8 8
skipBackupToMetricsScreen 35 34 36 1 36 36
agreeButtonToOnboardingSuccess 16 16 16 0 16 16
doneButtonToAssetList 547 477 682 87 618 682
total 940 861 1118 103 998 1118
Asset Details assetClickToPriceChart 55 45 71 12 69 71
total 55 45 71 12 69 71
Solana Asset Details assetClickToPriceChart 78 71 86 6 82 86
total 78 71 86 6 82 86
Import Srp Home loginToHomeScreen 2178 1969 2525 211 2316 2525
openAccountMenuAfterLogin 43 37 50 5 44 50
homeAfterImportWithNewWallet 3020 2712 3693 369 3140 3693
total 4985 4852 5153 133 5078 5153
Send Transactions openSendPageFromHome 24 17 31 5 29 31
selectTokenToSendFormLoaded 19 18 20 1 20 20
reviewTransactionToConfirmationPage 848 846 851 2 850 851
total 891 883 898 7 898 898
Swap openSwapPageFromHome 129 108 152 17 140 152
fetchAndDisplaySwapQuotes 2894 2893 2895 1 2895 2895
total 3023 3001 3053 18 3028 3053

🌐 Dapp Page Load Benchmarks

Current Commit: fedc086 | Date: 3/4/2026

📄 Localhost MetaMask Test Dapp

Samples: 100

Summary

pageLoadTime-> current mean value: 985ms (±73ms) 🟢 | historical mean value: 1.05s ⬇️ (historical data)
domContentLoaded-> current mean value: 698ms (±81ms) 🟢 | historical mean value: 740ms ⬇️ (historical data)
firstContentfulPaint-> current mean value: 88ms (±118ms) 🟢 | historical mean value: 81ms ⬆️ (historical data)

📈 Detailed Results

Metric	Mean	Std Dev	Min	Max	P95	P99
pageLoadTime	985ms	73ms	940ms	1.30s	1.21s	1.30s
domContentLoaded	698ms	81ms	656ms	1.20s	903ms	1.20s
firstPaint	88ms	118ms	60ms	1.26s	88ms	1.26s
firstContentfulPaint	88ms	118ms	60ms	1.26s	88ms	1.26s
largestContentfulPaint	0ms	0ms	0ms	0ms	0ms	0ms

Bundle size diffs [🚨 Warning! Bundle size has increased!]

background: 7.69 MiB (100%)
ui: 8.18 MiB (100%)
common: 10.9 MiB (100%)

…etamask-controller

abretonc7s temporarily deployed to pr-comment March 4, 2026 13:01 — with GitHub Actions Inactive

metamaskbot added team-perps Perps team INVALID-PR-TEMPLATE PR's body doesn't match template labels Mar 4, 2026

github-actions bot added the size-XL label Mar 4, 2026

abretonc7s temporarily deployed to pr-comment March 4, 2026 13:31 — with GitHub Actions Inactive

gambinish mentioned this pull request Mar 4, 2026

feat: Perps Controller integration #40078

Open

7 tasks

cleanup: extract a dedicated PerpsStreamBridge, remove footprint in m…

7ccb20e

…etamask-controller

gambinish temporarily deployed to pr-comment March 4, 2026 18:53 — with GitHub Actions Inactive

gambinish added 2 commits March 4, 2026 11:11

chore: cleanup dead code

fd9cdc1

perf: lazy-load PerpsControllerProvider to reduce common bundle size

d9fa712

gambinish temporarily deployed to pr-comment March 4, 2026 19:19 — with GitHub Actions Inactive

gambinish added 2 commits March 4, 2026 11:21

chore: cleanup

837b5c9

chore: cleanup, remove mocks

6b84b7f

gambinish temporarily deployed to pr-comment March 4, 2026 19:25 — with GitHub Actions Inactive

chore: remove mocks from production bundle

dbf0874

gambinish temporarily deployed to pr-comment March 4, 2026 19:51 — with GitHub Actions Inactive

fix: live subscriptions to order, account, and positions

11b8756

gambinish had a problem deploying to pr-comment March 4, 2026 19:53 — with GitHub Actions Error

gambinish marked this pull request as ready for review March 4, 2026 19:53

gambinish requested a review from a team as a code owner March 4, 2026 19:53

gambinish merged commit 30bd5e1 into perps/poc-controller-integration-temp Mar 4, 2026
5 of 8 checks passed

gambinish had a problem deploying to pr-comment March 4, 2026 19:53 — with GitHub Actions Failure

gambinish deleted the perps/phase2-background-streaming branch March 4, 2026 19:53

github-actions bot locked and limited conversation to collaborators Mar 4, 2026

gambinish temporarily deployed to pr-comment March 4, 2026 20:23 — with GitHub Actions Inactive

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: move perps streaming ownership to background (Phase 2 POC)#40600

feat: move perps streaming ownership to background (Phase 2 POC)#40600
gambinish merged 8 commits intoperps/poc-controller-integration-tempfrom
perps/phase2-background-streaming

abretonc7s commented Mar 4, 2026 •

edited by cursor bot

Loading

Uh oh!

github-actions bot commented Mar 4, 2026 •

edited

Loading

Uh oh!

metamaskbotv2 bot commented Mar 4, 2026 •

edited

Loading

Uh oh!

abretonc7s commented Mar 4, 2026

Uh oh!

metamaskbotv2 bot commented Mar 4, 2026

📄 Localhost MetaMask Test Dapp

Summary

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

abretonc7s commented Mar 4, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

The Problem (from #40078 review)

Path 2: Custom JSON-RPC Notification Channel

What Changed

Key Properties

Tests

Changelog

Related

Uh oh!

github-actions bot commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

metamaskbotv2 bot commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✨ Files requiring CODEOWNER review ✨

Uh oh!

abretonc7s commented Mar 4, 2026

Uh oh!

metamaskbotv2 bot commented Mar 4, 2026

📄 Localhost MetaMask Test Dapp

Summary

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

abretonc7s commented Mar 4, 2026 •

edited by cursor bot

Loading

github-actions bot commented Mar 4, 2026 •

edited

Loading

metamaskbotv2 bot commented Mar 4, 2026 •

edited

Loading