feat(core-backend): add package #6722
Merged
Conversation
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
Kriys94
changed the title
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
mcmire
reviewed
Sep 25, 2025
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
juanmigdr
reviewed
Sep 29, 2025
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
mcmire
reviewed
Sep 29, 2025
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Kriys94
force-pushed
the
feature/core-backend-platform
branch
from
5b566ef to
1257213
Compare
Kriys94
force-pushed
the
feature/core-backend-platform
branch
from
a179f5c to
7a73ee0
Compare
Prithpal-Sooriya
previously approved these changes
Oct 7, 2025
Prithpal-Sooriya
previously approved these changes
Oct 7, 2025
4 tasks
mcmire
previously approved these changes
Oct 7, 2025
Kriys94
force-pushed
the
feature/core-backend-platform
branch
from
6670c5b to
bc80f5a
Compare
|
@metamaskbot publish-preview |
|
Preview builds have been published. See these instructions for more information about preview builds. Expand for full list of packages and versions. |
Kriys94
added a commit
that referenced
this pull request
Oct 8, 2025
## Release @metamask/core-backend@1.0.0 This PR releases the initial version of the `@metamask/core-backend` package. ### 📦 Package Overview `@metamask/core-backend` provides core backend services for MetaMask, serving as the data layer between Backend services (REST APIs, WebSocket services) and Frontend applications (Extension, Mobile). This package enables authenticated real-time data delivery with type-safe controller integration. ### ✨ What's New in v1.0.0 This is the **initial release** of the package, introducing: #### Core Services - **BackendWebSocketService** - WebSocket client providing authenticated real-time data delivery with: - Connection management and automatic reconnection with exponential backoff - Message routing and subscription management - Authentication integration with `AuthenticationController` - Type-safe messenger-based API for controller integration - **AccountActivityService** - High-level service for monitoring account activity with: - Real-time account activity monitoring via WebSocket subscriptions - Balance update notifications for integration with `TokenBalancesController` - Chain status change notifications for dynamic polling coordination - Account subscription management with automatic cleanup #### Infrastructure - **Type definitions** - Comprehensive TypeScript types for transactions, balances, WebSocket messages, and service configurations - **Logging infrastructure** - Structured logging with module-specific loggers for debugging and monitoring ### 📄 Changelog See [CHANGELOG.md](https://github.com/MetaMask/core/blob/main/packages/core-backend/CHANGELOG.md) for full details. ### 🔗 Related PR - Initial implementation: #6722 ### ✅ Release Checklist - [x] Version bump is correct (1.0.0 for initial release) - [x] Changelog entries are accurate and comprehensive - [x] All changes are properly documented - [x] Package is ready for publication - [x] No additional changes from `main` need to be incorporated ### 📚 Documentation - [Package README](https://github.com/MetaMask/core/blob/main/packages/core-backend/README.md) - [Architecture documentation](https://github.com/MetaMask/core/blob/main/packages/core-backend/README.md#architecture--design) ---
Kriys94
added a commit
that referenced
this pull request
Oct 8, 2025
## Release @metamask/core-backend@1.0.0 This PR releases the initial version of the `@metamask/core-backend` package. ### 📦 Package Overview `@metamask/core-backend` provides core backend services for MetaMask, serving as the data layer between Backend services (REST APIs, WebSocket services) and Frontend applications (Extension, Mobile). This package enables authenticated real-time data delivery with type-safe controller integration. ### ✨ What's New in v1.0.0 This is the **initial release** of the package, introducing: #### Core Services - **BackendWebSocketService** - WebSocket client providing authenticated real-time data delivery with: - Connection management and automatic reconnection with exponential backoff - Message routing and subscription management - Authentication integration with `AuthenticationController` - Type-safe messenger-based API for controller integration - **AccountActivityService** - High-level service for monitoring account activity with: - Real-time account activity monitoring via WebSocket subscriptions - Balance update notifications for integration with `TokenBalancesController` - Chain status change notifications for dynamic polling coordination - Account subscription management with automatic cleanup #### Infrastructure - **Type definitions** - Comprehensive TypeScript types for transactions, balances, WebSocket messages, and service configurations - **Logging infrastructure** - Structured logging with module-specific loggers for debugging and monitoring ### 📄 Changelog See [CHANGELOG.md](https://github.com/MetaMask/core/blob/main/packages/core-backend/CHANGELOG.md) for full details. ### 🔗 Related PR - Initial implementation: #6722 ### ✅ Release Checklist - [x] Version bump is correct (1.0.0 for initial release) - [x] Changelog entries are accurate and comprehensive - [x] All changes are properly documented - [x] Package is ready for publication - [x] No additional changes from `main` need to be incorporated ### 📚 Documentation - [Package README](https://github.com/MetaMask/core/blob/main/packages/core-backend/README.md) - [Architecture documentation](https://github.com/MetaMask/core/blob/main/packages/core-backend/README.md#architecture--design) --- <!-- CURSOR_SUMMARY --> > [!NOTE] > Publishes initial @metamask/core-backend v1.0.0 with changelog updates and bumps monorepo version to 606.0.0. > > - **Releases**: > - `@metamask/core-backend@1.0.0`: initial release; adds formal changelog section and release links in `packages/core-backend/CHANGELOG.md`. > - **Versioning**: > - Monorepo `package.json` version bumped `605.0.0` -> `606.0.0`. > - `packages/core-backend/package.json` version set `0.0.0` -> `1.0.0`. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 0d6d6dd. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup> <!-- /CURSOR_SUMMARY -->
Kriys94
added a commit
that referenced
this pull request
Oct 10, 2025
…lancesController (#6784) This PR integrates the `TokenBalancesController` with the new `@metamask/core-backend` package to enable real-time balance updates via WebSocket connections. This provides users with instant balance updates without relying solely on periodic polling. ### Context & Dependencies⚠️ **This PR depends on [#6722](#6722) being merged first**, which introduces the `@metamask/core-backend` package with `BackendWebSocketService` and `AccountActivityService`. ### Current State & Problem Currently, the `TokenBalancesController` relies exclusively on periodic REST API polling to detect balance changes. This approach has several limitations: - **High latency**: Users must wait for the next polling interval (default 180s) to see balance updates - **Increased API load**: Constant polling from all users creates unnecessary server load - **Poor UX for time-sensitive operations**: Users don't get immediate feedback when balances change ### Solution This PR enhances `TokenBalancesController` to: - **Subscribe to real-time balance updates** via WebSocket when the `AccountActivityService` is available - **Coordinate polling dynamically** based on WebSocket connection state: - When WebSocket is connected: Reduce polling to 5-minute backup intervals - When WebSocket is disconnected: Resume default 20-second polling intervals - **Maintain backward compatibility**: Works identically when core-backend package is unavailable - **Provide graceful degradation**: Automatically falls back to polling if WebSocket fails ### Key Implementation Details **Integration with AccountActivityService**: - Subscribes to `AccountActivityService:balanceUpdated` events via messenger - Updates token balances immediately when WebSocket notifications arrive - Processes balance changes without waiting for polling cycles **Connection State Coordination**: - Listens to `BackendWebSocketService:connectionStateChanged` events - Dynamically adjusts polling intervals to reduce API load when real-time updates are active - Ensures continuous data flow even during WebSocket reconnection attempts ## References - **Depends on**: [#6722 - feat(core-backend): add package](#6722) - Foundation for future real-time features (price updates, transaction monitoring) - Part of broader MetaMask backend services architecture ## Checklist - [x] I've updated the test suite for new or updated code as appropriate - Enhanced TokenBalancesController tests to 1,225 lines covering WebSocket integration scenarios - Added tests for connection state coordination and fallback behavior - Verified graceful degradation when core-backend is unavailable - [x] I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate - Updated JSDoc for new methods and configuration options - Documented WebSocket integration behavior - [x] I've communicated my changes to consumers by updating changelogs for packages I've changed, highlighting breaking changes as necessary - Added CHANGELOG.md entries for `@metamask/assets-controllers` - [ ] I've prepared draft pull requests for clients and consumer packages to resolve any breaking changes - N/A - no breaking changes introduced, backward compatible integration <!-- CURSOR_SUMMARY --> --- > [!NOTE] > Integrates TokenBalancesController with AccountActivityService for real-time balance updates, adds status-driven polling (with debounce/jitter) and WS-based token import, updates docs/tests, and introduces core-backend dependency with BREAKING messenger and interval changes. > > - **Assets Controllers**: > - **TokenBalancesController**: > - Subscribes to `AccountActivityService:balanceUpdated` and `statusChanged` for real-time updates and status-driven polling. > - Adjusts polling dynamically (debounced 5s, jittered) and sets defaults: `30s` (down) and `5m` when WebSocket is up. > - Processes ERC20/native updates, updates `AccountTracker`, imports untracked tokens via `TokenDetectionController:addDetectedTokensViaWs`. > - Adds utilities (`caipChainIdToHex`, `parseAssetType`), handles `allIgnoredTokens`, and cleans up timers on destroy. > - **TokenDetectionController**: > - Adds public/action `addDetectedTokensViaWs` to add WS-detected tokens from cache; minor cleanups. > - **BREAKING**: > - Messenger must allow `AccountActivityService:balanceUpdated`, `AccountActivityService:statusChanged`, and `TokenDetectionController:addDetectedTokensViaWs`. > - Default polling interval changed to `30s` (was `180s`). > - **Docs/Tests**: > - Adds `docs/real-time-balance-updates-flow.md` and updates README. > - Extensive new tests for WS flows, utilities, and polling logic; tweaks Jest coverage threshold. > - **Deps/Config**: > - Adds `@metamask/core-backend` as dependency and peerDependency; updates tsconfig references and yarn.lock. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 5dac77e. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup> <!-- /CURSOR_SUMMARY -->
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Follow-up of #6490
PR focusing on merging the core-backend package first
Explanation
What is the current state, and why does it need to change?
Currently, MetaMask relies on polling-based HTTP requests to fetch blockchain data like account balances and transaction updates. This approach has several limitations:
What is the solution and how does it work?
This PR introduces the
@metamask/core-backendpackage - a new data layer platform that bridges backend services with MetaMask frontend applications through efficient WebSocket-based real-time communication.The solution provides:
BackendWebSocketService: Low-level WebSocket connection management with automatic reconnection, authentication integration, and intelligent message routing
AccountActivityService: High-level service for real-time account activity monitoring
Intelligent Fallback Strategy: Dynamic coordination with existing HTTP polling controllers - when WebSocket is connected, polling intervals increase from 20s to 10 minutes; when disconnected, polling returns to 20s with immediate balance fetches
Key architectural benefits:
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, highlighting breaking changes as necessary
I've prepared draft pull requests for clients and consumer packages to resolve any breaking changes
Note
Adds the new @metamask/core-backend package providing a WebSocket client and account activity service, with types, tests, docs, and repo wiring.
packages/core-backend(new):BackendWebSocketService: authenticated WS client with reconnection, request/response, subscriptions, channel callbacks, and connection-state events.AccountActivityService: real-time account activity (transactions/balances), system notifications, selected-account resubscription, and supported-chain fetching/caching.transactions,balances, messages), logger, exports, README, CHANGELOG, LICENSE, Jest config, TypeDoc, tsconfigs.core-backend.tsconfig*.json) andyarn.lock.Written by Cursor Bugbot for commit 19edb84. This will update automatically on new commits. Configure here.