feat(core-backend): update websocket behavior (#6819)

## Explanation

### Current State & Motivation

The `core-backend` package had several architectural issues that needed
to be addressed:

1. **Inflexible Chain Management**: `AccountActivityService` was
proactively fetching supported chains from the Accounts API
(`/v2/supportedNetworks`) with a hardcoded fallback list. This approach
was:
- Out of sync with backend capabilities (client-side caching vs.
real-time backend state)
   - Unnecessarily complex with cache expiration logic
- Made assumptions about supported chains rather than reacting to actual
backend status

2. **Incomplete Connection Management**: `BackendWebSocketService` only
subscribed to `AuthenticationController:stateChange` events but didn't
directly respond to wallet lock/unlock events from `KeyringController`.
This created a dependency where connection management relied solely on
authentication state changes.

3. **Reconnection Logic Based on Close Codes**: The service used
WebSocket close codes to determine reconnection behavior, which was
fragile and didn't properly distinguish between manual disconnects (user
action) and unexpected disconnects (network issues).

4. **Type Mismatches**: The `Transaction` and `Asset` types didn't match
the backend API contract, causing potential integration issues.

5. **No Performance Monitoring**: There was no way to trace WebSocket
operations for performance analysis in production environments.

6. **Inconsistent Address Casing**: WebSocket-based token balance and
detection updates had inconsistent address normalization, causing issues
with state lookups and controller integration.

### Solution

#### 1. System Notification-Driven Chain Tracking
(`AccountActivityService`)

**Before**: Client proactively fetches and caches supported chains
```typescript
async getSupportedChains(): Promise<string[]> {
  // Fetch from API with cache + fallback to hardcoded list
}
```

**After**: Client reacts to backend system notifications
```typescript
#chainsUp: Set<string> = new Set();

// Backend automatically sends system notifications with chain status
// Service tracks chains dynamically based on real-time backend state
```

**Benefits**:
- Real-time chain status that matches backend capabilities
- No stale cache issues
- Simpler code (removed ~100 lines)
- Backend has single source of truth

**Flow**:
1. Client subscribes to account activity
2. Backend automatically sends system notification: `{chainIds:
['eip155:1', 'eip155:137'], status: 'up'}`
3. Service tracks these chains internally
4. On disconnect, service flushes all tracked chains as 'down'
5. On reconnect, backend sends fresh system notification with current
status

#### 2. Simplified Reconnection Logic (`BackendWebSocketService`)

**Before**: Reconnection based on close codes
```typescript
#shouldReconnectOnClose(code: number): boolean {
  return code !== 1000; // Only don't reconnect on normal closure
}
```

**After**: Reconnection based on manual disconnect flag
```typescript
#manualDisconnect = false;

connect() {
  this.#manualDisconnect = false; // Reset flag on explicit connect
}

disconnect() {
  this.#manualDisconnect = true; // Set flag to prevent auto-reconnect
}

onclose() {
  if (!this.#manualDisconnect) {
    this.#scheduleReconnect(); // Auto-reconnect unless manually disconnected
  }
}
```

**Benefits**:
- Clear intent: manual disconnects stay disconnected, unexpected
disconnects auto-reconnect
- No ambiguity with close codes
- Simpler logic

#### 3. KeyringController Event Integration

Added direct subscriptions to wallet lock state:

```typescript
#subscribeEvents() {
  // Sign in/out
  this.#messenger.subscribe('AuthenticationController:stateChange', ...);
  
  // Wallet lock/unlock (NEW)
  this.#messenger.subscribe('KeyringController:unlock', () => this.connect());
  this.#messenger.subscribe('KeyringController:lock', () => this.disconnect());
}
```

**Connection Requirements** (all must be true):
1. ✅ Feature enabled (`isEnabled()` callback)
2. ✅ User signed in (`AuthenticationController.isSignedIn`)
3. ✅ Wallet unlocked (`KeyringController` state)

