@metamask-previews/assets-controller 16.1.0-preview-c6cdff1dd → 16.1.0-preview-9d2a9bdf5

package/dist/AssetsController.js

@@ -13,7 +13,7 @@ import { RpcDataSource } from './data-sources/RpcDataSource.js';
 import { SnapDataSource } from './data-sources/SnapDataSource.js';
 import { StakedBalanceDataSource } from './data-sources/StakedBalanceDataSource.js';
 import { CaipAssetNamespace, TokenDataSource, } from './data-sources/TokenDataSource.js';
-import { CHAINS_WITH_DEFAULT_TRACKED_ASSETS, DEFAULT_TRACKED_ASSETS_BY_CHAIN, buildDefaultAssetsInfo, getDefaultAssetMetadata, } from './defaults.js';
+import { CHAINS_WITH_DEFAULT_TRACKED_ASSETS, DEFAULT_TRACKED_ASSETS_BY_CHAIN, buildDefaultAssetsInfo, getDefaultAssetMetadata, getDefaultTrackedAssetsForChain, } from './defaults.js';
 import { projectLogger, createModuleLogger } from './logger.js';
 import { CustomAssetGraduationMiddleware } from './middlewares/CustomAssetGraduationMiddleware.js';
 import { DetectionMiddleware } from './middlewares/DetectionMiddleware.js';
@@ -187,6 +187,10 @@ function normalizeResponse(response) {
     if (response.replaceCoveredChainBalances) {
         normalized.replaceCoveredChainBalances = true;
     }
+    if (response.unprocessedCustomAssets &&
+        response.unprocessedCustomAssets.length > 0) {
+        normalized.unprocessedCustomAssets = response.unprocessedCustomAssets.map((assetId) => normalizeAssetId(assetId));
+    }
     return normalized;
 }
 /**
@@ -194,12 +198,13 @@ function normalizeResponse(response) {
  *
  * @param previousBalances - Balances already in state for this account.
  * @param accountBalances - Balances from the incoming response.
- * @param customAssetIds - Custom assets to preserve when replacing covered chains.
- * @param replaceCoveredChains - When true, drop prior balances on chains present
- *   in the response before applying it (authoritative chain slice).
+ * @param customAssetIds - Custom assets to preserve when replacing covered chains
+ *   on the Accounts API v5 path (`replaceCoveredChainBalances`).
+ * @param replaceCoveredChains - When true (v5 force refresh), drop prior balances
+ *   on chains present in the response before applying it, then restore custom assets.
  * @returns The merged balance map for the account.
  */
-function mergeAccountBalances(previousBalances, accountBalances, customAssetIds, replaceCoveredChains) {
+function mergeAccountBalancesV5(previousBalances, accountBalances, customAssetIds, replaceCoveredChains) {
     if (!replaceCoveredChains) {
         return { ...previousBalances, ...accountBalances };
     }
@@ -228,6 +233,53 @@ function mergeAccountBalances(previousBalances, accountBalances, customAssetIds,
     }
     return next;
 }
+/**
+ * Apply an Accounts API v6 authoritative chain snapshot.
+ *
+ * @param previousBalances - Balances already in state for this account.
+ * @param accountBalances - Balances from the incoming response.
+ * @param unprocessedCustomAssets - Pins that v6 and RPC could not resolve.
+ * @returns The merged balance map for the account.
+ */
+function mergeAccountBalancesV6(previousBalances, accountBalances, unprocessedCustomAssets = []) {
+    const coveredChains = new Set(Object.keys(accountBalances).map((assetId) => assetId.split('/')[0]));
+    const next = {};
+    for (const [assetId, balance] of Object.entries(previousBalances)) {
+        if (!coveredChains.has(assetId.split('/')[0])) {
+            next[assetId] = balance;
+        }
+    }
+    Object.assign(next, accountBalances);
+    const unprocessedSet = new Set(unprocessedCustomAssets.map((assetId) => normalizeAssetId(assetId)));
+    for (const [assetId, balance] of Object.entries(previousBalances)) {
+        if (unprocessedSet.has(normalizeAssetId(assetId)) &&
+            !Object.prototype.hasOwnProperty.call(next, assetId)) {
+            next[assetId] = balance;
+        }
+    }
+    for (const [assetId, balance] of Object.entries(previousBalances)) {
+        if (isStakingContractAssetId(assetId) &&
+            !Object.prototype.hasOwnProperty.call(next, assetId)) {
+            next[assetId] = balance;
+        }
+    }
+    // Default tracked assets (mUSD) are controller-managed and must render at
+    // zero when the account holds none. The v6 snapshot omits them in that
+    // case, so re-assert them on covered chains — otherwise a force refresh
+    // would drop them from the token list.
+    // TODO: seed defaults as visible pins in `customAssets` instead (skip if
+    // already present or `assetPreferences[assetId].hidden`), then drop this
+    // merge special case.
+    for (const chainId of coveredChains) {
+        for (const assetId of getDefaultTrackedAssetsForChain(chainId)) {
+            if (!Object.prototype.hasOwnProperty.call(next, assetId)) {
+                next[assetId] =
+                    previousBalances[assetId] ?? { amount: '0' };
+            }
+        }
+    }
+    return next;
+}
 // ============================================================================
 // CONTROLLER IMPLEMENTATION
 // ============================================================================
@@ -463,6 +515,8 @@ export class AssetsController extends BaseController {
             queryApiClient,
             onActiveChainsUpdated: this.#onActiveChainsUpdated,
             ...accountsApiDataSourceConfig,
+            isBalanceV6Enabled: () => this.#isBalanceV6Enabled(),
+            getAssetsState: () => this.state,
         });
         this.#snapDataSource = new SnapDataSource({
             messenger: this.messenger,
