chore: add OHLCVService for real-time candlestick WebSocket streaming (#8695)

## Explanation

### Architecture Overview

```
┌─────────────────┐        messenger         ┌──────────────────────────┐
│   OHLCVService   │ ─── calls actions ────► │  BackendWebSocketService  │
│  (domain logic)  │                          │  (raw WS connection)      │
│                  │ ◄── listens to events ── │                           │
└────────┬────────┘                           └──────────┬───────────────┘
         │                                               │
    publishes events                              actual WebSocket
    to UI consumers                          (connect, auth, reconnect,
                                              heartbeat, JSON framing)
         │
         ▼
┌──────────────────┐
│   Mobile UI       │
│  (React hooks)    │
│  useOHLCVRealtime │
└──────────────────┘
```

### What

- Add `OHLCVService` for real-time OHLCV (candlestick) data streaming
via the backend WebSocket gateway
- Move all WebSocket-related files (`BackendWebSocketService`,
`AccountActivityService`) into a new `src/ws/` directory per code review
feedback

### Why

- Enable real-time chart updates on the Token Details screen without
polling
- Reduce API load by replacing periodic HTTP calls with persistent
WebSocket subscriptions
- Organize WebSocket code into a dedicated `ws/` folder for better
discoverability

### New files

- `src/ws/ohlcv/OHLCVService.ts` — main service with
subscribe/unsubscribe semantics, reference counting, grace-period
unsubscribe, idempotency checks, chain-status forwarding, and automatic
resubscription on reconnect
- `src/ws/ohlcv/OHLCVService.test.ts` — 22 unit tests covering all paths
(100% branch coverage)
- `src/ws/ohlcv/OHLCVService-method-action-types.ts` — auto-generated
messenger action types
- `src/ws/ohlcv/types.ts` — `OHLCVBar` and `OHLCVSubscriptionOptions`
types
- `src/ws/ohlcv/index.ts` — barrel exports

### Modified files

- `src/index.ts` — added exports for `OHLCVService`, its types, and
allowed actions/events; updated import paths to `./ws/`
- `eslint-suppressions.json` — updated paths for moved files, added
suppressions for new test file
- `CHANGELOG.md` — documented new service and exports

### Moved files (no logic changes)

- `src/BackendWebSocketService.ts` → `src/ws/BackendWebSocketService.ts`
- `src/BackendWebSocketService.test.ts` →
`src/ws/BackendWebSocketService.test.ts`
- `src/BackendWebSocketService-method-action-types.ts` →
`src/ws/BackendWebSocketService-method-action-types.ts`
- `src/AccountActivityService.ts` → `src/ws/AccountActivityService.ts`
- `src/AccountActivityService.test.ts` →
`src/ws/AccountActivityService.test.ts`
- `src/AccountActivityService-method-action-types.ts` →
`src/ws/AccountActivityService-method-action-types.ts`
- Only import path updates (`./logger` → `../logger`, `./types` →
`../types`, test helper paths)

### Key design decisions

- **UI-driven lifecycle** — unlike `AccountActivityService`
(auto-subscribes on account change), `OHLCVService` exposes
`subscribe()`/`unsubscribe()` called by the UI when the chart
mounts/unmounts
- **Reference counting** — multiple UI consumers subscribing to the same
assetId/interval/currency share one WebSocket subscription
- **Grace period (3s)** — when all consumers unsubscribe, actual WS
unsubscribe is delayed 3 seconds to absorb rapid navigation (Token A →
Token B → Token A)
- **Idempotency** — uses `channelHasSubscription` before subscribing;
duplicate calls are no-ops (React Strict Mode safe)
- **Chain status** — listens to `system-notifications.v1.market-data.v1`
(auto-subscribed by server) and publishes
`OHLCVService:chainStatusChanged`
- **Disconnect handling** — on WebSocket disconnect, publishes
`chainStatusChanged { status: 'down' }` for all tracked chains,
triggering UI polling fallback
- **Reconnect** — resubscribes all active channels when WebSocket
reconnects (no `sessionId` needed for OHLCV; UI polling fallback covers
the gap)
- **`init()` method** — system notification callback registered in
`init()` (not constructor) to comply with messenger-in-constructor lint
rule

### Events published

- `OHLCVService:barUpdated` — `{ channel, bar: OHLCVBar }` — new candle
data from WebSocket
- `OHLCVService:chainStatusChanged` — `{ chainIds, status, timestamp? }`
— chain up/down (server notification or WS disconnect)
- `OHLCVService:subscriptionError` — `{ channel, error, operation }` —
subscribe or unsubscribe failure

## References

* Related to
https://www.notion.so/metamask-consensys/OHLCV-WebSocket-Integration-UI-Implementation-Guide-346f86d67d6880b6a70fc3be0f0c34b9
* Related to MetaMask/metamask-mobile#29739
* Fixes https://consensyssoftware.atlassian.net/browse/ASSETS-3195

## Checklist

- [ ] I've updated the test suite for new or updated code as appropriate
- [ ] I've updated documentation (JSDoc, Markdown, etc.) for new or
updated code as appropriate
- [ ] I've communicated my changes to consumers by [updating changelogs
for packages I've
changed](https://github.com/MetaMask/core/tree/main/docs/processes/updating-changelogs.md)
- [ ] I've introduced [breaking
changes](https://github.com/MetaMask/core/tree/main/docs/processes/breaking-changes.md)
in this PR and have prepared draft pull requests for clients and
consumer packages to resolve them


<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Adds a new WebSocket-driven market-data service with reference
counting, timers, and reconnect resubscription logic, which can affect
subscription lifecycles and event delivery. Also moves existing
WebSocket services into `src/ws/`, so consumers relying on internal
paths (vs package exports) could break if any remain.
> 
> **Overview**
> Adds a new `OHLCVService` to stream real-time OHLCV bars over
WebSocket, exposing `subscribe`/`unsubscribe` via messenger actions,
publishing `barUpdated`/`chainStatusChanged`/`subscriptionError` events,
and handling reconnect resubscription with ref-counting plus a
grace-period unsubscribe (mutex-protected).
> 
> Refactors `core-backend` by moving `BackendWebSocketService` and
`AccountActivityService` (and their tests/action-type files) into
`src/ws/`, updating imports/exports (`src/index.ts`), and updating lint
suppressions; also adds `async-mutex` plus comprehensive unit tests for
the new service and documents the addition in the changelog.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
730af62. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: sahar-fehri

eslint-suppressions.json

@@ -862,34 +862,45 @@
       "count": 1
     }
   },