#### 4. Type Alignment with Backend API

- `Transaction.hash` → `Transaction.id` (matches backend field name)
- `Asset` now requires `decimals: number` (needed for proper token
formatting)

#### 5. Performance Tracing Integration

Added optional `traceFn` parameter to enable performance monitoring:

```typescript
new BackendWebSocketService({
  messenger,
  url: BACKEND_WS_URL,
  traceFn: trace as TraceCallback, // Inject platform-specific trace function
  // ...other options
});
```

**Benefits**:
- Platform-agnostic tracing support (enables Sentry integration in
extension/mobile)
- Traces WebSocket operations (connect, disconnect methods)
- Enables performance monitoring in production
- Core package remains platform-agnostic with no-op default

**Integration**:
- **Extension**: Uses `trace` from `shared/lib/trace.ts` (Sentry-backed)
- **Mobile**: Uses `trace` from `app/util/trace.ts` (Sentry-backed)
- **Core**: Defaults to no-op if not provided, keeping the package
platform-agnostic

**Example usage**:
```typescript
// Extension/Mobile init files inject their platform-specific trace function
const service = new BackendWebSocketService({
  messenger,
  url: BACKEND_WS_URL,
  traceFn: trace as TraceCallback,
  // When operations occur, they're automatically traced:
  // - "BackendWebSocketService:connect"
  // - "BackendWebSocketService:disconnect"
});
```

#### 6. Address Normalization for WebSocket Updates
(`assets-controllers`)

Fixed inconsistent address casing in WebSocket-based token balance and
detection updates to ensure proper state lookups and controller
integration.

**TokenBalancesController** (`#onAccountActivityBalanceUpdate`):
- **Account addresses**: Normalized to lowercase for `tokenBalances`
state lookups
- **Token addresses**: Normalized to checksum format for `tokenBalances`
state storage
- **Native balance updates**: Uses checksummed account addresses for
`AccountTrackerController:updateNativeBalances`
- **New tokens**: Uses checksummed token addresses for
`TokensController:addTokens`

**TokenDetectionController** (`addDetectedTokensViaWs`):
- **Token addresses**: Explicitly normalized to checksum format before
calling `TokensController:addTokens`
- **Token cache lookups**: Uses lowercase token addresses for
`tokensChainsCache` lookups
- **Fresh cache**: Fetches `tokensChainsCache` at the start of the
method to prevent stale data

**Benefits**:
- Consistent address format across different state stores
- Prevents state lookup failures due to casing mismatches
- Ensures compatibility between controllers with different address
format expectations
- Robust handling without assumptions about input format

**Example**:
```typescript
// Before: Address casing was inconsistent
state.tokenBalances[address][tokenAddress] = balance; // Could fail if casing mismatched

// After: Explicit normalization
const normalizedAccount = address.toLowerCase();
const checksummedToken = toChecksumAddress(tokenAddress);
state.tokenBalances[normalizedAccount as Hex][checksummedToken] = balance;
```

### Breaking Changes Impact

**For `AccountActivityService` consumers**:
- ❌ **Removed**: `getSupportedChains()` method - consumers should
subscribe to `AccountActivityService:statusChanged` events instead
- Chain status is now event-driven rather than request-response

**For type definitions**:
- `Transaction` objects must use `id` instead of `hash`
- `Asset` objects must include `decimals` field

### Testing Updates

- Removed `nock` dependency (no longer fetching from external API)
- Updated all tests to use system notification-driven flow
- Added tests for KeyringController event integration
- Added tests for manual disconnect flag behavior
- Increased test coverage for edge cases in reconnection logic
- Updated `TokenDetectionController` tests to expect checksummed
addresses in `addTokens` calls

## References

- Part of ongoing core-backend stabilization effort
- Aligns with backend system notification architecture