@@ -514,6 +568,7 @@ export class AssetsController extends BaseController {
         });
         this.#rpcFallbackMiddleware = new RpcFallbackMiddleware({
             rpcDataSource: this.#rpcDataSource,
+            isBalanceV6Enabled: () => this.#isBalanceV6Enabled(),
         });
         log('Initializing AssetsController', {
             defaultUpdateInterval: this.#defaultUpdateInterval,
@@ -868,143 +923,298 @@ export class AssetsController extends BaseController {
         if (accounts.length === 0 || chainIds.length === 0) {
             return this.#getAssetsFromState(accounts, chainIds, assetTypes);
         }
-        // Collect custom assets for all requested accounts
-        const customAssets = [];
-        for (const account of accounts) {
-            const accountCustomAssets = this.getCustomAssets(account.id);
-            customAssets.push(...accountCustomAssets);
-        }
         if (options?.forceUpdate) {
-            // Pipeline spans only on unlock/first-init fetch; later forceUpdates pass
-            // `undefined` so `emitTrace` / `withTrace` no-op without call-site if/else.
             const pipelineTrace = this.#firstInitFetchReported
                 ? undefined
                 : this.#trace;
-            const request = this.#buildDataRequest(accounts, chainIds, {
+            const requestOptions = {
                 assetTypes,
                 dataTypes,
-                customAssets: customAssets.length > 0 ? customAssets : undefined,
                 forceUpdate: true,
                 bypassServerCache: options?.bypassServerCache,
                 assetsForPriceUpdate: options?.assetsForPriceUpdate,
-            });
-            // Fast pipeline: accountsApi + stakedBalance → detection → token + price.
-            // Snap and RPC are excluded here due to their latency (snap triggers account
-            // creation, RPC is slow on many chains). Results are committed to state
-            // immediately so the UI can display balances without waiting for them.
-            //
-            // Fast/slow pipelines use merge so partial API snapshots cannot wipe
-            // tokens missing from the response (e.g. USDC when only native balance
-            // is returned). Balances present in the response are still refreshed.
-            const fastSources = buildFastFetchSources({
-                accountsApiDataSource: this.#accountsApiDataSource,
-                stakedBalanceDataSource: this.#stakedBalanceDataSource,
-                customAssetGraduationMiddleware: this.#customAssetGraduationMiddleware,
-                rpcFallbackMiddleware: this.#rpcFallbackMiddleware,
-                detectionMiddleware: this.#detectionMiddleware,
-                tokenDataSource: this.#tokenDataSource,
-                priceDataSource: this.#priceDataSource,
-            }, { isBasicFunctionality: this.#isBasicFunctionality() });
-            const { response } = await withTrace({
-                name: TRACE_FETCH_PIPELINE,
-                trace: pipelineTrace,
-                data: {
-                    chain_count: chainIds.length,
-                    account_count: accounts.length,
-                    basic_functionality: this.#isBasicFunctionality(),
-                },
-                fn: async (parentContext) => {
-                    const startTime = performance.now();
-                    const result = await this.#executeMiddlewares({
-                        sources: fastSources,
-                        request,
-                        parentContext,
-                        trace: pipelineTrace,
-                    });
-                    await this.#updateState({
-                        ...result.response,
-                        updateMode: 'merge',
-                        replaceCoveredChainBalances: true,
-                    });
-                    const durationMs = performance.now() - startTime;
-                    // Summary fields for Assets Health (nested under the parent span).
-                    emitTrace({
-                        name: TRACE_FULL_FETCH,
-                        trace: pipelineTrace,
-                        data: {
-                            duration_ms: durationMs,
-                            chain_count: chainIds.length,
-                            account_count: accounts.length,
-                            basic_functionality: this.#isBasicFunctionality(),
-                            asset_count: result.response.assetsBalance
-                                ? Object.values(result.response.assetsBalance).reduce((sum, acct) => sum + Object.keys(acct).length, 0)
-                                : 0,
-                            price_count: result.response.assetsPrice
-                                ? Object.keys(result.response.assetsPrice).length
-                                : 0,
-                            ...result.durationByDataSource,
-                        },
-                        parentContext,
-                    });
-                    emitTrace({
-                        name: TRACE_FIRST_INIT_FETCH,
-                        trace: pipelineTrace,
-                        data: {
-                            duration_ms: durationMs,
-                            chain_ids: JSON.stringify(chainIds),
-                            ...result.durationByDataSource,
-                        },
-                        parentContext,
-                    });
-                    return result;
-                },
-            });
-            // Mark after the unlock/first forceUpdate so later polls skip pipeline spans.
-            this.#firstInitFetchReported = true;
-            // Background (slow) lane — flattened sibling of the fast lane (not nested
-            // inside its withTrace callback). Still fire-and-forget so UI is not blocked.
-            const slowPipelineChainIds = this.#getSlowPipelineChainIds(chainIds, response);
-            if (slowPipelineChainIds.length > 0) {
-                const slowSources = this.#isBasicFunctionality()
-                    ? [this.#snapDataSource, this.#rpcDataSource]
-                    : [this.#rpcDataSource];
-                const slowRequest = { ...request, chainIds: slowPipelineChainIds };
-                withTrace({
-                    name: TRACE_BACKGROUND_FETCH,
-                    trace: pipelineTrace,
-                    data: {
-                        chain_count: slowPipelineChainIds.length,
-                        account_count: accounts.length,
-                    },
-                    fn: async (slowParentContext) => {
-                        const { response: slowResponse } = await this.#executeMiddlewares({
-                            sources: [
-                                createParallelBalanceMiddleware(slowSources),
-                                this.#detectionMiddleware,
-                                ...(this.#isBasicFunctionality()
-                                    ? [
-                                        createParallelMiddleware([
-                                            this.#tokenDataSource,
-                                            this.#priceDataSource,
-                                        ]),
-                                    ]
-                                    : []),
-                            ],
-                            request: slowRequest,
-                            parentContext: slowParentContext,
-                            trace: pipelineTrace,
-                        });
-                        await this.#updateState({
-                            ...slowResponse,
-                            updateMode: 'merge',
-                        });
-                    },
-                }).catch((error) => log('Background pipeline failed', { error }));
+            };
+            if (this.#isBalanceV6Enabled()) {
+                await this.#forceUpdateAssetsV6({
+                    accounts,
+                    chainIds,
+                    request: this.#buildForceUpdateRequestV6(accounts, chainIds, {
+                        ...requestOptions,
+                        customAssetsOverride: options?.customAssets,
+                    }),
+                    pipelineTrace,
+                });
+            }
+            else {
+                await this.#forceUpdateAssetsV5({
+                    accounts,
+                    chainIds,
+                    request: this.#buildForceUpdateRequestV5(accounts, chainIds, requestOptions),
+                    pipelineTrace,
+                });
             }
         }
         const result = this.#getAssetsFromState(accounts, chainIds, assetTypes);
         return result;
     }