-  "packages/core-backend/src/AccountActivityService.test.ts": {
+  "packages/core-backend/src/api/shared-types.ts": {
     "no-restricted-syntax": {
-      "count": 2
+      "count": 1
     }
   },
-  "packages/core-backend/src/AccountActivityService.ts": {
+  "packages/core-backend/src/index.ts": {
     "no-restricted-syntax": {
-      "count": 1
+      "count": 4
     }
   },
-  "packages/core-backend/src/BackendWebSocketService.test.ts": {
+  "packages/core-backend/src/ws/AccountActivityService.test.ts": {
     "no-restricted-syntax": {
-      "count": 1
+      "count": 2
     }
   },
-  "packages/core-backend/src/BackendWebSocketService.ts": {
+  "packages/core-backend/src/ws/AccountActivityService.ts": {
     "no-restricted-syntax": {
-      "count": 5
+      "count": 1
     }
   },
-  "packages/core-backend/src/api/shared-types.ts": {
+  "packages/core-backend/src/ws/BackendWebSocketService.test.ts": {
     "no-restricted-syntax": {
       "count": 1
     }
   },
-  "packages/core-backend/src/index.ts": {
+  "packages/core-backend/src/ws/BackendWebSocketService.ts": {
     "no-restricted-syntax": {
+      "count": 5
+    }
+  },
+  "packages/core-backend/src/ws/ohlcv/OHLCVService.test.ts": {
+    "@typescript-eslint/naming-convention": {
       "count": 2
+    },
+    "id-length": {
+      "count": 1
+    },
+    "no-restricted-syntax": {
+      "count": 1
     }
   },
   "packages/delegation-controller/src/DelegationController.test.ts": {

packages/core-backend/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add `OHLCVService` for real-time OHLCV (candlestick) data streaming via WebSocket ([#8695](https://github.com/MetaMask/core/pull/8695))
+  - Wraps `BackendWebSocketService` through the messenger pattern to provide subscribe/unsubscribe semantics for market-data OHLCV channels
+  - Includes reference counting, grace-period unsubscribe, idempotency checks, chain-status forwarding, and automatic resubscription on reconnect
+- Export new types `OHLCVBar`, `OHLCVSubscriptionOptions`, `OHLCVSystemNotificationData`, `OHLCVServiceOptions`, `OHLCVServiceActions`, `OHLCVServiceAllowedActions`, `OHLCVServiceBarUpdatedEvent`, `OHLCVServiceChainStatusChangedEvent`, `OHLCVServiceSubscriptionErrorEvent`, `OHLCVServiceEvents`, `OHLCVServiceAllowedEvents`, and `OHLCVServiceMessenger` ([#8695](https://github.com/MetaMask/core/pull/8695))
+- Export new constants `OHLCV_SERVICE_ALLOWED_ACTIONS` and `OHLCV_SERVICE_ALLOWED_EVENTS` for configuring the messenger ([#8695](https://github.com/MetaMask/core/pull/8695))
+
 ### Changed
 
 - Bump `@metamask/accounts-controller` from `^38.1.0` to `^38.1.1` ([#8774](https://github.com/MetaMask/core/pull/8774))

packages/core-backend/package.json

@@ -60,6 +60,7 @@
     "@metamask/profile-sync-controller": "^28.1.0",
     "@metamask/utils": "^11.9.0",
     "@tanstack/query-core": "^5.62.16",
+    "async-mutex": "^0.5.0",
     "uuid": "^8.3.2"
   },
   "devDependencies": {

packages/core-backend/src/index.ts

@@ -9,7 +9,7 @@ export {
   getCloseReason,
   WebSocketState,
   WebSocketEventType,
-} from './BackendWebSocketService';
+} from './ws/BackendWebSocketService';
 
 export type {
   BackendWebSocketServiceOptions,
@@ -24,7 +24,7 @@ export type {
   BackendWebSocketServiceConnectionStateChangedEvent,
   BackendWebSocketServiceEvents,
   BackendWebSocketServiceMessenger,
-} from './BackendWebSocketService';
+} from './ws/BackendWebSocketService';
 
 // ============================================================================
 // ACCOUNT ACTIVITY SERVICE
@@ -34,7 +34,7 @@ export {
   AccountActivityService,
   ACCOUNT_ACTIVITY_SERVICE_ALLOWED_ACTIONS,
   ACCOUNT_ACTIVITY_SERVICE_ALLOWED_EVENTS,
-} from './AccountActivityService';
+} from './ws/AccountActivityService';
 
 export type {
   SystemNotificationData,
@@ -49,7 +49,7 @@ export type {
   AccountActivityServiceEvents,
   AllowedEvents as AccountActivityServiceAllowedEvents,
   AccountActivityServiceMessenger,
-} from './AccountActivityService';
+} from './ws/AccountActivityService';
 
 // ============================================================================
 // SHARED TYPES
@@ -80,6 +80,31 @@ export type {
   ApiPlatformClientServiceMessenger,
 } from './ApiPlatformClientService';
 
+// ============================================================================
+// OHLCV SERVICE
+// ============================================================================
+
+export {
+  OHLCVService,
+  OHLCV_SERVICE_ALLOWED_ACTIONS,
+  OHLCV_SERVICE_ALLOWED_EVENTS,
+} from './ws/ohlcv';
+
+export type {
+  OHLCVBar,
+  OHLCVSubscriptionOptions,
+  OHLCVSystemNotificationData,
+  OHLCVServiceOptions,
+  OHLCVServiceActions,
+  OHLCVServiceAllowedActions,
+  OHLCVServiceBarUpdatedEvent,
+  OHLCVServiceChainStatusChangedEvent,
+  OHLCVServiceSubscriptionErrorEvent,
+  OHLCVServiceEvents,
+  OHLCVServiceAllowedEvents,
+  OHLCVServiceMessenger,
+} from './ws/ohlcv';
+
 // ============================================================================
 // API PLATFORM CLIENT
 // ============================================================================

…ntActivityService-method-action-types.ts …ntActivityService-method-action-types.tspackages/core-backend/src/AccountActivityService-method-action-types.ts renamed to packages/core-backend/src/ws/AccountActivityService-method-action-types.ts packages/core-backend/src/AccountActivityService-method-action-types.ts renamed to packages/core-backend/src/ws/AccountActivityService-method-action-types.ts

@@ -7,16 +7,16 @@ import type {
 } from '@metamask/messenger';
 import type { Hex } from '@metamask/utils';
 
-import { flushPromises } from '../../../tests/helpers';
+import { flushPromises } from '../../../../tests/helpers';
+import type { Transaction, BalanceUpdate } from '../types';
+import type { AccountActivityMessage } from '../types';
 import { AccountActivityService } from './AccountActivityService';
 import type {
   AccountActivityServiceMessenger,
   SubscriptionOptions,
 } from './AccountActivityService';
 import type { ServerNotificationMessage } from './BackendWebSocketService';
 import { WebSocketState } from './BackendWebSocketService';
-import type { Transaction, BalanceUpdate } from './types';
-import type { AccountActivityMessage } from './types';
 
 type AllAccountActivityServiceActions =
   MessengerActions<AccountActivityServiceMessenger>;

…ckend/src/AccountActivityService.test.ts …nd/src/ws/AccountActivityService.test.tspackages/core-backend/src/AccountActivityService.test.ts renamed to packages/core-backend/src/ws/AccountActivityService.test.ts packages/core-backend/src/AccountActivityService.test.ts renamed to packages/core-backend/src/ws/AccountActivityService.test.ts

@@ -13,6 +13,12 @@ import type { TraceCallback } from '@metamask/controller-utils';
 import type { InternalAccount } from '@metamask/keyring-internal-api';
 import type { Messenger } from '@metamask/messenger';
 
+import { projectLogger, createModuleLogger } from '../logger';
+import type {
+  Transaction,
+  AccountActivityMessage,
+  BalanceUpdate,
+} from '../types';
 import type { AccountActivityServiceMethodActions } from './AccountActivityService-method-action-types';
 import type {
   WebSocketConnectionInfo,
@@ -21,12 +27,6 @@ import type {
 } from './BackendWebSocketService';
 import { WebSocketState } from './BackendWebSocketService';
 import type { BackendWebSocketServiceMethodActions } from './BackendWebSocketService-method-action-types';
-import { projectLogger, createModuleLogger } from './logger';
-import type {
-  Transaction,
-  AccountActivityMessage,
-  BalanceUpdate,
-} from './types';
 
 // =============================================================================
 // Types and Constants

…re-backend/src/AccountActivityService.ts …backend/src/ws/AccountActivityService.tspackages/core-backend/src/AccountActivityService.ts renamed to packages/core-backend/src/ws/AccountActivityService.ts packages/core-backend/src/AccountActivityService.ts renamed to packages/core-backend/src/ws/AccountActivityService.ts

@@ -5,7 +5,7 @@ import type {
   MockAnyNamespace,
 } from '@metamask/messenger';
 
-import { flushPromises } from '../../../tests/helpers';
+import { flushPromises } from '../../../../tests/helpers';
 import {
   BackendWebSocketService,
   getCloseReason,

…dWebSocketService-method-action-types.ts …dWebSocketService-method-action-types.tspackages/core-backend/src/BackendWebSocketService-method-action-types.ts renamed to packages/core-backend/src/ws/BackendWebSocketService-method-action-types.ts packages/core-backend/src/BackendWebSocketService-method-action-types.ts renamed to packages/core-backend/src/ws/BackendWebSocketService-method-action-types.ts

@@ -9,8 +9,8 @@ import type { AuthenticationController } from '@metamask/profile-sync-controller
 import { getErrorMessage } from '@metamask/utils';
 import { v4 as uuidV4 } from 'uuid';
 
+import { projectLogger, createModuleLogger } from '../logger';
 import type { BackendWebSocketServiceMethodActions } from './BackendWebSocketService-method-action-types';
-import { projectLogger, createModuleLogger } from './logger';
 
 const SERVICE_NAME = 'BackendWebSocketService' as const;