@metamask-previews/assets-controllers 95.1.0-preview-f075c1f → 95.1.0-preview-821afcb8

package/CHANGELOG.md

@@ -14,6 +14,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **BREAKING:** `TokenListController` now persists `tokensChainsCache` via `StorageService` and requires clients to call `initialize()` after construction ([#7413](https://github.com/MetaMask/core/pull/7413))
+  - Each chain's token cache is stored in a separate file, reducing write amplification
+  - All chains are loaded in parallel at startup to maintain compatibility with TokenDetectionController
+  - `tokensChainsCache` state metadata now has `persist: false` to prevent duplicate persistence
+  - Clients must call `await controller.initialize()` before using the controller
+  - State changes are automatically persisted via debounced subscription
+- Bump `@metamask/transaction-controller` from `^62.8.0` to `^62.9.0` ([#7602](https://github.com/MetaMask/core/pull/7602))
 - Bump `@metamask/transaction-controller` from `^62.8.0` to `^62.9.1` ([#7602](https://github.com/MetaMask/core/pull/7602), [#7604](https://github.com/MetaMask/core/pull/7604))
 - Bump `@metamask/network-controller` from `^27.2.0` to `^28.0.0` ([#7604](https://github.com/MetaMask/core/pull/7604))
 - Bump `@metamask/accounts-controller` from `^35.0.0` to `^35.0.1` ([#7604](https://github.com/MetaMask/core/pull/7604))

package/dist/TokenListController.cjs

@@ -4,12 +4,17 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _TokenListController_instances, _TokenListController_onNetworkControllerStateChange, _TokenListController_startDeprecatedPolling;
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var _TokenListController_instances, _a, _TokenListController_initializationPromise, _TokenListController_persistDebounceTimer, _TokenListController_persistInFlightPromise, _TokenListController_changedChainsToPersist, _TokenListController_previousTokensChainsCache, _TokenListController_persistDebounceMs, _TokenListController_storageKeyPrefix, _TokenListController_getChainStorageKey, _TokenListController_intervalId, _TokenListController_intervalDelay, _TokenListController_cacheRefreshThreshold, _TokenListController_chainId, _TokenListController_abortController, _TokenListController_initializeFromStorage, _TokenListController_onCacheChanged, _TokenListController_debouncePersist, _TokenListController_persistChangedChains, _TokenListController_loadCacheFromStorage, _TokenListController_saveChainCacheToStorage, _TokenListController_onNetworkControllerStateChange, _TokenListController_stopPolling, _TokenListController_startDeprecatedPolling;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TokenListController = exports.getDefaultTokenListState = void 0;
 const controller_utils_1 = require("@metamask/controller-utils");
 const polling_controller_1 = require("@metamask/polling-controller");
-const async_mutex_1 = require("async-mutex");
 const assetsUtil_1 = require("./assetsUtil.cjs");
 const token_service_1 = require("./token-service.cjs");
 // 4 Hour Interval Cache Refresh Threshold
@@ -19,7 +24,7 @@ const name = 'TokenListController';
 const metadata = {
     tokensChainsCache: {
         includeInStateLogs: false,
-        persist: true,
+        persist: false, // Persisted separately via StorageService
         includeInDebugSnapshot: true,
         usedInUi: true,
     },
@@ -61,13 +66,41 @@ class TokenListController extends (0, polling_controller_1.StaticIntervalPolling
             state: { ...(0, exports.getDefaultTokenListState)(), ...state },
         });
         _TokenListController_instances.add(this);
-        this.mutex = new async_mutex_1.Mutex();
-        this.intervalDelay = interval;
+        /**
+         * Promise that resolves when initialization (loading cache from storage) is complete.
+         */
+        _TokenListController_initializationPromise.set(this, Promise.resolve());
+        /**
+         * Debounce timer for persisting state changes to storage.
+         */
+        _TokenListController_persistDebounceTimer.set(this, void 0);
+        /**
+         * Promise that resolves when the current persist operation completes.
+         * Used to prevent race conditions between persist and clear operations.
+         */
+        _TokenListController_persistInFlightPromise.set(this, void 0);
+        /**
+         * Tracks which chains have pending changes to persist.
+         * Only changed chains are persisted to reduce write amplification.
+         */
+        _TokenListController_changedChainsToPersist.set(this, new Set());
+        /**
+         * Previous tokensChainsCache for detecting which chains changed.
+         */
+        _TokenListController_previousTokensChainsCache.set(this, {});
+        _TokenListController_intervalId.set(this, void 0);
+        _TokenListController_intervalDelay.set(this, void 0);
+        _TokenListController_cacheRefreshThreshold.set(this, void 0);
+        _TokenListController_chainId.set(this, void 0);
+        _TokenListController_abortController.set(this, void 0);
+        __classPrivateFieldSet(this, _TokenListController_intervalDelay, interval, "f");
         this.setIntervalLength(interval);
-        this.cacheRefreshThreshold = cacheRefreshThreshold;
-        this.chainId = chainId;
+        __classPrivateFieldSet(this, _TokenListController_cacheRefreshThreshold, cacheRefreshThreshold, "f");
+        __classPrivateFieldSet(this, _TokenListController_chainId, chainId, "f");
         this.updatePreventPollingOnNetworkRestart(preventPollingOnNetworkRestart);
-        this.abortController = new AbortController();
+        __classPrivateFieldSet(this, _TokenListController_abortController, new AbortController(), "f");
+        // Subscribe to state changes to automatically persist tokensChainsCache
+        this.messenger.subscribe('TokenListController:stateChange', (newCache) => __classPrivateFieldGet(this, _TokenListController_instances, "m", _TokenListController_onCacheChanged).call(this, newCache), (controllerState) => controllerState.tokensChainsCache);
         if (onNetworkStateChange) {
             // TODO: Either fix this lint violation or explain why it's necessary to ignore.
             // eslint-disable-next-line @typescript-eslint/no-misused-promises
@@ -84,6 +117,16 @@ class TokenListController extends (0, polling_controller_1.StaticIntervalPolling
             });
         }
     }
+    /**
+     * Initialize the controller by loading cache from storage and running migration.
+     * This method should be called by clients after construction.
+     *
+     * @returns A promise that resolves when initialization is complete.
+     */
+    async initialize() {
+        __classPrivateFieldSet(this, _TokenListController_initializationPromise, __classPrivateFieldGet(this, _TokenListController_instances, "m", _TokenListController_initializeFromStorage).call(this), "f");
+        await __classPrivateFieldGet(this, _TokenListController_initializationPromise, "f");
+    }
     // Eventually we want to remove start/restart/stop controls in favor of new _executePoll API
     // Maintaining these functions for now until we can safely deprecate them for backwards compatibility
     /**
@@ -93,7 +136,7 @@ class TokenListController extends (0, polling_controller_1.StaticIntervalPolling
      * Consider using the new polling approach instead
      */
     async start() {
-        if (!(0, assetsUtil_1.isTokenListSupportedForNetwork)(this.chainId)) {
+        if (!(0, assetsUtil_1.isTokenListSupportedForNetwork)(__classPrivateFieldGet(this, _TokenListController_chainId, "f"))) {
             return;
         }
         await __classPrivateFieldGet(this, _TokenListController_instances, "m", _TokenListController_startDeprecatedPolling).call(this);
@@ -105,7 +148,7 @@ class TokenListController extends (0, polling_controller_1.StaticIntervalPolling
      * Consider using the new polling approach instead
      */
     async restart() {
-        this.stopPolling();
+        __classPrivateFieldGet(this, _TokenListController_instances, "m", _TokenListController_stopPolling).call(this);
         await __classPrivateFieldGet(this, _TokenListController_instances, "m", _TokenListController_startDeprecatedPolling).call(this);
     }
     /**
@@ -115,7 +158,7 @@ class TokenListController extends (0, polling_controller_1.StaticIntervalPolling
      * Consider using the new polling approach instead
      */
     stop() {
-        this.stopPolling();
+        __classPrivateFieldGet(this, _TokenListController_instances, "m", _TokenListController_stopPolling).call(this);
     }
     /**
      * This stops any active polling.
@@ -125,18 +168,13 @@ class TokenListController extends (0, polling_controller_1.StaticIntervalPolling
      */
     destroy() {
         super.destroy();
-        this.stopPolling();
-    }
-    /**
-     * This stops any active polling intervals.
-     *
-     * @deprecated This method is deprecated and will be removed in the future.
-     * Consider using the new polling approach instead
-     */
-    stopPolling() {
-        if (this.intervalId) {
-            clearInterval(this.intervalId);
+        __classPrivateFieldGet(this, _TokenListController_instances, "m", _TokenListController_stopPolling).call(this);
+        // Cancel any pending debounced persistence operations
+        if (__classPrivateFieldGet(this, _TokenListController_persistDebounceTimer, "f")) {
+            clearTimeout(__classPrivateFieldGet(this, _TokenListController_persistDebounceTimer, "f"));
+            __classPrivateFieldSet(this, _TokenListController_persistDebounceTimer, undefined, "f");
         }
+        __classPrivateFieldGet(this, _TokenListController_changedChainsToPersist, "f").clear();
     }
     /**
      * This starts a new polling loop for any given chain. Under the hood it is deduping polls
@@ -149,71 +187,141 @@ class TokenListController extends (0, polling_controller_1.StaticIntervalPolling
         return this.fetchTokenList(chainId);
     }
     /**
-     * Fetching token list from the Token Service API. This will fetch tokens across chains. It will update tokensChainsCache (scoped across chains), and also the tokenList (scoped for the selected chain)
+     * Fetching token list from the Token Service API. This will fetch tokens across chains.
+     * State changes are automatically persisted via the stateChange subscription.
      *
      * @param chainId - The chainId of the current chain triggering the fetch.
      */
     async fetchTokenList(chainId) {
-        const releaseLock = await this.mutex.acquire();
-        try {
-            if (this.isCacheValid(chainId)) {
-                return;
-            }
-            // Fetch fresh token list from the API
-            const tokensFromAPI = await (0, controller_utils_1.safelyExecute)(() => (0, token_service_1.fetchTokenListByChainId)(chainId, this.abortController.signal));
-            // Have response - process and update list
-            if (tokensFromAPI) {
-                // Format tokens from API (HTTP) and update tokenList
-                const tokenList = {};
-                for (const token of tokensFromAPI) {
-                    tokenList[token.address] = {
-                        ...token,
-                        aggregators: (0, assetsUtil_1.formatAggregatorNames)(token.aggregators),
-                        iconUrl: (0, assetsUtil_1.formatIconUrlWithProxy)({
-                            chainId,
-                            tokenAddress: token.address,
-                        }),
-                    };
-                }
-                this.update((state) => {
-                    var _a;
-                    const newDataCache = { data: {}, timestamp: Date.now() };
-                    (_a = state.tokensChainsCache)[chainId] ?? (_a[chainId] = newDataCache);
-                    state.tokensChainsCache[chainId].data = tokenList;
-                    state.tokensChainsCache[chainId].timestamp = Date.now();
-                });
-                return;
+        if (this.isCacheValid(chainId)) {
+            return;
+        }
+        // Fetch fresh token list from the API
+        const tokensFromAPI = await (0, controller_utils_1.safelyExecute)(() => (0, token_service_1.fetchTokenListByChainId)(chainId, __classPrivateFieldGet(this, _TokenListController_abortController, "f").signal));
+        // Have response - process and update list
+        if (tokensFromAPI) {
+            // Format tokens from API (HTTP) and update tokenList
+            const tokenList = {};
+            for (const token of tokensFromAPI) {
+                tokenList[token.address] = {
+                    ...token,
+                    aggregators: (0, assetsUtil_1.formatAggregatorNames)(token.aggregators),
+                    iconUrl: (0, assetsUtil_1.formatIconUrlWithProxy)({
+                        chainId,
+                        tokenAddress: token.address,
+                    }),
+                };
             }
-            // No response - fallback to previous state, or initialise empty
-            if (!tokensFromAPI) {
+            // Update state - persistence happens automatically via subscription
+            const newDataCache = {
+                data: tokenList,
+                timestamp: Date.now(),
+            };
+            this.update((state) => {
+                state.tokensChainsCache[chainId] = newDataCache;
+            });
+            return;
+        }
+        // No response - fallback to previous state, or initialise empty.
+        // Only initialize with a new timestamp if there's no existing cache.
+        // If there's existing cache, keep it as-is without updating the timestamp
+        // to avoid making stale data appear "fresh" and preventing retry attempts.
+        if (!tokensFromAPI) {
+            const existingCache = this.state.tokensChainsCache[chainId];
+            if (!existingCache) {
+                // No existing cache - initialize empty (persistence happens automatically)
+                const newDataCache = { data: {}, timestamp: Date.now() };
                 this.update((state) => {
-                    var _a;
-                    const newDataCache = { data: {}, timestamp: Date.now() };
-                    (_a = state.tokensChainsCache)[chainId] ?? (_a[chainId] = newDataCache);
-                    state.tokensChainsCache[chainId].timestamp = Date.now();
+                    state.tokensChainsCache[chainId] = newDataCache;
                 });
             }
-        }
-        finally {
-            releaseLock();
+            // If there's existing cache, keep it as-is (don't update timestamp or persist)
         }
     }
     isCacheValid(chainId) {
         const { tokensChainsCache } = this.state;
         const timestamp = tokensChainsCache[chainId]?.timestamp;
         const now = Date.now();
-        return (timestamp !== undefined && now - timestamp < this.cacheRefreshThreshold);
+        return (timestamp !== undefined && now - timestamp < __classPrivateFieldGet(this, _TokenListController_cacheRefreshThreshold, "f"));
     }
     /**
      * Clearing tokenList and tokensChainsCache explicitly.
+     * This clears both state and all per-chain files in StorageService.
+     *
+     * Uses Promise.allSettled to handle partial failures gracefully.
+     * After all removal attempts complete, state is updated to match storage:
+     * - Successfully removed chains are cleared from state
+     * - Failed removals are kept in state to maintain consistency with storage
+     *
+     * Note: This method explicitly deletes from storage rather than relying on the
+     * stateChange subscription, since the subscription handles saves, not deletes.
      */
-    clearingTokenListData() {
-        this.update(() => {
-            return {
-                ...this.state,
-                tokensChainsCache: {},
-            };
-        });
+    async clearingTokenListData() {
+        if (__classPrivateFieldGet(this, _TokenListController_persistDebounceTimer, "f")) {
+            clearTimeout(__classPrivateFieldGet(this, _TokenListController_persistDebounceTimer, "f"));
+            __classPrivateFieldSet(this, _TokenListController_persistDebounceTimer, undefined, "f");
+        }
+        __classPrivateFieldGet(this, _TokenListController_changedChainsToPersist, "f").clear();
+        __classPrivateFieldSet(this, _TokenListController_previousTokensChainsCache, {}, "f");
+        // Wait for any in-flight persist operation to complete before clearing storage.
+        // This prevents race conditions where persist setItem calls interleave with
+        // our removeItem calls, potentially re-saving data after we remove it.
+        if (__classPrivateFieldGet(this, _TokenListController_persistInFlightPromise, "f")) {
+            try {
+                await __classPrivateFieldGet(this, _TokenListController_persistInFlightPromise, "f");
+            }
+            catch {
+                // Ignore
+            }
+        }
+        try {
+            const allKeys = await this.messenger.call('StorageService:getAllKeys', name);
+            // Filter and remove all tokensChainsCache keys
+            const cacheKeys = allKeys.filter((key) => key.startsWith(`${__classPrivateFieldGet(_a, _a, "f", _TokenListController_storageKeyPrefix)}:`));
+            if (cacheKeys.length === 0) {
+                // No storage keys to remove, just clear state
+                this.update((state) => {
+                    state.tokensChainsCache = {};
+                });
+                return;
+            }
+            // Use Promise.allSettled to handle partial failures gracefully.
+            // This ensures all removals are attempted and we can track which succeeded.
+            const results = await Promise.allSettled(cacheKeys.map((key) => this.messenger.call('StorageService:removeItem', name, key)));
+            // Identify which chains failed to be removed from storage
+            const failedChainIds = new Set();
+            results.forEach((result, index) => {
+                if (result.status === 'rejected') {
+                    const key = cacheKeys[index];
+                    const chainId = key.split(':')[1];
+                    failedChainIds.add(chainId);
+                    console.error(`TokenListController: Failed to remove cache for chain ${chainId}:`, result.reason);
+                }
+            });
+            // Update state to match storage: keep only chains that failed to be removed
+            this.update((state) => {
+                if (failedChainIds.size === 0) {
+                    state.tokensChainsCache = {};
+                }
+                else {
+                    // Keep only chains that failed to be removed from storage
+                    const preservedCache = {};
+                    for (const chainId of failedChainIds) {
+                        if (state.tokensChainsCache[chainId]) {
+                            preservedCache[chainId] = state.tokensChainsCache[chainId];
+                        }
+                    }
+                    state.tokensChainsCache = preservedCache;
+                }
+            });
+        }
+        catch (error) {
+            console.error('TokenListController: Failed to clear cache from storage:', error);
+            // Still clear state even if storage access fails
+            this.update((state) => {
+                state.tokensChainsCache = {};
+            });
+        }
     }
     /**
      * Updates preventPollingOnNetworkRestart from extension.
@@ -230,7 +338,163 @@ class TokenListController extends (0, polling_controller_1.StaticIntervalPolling
     }
 }
 exports.TokenListController = TokenListController;
-_TokenListController_instances = new WeakSet(), _TokenListController_onNetworkControllerStateChange = 
+_a = TokenListController, _TokenListController_initializationPromise = new WeakMap(), _TokenListController_persistDebounceTimer = new WeakMap(), _TokenListController_persistInFlightPromise = new WeakMap(), _TokenListController_changedChainsToPersist = new WeakMap(), _TokenListController_previousTokensChainsCache = new WeakMap(), _TokenListController_intervalId = new WeakMap(), _TokenListController_intervalDelay = new WeakMap(), _TokenListController_cacheRefreshThreshold = new WeakMap(), _TokenListController_chainId = new WeakMap(), _TokenListController_abortController = new WeakMap(), _TokenListController_instances = new WeakSet(), _TokenListController_getChainStorageKey = function _TokenListController_getChainStorageKey(chainId) {
+    return `${__classPrivateFieldGet(_a, _a, "f", _TokenListController_storageKeyPrefix)}:${chainId}`;
+}, _TokenListController_initializeFromStorage = 
+/**
+ * Internal method to load cache from storage and run migration.
+ *
+ * @returns A promise that resolves when initialization is complete.
+ */
+async function _TokenListController_initializeFromStorage() {
+    await __classPrivateFieldGet(this, _TokenListController_instances, "m", _TokenListController_loadCacheFromStorage).call(this);
+}, _TokenListController_onCacheChanged = function _TokenListController_onCacheChanged(newCache) {
+    // Detect which chains changed by comparing with previous cache
+    for (const chainId of Object.keys(newCache)) {
+        const newData = newCache[chainId];
+        const prevData = __classPrivateFieldGet(this, _TokenListController_previousTokensChainsCache, "f")[chainId];
+        // Chain is new or timestamp changed (indicating data update)
+        if (!prevData || prevData.timestamp !== newData.timestamp) {
+            __classPrivateFieldGet(this, _TokenListController_changedChainsToPersist, "f").add(chainId);
+        }
+    }
+    // Update previous cache reference
+    __classPrivateFieldSet(this, _TokenListController_previousTokensChainsCache, { ...newCache }, "f");
+    // Schedule persistence if there are changes
+    if (__classPrivateFieldGet(this, _TokenListController_changedChainsToPersist, "f").size > 0) {
+        __classPrivateFieldGet(this, _TokenListController_instances, "m", _TokenListController_debouncePersist).call(this);
+    }
+}, _TokenListController_debouncePersist = function _TokenListController_debouncePersist() {
+    if (__classPrivateFieldGet(this, _TokenListController_persistDebounceTimer, "f")) {
+        clearTimeout(__classPrivateFieldGet(this, _TokenListController_persistDebounceTimer, "f"));
+    }
+    __classPrivateFieldSet(this, _TokenListController_persistDebounceTimer, setTimeout(() => {
+        // Note: #persistChangedChains handles errors internally via #saveChainCacheToStorage,
+        // so this promise will not reject.
+        // eslint-disable-next-line @typescript-eslint/no-floating-promises
+        __classPrivateFieldGet(this, _TokenListController_instances, "m", _TokenListController_persistChangedChains).call(this);
+    }, __classPrivateFieldGet(_a, _a, "f", _TokenListController_persistDebounceMs)), "f");
+}, _TokenListController_persistChangedChains = 
+/**
+ * Persist only the chains that have changed to storage.
+ * Reduces write amplification by skipping unchanged chains.
+ *
+ * Tracks the in-flight operation via #persistInFlightPromise so that
+ * clearingTokenListData() can wait for it to complete before removing
+ * items from storage, preventing race conditions.
+ *
+ * @returns A promise that resolves when changed chains are persisted.
+ */
+async function _TokenListController_persistChangedChains() {
+    const chainsToPersist = [...__classPrivateFieldGet(this, _TokenListController_changedChainsToPersist, "f")];
+    __classPrivateFieldGet(this, _TokenListController_changedChainsToPersist, "f").clear();
+    if (chainsToPersist.length === 0) {
+        return;
+    }
+    __classPrivateFieldSet(this, _TokenListController_persistInFlightPromise, Promise.all(chainsToPersist.map((chainId) => __classPrivateFieldGet(this, _TokenListController_instances, "m", _TokenListController_saveChainCacheToStorage).call(this, chainId))).then(() => undefined), "f"); // Convert Promise<void[]> to Promise<void>
+    try {
+        await __classPrivateFieldGet(this, _TokenListController_persistInFlightPromise, "f");
+    }
+    finally {
+        __classPrivateFieldSet(this, _TokenListController_persistInFlightPromise, undefined, "f");
+    }
+}, _TokenListController_loadCacheFromStorage = 
+/**
+ * Load tokensChainsCache from StorageService into state.
+ * Loads all cached chains from separate per-chain files in parallel.
+ * Called during initialization to restore cached data.
+ *
+ * Note: This method merges loaded data with existing state to avoid
+ * overwriting any fresh data that may have been fetched concurrently.
+ * Caller must hold the mutex.
+ *
+ * @returns A promise that resolves when loading is complete.
+ */
+async function _TokenListController_loadCacheFromStorage() {
+    try {
+        const allKeys = await this.messenger.call('StorageService:getAllKeys', name);
+        // Filter keys that belong to tokensChainsCache (per-chain files)
+        const cacheKeys = allKeys.filter((key) => key.startsWith(`${__classPrivateFieldGet(_a, _a, "f", _TokenListController_storageKeyPrefix)}:`));
+        if (cacheKeys.length === 0) {
+            return;
+        }
+        // Load all chains in parallel
+        const chainCaches = await Promise.all(cacheKeys.map(async (key) => {
+            // Extract chainId from key: 'tokensChainsCache:0x1' → '0x1'
+            const chainId = key.split(':')[1];
+            const { result, error } = await this.messenger.call('StorageService:getItem', name, key);
+            if (error) {
+                console.error(`TokenListController: Error loading cache for ${chainId}:`, error);
+                return null;
+            }
+            return result ? { chainId, data: result } : null;
+        }));
+        // Build complete cache from loaded chains
+        const loadedCache = {};
+        chainCaches.forEach((chainCache) => {
+            if (chainCache) {
+                loadedCache[chainCache.chainId] = chainCache.data;
+            }
+        });
+        // Merge loaded cache with existing state, preferring existing data
+        // (which may be fresher if fetched during initialization)
+        if (Object.keys(loadedCache).length > 0) {
+            this.update((state) => {
+                // Only load chains that don't already exist in state
+                // This prevents overwriting fresh API data with stale cached data
+                for (const [chainId, cacheData] of Object.entries(loadedCache)) {
+                    if (!state.tokensChainsCache[chainId]) {
+                        state.tokensChainsCache[chainId] = cacheData;
+                    }
+                }
+            });
+            // Clear persistence for chains loaded from storage only.
+            // Data loaded from storage doesn't need to be re-persisted.
+            // The update() call above triggers #onCacheChanged which detects all
+            // loaded chains as "new" (since #previousTokensChainsCache is empty)
+            // and schedules them for persistence. We must clear these to avoid
+            // redundant storage writes on every initialization.
+            // However, we must NOT clear chains from initial state that were never
+            // persisted to storage - those still need their first persist.
+            if (__classPrivateFieldGet(this, _TokenListController_persistDebounceTimer, "f")) {
+                clearTimeout(__classPrivateFieldGet(this, _TokenListController_persistDebounceTimer, "f"));
+                __classPrivateFieldSet(this, _TokenListController_persistDebounceTimer, undefined, "f");
+            }
+            // Only remove loaded chains, not chains from initial state that need first persist
+            for (const chainId of Object.keys(loadedCache)) {
+                __classPrivateFieldGet(this, _TokenListController_changedChainsToPersist, "f").delete(chainId);
+            }
+            // Re-schedule persistence if there are remaining chains to persist
+            if (__classPrivateFieldGet(this, _TokenListController_changedChainsToPersist, "f").size > 0) {
+                __classPrivateFieldGet(this, _TokenListController_instances, "m", _TokenListController_debouncePersist).call(this);
+            }
+        }
+    }
+    catch (error) {
+        console.error('TokenListController: Failed to load cache from storage:', error);
+    }
+}, _TokenListController_saveChainCacheToStorage = 
+/**
+ * Save a specific chain's cache to StorageService.
+ * This persists only the updated chain's data, reducing write amplification.
+ *
+ * @param chainId - The chain ID to save.
+ * @returns A promise that resolves when saving is complete.
+ */
+async function _TokenListController_saveChainCacheToStorage(chainId) {
+    try {
+        const chainData = this.state.tokensChainsCache[chainId];
+        if (!chainData) {
+            console.warn(`TokenListController: No cache data for chain ${chainId}`);
+            return;
+        }
+        const storageKey = __classPrivateFieldGet(_a, _a, "m", _TokenListController_getChainStorageKey).call(_a, chainId);
+        await this.messenger.call('StorageService:setItem', name, storageKey, chainData);
+    }
+    catch (error) {
+        console.error(`TokenListController: Failed to save cache for ${chainId}:`, error);
+    }
+}, _TokenListController_onNetworkControllerStateChange = 
 /**
  * Updates state and restarts polling on changes to the network controller
  * state.
@@ -240,14 +504,19 @@ _TokenListController_instances = new WeakSet(), _TokenListController_onNetworkCo
 async function _TokenListController_onNetworkControllerStateChange(networkControllerState) {
     const selectedNetworkClient = this.messenger.call('NetworkController:getNetworkClientById', networkControllerState.selectedNetworkClientId);
     const { chainId } = selectedNetworkClient.configuration;
-    if (this.chainId !== chainId) {
-        this.abortController.abort();
-        this.abortController = new AbortController();
-        this.chainId = chainId;
+    if (__classPrivateFieldGet(this, _TokenListController_chainId, "f") !== chainId) {
+        __classPrivateFieldGet(this, _TokenListController_abortController, "f").abort();
+        __classPrivateFieldSet(this, _TokenListController_abortController, new AbortController(), "f");
+        __classPrivateFieldSet(this, _TokenListController_chainId, chainId, "f");
         if (this.state.preventPollingOnNetworkRestart) {
+            // eslint-disable-next-line @typescript-eslint/no-floating-promises
             this.clearingTokenListData();
         }
     }
+}, _TokenListController_stopPolling = function _TokenListController_stopPolling() {
+    if (__classPrivateFieldGet(this, _TokenListController_intervalId, "f")) {
+        clearInterval(__classPrivateFieldGet(this, _TokenListController_intervalId, "f"));
+    }
 }, _TokenListController_startDeprecatedPolling = 
 /**
  * Starts a new polling interval for a given chainId (this should be deprecated in favor of _executePoll)
@@ -257,12 +526,18 @@ async function _TokenListController_onNetworkControllerStateChange(networkContro
  */
 async function _TokenListController_startDeprecatedPolling() {
     // renaming this to avoid collision with base class
-    await (0, controller_utils_1.safelyExecute)(() => this.fetchTokenList(this.chainId));
+    await (0, controller_utils_1.safelyExecute)(() => this.fetchTokenList(__classPrivateFieldGet(this, _TokenListController_chainId, "f")));
     // TODO: Either fix this lint violation or explain why it's necessary to ignore.
     // eslint-disable-next-line @typescript-eslint/no-misused-promises
-    this.intervalId = setInterval(async () => {
-        await (0, controller_utils_1.safelyExecute)(() => this.fetchTokenList(this.chainId));
-    }, this.intervalDelay);
+    __classPrivateFieldSet(this, _TokenListController_intervalId, setInterval(async () => {
+        await (0, controller_utils_1.safelyExecute)(() => this.fetchTokenList(__classPrivateFieldGet(this, _TokenListController_chainId, "f")));
+    }, __classPrivateFieldGet(this, _TokenListController_intervalDelay, "f")), "f");
 };
+/**
+ * Debounce delay for persisting state changes (in milliseconds).
+ */
+_TokenListController_persistDebounceMs = { value: 500 };
+// Storage key prefix for per-chain files
+_TokenListController_storageKeyPrefix = { value: 'tokensChainsCache' };
 exports.default = TokenListController;
 //# sourceMappingURL=TokenListController.cjs.map