## Checklist

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

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Revamps core-backend WebSocket lifecycle (keyring lock/unlock, manual
disconnect, tracing, new params/types, system notification–driven
chains) and fixes assets controllers to normalize addresses for
WebSocket token updates; docs/tests updated.
> 
> - **Core Backend (`@metamask/core-backend`)**:
> - **WebSocket**: New connection model (idempotent connect,
auto-reconnect unless manual disconnect), subscribes to
`KeyringController:lock/unlock`; exposes richer `getConnectionInfo`.
>   - **API Changes (BREAKING)**:
>     - `BackendWebSocketService.subscribe` now requires `channelType`.
> - Types: `Transaction.hash` → `id`; `Asset` adds required `decimals`;
`ServerNotificationMessage` includes `timestamp`.
> - Messenger/events expanded; add peer dep on
`@metamask/keyring-controller`.
> - **Tracing**: Optional `traceFn` to instrument
connect/disconnect/notifications.
> - **AccountActivityService**: Drops `getSupportedChains`; chains
tracked via system notifications; publishes `statusChanged` with
optional `timestamp`.
> - **Docs**: README updated with new flow and “WebSocket Connection
Management”.
> - **Assets Controllers**:
> - **TokenBalancesController**: Normalizes account (lowercase) and
token (checksum) for WS updates; fixes tracking checks; updates native
balance propagation; adds decimals handling in tests.
> - **TokenDetectionController**: Adds checksummed addresses and
lowercase cache lookups in `addDetectedTokensViaWs`; metrics use
checksummed addresses.
>   - **Changelog**: Notes fix for address casing in WS balance updates.
> - **Repo**:
> - README: adds `@metamask/core-backend` to package list and dependency
graph; minor graph edge additions.
> - Build/config: add keyring-controller refs; adjust dev/peer deps;
test updates to reflect new behavior.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
16e8b32. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: Kriys94

README.md

@@ -34,6 +34,7 @@ Each package in this repository has its own README where you can find installati
 - [`@metamask/chain-agnostic-permission`](packages/chain-agnostic-permission)
 - [`@metamask/composable-controller`](packages/composable-controller)
 - [`@metamask/controller-utils`](packages/controller-utils)
+- [`@metamask/core-backend`](packages/core-backend)
 - [`@metamask/delegation-controller`](packages/delegation-controller)
 - [`@metamask/earn-controller`](packages/earn-controller)
 - [`@metamask/eip-5792-middleware`](packages/eip-5792-middleware)
@@ -98,6 +99,7 @@ linkStyle default opacity:0.5
   chain_agnostic_permission(["@metamask/chain-agnostic-permission"]);
   composable_controller(["@metamask/composable-controller"]);
   controller_utils(["@metamask/controller-utils"]);
+  core_backend(["@metamask/core-backend"]);
   delegation_controller(["@metamask/delegation-controller"]);
   earn_controller(["@metamask/earn-controller"]);
   eip_5792_middleware(["@metamask/eip-5792-middleware"]);
@@ -159,6 +161,7 @@ linkStyle default opacity:0.5
   assets_controllers --> account_tree_controller;
   assets_controllers --> accounts_controller;
   assets_controllers --> approval_controller;
+  assets_controllers --> core_backend;
   assets_controllers --> keyring_controller;
   assets_controllers --> multichain_account_service;
   assets_controllers --> network_controller;
@@ -192,6 +195,11 @@ linkStyle default opacity:0.5
   chain_agnostic_permission --> permission_controller;
   composable_controller --> base_controller;
   composable_controller --> json_rpc_engine;
+  core_backend --> base_controller;
+  core_backend --> controller_utils;
+  core_backend --> profile_sync_controller;
+  core_backend --> accounts_controller;
+  core_backend --> keyring_controller;
   delegation_controller --> base_controller;
   delegation_controller --> accounts_controller;
   delegation_controller --> keyring_controller;
@@ -264,6 +272,7 @@ linkStyle default opacity:0.5
   permission_log_controller --> json_rpc_engine;
   phishing_controller --> base_controller;
   phishing_controller --> controller_utils;