+    /**
+     * v5 force-update request: every pin of the requested accounts, unscoped.
+     * Delete with the rest of the v5 path when `assetsAccountsApiV6` is the default.
+     *
+     * @param accounts - Accounts in this fetch.
+     * @param chainIds - Chains in this fetch.
+     * @param requestOptions - Shared force-update request fields.
+     * @param requestOptions.assetTypes - Asset types to fetch.
+     * @param requestOptions.dataTypes - Data types to fetch.
+     * @param requestOptions.forceUpdate - Always `true` to bypass caches.
+     * @param requestOptions.bypassServerCache - Also bypass server-side HTTP caches.
+     * @param requestOptions.assetsForPriceUpdate - Assets to refresh prices for.
+     * @returns The v5 data request.
+     */
+    #buildForceUpdateRequestV5(accounts, chainIds, requestOptions) {
+        const customAssets = [];
+        for (const account of accounts) {
+            customAssets.push(...this.getCustomAssets(account.id));
+        }
+        return this.#buildDataRequest(accounts, chainIds, {
+            ...requestOptions,
+            customAssets: customAssets.length > 0 ? customAssets : undefined,
+        });
+    }
+    /**
+     * v6 force-update request. Pins and hides are read from state by the
+     * Accounts API unless `customAssetsOverride` scopes this fetch.
+     *
+     * @param accounts - Accounts in this fetch.
+     * @param chainIds - Chains in this fetch.
+     * @param requestOptions - Shared force-update request fields and optional pin scope.
+     * @param requestOptions.assetTypes - Asset types to fetch.
+     * @param requestOptions.dataTypes - Data types to fetch.
+     * @param requestOptions.forceUpdate - Always `true` to bypass caches.
+     * @param requestOptions.bypassServerCache - Also bypass server-side HTTP caches.
+     * @param requestOptions.assetsForPriceUpdate - Assets to refresh prices for.
+     * @param requestOptions.customAssetsOverride - When set, fetch only these pins.
+     * @returns The v6 data request.
+     */
+    #buildForceUpdateRequestV6(accounts, chainIds, requestOptions) {
+        const requestedChains = new Set(chainIds);
+        const customAssetsSet = new Set();
+        for (const assetId of requestOptions.customAssetsOverride ?? []) {
+            try {
+                const normalizedAssetId = normalizeAssetId(assetId);
+                if (requestedChains.has(parseCaipAssetType(normalizedAssetId).chainId) &&
+                    !this.state.assetPreferences[normalizedAssetId]?.hidden) {
+                    customAssetsSet.add(normalizedAssetId);
+                }
+            }
+            catch {
+                // Skip unparseable asset IDs
+            }
+        }
+        const customAssets = [...customAssetsSet];
+        return this.#buildDataRequest(accounts, chainIds, {
+            assetTypes: requestOptions.assetTypes,
+            dataTypes: requestOptions.dataTypes,
+            forceUpdate: requestOptions.forceUpdate,
+            bypassServerCache: requestOptions.bypassServerCache,
+            assetsForPriceUpdate: requestOptions.assetsForPriceUpdate,
+            customAssets: customAssets.length > 0 ? customAssets : undefined,
+        });
+    }
+    async #forceUpdateAssetsV5({ accounts, chainIds, request, pipelineTrace, }) {
+        const isBasicFunctionality = this.#isBasicFunctionality();
+        const fastSources = buildFastFetchSources({
+            accountsApiDataSource: this.#accountsApiDataSource,
+            stakedBalanceDataSource: this.#stakedBalanceDataSource,
+            customAssetGraduationMiddleware: this.#customAssetGraduationMiddleware,
+            rpcFallbackMiddleware: this.#rpcFallbackMiddleware,
+            detectionMiddleware: this.#detectionMiddleware,
+            tokenDataSource: this.#tokenDataSource,
+            priceDataSource: this.#priceDataSource,
+        }, { isBasicFunctionality, includeCustomAssetGraduation: true });
+        const fastResponse = await this.#runFastFetchV5({
+            accounts,
+            chainIds,
+            request,
+            pipelineTrace,
+            fastSources,
+            isBasicFunctionality,
+        });
+        this.#firstInitFetchReported = true;
+        this.#runBackgroundFetch({
+            accounts,
+            request,
+            pipelineTrace,
+            chainIds: this.#getSlowPipelineChainIds(chainIds, fastResponse),
+            isBasicFunctionality,
+        });
+    }
+    async #forceUpdateAssetsV6({ accounts, chainIds, request, pipelineTrace, }) {
+        const isBasicFunctionality = this.#isBasicFunctionality();
+        const fastSources = buildFastFetchSources({
+            accountsApiDataSource: this.#accountsApiDataSource,
+            stakedBalanceDataSource: this.#stakedBalanceDataSource,
+            customAssetGraduationMiddleware: this.#customAssetGraduationMiddleware,
+            rpcFallbackMiddleware: this.#rpcFallbackMiddleware,
+            detectionMiddleware: this.#detectionMiddleware,
+            tokenDataSource: this.#tokenDataSource,
+            priceDataSource: this.#priceDataSource,
+        }, {
+            isBasicFunctionality,
+            includeCustomAssetGraduation: false,
+        });
+        const fastResponse = await this.#runFastFetchV6({
+            accounts,
+            chainIds,
+            request,
+            pipelineTrace,
+            fastSources,
+            isBasicFunctionality,
+        });
+        this.#firstInitFetchReported = true;
+        this.#runBackgroundFetch({
+            accounts,
+            request,
+            pipelineTrace,
+            chainIds: this.#getSlowPipelineChainIds(chainIds, fastResponse),
+            isBasicFunctionality,
+        });
+    }
+    async #runFastFetchV5({ accounts, chainIds, request, pipelineTrace, fastSources, isBasicFunctionality, }) {
+        const { response } = await withTrace({
+            name: TRACE_FETCH_PIPELINE,
+            trace: pipelineTrace,
+            data: {
+                chain_count: chainIds.length,
+                account_count: accounts.length,
+                basic_functionality: isBasicFunctionality,
+            },
+            fn: async (parentContext) => {
+                const startTime = performance.now();
+                const result = await this.#executeMiddlewares({
+                    sources: fastSources,
+                    request,
+                    parentContext,
+                    trace: pipelineTrace,
+                });
+                await this.#updateState({
+                    ...result.response,
+                    updateMode: 'merge',
+                    replaceCoveredChainBalances: true,
+                });
+                this.#emitFastFetchTraces({
+                    accounts,
+                    chainIds,
+                    result,
+                    durationMs: performance.now() - startTime,
+                    isBasicFunctionality,
+                    parentContext,
+                    pipelineTrace,
+                });
+                return result;
+            },
+        });
+        return response;
+    }
+    async #runFastFetchV6({ accounts, chainIds, request, pipelineTrace, fastSources, isBasicFunctionality, }) {
+        const { response } = await withTrace({
+            name: TRACE_FETCH_PIPELINE,
+            trace: pipelineTrace,
+            data: {
+                chain_count: chainIds.length,
+                account_count: accounts.length,
+                basic_functionality: isBasicFunctionality,
+            },
+            fn: async (parentContext) => {
+                const startTime = performance.now();
+                const result = await this.#executeMiddlewares({
+                    sources: fastSources,
+                    request,
+                    parentContext,
+                    trace: pipelineTrace,
+                });
+                await this.#updateState(result.response);
+                this.#emitFastFetchTraces({
+                    accounts,
+                    chainIds,
+                    result,
+                    durationMs: performance.now() - startTime,
+                    isBasicFunctionality,
+                    parentContext,
+                    pipelineTrace,
+                });
+                return result;
+            },
+        });
+        return response;
+    }
+    #runBackgroundFetch({ accounts, chainIds, request, pipelineTrace, isBasicFunctionality, }) {
+        if (chainIds.length === 0) {
+            return;
+        }
+        const slowSources = isBasicFunctionality
+            ? [this.#snapDataSource, this.#rpcDataSource]
+            : [this.#rpcDataSource];
+        const slowRequest = { ...request, chainIds };
+        withTrace({
+            name: TRACE_BACKGROUND_FETCH,
+            trace: pipelineTrace,
+            data: {
+                chain_count: chainIds.length,
+                account_count: accounts.length,
+            },
+            fn: async (parentContext) => {
+                const { response } = await this.#executeMiddlewares({
+                    sources: [
+                        createParallelBalanceMiddleware(slowSources),
+                        this.#detectionMiddleware,
+                        ...(isBasicFunctionality
+                            ? [
+                                createParallelMiddleware([
+                                    this.#tokenDataSource,
+                                    this.#priceDataSource,
+                                ]),
+                            ]
+                            : []),
+                    ],
+                    request: slowRequest,
+                    parentContext,
+                    trace: pipelineTrace,
+                });
+                await this.#updateState({ ...response, updateMode: 'merge' });
+            },
+        }).catch((error) => log('Background pipeline failed', { error }));
+    }
+    #emitFastFetchTraces({ accounts, chainIds, result, durationMs, isBasicFunctionality, parentContext, pipelineTrace, }) {
+        emitTrace({
+            name: TRACE_FULL_FETCH,
+            trace: pipelineTrace,
+            data: {
+                duration_ms: durationMs,
+                chain_count: chainIds.length,
+                account_count: accounts.length,
+                basic_functionality: isBasicFunctionality,
+                asset_count: result.response.assetsBalance
+                    ? Object.values(result.response.assetsBalance).reduce((sum, account) => sum + Object.keys(account).length, 0)
+                    : 0,
+                price_count: result.response.assetsPrice
+                    ? Object.keys(result.response.assetsPrice).length
+                    : 0,
+                ...result.durationByDataSource,
+            },
+            parentContext,
+        });
+        emitTrace({
+            name: TRACE_FIRST_INIT_FETCH,
+            trace: pipelineTrace,
+            data: {
+                duration_ms: durationMs,
+                chain_ids: JSON.stringify(chainIds),
+                ...result.durationByDataSource,
+            },
+            parentContext,
+        });
+    }
     async getAssetsBalance(accounts, options) {
         // Reuse getAssets with dataTypes: ['balance'] only
         const assets = await this.getAssets(accounts, {
@@ -1272,20 +1482,28 @@ export class AssetsController extends BaseController {
             balances[accountId] ??= {};
             balances[accountId][normalizedAssetId] ??= { amount: '0' };
         });
-        // Fetch data for the newly added custom asset (merge to preserve other chains)
         const account = this.#getSelectedAccounts().find((a) => a.id === accountId);
         if (account) {
             const chainId = extractChainId(normalizedAssetId);
-            await this.getAssets([account], {
-                chainIds: [chainId],
-                dataTypes: ['balance', 'metadata', 'price'],
-                assetTypes: ['fungible'],
-                forceUpdate: true,
-                updateMode: 'merge',
-            });
+            if (this.#isBalanceV6Enabled()) {
+                await this.getAssets([account], {
+                    chainIds: [chainId],
+                    dataTypes: ['balance', 'metadata', 'price'],
+                    assetTypes: ['fungible'],
+                    forceUpdate: true,
+                    customAssets: [normalizedAssetId],
+                });
+            }
+            else {
+                await this.getAssets([account], {
+                    chainIds: [chainId],
+                    dataTypes: ['balance', 'metadata', 'price'],
+                    assetTypes: ['fungible'],
+                    forceUpdate: true,
+                });
+            }
         }
-        // Re-evaluate subscriptions so the supplemental RPC poll picks up the
-        // new customAsset on chains another data source already owns.
+        // Re-evaluate subscriptions so polls pick up the new pin.
         this.#subscribeAssets();
     }
     /**
@@ -1306,8 +1524,7 @@ export class AssetsController extends BaseController {
                 }
             }
         });
-        // Re-evaluate subscriptions so the supplemental RPC poll for that chain
-        // is torn down when no more customAssets remain there.
+        // Re-evaluate subscriptions so polls drop the removed pin.
         this.#subscribeAssets();
     }
     /**
@@ -1338,6 +1555,8 @@ export class AssetsController extends BaseController {
             }
             state.assetPreferences[normalizedAssetId].hidden = true;
         });
+        // Re-evaluate subscriptions so polls exclude the newly hidden asset.
+        this.#subscribeAssets();
     }
     /**
      * Unhide an asset globally.
@@ -1356,6 +1575,26 @@ export class AssetsController extends BaseController {
                 }
             }
         });
+        // Re-evaluate subscriptions so polls stop excluding the asset.
+        this.#subscribeAssets();
+    }
+    /**
+     * Whether Accounts API v6 (and the v6 custom-asset path) is enabled.
+     * Injected into AccountsApiDataSource and RpcFallbackMiddleware.
+     *
+     * `RemoteFeatureFlagController` resolves a threshold-scoped flag to the
+     * selected group's `value`, so processed state is a boolean.
+     *
+     * @returns `true` when the v6 remote flag is on.
+     */
+    #isBalanceV6Enabled() {
+        try {
+            const { remoteFeatureFlags } = this.messenger.call('RemoteFeatureFlagController:getState');
+            return remoteFeatureFlags?.assetsAccountsApiV6 === true;
+        }
+        catch {
+            return false;
+        }
     }
     // ============================================================================
     // CURRENT CURRENCY MANAGEMENT
