feat(core-backend): update websocket behavior #6819
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -16,6 +16,9 @@ Core backend services for MetaMask, serving as the data layer between Backend se | |
| - [Data Flow](#data-flow) | ||
| - [Sequence Diagram: Real-time Account Activity Flow](#sequence-diagram-real-time-account-activity-flow) | ||
| - [Key Flow Characteristics](#key-flow-characteristics) | ||
| - [WebSocket Connection Management](#websocket-connection-management) | ||
| - [Connection Requirements](#connection-requirements) | ||
| - [Connection Behavior](#connection-behavior) | ||
| - [API Reference](#api-reference) | ||
| - [BackendWebSocketService](#backendwebsocketservice) | ||
| - [Constructor Options](#constructor-options) | ||
|
|
@@ -227,16 +230,17 @@ sequenceDiagram | |
| Backend->>WS: Connection established | ||
| WS->>AA: WebSocket connection status notification<br/>(BackendWebSocketService:connectionStateChanged)<br/>{state: 'CONNECTED'} | ||
|
|
||
| AA->>AA: call('AccountsController:getSelectedAccount') | ||
| AA->>WS: subscribe({channels, callback}) | ||
| WS->>Backend: {event: 'subscribe', channels: ['account-activity.v1.eip155:0:0x123...']} | ||
| Backend->>WS: {event: 'subscribe-response', subscriptionId: 'sub-456'} | ||
|
|
||
| Note over WS,Backend: System notification sent automatically upon subscription | ||
| Backend->>WS: {event: 'system-notification', data: {chainIds: ['eip155:1', 'eip155:137', ...], status: 'up'}} | ||
| WS->>AA: System notification received | ||
| AA->>AA: Track chains as 'up' internally | ||
| AA->>TBC: Chain availability notification<br/>(AccountActivityService:statusChanged)<br/>{chainIds: ['0x1', '0x89', ...], status: 'up'} | ||
| TBC->>TBC: Increase polling interval from 20s to 10min<br/>(.updateChainPollingConfigs({0x89: 600000})) | ||
|
|
||
| Note over TBC,Backend: User Account Change | ||
|
|
||
|
|
@@ -285,24 +289,60 @@ sequenceDiagram | |
| Note over TBC,Backend: Connection Health Management | ||
|
|
||
| Backend-->>WS: Connection lost | ||
| WS->>AA: WebSocket connection status notification<br/>(BackendWebSocketService:connectionStateChanged)<br/>{state: 'DISCONNECTED'} | ||
| AA->>AA: Mark all tracked chains as 'down'<br/>(flush internal tracking set) | ||
| AA->>TBC: Chain status notification for all tracked chains<br/>(AccountActivityService:statusChanged)<br/>{chainIds: ['0x1', '0x89', ...], status: 'down'} | ||
| TBC->>TBC: Decrease polling interval from 10min to 20s<br/>(.updateChainPollingConfigs({0x89: 20000})) | ||
| TBC->>HTTP: Fetch balances immediately | ||
| WS->>WS: Automatic reconnection<br/>with exponential backoff | ||
| WS->>Backend: Reconnection successful | ||
|
|
||
| Note over AA,Backend: Restart initial setup - resubscribe and get fresh chain status | ||
| AA->>WS: subscribe (same account, new subscription) | ||
| WS->>Backend: {event: 'subscribe', channels: ['account-activity.v1.eip155:0:0x123...']} | ||
| Backend->>WS: {event: 'subscribe-response', subscriptionId: 'sub-999'} | ||
| Backend->>WS: {event: 'system-notification', data: {chainIds: [...], status: 'up'}} | ||
| WS->>AA: System notification received | ||
| AA->>AA: Track chains as 'up' again | ||
| AA->>TBC: Chain availability notification<br/>(AccountActivityService:statusChanged)<br/>{chainIds: [...], status: 'up'} | ||
| TBC->>TBC: Increase polling interval back to 10min | ||
| ``` | ||
|
|
||
| #### Key Flow Characteristics | ||
|
|
||
| 1. **Initial Setup**: BackendWebSocketService establishes connection, then AccountActivityService subscribes to selected account. Backend automatically sends a system notification with all chains that are currently up. AccountActivityService tracks these chains internally and notifies TokenBalancesController, which increases polling interval to 5 min | ||
| 2. **Chain Status Tracking**: AccountActivityService maintains an internal set of chains that are 'up' based on system notifications. On disconnect/error, it marks all tracked chains as 'down' before clearing the set | ||
| 3. **System Notifications**: Backend automatically sends chain status updates (up/down) upon subscription and when status changes. AccountActivityService forwards these to TokenBalancesController, which adjusts polling intervals (up: 5min, down: 30s + immediate fetch) | ||
| 4. **User Account Changes**: When users switch accounts, AccountActivityService unsubscribes from old account and subscribes to new account. Backend sends fresh system notification with current chain status for the new account | ||
| 5. **Connection Resilience**: On reconnection, AccountActivityService resubscribes to selected account and receives fresh chain status via system notification. Automatic reconnection with exponential backoff | ||
| 6. **Real-time Updates**: Backend pushes data through: Backend → BackendWebSocketService → AccountActivityService → TokenBalancesController (+ future TransactionController integration) | ||
| 7. **Parallel Processing**: Transaction and balance updates processed simultaneously - AccountActivityService publishes both transactionUpdated (future) and balanceUpdated events in parallel | ||
| 8. **Direct Balance Processing**: Real-time balance updates bypass HTTP polling and update TokenBalancesController state directly | ||
|
|
||
| ## WebSocket Connection Management | ||
|
|
||
| ### Connection Requirements | ||
|
|
||
| The WebSocket connects when **ALL 3 conditions are true**: | ||
|
|
||
| 1. ✅ **Feature enabled** - `isEnabled()` callback returns `true` (feature flag) | ||
| 2. ✅ **User signed in** - `AuthenticationController.isSignedIn = true` | ||
| 3. ✅ **Wallet unlocked** - `KeyringController.isUnlocked = true` | ||
|
|
||
| **Plus:** Platform code must call `connect()` when app opens/foregrounds and `disconnect()` when app closes/backgrounds. | ||
|
|
||
| ### Connection Behavior | ||
|
|
||
| **Idempotent `connect()`:** | ||
|
|
||
| - Safe to call multiple times - validates conditions and returns early if already connected | ||
| - Multiple rapid calls reuse the same connection promise (no duplicate connections) | ||
| - No debouncing needed - handled automatically | ||
|
|
||
| **Auto-Reconnect:** | ||
|
|
||
| - ✅ **Unexpected disconnects** (network issues, server restart) → Auto-reconnect | ||
| - ❌ **Manual disconnects** (app backgrounds, wallet locks, user signs out) → Stay disconnected | ||
|
|
||
| ## API Reference | ||
|
|
||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -56,19 +56,20 @@ | |
| "devDependencies": { | ||
| "@metamask/accounts-controller": "^33.1.1", | ||
| "@metamask/auto-changelog": "^3.4.4", | ||
| "@metamask/keyring-controller": "^23.1.1", | ||
| "@ts-bridge/cli": "^0.6.1", | ||
| "@types/jest": "^27.4.1", | ||
| "deepmerge": "^4.2.2", | ||
| "jest": "^27.5.1", | ||
| "sinon": "^9.2.4", | ||
| "ts-jest": "^27.1.4", | ||
| "typedoc": "^0.24.8", | ||
| "typedoc-plugin-missing-exports": "^2.0.0", | ||
| "typescript": "~5.2.2" | ||
| }, | ||
| "peerDependencies": { | ||
| "@metamask/accounts-controller": "^33.1.0", | ||
| "@metamask/keyring-controller": "^23.0.0" | ||
| }, | ||
| "engines": { | ||
| "node": "^18.18 || >=20" | ||
|
|
||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
A few notes:
connect,disconnect, etc. (And to be clear, if a change is "breaking" it means that there is some change that needs to be made on the client side to adjust to the change or else an error at compile-time or runtime will occur.)Putting this together, what if we do something like this: