[DRAFT] PoC: TanStack Query Option B — `UIMessenger`-enforced background ownership + UI-side `staleTime` support by MajorLift · Pull Request #41102 · MetaMask/metamask-extension

MajorLift · 2026-03-20T20:29:30Z

PoC: TanStack Query Option B

PoC demonstrating Option B from ADR #131.
Companion core changes: core diff

Summary

UIMessenger capability gating - Background ownership enforcement without axis coupling with UIMessenger gating (decisions#126) and queryFn scope lint rule enforce the same boundary as OmitKeyof, without stripping staleTime from the UI type signature.
Call-site cache policy — per-component staleTime (5s swaps, 30s portfolio) on the same hook and queryKey — a type error under Option A's OmitKeyof.
Axis independence — fetch ownership (Axis 2) and cache policy location (Axis 1) enforced as independent constraints, not coupled via type erasure.

Option A vs Option B

	Option A (`fb/rq-poc`)	Option B (this PoC)
Ownership enforcement	`OmitKeyof` strips `queryFn` + `staleTime`	UIMessenger capability gating + lint rule
UI `staleTime`	Stripped from type signature	Call-site API, per-component freshness
UI `queryFn`	Proxy to background via messenger	Own `queryFn` from `get*QueryOptions`
Axis coupling	Coupled. Background ownership implies service-layer cache policy	Decoupled. Independent enforcement per axis
New API lead time	Data service `fetchQuery` + proxy routing per endpoint	`getQueryOptions` direct, zero lead time*
Background sync	`createUIQueryClient` -> `hydrate()`	`BaseDataService` -> `cacheUpdate` -> `useSyncExternalStore`
`BaseDataService`	Required for all queries (proxy through background)	Background-owned queries only. UI-direct coexists
`core-backend` usage	`get*QueryOptions` wrapped in proxy; `staleTime` stripped	`get*QueryOptions` consumed directly. `staleTime`/`select`/`retry` preserved

Ownership boundary enforcement

The central question between Option A and Option B: how is the fetch ownership boundary enforced?

Option A: `OmitKeyof`

Background owns all fetches. UI receives a QueryClient with staleTime: 0 and OmitKeyof stripping staleTime/queryFn from the type signature. This enforces ownership — but as a blunt instrument. Stripping staleTime is a side effect of stripping queryFn, not an independent constraint.

Option B: UIMessenger capability gating + lint rule

Two independent, composable mechanisms — each enforcing one axis:

1. UIMessenger capability gating (Axis 2 — fetch ownership)

Per-controller messenger configs declare which events are exposed to the UI. Routes declare which events they can subscribe to. Components use useMessenger() with compile-time and runtime validation against the route's declared capabilities.

// Route declares its sync event capabilities via layout route
{
  element: (
    <RouteWithMessenger events={['CurrencyRateDataService:cacheUpdate']}>
      <Outlet />
    </RouteWithMessenger>
  ),
  children: [{ path: DEFAULT_ROUTE, element: <Home /> }],
}

// useControllerState validates route capabilities internally via useMessenger().
// Subscribing to an undeclared event is a compile-time type error and a runtime throw.
const data = useControllerState(currencyRatesStore, 'CurrencyRateDataService:cacheUpdate');

The enforcement hierarchy:

Per-controller config (shared/messenger-config/*.ts) — team-owned declaration of UI-exposed events using DataServiceEvents types from BaseDataService. Adding/removing an event here controls access at compile time and runtime.
Route declaration (layout route with RouteWithMessenger) — scopes event access per route. RouteWithMessenger creates a child messenger that only delegates declared events.
Component access (useMessenger({ events })) — validates requested events against the route's delegated capabilities. Undeclared event = type error + runtime throw.
Hook-level enforcement — useControllerState calls useMessenger() internally, so every controller-state subscription is validated against the route's declared capabilities. The underlying createControllerStore subscribes at module scope for efficiency, but the React hook enforces the messenger hierarchy at render time.

This follows the three-tier messenger hierarchy from decisions#126: RootMessenger → UIMessenger → RouteMessenger.

2. `queryFn` scope lint rule (Axis 2 — fetch authorship)

no-restricted-imports in ui/hooks/** requires queryFn via get*QueryOptions from @metamask/core-backend. Blocks unauthorized direct-API calls in UI hooks — without restricting staleTime or other cache policy.

Together: UIMessenger gates event subscriptions (controller access boundary). Lint rule gates queryFn authorship (fetch ownership boundary). These are the same constraints OmitKeyof enforces — but as independent mechanisms that don't couple Axis 1 to Axis 2.

Per-screen vs per-client cache policy

Per-client divergence (extension vs mobile) is solvable under both options via data service constructor config. The constraint unique to Option A is per-screen divergence within the same client: the data service instance is shared across all screens, so a single staleTime governs every consumer.

Examples: gas estimates (activity list 30s vs confirmation 3s), token balances (dashboard 30s vs send confirmation 0), select for re-render scope (home: all tokens, swap: only source/dest), refetchOnMount: 'always' for confirmation screens. staleTime is type-stripped by OmitKeyof; other options remain available but staleTime: 0 breaks the conditional interaction system (e.g., refetchOnMount: true always fires because data is always stale).

What background proxy uniquely provides

After accounting for core-backend (shared query definitions), constructor config (per-client divergence), and persistQueryClient (cache persistence):

Bypass resistance — OmitKeyof is compile-time; lint rules can be eslint-disabled
Single-process observability — all fetches in one process
Process-persistent cache — extension only; independently solvable via persistQueryClient

These are operational concerns. The ADR question: do they justify staleTime: 0 breaking the conditional refetch system, core-backend pass-through freshness undermined, and split-process staleness indirection?

Staleness indirection

The ADR identifies a structural problem with background-owned fetches: when the QueryClient that detects staleness is not the one that owns the queryFn, two staleTime values interact opaquely.

	UI-direct (`useSpotPricesQuery`)	Controller-driven (`useCurrencyRatesQuery`)
`queryFn` owner	UI `QueryClient` directly	Background (`CurrencyRateDataService`)
Staleness indirection	Absent. Single `staleTime`, single process	Absent. No proxy cycle. UI is a passive receiver
Call-site cache policy	Yes, `staleTimeOverride` per component	No. Background cadence is authoritative

Option A's proxy pattern produces the indirection for all queries. Option B eliminates it for UI-direct queries (structurally impossible, single owner) and replaces it with transparent push semantics for controller-driven queries (isFetching: false, dataUpdatedAt reflects background timing via DehydratedState).

Architecture

flowchart TB
    subgraph UIDirectFetch["UI-direct: server state (useQuery)"]
        direction TB
        A1["useSpotPricesQuery(staleTimeOverride?)"]
        A2["useQuery(apiClient.prices.getV3SpotPricesQueryOptions(...))"]
        A3["price.api.cx.metamask.io"]
        A1 --> A2 --> A3
    end

    subgraph BackgroundSync["Controller state (useSyncExternalStore)"]
        direction TB
        B1["CurrencyRateController:stateChange"]
        B2["CurrencyRateDataService.fetchQuery()"]
        B3["@tanstack/query-core (background-internal)"]
        B4["cacheUpdate messenger event"]
        B5["useSyncExternalStore → component"]
        B1 --> B2 --> B3 --> B4 --> B5
    end

    style B3 fill:#f5f5f5,stroke:#ccc,stroke-dasharray: 5 5

Two tools for two problems. TQ on the background side is an implementation detail — its only UI-visible output is the messenger event.

TQ usage by layer

Layer	TQ involvement	What it does
Background (BaseDataService)	`@tanstack/query-core` — internal	`fetchQuery` for caching, deduplication, gc. `staleTime`/`gcTime`/`retry` are background-internal. Publishes `cacheUpdate` messenger events.
Transport	None	Messenger events carry data across the process boundary. Payload format (currently DehydratedState) is an implementation detail of BaseDataService.
UI, server state	`@tanstack/react-query` — full API	`useQuery`/`useInfiniteQuery` with `get*QueryOptions` from `@metamask/core-backend`. Call-site `staleTime`, `refetchOnFocus`, `select`, `retry`.
UI, controller state	None	`useSyncExternalStore` over messenger events. No `queryFn`, no `staleTime`, no TQ cache policy. Background owns cadence. `useControllerState` validates route-level messenger capabilities via `useMessenger()`.

Background-side TQ guidelines

Data services use @tanstack/query-core as internal infrastructure. The UI does not consume background TQ artifacts directly.

queryKey is internal. The messenger event name (e.g., CurrencyRateDataService:cacheUpdate) is the contract between background and UI — not the queryKey.
staleTime/gcTime/retry are background-internal cache policy. They govern how the background caches and refreshes data. They do not leak to the UI.
fetchQuery vs prefetchQuery: Use fetchQuery when the caller needs the result (e.g., controller consuming the data). Use prefetchQuery when the goal is just to populate the cache for later cacheUpdate events.
One data service per controller concern, not per UI view. The data service models the background's data domain; the UI subscribes to the events it needs.
Do not export queryOptions from data services. If the UI needs to fetch the same data directly (display-only context), it uses get*QueryOptions from @metamask/core-backend — a separate code path with its own queryFn.

Per-controller vs multi-endpoint data services

The ADR identifies a packaging choice for background data services: per-controller (TokenRatesDataService) vs multi-endpoint (@metamask/core-backend). Under Option A, where all data routes through the background, these are competing organizational models for the same concern.

This PoC resolves the tension: they serve different data categories.

	Per-controller data service	Multi-endpoint (core-backend)
Data category	Controller state	Server state
Purpose	Bridge controller state to UI via messenger	Library of query definitions for direct UI use
UI consumption	`useControllerState` (useSyncExternalStore)	`useQuery(get*QueryOptions(...))`
TQ involvement (UI)	None	Full API
TQ involvement (bg)	`@tanstack/query-core` — internal	N/A (no runtime, just config)
Cross-client reuse	Shared via core data service package	Shared via core-backend package

Per the ADR: "A per-controller data service can consume core-backend's exported get*QueryOptions while owning its own QueryClient and lifecycle — using core-backend as a query definition library rather than a runtime service." This PoC makes that concrete: core-backend is the library, per-controller data services are the runtime — and they don't overlap.

`core-backend` alignment

@metamask/core-backend exports get*QueryOptions for 40+ endpoints with { queryKey, queryFn, staleTime, gcTime }. Its FetchOptions pass-through preserves staleTime, select, retry at the call site. Option B consumes this directly:

const queryOptions = apiClient.prices.getV3SpotPricesQueryOptions(assetIds, { currency });
return useQuery({
  ...queryOptions,
  ...(staleTimeOverride !== undefined && { staleTime: staleTimeOverride }),
});

Option A wraps the same get*QueryOptions in a proxy queryFn and strips staleTime via OmitKeyof. The pass-through that core-backend preserves is removed at the consumption layer.

Existing usage on main and mobile confirms the full API surface is needed:

activity-v2 uses useInfiniteQuery, select, keepPreviousData, refetchOnMount, prefetchInfiniteQuery. select and refetchOnMount are available under Option A (not stripped by OmitKeyof), but staleTime: 0 breaks conditional behavior — refetchOnMount: true always fires.
metamask-mobile test: header integration test for contract interaction #25981 uses staleTime: 10_000, full status API, controller-boundary queryFn. Call-site staleTime, stripped under Option A.

Option B is a superset: full TQ API at call site, plus controller state via useSyncExternalStore, plus per-component staleTimeOverride.

Model selection: UI-direct vs controller-driven

When adding a new data hook, use this decision tree:

Does a background controller already consume this data?
├── YES → Does the data need to persist when UI is unmounted?
│   ├── YES → Controller state (useSyncExternalStore over messenger)
│   └── NO  → Is the fetch cadence externally driven (WebSocket, polling)?
│       ├── YES → Controller state
│       └── NO  → Server state (useQuery — component declares freshness)
└── NO  → Server state (useQuery with get*QueryOptions from core-backend)

Rule of thumb: default to UI-direct (useQuery). Cross-client reuse is automatic — @metamask/core-backend is the shared query options package, consumed directly by both extension and mobile. Upgrade to controller state only when an independent background ownership criterion is met (controller dependency, process persistence, externally driven cadence).

Shared queryKey staleTime behavior

When multiple useQuery observers share a queryKey with different staleTime values, TQ uses the shortest staleTime for refetch decisions. Per-component staleTimeOverride (e.g., 5s swap vs 30s portfolio) achieves differentiated freshness only when the components are on separate routes (mutually exclusive mounts). When co-mounted, the shorter staleTime governs both.

Changelog

CHANGELOG entry:

Related issues

Fixes:

Manual testing steps

Go to this page...

Screenshots/Recordings

Before

After

Pre-merge author checklist

I've followed MetaMask Contributor Docs and MetaMask Extension 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.

`fetchQuery` with `staleTime: 0` is intentional for controller-driven push data: each state change executes the `queryFn` (which returns the state directly), storing it in the background `QueryClient` cache. `BaseDataService` then auto-publishes `cacheUpdate` with `DehydratedState`. This is the fetch ownership boundary — the controller decides when to update, not the UI.

…ery` Uses `hydrate()` instead of `setQueryData` so the `DehydratedState` from `BaseDataService:cacheUpdate` carries cache metadata (`dataUpdatedAt`, `staleTime`) from the background — UI cache reflects background timing semantics without re-fetching. `useCurrencyRatesQuery` is a passive cache reader (`queryFn: () => undefined`); `isFetching` stays false.

… enforcement Per-route gating instead of global subscription prevents components from silently depending on events their route hasn't declared. Undeclared event subscriptions are a compile-time type error (via `useMessenger` generics) and a runtime throw (via delegated capabilities check).

github-actions · 2026-03-20T20:29:49Z

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.

socket-security · 2026-03-20T20:30:36Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@metamask-previews/base-data-service@0.0.0-preview-00245ea

View full report

metamaskbotv2 · 2026-03-20T20:32:20Z

✨ Files requiring CODEOWNER review ✨

👨‍🔧 @MetaMask/core-extension-ux (1 files, +264 -0)

📁 ui/
- 📁 components/
  - 📁 multichain/
    - 📁 spot-prices-query/
      - 📄 SpotPricesQueryPanel.tsx +264 -0

📜 @MetaMask/policy-reviewers (12 files, +84 -0)

📁 lavamoat/
- 📁 browserify/
  - 📁 beta/
    - 📄 policy.json +9 -0
  - 📁 experimental/
    - 📄 policy.json +9 -0
  - 📁 flask/
    - 📄 policy.json +9 -0
  - 📁 main/
    - 📄 policy.json +9 -0
- 📁 webpack/
  - 📁 mv2/
    - 📁 beta/
      - 📄 policy.json +7 -0
    - 📁 experimental/
      - 📄 policy.json +7 -0
    - 📁 flask/
      - 📄 policy.json +7 -0
    - 📁 main/
      - 📄 policy.json +7 -0
  - 📁 mv3/
    - 📁 beta/
      - 📄 policy.json +5 -0
    - 📁 experimental/
      - 📄 policy.json +5 -0
    - 📁 flask/
      - 📄 policy.json +5 -0
    - 📁 main/
      - 📄 policy.json +5 -0

Tip

Follow the policy review process outlined in the LavaMoat Policy Review Process doc before expecting an approval from Policy Reviewers.

MajorLift · 2026-03-20T21:24:15Z

@metamaskbot update-policies

metamaskbot · 2026-03-20T21:39:31Z

Policies updated.
👀 Please review the diff for suspicious new powers.

🧠 Learn how: https://lavamoat.github.io/guides/policy-diff/#what-to-look-for-when-reviewing-a-policy-diff

👀 lavamoat/browserify/beta/policy.json changes differ from main/policy.json policy changes
👀 lavamoat/browserify/experimental/policy.json changes differ from main/policy.json policy changes
👀 lavamoat/browserify/flask/policy.json changes differ from main/policy.json policy changes
👀 lavamoat/webpack/mv2/beta/policy.json changes differ from mv2/main/policy.json policy changes
👀 lavamoat/webpack/mv2/experimental/policy.json changes differ from mv2/main/policy.json policy changes
👀 lavamoat/webpack/mv2/flask/policy.json changes differ from mv2/main/policy.json policy changes
👀 lavamoat/webpack/mv3/beta/policy.json changes differ from mv3/main/policy.json policy changes
👀 lavamoat/webpack/mv3/experimental/policy.json changes differ from mv3/main/policy.json policy changes
👀 lavamoat/webpack/mv3/flask/policy.json changes differ from mv3/main/policy.json policy changes

metamaskbotv2 · 2026-03-20T22:27:57Z

Builds ready [bd5fb82]

builds: chrome, firefox
builds (beta): chrome, firefox
builds (flask): chrome, firefox
builds (test): chrome, firefox
builds (test-flask): chrome, firefox
webpack builds: chrome, firefox
webpack builds (beta): chrome, firefox
webpack builds (flask): chrome, firefox
webpack builds (test): chrome, firefox
webpack builds (test-flask): chrome, firefox
lavamoat build viz: Build System
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
- 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, 21
- 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 373 263 557 128 501 557
total 373 263 557 128 501 557
Confirm Tx confirm_tx 6005 5981 6039 22 6020 6039
total 6005 5981 6039 22 6020 6039
Bridge User Actions bridge_load_page 215 181 252 24 232 252
bridge_load_asset_picker 229 185 253 25 244 253
bridge_search_token 759 751 766 6 762 766
total 1178 1140 1202 24 1193 1202

🔌 Startup Benchmarks
Benchmark Metric Mean (ms) Min (ms) Max (ms) Std Dev (ms) P75 (ms) P95 (ms)
Standard Home uiStartup 1428 1172 1696 108 1480 1625
load 1170 962 1405 92 1223 1338
domContentLoaded 1164 959 1393 91 1217 1329
domInteractive 29 16 101 20 24 83
firstPaint 187 63 1287 185 206 336
backgroundConnect 210 192 261 14 213 242
firstReactRender 19 13 52 5 21 29
initialActions 1 0 6 1 1 4
loadScripts 971 766 1200 90 1024 1127
setupStore 13 7 51 7 14 24
numNetworkReqs 40 32 90 16 32 79
Power User Home uiStartup 5638 2462 13767 2225 6637 9214
load 1332 1105 1899 137 1382 1647
domContentLoaded 1312 1088 1860 131 1370 1625
domInteractive 44 20 270 47 36 131
firstPaint 196 89 499 103 275 350
backgroundConnect 1748 314 10449 1819 2545 4999
firstReactRender 25 17 52 6 25 38
initialActions 1 0 10 1 1 4
loadScripts 1077 869 1594 124 1114 1373
setupStore 18 7 298 29 17 32
numNetworkReqs 237 127 450 62 269 344

🧭 User Journey Benchmarks
Benchmark Metric Mean (ms) Min (ms) Max (ms) Std Dev (ms) P75 (ms) P95 (ms)
Onboarding Import Wallet importWalletToSocialScreen 218 217 219 1 218 219
srpButtonToSrpForm 92 91 93 1 93 93
confirmSrpToPwForm 21 21 22 0 21 22
pwFormToMetricsScreen 15 15 15 0 15 15
metricsToWalletReadyScreen 15 15 16 0 16 16
doneButtonToHomeScreen 611 523 735 93 712 735
openAccountMenuToAccountListLoaded 2920 2895 2966 27 2914 2966
total 3931 3790 3991 78 3987 3991
Onboarding New Wallet createWalletToSocialScreen 219 219 219 0 219 219
srpButtonToPwForm 110 109 112 1 111 112
createPwToRecoveryScreen 9 8 9 0 9 9
skipBackupToMetricsScreen 40 38 42 2 42 42
agreeButtonToOnboardingSuccess 16 16 16 0 16 16
doneButtonToAssetList 516 471 553 29 543 553
total 910 866 948 29 937 948
Asset Details assetClickToPriceChart 49 48 51 1 49 51
total 49 48 51 1 49 51
Solana Asset Details assetClickToPriceChart 116 83 187 41 137 187
total 116 83 187 41 137 187
Import Srp Home loginToHomeScreen 2394 2292 2515 86 2428 2515
openAccountMenuAfterLogin 67 65 69 2 69 69
homeAfterImportWithNewWallet 1224 323 2439 969 2376 2439
total 3820 2683 5595 1217 4981 5595
Send Transactions openSendPageFromHome 49 21 66 18 64 66
selectTokenToSendFormLoaded 35 28 47 7 33 47
reviewTransactionToConfirmationPage 980 895 1082 67 974 1082
total 1073 993 1164 61 1070 1164
Swap openSwapPageFromHome 105 63 137 27 125 137
fetchAndDisplaySwapQuotes 2689 2685 2693 3 2692 2693
total 2794 2752 2821 26 2817 2821

🌐 Dapp Page Load Benchmarks

Current Commit: bd5fb82 | Date: 3/20/2026

📄 Localhost MetaMask Test Dapp

Samples: 100

Summary

pageLoadTime-> current mean value: 1.01s (±45ms) 🟡 | historical mean value: 1.04s ⬇️ (historical data)
domContentLoaded-> current mean value: 708ms (±41ms) 🟢 | historical mean value: 732ms ⬇️ (historical data)
firstContentfulPaint-> current mean value: 84ms (±13ms) 🟢 | historical mean value: 86ms ⬇️ (historical data)

📈 Detailed Results

Metric	Mean	Std Dev	Min	Max	P95	P99
pageLoadTime	1.01s	45ms	968ms	1.29s	1.07s	1.29s
domContentLoaded	708ms	41ms	677ms	974ms	762ms	974ms
firstPaint	84ms	13ms	68ms	184ms	104ms	184ms
firstContentfulPaint	84ms	13ms	68ms	184ms	104ms	184ms
largestContentfulPaint	0ms	0ms	0ms	0ms	0ms	0ms

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

background: 1.68 MiB (32.48%)
ui: -69.4 KiB (-0.81%)
common: 397.23 KiB (3.52%)

metamaskbotv2 · 2026-03-22T21:21:33Z

Builds ready [150cc56]

builds: chrome, firefox
builds (beta): chrome, firefox
builds (flask): chrome, firefox
builds (test): chrome, firefox
builds (test-flask): chrome, firefox
webpack builds: chrome, firefox
webpack builds (beta): chrome, firefox
webpack builds (flask): chrome, firefox
webpack builds (test): chrome, firefox
webpack builds (test-flask): chrome, firefox
lavamoat build viz: Build System
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
- 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, 21
- 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 281 272 289 7 285 289
total 281 272 289 7 285 289
Confirm Tx confirm_tx 6059 6043 6081 14 6062 6081
total 6059 6043 6081 14 6062 6081
Bridge User Actions bridge_load_page 319 217 403 67 371 403
bridge_load_asset_picker 178 137 227 30 193 227
bridge_search_token 721 701 732 11 732 732
total 1246 1216 1271 22 1262 1271

🔌 Startup Benchmarks
Benchmark Metric Mean (ms) Min (ms) Max (ms) Std Dev (ms) P75 (ms) P95 (ms)
Standard Home uiStartup 1510 1288 2037 117 1594 1683
load 1242 1033 1737 111 1309 1408
domContentLoaded 1236 1030 1728 110 1301 1398
domInteractive 30 18 152 23 26 88
firstPaint 139 68 376 65 182 229
backgroundConnect 225 204 276 14 231 255
firstReactRender 20 14 64 6 21 29
initialActions 1 0 9 1 1 3
loadScripts 1027 824 1513 107 1089 1174
setupStore 14 7 37 5 16 21
numNetworkReqs 40 32 83 15 41 78
Power User Home uiStartup 5604 2280 13528 2144 6466 7965
load 1314 1142 3123 223 1329 1612
domContentLoaded 1294 1136 3108 217 1302 1572
domInteractive 39 20 186 36 31 146
firstPaint 225 86 1374 191 283 414
backgroundConnect 2277 308 9102 1906 3208 5179
firstReactRender 25 16 61 6 27 33
initialActions 1 0 4 1 1 3
loadScripts 1061 927 2864 211 1070 1324
setupStore 17 7 60 9 18 34
numNetworkReqs 144 85 301 41 148 244

🧭 User Journey Benchmarks
Benchmark Metric Mean (ms) Min (ms) Max (ms) Std Dev (ms) P75 (ms) P95 (ms)
Onboarding Import Wallet importWalletToSocialScreen 219 217 222 2 221 222
srpButtonToSrpForm 92 91 92 0 92 92
confirmSrpToPwForm 21 21 22 0 22 22
pwFormToMetricsScreen 15 15 16 0 15 16
metricsToWalletReadyScreen 16 15 17 1 16 17
doneButtonToHomeScreen 664 509 790 96 729 790
openAccountMenuToAccountListLoaded 2992 2717 3328 206 3093 3328
total 3992 3960 4048 40 4048 4048
Onboarding New Wallet createWalletToSocialScreen 219 219 219 0 219 219
srpButtonToPwForm 110 109 110 1 110 110
createPwToRecoveryScreen 9 8 9 0 9 9
skipBackupToMetricsScreen 41 40 41 0 41 41
agreeButtonToOnboardingSuccess 16 16 17 0 16 17
doneButtonToAssetList 618 508 739 98 711 739
total 1020 902 1143 105 1131 1143
Asset Details assetClickToPriceChart 48 45 52 3 48 52
total 48 45 52 3 48 52
Solana Asset Details assetClickToPriceChart 80 43 119 27 82 119
total 80 43 119 27 82 119
Import Srp Home loginToHomeScreen 2436 2387 2474 32 2446 2474
openAccountMenuAfterLogin 59 31 110 30 73 110
homeAfterImportWithNewWallet 1614 377 2552 955 2351 2552
total 4139 2887 5030 908 4829 5030
Send Transactions openSendPageFromHome 32 30 34 2 34 34
selectTokenToSendFormLoaded 35 30 42 5 41 42
reviewTransactionToConfirmationPage 1127 850 1455 240 1272 1455
total 1195 921 1518 236 1340 1518
Swap openSwapPageFromHome 90 76 101 10 99 101
fetchAndDisplaySwapQuotes 2687 2684 2690 2 2687 2690
total 2789 2763 2820 22 2809 2820

🌐 Dapp Page Load Benchmarks

Current Commit: 150cc56 | Date: 3/22/2026

📄 Localhost MetaMask Test Dapp

Samples: 100

Summary

pageLoadTime-> current mean value: 1.05s (±66ms) 🟡 | historical mean value: 1.04s ⬆️ (historical data)
domContentLoaded-> current mean value: 742ms (±79ms) 🟢 | historical mean value: 732ms ⬆️ (historical data)
firstContentfulPaint-> current mean value: 91ms (±128ms) 🟢 | historical mean value: 86ms ⬆️ (historical data)

📈 Detailed Results

Metric	Mean	Std Dev	Min	Max	P95	P99
pageLoadTime	1.05s	66ms	1.01s	1.37s	1.27s	1.37s
domContentLoaded	742ms	79ms	703ms	1.30s	955ms	1.30s
firstPaint	91ms	128ms	64ms	1.37s	92ms	1.37s
firstContentfulPaint	91ms	128ms	64ms	1.37s	92ms	1.37s
largestContentfulPaint	0ms	0ms	0ms	0ms	0ms	0ms

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

background: 1.68 MiB (32.48%)
ui: -70.92 KiB (-0.83%)
common: 397.23 KiB (3.52%)

…tate subscriptions `useSyncExternalStore` adapter for background messenger events. Controller state is not server state — the background owns cadence, the UI renders the latest value. No TQ involvement on the UI side.

Currency rates are controller state pushed from background — not server state the UI fetches. Replace no-op `queryFn` + `staleTime` with direct messenger event subscription via `useSyncExternalStore`.

…drate()` path No longer needed — controller state flows through `useControllerState` over messenger events. Simplify `QueryClient` to standard TQ defaults; per-query cache policy via `get*QueryOptions`.

…outes `createRouteWithLayout` is a temporary v5-to-v6 bridge being deprecated. Route-level messenger scoping now uses `RouteWithMessenger` as a layout route element with `Outlet` — idiomatic React Router v6.

…i-endpoint disambiguation

metamaskbotv2 · 2026-03-23T13:20:57Z

Builds ready [61d47e9]

builds: chrome, firefox
builds (beta): chrome, firefox
builds (flask): chrome, firefox
builds (test): chrome, firefox
builds (test-flask): chrome, firefox
webpack builds: chrome, firefox
webpack builds (beta): chrome, firefox
webpack builds (flask): chrome, firefox
webpack builds (test): chrome, firefox
webpack builds (test-flask): chrome, firefox
lavamoat build viz: Build System
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
- 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, 21
- 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 297 272 318 18 317 318
total 297 272 318 18 317 318
Confirm Tx confirm_tx 6056 6053 6063 4 6058 6063
total 6056 6053 6063 4 6058 6063
Bridge User Actions bridge_load_page 258 244 281 15 260 281
bridge_load_asset_picker 254 236 273 14 269 273
bridge_search_token 759 753 769 7 769 769
total 1264 1202 1303 38 1298 1303

🔌 Startup Benchmarks
Benchmark Metric Mean (ms) Min (ms) Max (ms) Std Dev (ms) P75 (ms) P95 (ms)
Standard Home uiStartup 1408 1190 1724 107 1460 1612
load 1156 938 1390 98 1225 1329
domContentLoaded 1148 934 1346 95 1218 1309
domInteractive 28 16 98 19 25 83
firstPaint 172 62 1355 172 199 346
backgroundConnect 205 189 254 13 207 237
firstReactRender 17 12 32 3 18 23
initialActions 1 0 7 1 1 3
loadScripts 960 751 1158 93 1023 1118
setupStore 12 7 44 5 15 20
numNetworkReqs 40 32 87 16 32 82
Power User Home uiStartup 6090 2346 14129 2196 6666 10710
load 1366 1183 2572 205 1386 1665
domContentLoaded 1340 1172 2564 195 1356 1601
domInteractive 42 21 283 41 34 138
firstPaint 254 83 1603 273 274 471
backgroundConnect 2070 312 10963 2203 3311 7526
firstReactRender 25 18 64 7 26 36
initialActions 1 0 5 1 1 2
loadScripts 1104 953 2348 179 1116 1363
setupStore 15 7 50 6 17 26
numNetworkReqs 205 117 367 50 223 306

🧭 User Journey Benchmarks
Benchmark Metric Mean (ms) Min (ms) Max (ms) Std Dev (ms) P75 (ms) P95 (ms)
Onboarding Import Wallet importWalletToSocialScreen 224 221 226 2 224 226
srpButtonToSrpForm 109 107 109 1 109 109
confirmSrpToPwForm 27 25 28 1 28 28
pwFormToMetricsScreen 16 15 18 1 16 18
metricsToWalletReadyScreen 19 16 23 2 20 23
doneButtonToHomeScreen 610 550 732 69 643 732
openAccountMenuToAccountListLoaded 2979 2975 2985 4 2985 2985
total 3969 3891 4100 79 3949 4100
Onboarding New Wallet createWalletToSocialScreen 219 217 221 1 220 221
srpButtonToPwForm 109 106 111 2 110 111
createPwToRecoveryScreen 9 8 9 0 9 9
skipBackupToMetricsScreen 38 37 39 0 38 39
agreeButtonToOnboardingSuccess 16 15 16 1 16 16
doneButtonToAssetList 493 490 497 3 497 497
total 882 877 891 6 891 891
Asset Details assetClickToPriceChart 46 43 47 2 47 47
total 46 43 47 2 47 47
Solana Asset Details assetClickToPriceChart 82 40 145 40 111 145
total 82 40 145 40 111 145
Import Srp Home loginToHomeScreen 2354 2210 2562 132 2444 2562
openAccountMenuAfterLogin 68 39 89 19 87 89
homeAfterImportWithNewWallet 2321 2227 2392 63 2365 2392
total 4673 4657 4691 14 4691 4691
Send Transactions openSendPageFromHome 30 26 34 3 33 34
selectTokenToSendFormLoaded 53 24 99 30 78 99
reviewTransactionToConfirmationPage 1302 1236 1337 39 1322 1337
total 1387 1361 1410 18 1398 1410
Swap openSwapPageFromHome 88 30 146 46 140 146
fetchAndDisplaySwapQuotes 2685 2683 2689 2 2684 2689
total 2778 2712 2848 54 2835 2848

🌐 Dapp Page Load Benchmarks

Current Commit: 61d47e9 | Date: 3/23/2026

📄 Localhost MetaMask Test Dapp

Samples: 100

Summary

pageLoadTime-> current mean value: 984ms (±70ms) 🟢 | historical mean value: 1.06s ⬇️ (historical data)
domContentLoaded-> current mean value: 695ms (±67ms) 🟢 | historical mean value: 746ms ⬇️ (historical data)
firstContentfulPaint-> current mean value: 76ms (±10ms) 🟢 | historical mean value: 91ms ⬇️ (historical data)

📈 Detailed Results

Metric	Mean	Std Dev	Min	Max	P95	P99
pageLoadTime	984ms	70ms	939ms	1.25s	1.21s	1.25s
domContentLoaded	695ms	67ms	655ms	953ms	912ms	953ms
firstPaint	76ms	10ms	64ms	160ms	88ms	160ms
firstContentfulPaint	76ms	10ms	64ms	160ms	88ms	160ms
largestContentfulPaint	0ms	0ms	0ms	0ms	0ms	0ms

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

background: 1.68 MiB (32.5%)
ui: -63.11 KiB (-0.74%)
common: 398.21 KiB (3.53%)

`createControllerStore` subscribes at module scope, bypassing the UIMessenger hierarchy. The hook now accepts an `event` parameter and calls `useMessenger()` to validate that the current route has declared the event in its `RouteWithMessenger` capabilities — enforcing the three-tier messenger boundary at the React layer.

metamaskbotv2 · 2026-03-23T17:51:22Z

Builds ready [9aa181c]

builds: chrome, firefox
builds (beta): chrome, firefox
builds (flask): chrome, firefox
builds (test): chrome, firefox
builds (test-flask): chrome, firefox
webpack builds: chrome, firefox
webpack builds (beta): chrome, firefox
webpack builds (flask): chrome, firefox
webpack builds (test): chrome, firefox
webpack builds (test-flask): chrome, firefox
lavamoat build viz: Build System
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
- 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, 21
- 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 311 274 352 34 350 352
total 311 274 352 34 350 352
Confirm Tx confirm_tx 6066 6055 6073 8 6073 6073
total 6066 6055 6073 8 6073 6073
Bridge User Actions bridge_load_page 308 262 364 35 316 364
bridge_load_asset_picker 211 172 251 27 225 251
bridge_search_token 734 725 751 10 740 751
total 1253 1200 1343 51 1272 1343

🔌 Startup Benchmarks
Benchmark Metric Mean (ms) Min (ms) Max (ms) Std Dev (ms) P75 (ms) P95 (ms)
Standard Home uiStartup 1487 1257 1792 109 1542 1680
load 1223 1011 1527 99 1279 1393
domContentLoaded 1216 1008 1518 98 1272 1386
domInteractive 30 18 104 20 26 89
firstPaint 152 72 1097 115 202 259
backgroundConnect 218 202 268 10 222 235
firstReactRender 21 13 63 7 22 28
initialActions 1 0 6 1 2 4
loadScripts 1012 813 1300 96 1068 1168
setupStore 14 7 36 6 17 24
numNetworkReqs 40 32 88 15 41 77
Power User Home uiStartup 6256 2179 17827 2846 6643 11258
load 1314 1160 1711 129 1369 1632
domContentLoaded 1292 1143 1680 120 1332 1534
domInteractive 36 20 183 27 31 90
firstPaint 215 89 1503 191 263 334
backgroundConnect 2261 340 14468 2895 3022 9044
firstReactRender 24 18 43 4 26 32
initialActions 1 0 4 1 1 2
loadScripts 1059 940 1439 110 1094 1282
setupStore 14 7 50 7 17 28
numNetworkReqs 183 100 317 48 206 281

🧭 User Journey Benchmarks
Benchmark Metric Mean (ms) Min (ms) Max (ms) Std Dev (ms) P75 (ms) P95 (ms)
Onboarding Import Wallet importWalletToSocialScreen 219 218 219 0 219 219
srpButtonToSrpForm 94 92 96 1 95 96
confirmSrpToPwForm 22 22 23 0 22 23
pwFormToMetricsScreen 15 15 16 0 16 16
metricsToWalletReadyScreen 16 15 17 1 16 17
doneButtonToHomeScreen 620 515 751 101 730 751
openAccountMenuToAccountListLoaded 2984 2893 3113 102 3103 3113
total 3994 3984 4008 10 4008 4008
Onboarding New Wallet createWalletToSocialScreen 219 217 222 2 219 222
srpButtonToPwForm 107 105 108 1 108 108
createPwToRecoveryScreen 8 8 8 0 8 8
skipBackupToMetricsScreen 36 35 37 1 37 37
agreeButtonToOnboardingSuccess 15 15 15 0 15 15
doneButtonToAssetList 507 488 539 19 504 539
total 944 874 1103 87 973 1103
Asset Details assetClickToPriceChart 52 47 57 3 54 57
total 52 47 57 3 54 57
Solana Asset Details assetClickToPriceChart 53 39 67 11 65 67
total 53 39 67 11 65 67
Import Srp Home loginToHomeScreen 2320 2315 2327 5 2327 2327
openAccountMenuAfterLogin 59 52 66 5 63 66
homeAfterImportWithNewWallet 1196 333 2489 973 2273 2489
total 3664 2714 4836 899 4658 4836
Send Transactions openSendPageFromHome 52 25 76 21 74 76
selectTokenToSendFormLoaded 37 35 39 1 37 39
reviewTransactionToConfirmationPage 1101 848 1383 218 1340 1383
total 1188 938 1494 217 1398 1494
Swap openSwapPageFromHome 114 101 130 11 115 130
fetchAndDisplaySwapQuotes 2683 2682 2684 1 2683 2684
total 2802 2791 2812 8 2803 2812

Dapp page load benchmarks: data not available.

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

background: 1.68 MiB (32.5%)
ui: -61.59 KiB (-0.72%)
common: 399.89 KiB (3.55%)

MajorLift added 7 commits March 20, 2026 15:52

Configure queryClient with @metamask/core-backend defaults

bd22527

Add useSpotPricesQuery with call-site staleTime override

ee69928

Add UIMessenger type hierarchy and context providers

93d837f

Add SpotPricesQueryPanel demo and wire into home route

5c7ec84

MajorLift temporarily deployed to pr-comment March 20, 2026 20:29 — with GitHub Actions Inactive

metamaskbot added the team-extension-platform Extension Platform team label Mar 20, 2026

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

Wrap hydrate in try-catch

fbe7c97

MajorLift temporarily deployed to pr-comment March 20, 2026 20:53 — with GitHub Actions Inactive

MajorLift added 2 commits March 20, 2026 17:15

Update LavaMoat policies

d41b07c

Add mock in unit test

9467392

MajorLift temporarily deployed to pr-comment March 20, 2026 21:21 — with GitHub Actions Inactive

MajorLift added the DO-NOT-MERGE Pull requests that should not be merged label Mar 20, 2026

Update LavaMoat policies

7a8dc3a

metamaskbot temporarily deployed to pr-comment March 20, 2026 21:39 — with GitHub Actions Inactive

Fix integration test fails

bd5fb82

MajorLift temporarily deployed to pr-comment March 20, 2026 21:52 — with GitHub Actions Inactive

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

MajorLift temporarily deployed to pr-comment March 22, 2026 20:40 — with GitHub Actions Inactive

MajorLift force-pushed the jongsun/poc/tq/ui-default-bg-sync branch from bf23bc6 to 150cc56 Compare March 22, 2026 20:45

MajorLift temporarily deployed to pr-comment March 22, 2026 20:45 — with GitHub Actions Inactive

MajorLift temporarily deployed to pr-comment March 22, 2026 21:16 — with GitHub Actions Inactive

MajorLift added 5 commits March 23, 2026 08:43

Migrate useCurrencyRatesQuery from useQuery to useControllerState

53bc687

Currency rates are controller state pushed from background — not server state the UI fetches. Replace no-op `queryFn` + `staleTime` with direct messenger event subscription via `useSyncExternalStore`.

Remove useBackgroundQuerySync, BackgroundQuerySyncBridge, and `hy…

0a83f9c

…drate()` path No longer needed — controller state flows through `useControllerState` over messenger events. Simplify `QueryClient` to standard TQ defaults; per-query cache policy via `get*QueryOptions`.

Decouple messenger scoping from createRouteWithLayout into layout r…

111fdf8

…outes `createRouteWithLayout` is a temporary v5-to-v6 bridge being deprecated. Route-level messenger scoping now uses `RouteWithMessenger` as a layout route element with `Outlet` — idiomatic React Router v6.

Document background-internal TQ guidelines and per-controller vs mult…

61d47e9

…i-endpoint disambiguation

MajorLift force-pushed the jongsun/poc/tq/ui-default-bg-sync branch from 150cc56 to 61d47e9 Compare March 23, 2026 12:45

MajorLift temporarily deployed to pr-comment March 23, 2026 12:45 — with GitHub Actions Inactive

MajorLift temporarily deployed to pr-comment March 23, 2026 13:16 — with GitHub Actions Inactive

MajorLift temporarily deployed to pr-comment March 23, 2026 17:15 — with GitHub Actions Inactive

MajorLift temporarily deployed to pr-comment March 23, 2026 17:46 — with GitHub Actions Inactive

MajorLift closed this Apr 8, 2026

github-actions bot locked and limited conversation to collaborators Apr 8, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[DRAFT] PoC: TanStack Query Option B — `UIMessenger`-enforced background ownership + UI-side `staleTime` support#41102

[DRAFT] PoC: TanStack Query Option B — `UIMessenger`-enforced background ownership + UI-side `staleTime` support#41102
MajorLift wants to merge 18 commits intomainfrom
jongsun/poc/tq/ui-default-bg-sync

MajorLift commented Mar 20, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 20, 2026

Uh oh!

socket-security bot commented Mar 20, 2026 •

edited

Loading

Uh oh!

metamaskbotv2 bot commented Mar 20, 2026 •

edited

Loading

Uh oh!

MajorLift commented Mar 20, 2026

Uh oh!

metamaskbot commented Mar 20, 2026

Uh oh!

metamaskbotv2 bot commented Mar 20, 2026

📄 Localhost MetaMask Test Dapp

Summary

Uh oh!

metamaskbotv2 bot commented Mar 22, 2026

📄 Localhost MetaMask Test Dapp

Summary

Uh oh!

metamaskbotv2 bot commented Mar 23, 2026

📄 Localhost MetaMask Test Dapp

Summary

Uh oh!

metamaskbotv2 bot commented Mar 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

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

Uh oh!

PoC: TanStack Query Option B

Summary

Option A vs Option B

Ownership boundary enforcement

Option A: OmitKeyof

Option B: UIMessenger capability gating + lint rule

1. UIMessenger capability gating (Axis 2 — fetch ownership)

2. queryFn scope lint rule (Axis 2 — fetch authorship)

Per-screen vs per-client cache policy

What background proxy uniquely provides

Staleness indirection

Architecture

TQ usage by layer

Background-side TQ guidelines

Per-controller vs multi-endpoint data services

core-backend alignment

Model selection: UI-direct vs controller-driven

Shared queryKey staleTime behavior

Changelog

Related issues

Manual testing steps

Screenshots/Recordings

Before

After

Pre-merge author checklist

Pre-merge reviewer checklist

Uh oh!

github-actions bot commented Mar 20, 2026

Uh oh!

socket-security bot commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

✨ Files requiring CODEOWNER review ✨

Uh oh!

MajorLift commented Mar 20, 2026

Uh oh!

metamaskbot commented Mar 20, 2026

Uh oh!

metamaskbotv2 bot commented Mar 20, 2026

📄 Localhost MetaMask Test Dapp

Summary

Uh oh!

metamaskbotv2 bot commented Mar 22, 2026

📄 Localhost MetaMask Test Dapp

Summary

Uh oh!

metamaskbotv2 bot commented Mar 23, 2026

📄 Localhost MetaMask Test Dapp

Summary

Uh oh!

metamaskbotv2 bot commented Mar 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

MajorLift commented Mar 20, 2026 •

edited

Loading

Option A: `OmitKeyof`

2. `queryFn` scope lint rule (Axis 2 — fetch authorship)

`core-backend` alignment

socket-security bot commented Mar 20, 2026 •

edited

Loading

metamaskbotv2 bot commented Mar 20, 2026 •

edited

Loading