feat: filter pooled-staking vault token and surface its balance as stakedBalance

[salimtb]

Filter the pooled-staking vault ERC-20 (0x4fef9d74…) from regular token/balance lists and instead populate stakedBalance on the account tracker entry so it is picked up by the StakingBalance component on the Token Details page.

Adds 7 new unit tests covering:

• stakedBalance is populated from the vault ERC-20 balance
• native balance spread-guard preserves stakedBalance regardless of iteration order
• regular ERC-20s do not set stakedBalance
• vault token is excluded from getTokensControllerAllTokens (assetsBalance and customAssets paths)
• vault token is excluded from getTokenBalancesControllerTokenBalances (balance and zero-placeholder paths)

Description

Changelog

CHANGELOG entry: filter pooled-staking vault token and surface its balance as stakedBalance

Related issues

Fixes: #32113

Manual testing steps

Feature: my feature name

  Scenario: user [verb for user action]
    Given [describe expected initial app state]

    When user [verb for user action]
    Then [describe expected outcome]

Screenshots/Recordings

Before

After

staking.mov

Pre-merge author checklist

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

Performance checks (if applicable)

• I've tested on Android
  • Ideally on a mid-range device; emulator is acceptable
• I've tested with a power user scenario
  • Use these power-user SRPs to import wallets with many accounts and tokens
• I've instrumented key operations with Sentry traces for production performance metrics
  • See trace() for usage and addToken for an example

For performance guidelines and tooling, see the Performance Guide.

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.

---

Note

Medium Risk
Changes balance and token list shaping behind a feature flag; wrong filtering could hide balances or mis-report staked ETH, but scope is limited to two known vault asset IDs and is well covered by tests.

Overview
When assets unify state is enabled, the pooled-staking vault ERC-20 (0x4FEF9D74… on Ethereum mainnet and Hoodi) is no longer shown as a normal token. Its balance is mapped to stakedBalance on the account-tracker migration so staking UI (e.g. Token Details / StakingBalance) can show staked ETH separately.

assets-migration.ts adds chain-scoped CAIP-19 filtering (STAKED_TOKEN_ASSET_IDS_TO_FILTER + isStakedTokenAssetId) and skips the vault in getTokensControllerAllTokens and getTokenBalancesControllerTokenBalances (including custom-asset zero placeholders). getAccountTrackerControllerAccountsByChainId now handles native balances and vault ERC-20 in one loop, setting stakedBalance from the vault amount and using a spread on the native branch so stakedBalance is not lost if asset iteration order varies.

Tests cover stakedBalance population, iteration-order preservation, non-vault ERC-20s unchanged, and vault exclusion from all token/balance migration paths.

^{Reviewed by Cursor Bugbot for commit f902b31. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

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.

[metamask-ci]

PR template — items to address before "Ready for review"

Warnings — informational, address before merging:

• Description section is empty. Describe what changed and why.
• Manual testing steps still contain template content (the Gherkin example title or a [...] placeholder). Replace with real steps, or write N/A — <reason>.
• Pre-merge author checklist has unchecked items (e.g. "I've followed MetaMask Contributor Docs and MetaMask Mobile Coding Standards."). Every box must be consciously checked — see docs/readme/ready-for-review.md.

See docs/readme/ready-for-review.md for the full Definition of Ready for Review.

[github-actions]

🔍 Smart E2E Test Selection

• Selected E2E tags: SmokeStake, SmokeWalletPlatform, SmokeConfirmations
• Selected Performance tags: @PerformanceAssetLoading
• Risk Level: medium
• AI Confidence: 82%

click to see 🤖 AI reasoning details

E2E Test Selection:
The changes in assets-migration.ts modify three key selectors:

1. getAccountTrackerControllerAccountsByChainId: Now populates stakedBalance from the pooled-staking vault ERC-20 token balance (filtered from regular token lists). This directly feeds into the staking display in the wallet (confirmed via Engine.ts:975 and selectors/multichain/evm.ts:76 which reads stakedBalance for display).

2. getTokensControllerAllTokens: Now skips the staked vault token, preventing it from appearing in the regular ERC-20 token list.

3. getTokenBalancesControllerTokenBalances: Now skips the staked vault token in two code paths (assetsBalance and customAssets).

SmokeStake: Directly impacted - the staked balance display mechanism is changed. The vault token is now the source of stakedBalance data rather than a separate on-chain call. This affects stake entry flows and balance display.

SmokeWalletPlatform: The token list filtering affects the wallet's token display. The vault token should no longer appear as a regular ERC-20 in the token list, affecting the wallet home screen token list.

SmokeConfirmations: Required per tag dependency rules when SmokeStake is selected (staking flows involve transaction confirmations).

The test file changes are unit tests only and don't affect E2E test selection directly.

Performance Test Selection:
The changes modify core asset balance selectors (getAccountTrackerControllerAccountsByChainId, getTokensControllerAllTokens, getTokenBalancesControllerTokenBalances) that are used during token list rendering and balance fetching. These selectors are called frequently during asset loading and the additional filtering logic (isStakedTokenAssetId with parseCaipAssetType and toChecksumHexAddress calls) runs on every asset in the balance map. This could impact asset loading performance, making @PerformanceAssetLoading relevant.

View GitHub Actions results

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
96.9% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[github-actions]

⚡ Performance Test Results

ℹ️ Performance test results are currently non-blocking and will not block this PR.

✅ All tests passed · 2 tests · 1 device

📱 Devices tested (1)

Android: Google Pixel 8 Pro (v14.0)

✅ Passed Tests (2)

Test	Platform	Device	Duration	Team	Recording
Asset View, SRP 1 + SRP 2 + SRP 3	Android	Google Pixel 8 Pro (v14.0)	2.77s	@assets-dev-team	📹 Watch
Aggregated Balance Loading Time, SRP 1 + SRP 2 + SRP 3	Android	Google Pixel 8 Pro (v14.0)	420.00s	@assets-dev-team	—

---

Branch: feat/staked-token-filter-and-tests · Build: Normal · Commit: b7a209d · View full run