+  phishing_controller --> transaction_controller;
   polling_controller --> base_controller;
   polling_controller --> controller_utils;
   polling_controller --> network_controller;

packages/assets-controllers/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- Fix address casing in WebSocket-based token balance updates to ensure consistency ([#6819](https://github.com/MetaMask/core/pull/6819))
+
 ## [80.0.0]
 
 ### Added

packages/assets-controllers/src/TokenBalancesController.test.ts

@@ -4328,6 +4328,7 @@ describe('TokenBalancesController', () => {
               type: `eip155:1/erc20:${tokenAddress}`,
               unit: 'USDC',
               fungible: true,
+              decimals: 6,
             },
             postBalance: {
               amount: '0xf4240', // 1000000 in hex (1 USDC with 6 decimals)
@@ -4378,6 +4379,7 @@ describe('TokenBalancesController', () => {
               type: 'eip155:1/slip44:60',
               unit: 'ETH',
               fungible: true,
+              decimals: 18,
             },
             postBalance: {
               amount: '0xde0b6b3a7640000', // 1 ETH in wei
@@ -4431,6 +4433,7 @@ describe('TokenBalancesController', () => {
               type: 'eip155:1/slip44:60',
               unit: 'ETH',
               fungible: true,
+              decimals: 18,
             },
             postBalance: {
               amount: '0',
@@ -4468,6 +4471,7 @@ describe('TokenBalancesController', () => {
               type: 'eip155:1/unknown:0x123',
               unit: 'UNKNOWN',
               fungible: true,
+              decimals: 18,
             },
             postBalance: {
               amount: '1000',
@@ -4650,6 +4654,7 @@ describe('TokenBalancesController', () => {
               type: `eip155:1/erc20:${token1}`,
               unit: 'USDC',
               fungible: true,
+              decimals: 6,
             },
             postBalance: {
               amount: '0xf4240', // 1000000 in hex
@@ -4661,6 +4666,7 @@ describe('TokenBalancesController', () => {
               type: `eip155:1/erc20:${token2}`,
               unit: 'USDT',
               fungible: true,
+              decimals: 6,
             },
             postBalance: {
               amount: '0x1e8480', // 2000000 in hex
@@ -4706,6 +4712,7 @@ describe('TokenBalancesController', () => {
               type: 'eip155:1/erc20:invalid-address', // Not a valid hex address
               unit: 'INVALID',
               fungible: true,
+              decimals: 18,
             },
             postBalance: { amount: '1000000' },
             transfers: [],
@@ -4780,6 +4787,7 @@ describe('TokenBalancesController', () => {
               type: `eip155:1/erc20:${newTokenAddress}`,
               unit: 'USDC',
               fungible: true,
+              decimals: 6,
             },
             postBalance: {
               amount: '0xf4240', // 1000000 in hex
@@ -4853,6 +4861,7 @@ describe('TokenBalancesController', () => {
               type: `eip155:1/erc20:${trackedTokenAddress}`,
               unit: 'USDC',
               fungible: true,
+              decimals: 6,
             },
             postBalance: {
               amount: '0xf4240', // 1000000 in hex
@@ -4916,6 +4925,7 @@ describe('TokenBalancesController', () => {
               type: `eip155:1/erc20:${ignoredTokenAddress}`,
               unit: 'USDC',
               fungible: true,
+              decimals: 6,
             },
             postBalance: {
               amount: '0xf4240', // 1000000 in hex
@@ -4973,6 +4983,7 @@ describe('TokenBalancesController', () => {
               type: 'eip155:1/slip44:60',
               unit: 'ETH',
               fungible: true,
+              decimals: 18,
             },
             postBalance: {
               amount: '0xde0b6b3a7640000', // 1 ETH in wei
@@ -5039,6 +5050,7 @@ describe('TokenBalancesController', () => {
               type: `eip155:1/erc20:${newTokenAddress}`,
               unit: 'USDC',
               fungible: true,
+              decimals: 6,
             },
             postBalance: {
               amount: '0xf4240', // 1000000 in hex
@@ -5109,6 +5121,7 @@ describe('TokenBalancesController', () => {
               type: `eip155:1/erc20:${trackedToken}`,
               unit: 'USDC',
               fungible: true,
+              decimals: 6,
             },
             postBalance: {
               amount: '0xf4240', // 1000000 in hex
@@ -5120,6 +5133,7 @@ describe('TokenBalancesController', () => {
               type: `eip155:1/erc20:${untrackedToken}`,
               unit: 'USDT',
               fungible: true,
+              decimals: 6,
             },
             postBalance: {
               amount: '0x1e8480', // 2000000 in hex

packages/assets-controllers/src/TokenBalancesController.ts

@@ -844,12 +844,10 @@ export class TokenBalancesController extends StaticIntervalPollingController<{
     account: ChecksumAddress,
     chainId: ChainIdHex,
   ): boolean {
-    const normalizedAddress = tokenAddress.toLowerCase();
-
     // Check if token exists in allTokens
     if (
       this.#allTokens?.[chainId]?.[account.toLowerCase()]?.some(
-        (token) => token.address.toLowerCase() === normalizedAddress,
+        (token) => token.address === tokenAddress,
       )
     ) {
       return true;
@@ -858,7 +856,7 @@ export class TokenBalancesController extends StaticIntervalPollingController<{
     // Check if token exists in allIgnoredTokens
     if (
       this.#allIgnoredTokens?.[chainId]?.[account.toLowerCase()]?.some(
-        (addr) => addr.toLowerCase() === normalizedAddress,
+        (token) => token === tokenAddress,
       )
     ) {
       return true;
@@ -1124,23 +1122,26 @@ export class TokenBalancesController extends StaticIntervalPollingController<{
     updates: BalanceUpdate[];
   }) => {
     const chainId = caipChainIdToHex(chain);
-    const account = checksum(address);
+    const checksummedAccount = checksum(address);
 
     try {
       // Process all balance updates at once
       const { tokenBalances, newTokens, nativeBalanceUpdates } =
-        this.#prepareBalanceUpdates(updates, account, chainId);
+        this.#prepareBalanceUpdates(updates, checksummedAccount, chainId);
 
       // Update state once with all token balances
       if (tokenBalances.length > 0) {
         this.update((state) => {
-          // Initialize account and chain structure
-          state.tokenBalances[account] ??= {};
-          state.tokenBalances[account][chainId] ??= {};
+          // Temporary until ADR to normalize all keys - tokenBalances state requires: account in lowercase, token in checksum
+          const lowercaseAccount =
+            checksummedAccount.toLowerCase() as ChecksumAddress;
+          state.tokenBalances[lowercaseAccount] ??= {};
+          state.tokenBalances[lowercaseAccount][chainId] ??= {};
 
           // Apply all token balance updates
           for (const { tokenAddress, balance } of tokenBalances) {
-            state.tokenBalances[account][chainId][tokenAddress] = balance;
+            state.tokenBalances[lowercaseAccount][chainId][tokenAddress] =
+              balance;
           }
         });
       }

packages/assets-controllers/src/TokenDetectionController.test.ts

@@ -3535,6 +3535,8 @@ describe('TokenDetectionController', () => {
   describe('addDetectedTokensViaWs', () => {
     it('should add tokens detected from websocket with metadata from cache', async () => {
       const mockTokenAddress = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48';
+      const checksummedTokenAddress =
+        '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
       const chainId = '0x1';
 
       await withController(
@@ -3581,7 +3583,7 @@ describe('TokenDetectionController', () => {
             'TokensController:addTokens',
             [
               {
-                address: mockTokenAddress,
+                address: checksummedTokenAddress,
                 decimals: 6,
                 symbol: 'USDC',
                 aggregators: [],
@@ -3652,7 +3654,11 @@ describe('TokenDetectionController', () => {
 
     it('should add all tokens provided without filtering (filtering is caller responsibility)', async () => {
       const mockTokenAddress = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48';
+      const checksummedTokenAddress =
+        '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
       const secondTokenAddress = '0x1f573d6fb3f13d689ff844b4ce37794d79a7ff1c';
+      const checksummedSecondTokenAddress =
+        '0x1F573D6Fb3F13d689FF844B4cE37794d79a7FF1C';
       const chainId = '0x1';
       const selectedAccount = createMockInternalAccount({
         address: '0x0000000000000000000000000000000000000001',
@@ -3718,7 +3724,7 @@ describe('TokenDetectionController', () => {
             'TokensController:addTokens',
             [
               {
-                address: mockTokenAddress,
+                address: checksummedTokenAddress,
                 decimals: 6,
                 symbol: 'USDC',
                 aggregators: [],
@@ -3727,7 +3733,7 @@ describe('TokenDetectionController', () => {
                 name: 'USD Coin',
               },
               {
-                address: secondTokenAddress,
+                address: checksummedSecondTokenAddress,
                 decimals: 18,
                 symbol: 'BNT',
                 aggregators: [],
@@ -3744,6 +3750,8 @@ describe('TokenDetectionController', () => {
 
     it('should track metrics when adding tokens from websocket', async () => {
       const mockTokenAddress = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48';
+      const checksummedTokenAddress =
+        '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
       const chainId = '0x1';
       const mockTrackMetricsEvent = jest.fn();
 
@@ -3793,7 +3801,7 @@ describe('TokenDetectionController', () => {
             event: 'Token Detected',
             category: 'Wallet',
             properties: {
-              tokens: [`USDC - ${mockTokenAddress}`],
+              tokens: [`USDC - ${checksummedTokenAddress}`],
               token_standard: 'ERC20',
               asset_type: 'TOKEN',
             },
@@ -3810,6 +3818,8 @@ describe('TokenDetectionController', () => {
 
     it('should be callable directly as a public method on the controller instance', async () => {
       const mockTokenAddress = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48';
+      const checksummedTokenAddress =
+        '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
       const chainId = '0x1';
 
       await withController(
@@ -3857,7 +3867,7 @@ describe('TokenDetectionController', () => {
             'TokensController:addTokens',
             [
               {
-                address: mockTokenAddress,
+                address: checksummedTokenAddress,
                 decimals: 6,
                 symbol: 'USDC',
                 aggregators: [],

packages/assets-controllers/src/TokenDetectionController.ts

@@ -15,6 +15,7 @@ import {
   ERC20,
   safelyExecute,
   isEqualCaseInsensitive,
+  toChecksumHexAddress,
 } from '@metamask/controller-utils';
 import type {
   KeyringControllerGetStateAction,
@@ -1042,27 +1043,28 @@ export class TokenDetectionController extends StaticIntervalPollingController<To
     const tokensWithBalance: Token[] = [];
     const eventTokensDetails: string[] = [];
 
-    for (const nonZeroTokenAddress of tokensSlice) {
-      // Check map of validated tokens
+    for (const tokenAddress of tokensSlice) {
+      // Normalize addresses explicitly (don't assume input format)
+      const lowercaseTokenAddress = tokenAddress.toLowerCase();
+      const checksummedTokenAddress = toChecksumHexAddress(tokenAddress);
+
+      // Check map of validated tokens (cache keys are lowercase)
       const tokenData =
-        this.#tokensChainsCache[chainId]?.data?.[
-          nonZeroTokenAddress.toLowerCase()
-        ];
+        this.#tokensChainsCache[chainId]?.data?.[lowercaseTokenAddress];
 
       if (!tokenData) {
         console.warn(
-          `Token metadata not found in cache for ${nonZeroTokenAddress} on chain ${chainId}`,
+          `Token metadata not found in cache for ${tokenAddress} on chain ${chainId}`,
         );
         continue;
       }
 
-      const { decimals, symbol, aggregators, iconUrl, name, address } =
-        tokenData;
+      const { decimals, symbol, aggregators, iconUrl, name } = tokenData;
 
-      // Push to lists
-      eventTokensDetails.push(`${symbol} - ${address}`);
+      // Push to lists with checksummed address (for allTokens storage)
+      eventTokensDetails.push(`${symbol} - ${checksummedTokenAddress}`);
       tokensWithBalance.push({
-        address,
+        address: checksummedTokenAddress,
         decimals,
         symbol,
         aggregators,

packages/core-backend/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **BREAKING:** Add required argument `channelType` to `BackendWebSocketService.subscribe` method ([#6819](https://github.com/MetaMask/core/pull/6819))
+  - Add `channelType` to argument of the `BackendWebSocketService:subscribe` messenger action
+  - Add `channelType` to `WebSocketSubscription` type
+- **BREAKING**: Update `Asset` type definition: add required `decimals` field for proper token amount formatting ([#6819](https://github.com/MetaMask/core/pull/6819))
+- Add optional `traceFn` parameter to `BackendWebSocketService` constructor for performance tracing integration (e.g., Sentry) ([#6819](https://github.com/MetaMask/core/pull/6819))
+  - Enables tracing of WebSocket operations including connect, disconnect methods
+  - Trace function receives operation metadata and callback to wrap for performance monitoring
+- Add optional `timestamp` property to `ServerNotificationMessage` and `SystemNoticationData` types ([#6819](https://github.com/MetaMask/core/pull/6819))
+- Add optional `timestamp` property to `AccountActivityService:statusChanged` event and corresponding event type ([#6819](https://github.com/MetaMask/core/pull/6819))
+
+### Changed
+
+- **BREAKING:** Update `BackendWebSocketService` to automatically manage WebSocket connections based on wallet lock state ([#6819](https://github.com/MetaMask/core/pull/6819))
+  - `KeyringController:lock` and `KeyringController:unlock` are now required events in the `BackendWebSocketService` messenger
+- **BREAKING**: Update `Transaction` type definition: rename `hash` field to `id` for consistency with backend API ([#6819](https://github.com/MetaMask/core/pull/6819))
+- **BREAKING:** Add peer dependency on `@metamask/keyring-controller` (^23.0.0) ([#6819](https://github.com/MetaMask/core/pull/6819))
+- Update `BackendWebSocketService` to simplify reconnection logic: auto-reconnect on any unexpected disconnect (not just code 1000), stay disconnected when manually disconnecting via `disconnect` ([#6819](https://github.com/MetaMask/core/pull/6819))
+- Improve error handling in `BackendWebSocketService.connect()` to properly rethrow errors to callers ([#6819](https://github.com/MetaMask/core/pull/6819))
+- Update `AccountActivityService` to replace API-based chain support detection with system notification-driven chain tracking ([#6819](https://github.com/MetaMask/core/pull/6819))
+  - Instead of hardcoding a list of supported chains, assume that the backend has the list
+  - When receiving a system notification, capture the backend-tracked status of each chain instead of assuming it is up or down
+  - Flush all tracked chains as 'down' on disconnect/error (instead of using hardcoded list)
+- Update documentation in `README.md` to reflect new connection management model and chain tracking behavior ([#6819](https://github.com/MetaMask/core/pull/6819))
+  - Add "WebSocket Connection Management" section explaining connection requirements and behavior
+  - Update sequence diagram to show system notification-driven chain status flow
+  - Update key flow characteristics to reflect internal chain tracking mechanism
+
+### Removed
+
+- **BREAKING**: Remove `getSupportedChains` method from `AccountActivityService` ([#6819](https://github.com/MetaMask/core/pull/6819))
+
 ## [1.0.1]
 
 ### Changed