@@ -1589,10 +1828,16 @@ export class AssetsController extends BaseController {
      */
     #getSlowPipelineChainIds(chainIds, fastResponse) {
         const accountsApiChains = new Set(this.#accountsApiDataSource.getActiveChainsSync());
+        // Chains whose pins went unresolved (`unprocessedCustomAssets`): route
+        // them to the slow pipeline so RPC fetches the pins.
+        const unprocessedCustomAssetChains = new Set((fastResponse.unprocessedCustomAssets ?? []).map((assetId) => assetId.split('/')[0]));
         return chainIds.filter((chainId) => {
             if (fastResponse.errors?.[chainId]) {
                 return true;
             }
+            if (unprocessedCustomAssetChains.has(chainId)) {
+                return true;
+            }
             if (!accountsApiChains.has(chainId)) {
                 return true;
             }
@@ -1755,9 +2000,9 @@ export class AssetsController extends BaseController {
                     for (const [accountId, accountBalances] of Object.entries(normalizedResponse.assetsBalance)) {
                         const previousBalances = previousState.assetsBalance[accountId] ?? {};
                         const customAssetIds = state.customAssets[accountId] ?? [];
-                        const replaceCoveredChains = mode === 'full' ||
-                            normalizedResponse.replaceCoveredChainBalances === true;
-                        const effective = mergeAccountBalances(previousBalances, accountBalances, customAssetIds, replaceCoveredChains);
+                        const effective = mode === 'full'
+                            ? mergeAccountBalancesV6(previousBalances, accountBalances, normalizedResponse.unprocessedCustomAssets ?? [])
+                            : mergeAccountBalancesV5(previousBalances, accountBalances, customAssetIds, normalizedResponse.replaceCoveredChainBalances === true);
                         // Ensure native tokens have an entry (0 if missing) for chains this account supports
                         const account = this.#getSelectedAccounts().find((a) => a.id === accountId);
                         const nativeAssetIdsForAccount = account
@@ -1787,10 +2032,12 @@ export class AssetsController extends BaseController {
                                 ...(newMetadata === undefined ? {} : { metadata: newMetadata }),
                             };
                             const oldAmount = previousBalance?.amount;
-                            const isNewDefaultNativeZero = oldAmount === undefined &&
+                            const isNewSeededZero = oldAmount === undefined &&
                                 newAmount === '0' &&
-                                nativeAssetIdsForAccount.includes(assetId);
-                            if (oldAmount !== newAmount && !isNewDefaultNativeZero) {
+                                (nativeAssetIdsForAccount.includes(assetId) ||
+                                    getDefaultAssetMetadata(assetId) !==
+                                        undefined);
+                            if (oldAmount !== newAmount && !isNewSeededZero) {
                                 changedBalances.push({
                                     accountId,
                                     assetId,
@@ -1824,10 +2071,8 @@ export class AssetsController extends BaseController {
                 changedPriceAssets.length > 0) {
                 log('State updated', {
                     changedBalances: changedBalances.length > 0 ? changedBalances : undefined,
-                    changedMetadataCount: changedMetadata.length > 0 ? changedMetadata.length : undefined,
-                    changedPricesCount: changedPriceAssets.length > 0
-                        ? changedPriceAssets.length
-                        : undefined,
+                    changedMetadata: changedMetadata.length > 0 ? changedMetadata : undefined,
+                    changedPrices: changedPriceAssets.length > 0 ? changedPriceAssets : undefined,
                     newAssets: Object.keys(detectedAssets).length > 0
                         ? Object.entries(detectedAssets).map(([accountId, assets]) => ({
                             accountId,
@@ -2049,16 +2294,10 @@ export class AssetsController extends BaseController {
             if (!subscriptionKey.startsWith('ds:')) {
                 continue;
             }
-            // Subscription keys take the form `ds:<SourceName>` for the regular
-            // subscription or `ds:<SourceName>:<suffix>` for supplemental
-            // subscriptions (e.g. `ds:RpcDataSource:custom`). Split on `:` and
-            // pick the source-name segment so both shapes resolve correctly.
+            // Subscription keys take the form `ds:<SourceName>`.
             const [, sourceId] = subscriptionKey.split(':');
             const source = allSources.find((ds) => ds.getName() === sourceId);
             if (source) {
-                // Unsubscribe by the actual key — `#unsubscribeDataSource` only
-                // knows the regular `ds:<SourceName>` shape and would miss
-                // supplemental subscriptions, leaking their polling timers.
                 this.#unsubscribeBySubscriptionKey(source, subscriptionKey);
             }
         }
@@ -2102,10 +2341,11 @@ export class AssetsController extends BaseController {
      * Strategy to minimize data source calls:
      * 1. Collect all chains to subscribe based on enabled networks
      * 2. Map chains to accounts based on their scopes
-     * 3. Split by data source (ordered by priority) - each data source gets ONE subscription
-     *
-     * This ensures we make minimal subscriptions to each data source while covering
-     * all accounts and chains.
+     * 3. Split by data source (priority order) — each source gets one
+     *    subscription for the chains it was assigned (accounts + chains only).
+     *    v6 sources read pins/hides from state themselves (Accounts API sends
+     *    `includeAssetIds` / `excludeAssetIds`). v5 uses a separate RPC
+     *    `customAssetsOnly` supplement for pins on chains another source owns.
      *
      * @param accounts - Accounts to subscribe balance updates for.
      * @param chainIds - Chain IDs to subscribe for.
@@ -2115,10 +2355,7 @@ export class AssetsController extends BaseController {
     #subscribeAssetsBalance(accounts, chainIds, options) {
         const chainToAccounts = this.#buildChainToAccountsMap(accounts, new Set(chainIds));
         const remainingChains = new Set(chainToAccounts.keys());
-        // When basic functionality is on, use all balance data sources; when off,
-        // RPC only.
-        const isBasicFunctionality = this.#isBasicFunctionality();
-        const balanceDataSources = isBasicFunctionality
+        const balanceDataSources = this.#isBasicFunctionality()
             ? this.#allBalanceDataSources
             : [this.#rpcDataSource];
         let rpcAssignedChains = new Set();
@@ -2157,22 +2394,15 @@ export class AssetsController extends BaseController {
                 });
             }
         }
-        // Supplemental RPC subscription for customAssets on chains another data
-        // source claimed during regular handoff. RPC is the sole balance fetcher
-        // for customAssets, so we must always poll them — even when (e.g.)
-        // AccountsApi is already covering the chain for normal balances. The
-        // supplemental subscription runs in `customAssetsOnly` mode so it does
-        // NOT double-poll the regular tracked balances.
-        this.#subscribeRpcCustomAssetsSupplement(accounts, chainToAccounts, rpcAssignedChains);
+        if (!this.#isBalanceV6Enabled()) {
+            this.#subscribeRpcCustomAssetsSupplement(accounts, chainToAccounts, rpcAssignedChains);
+        }
     }
     /**
      * Guarantee that customAssets are **always** polled by RPC, even when
      * AccountsApi or another data source has claimed the chain in the
      * regular handoff. RPC is the sole balance fetcher for user-imported
-     * tokens (see `pickRpcCustomAssetsSupplement` for the full rationale),
-     * so we run a dedicated subscription in `customAssetsOnly` mode under a
-     * distinct subscription key (`ds:RpcDataSource:custom`) that does not
-     * interfere with the regular RPC subscription.
+     * tokens on the Accounts API v5 path (see `pickRpcCustomAssetsSupplement`).
      *
      * @param accounts - Accounts to consider for customAssets.
      * @param chainToAccounts - Map of chain → accounts (built by caller).
@@ -2270,7 +2500,8 @@ export class AssetsController extends BaseController {
      * @param chains - Array of chain IDs to subscribe for.
      * @param options - Optional subscription overrides.
      * @param options.subscriptionKey - Custom subscription key (default: `ds:<sourceId>`).
-     * @param options.customAssetsOnly - When true, only poll customAssets for these chains.
+     * @param options.customAssetsOnly - When true, only poll customAssets for these
+     * chains (Accounts API v5 supplemental RPC subscription).
      * @param options.skipInitialFetch - When true, skip the data source's subscribe-time fetch.
      */
     #subscribeDataSource(source, accounts, chains, options = {}) {
@@ -2483,13 +2714,13 @@ export class AssetsController extends BaseController {
         // The data will simply not be updated until the network is re-enabled.
         // Refresh subscriptions for new chain set
         this.#subscribeAssets();
-        // Do one-time fetch for newly enabled chains; merge so we keep existing chain balances
+        // One-time fetch for newly enabled chains. v6 `full` replace is scoped to
+        // those chains; existing balances on other chains are left untouched.
         const accounts = this.#getSelectedAccounts();
         if (addedChains.length > 0 && accounts.length > 0) {
             await this.getAssets(accounts, {
                 chainIds: addedChains,
                 forceUpdate: true,
-                updateMode: 'merge',
             });
         }
         this.#ensureNativeBalancesDefaultZero();
@@ -2649,48 +2880,28 @@ export class AssetsController extends BaseController {
     async handleAssetsUpdate(response, sourceId, request) {
         log('Assets updated from data source', {
             sourceId,
-            hasBalance: Boolean(response.assetsBalance),
-            hasPrice: Boolean(response.assetsPrice),
+            assetsBalance: response.assetsBalance,
+            assetsPrice: response.assetsPrice,
         });
-        // Enrichment spans only before unlock/first-init fetch completes.
+        if (this.#isBalanceV6Enabled()) {
+            await this.#handleAssetsUpdateV6(response, sourceId, request);
+            return;
+        }
+        await this.#handleAssetsUpdateV5(response, sourceId, request);
+    }
+    async #handleAssetsUpdateV5(response, sourceId, request) {
         const pipelineTrace = this.#firstInitFetchReported
             ? undefined
             : this.#trace;
         await withTrace({
             name: TRACE_UPDATE_PARENT,
             trace: pipelineTrace,
-            data: {
-                source: sourceId,
-                has_balance: Boolean(response.assetsBalance),
-                has_price: Boolean(response.assetsPrice),
-                balance_account_count: response.assetsBalance
-                    ? Object.keys(response.assetsBalance).length
-                    : 0,
-            },
+            data: this.#getUpdateTraceData(response, sourceId),
             fn: async (parentContext) => {
                 const updateStart = performance.now();
-                const resolvedRequest = request ?? {
-                    accountsWithSupportedChains: [],
-                    chainIds: [],
-                    dataTypes: ['balance', 'metadata', 'price'],
-                };
-                // RPC-only mode (basic functionality off): never run token/price APIs. Strip
-                // those data types so downstream middleware cannot treat them as requested.
-                const pipelineRequest = this.#isBasicFunctionality()
-                    ? resolvedRequest
-                    : {
-                        ...resolvedRequest,
-                        dataTypes: resolvedRequest.dataTypes.filter((dt) => dt !== 'metadata' && dt !== 'price'),
-                    };
-                // Graduate custom assets only when AccountsAPI / AccountActivity reports
-                // them. RPC already fetches custom assets on purpose, and Snap handles
-                // non-EVM chains the rule does not apply to, so skip the middleware for
-                // those.
+                const pipelineRequest = this.#getUpdatePipelineRequest(request);
                 const shouldGraduateCustomAssets = sourceId === 'AccountsApiDataSource' ||
                     sourceId === 'AccountActivityDataSource';
-                // Websocket updates can carry brand-new spam airdrops: enrich them
-                // with Token API occurrences and drop below-floor tokens BEFORE
-                // detection, so spam is never detected, enriched, priced or persisted.
                 const shouldFilterOccurrences = sourceId === 'AccountActivityDataSource' &&
                     this.#isBasicFunctionality();
                 const shouldRunRpcFallback = sourceId === 'AccountsApiDataSource';
@@ -2709,6 +2920,7 @@ export class AssetsController extends BaseController {
                     ...(shouldRunRpcFallback ? [this.#rpcFallbackMiddleware] : []),
                     this.#detectionMiddleware,
                 ];
+                enrichmentSources.push(this.#detectionMiddleware);
                 if (this.#isBasicFunctionality()) {
                     enrichmentSources.push(createParallelMiddleware([
                         this.#tokenDataSource,
@@ -2726,25 +2938,110 @@ export class AssetsController extends BaseController {
                     ...enrichedResponse,
                     replaceCoveredChainBalances: response.replaceCoveredChainBalances,
                 });
-                // Summary fields for Assets Health (nested under the parent span).
-                emitTrace({
-                    name: TRACE_UPDATE_PIPELINE,
+                this.#emitUpdateTrace({
+                    response,
+                    sourceId,
+                    enrichedResponse,
+                    updateStart,
+                    pipelineTrace,
+                    parentContext,
+                });
+            },
+        });
+    }
+    async #handleAssetsUpdateV6(response, sourceId, request) {
+        const pipelineTrace = this.#firstInitFetchReported
+            ? undefined
+            : this.#trace;
+        await withTrace({
+            name: TRACE_UPDATE_PARENT,
+            trace: pipelineTrace,
+            data: this.#getUpdateTraceData(response, sourceId),
+            fn: async (parentContext) => {
+                const updateStart = performance.now();
+                const pipelineRequest = this.#getUpdatePipelineRequest(request);
+                const shouldFilterOccurrences = sourceId === 'AccountActivityDataSource' &&
+                    this.#isBasicFunctionality();
+                const enrichmentSources = [
+                    ...(shouldFilterOccurrences
+                        ? [
+                            {
+                                getName: () => 'OccurrenceFloorFilter',
+                                assetsMiddleware: this.#tokenDataSource.occurrenceFilterMiddleware,
+                            },
+                        ]
+                        : []),
+                ];
+                if (this.#isBasicFunctionality()) {
+                    enrichmentSources.push(this.#rpcFallbackMiddleware);
+                }
+                enrichmentSources.push(this.#detectionMiddleware);
+                if (this.#isBasicFunctionality()) {
+                    enrichmentSources.push(createParallelMiddleware([
+                        this.#tokenDataSource,
+                        this.#priceDataSource,
+                    ]));
+                }
+                const { response: enrichedResponse } = await this.#executeMiddlewares({
+                    sources: enrichmentSources,
+                    request: pipelineRequest,
+                    initialResponse: response,
+                    parentContext,
                     trace: pipelineTrace,
-                    data: {
-                        source: sourceId,
-                        duration_ms: performance.now() - updateStart,
-                        has_balance: Boolean(response.assetsBalance),
-                        has_price: Boolean(response.assetsPrice),
-                        has_metadata: Boolean(enrichedResponse.assetsInfo),
-                        balance_account_count: response.assetsBalance
-                            ? Object.keys(response.assetsBalance).length
-                            : 0,
-                    },
+                });
+                await this.#updateState(enrichedResponse);
+                this.#emitUpdateTrace({
+                    response,
+                    sourceId,
+                    enrichedResponse,
+                    updateStart,
+                    pipelineTrace,
                     parentContext,
                 });
             },
         });
     }
+    #getUpdatePipelineRequest(request) {
+        const resolvedRequest = request ?? {
+            accountsWithSupportedChains: [],
+            chainIds: [],
+            dataTypes: ['balance', 'metadata', 'price'],
+        };
+        if (this.#isBasicFunctionality()) {
+            return resolvedRequest;
+        }
+        return {
+            ...resolvedRequest,
+            dataTypes: resolvedRequest.dataTypes.filter((dataType) => dataType !== 'metadata' && dataType !== 'price'),
+        };
+    }
+    #getUpdateTraceData(response, sourceId) {
+        return {
+            source: sourceId,
+            has_balance: Boolean(response.assetsBalance),
+            has_price: Boolean(response.assetsPrice),
+            balance_account_count: response.assetsBalance
+                ? Object.keys(response.assetsBalance).length
+                : 0,
+        };
+    }
+    #emitUpdateTrace({ response, sourceId, enrichedResponse, updateStart, pipelineTrace, parentContext, }) {
+        emitTrace({
+            name: TRACE_UPDATE_PIPELINE,
+            trace: pipelineTrace,
+            data: {
+                source: sourceId,
+                duration_ms: performance.now() - updateStart,
+                has_balance: Boolean(response.assetsBalance),
+                has_price: Boolean(response.assetsPrice),
+                has_metadata: Boolean(enrichedResponse.assetsInfo),
+                balance_account_count: response.assetsBalance
+                    ? Object.keys(response.assetsBalance).length
+                    : 0,
+            },
+            parentContext,
+        });
+    }
     // ============================================================================
     // CLEANUP
     // ============================================================================