@metamask-previews/assets-controllers 96.0.0-preview-766f7065 → 98.0.0-preview-cd0d0950

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_persistDebounceTimer, _TokenListController_persistInFlightPromise, _TokenListController_changedChainsToPersist, _TokenListController_chainsLoadedFromStorage, _TokenListController_previousTokensChainsCache, _TokenListController_persistDebounceMs, _TokenListController_storageKeyPrefix, _TokenListController_getChainStorageKey, _TokenListController_intervalId, _TokenListController_intervalDelay, _TokenListController_cacheRefreshThreshold, _TokenListController_chainId, _TokenListController_abortController, _TokenListController_onCacheChanged, _TokenListController_debouncePersist, _TokenListController_persistChangedChains, _TokenListController_synchronizeCacheWithStorage, _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,44 @@ 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;
+        /**
+         * 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());
+        /**
+         * Tracks chains that were just loaded from storage and should skip
+         * the next persistence cycle. This prevents redundant writes where
+         * data loaded from storage would be immediately written back.
+         * Chains are removed from this set after being skipped once.
+         */
+        _TokenListController_chainsLoadedFromStorage.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 +120,15 @@ 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() {
+        await __classPrivateFieldGet(this, _TokenListController_instances, "m", _TokenListController_synchronizeCacheWithStorage).call(this);
+    }
     // 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 +138,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 +150,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 +160,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 +170,14 @@ 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();
+        __classPrivateFieldGet(this, _TokenListController_chainsLoadedFromStorage, "f").clear();
     }
     /**
      * This starts a new polling loop for any given chain. Under the hood it is deduping polls
@@ -149,71 +190,146 @@ 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();
+        __classPrivateFieldGet(this, _TokenListController_chainsLoadedFromStorage, "f").clear();
+        // 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 = {};
+                });
+                // Reset previous cache after state is cleared to prevent false "new chain" detections
+                __classPrivateFieldSet(this, _TokenListController_previousTokensChainsCache, {}, "f");
+                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;
+                }
+            });
+            // Reset previous cache after state is cleared to prevent false "new chain" detections
+            __classPrivateFieldSet(this, _TokenListController_previousTokensChainsCache, { ...this.state.tokensChainsCache }, "f");
+        }
+        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 = {};
+            });
+            __classPrivateFieldSet(this, _TokenListController_previousTokensChainsCache, {}, "f");
+        }
     }
     /**
      * Updates preventPollingOnNetworkRestart from extension.
@@ -230,7 +346,177 @@ class TokenListController extends (0, polling_controller_1.StaticIntervalPolling
     }
 }
 exports.TokenListController = TokenListController;
-_TokenListController_instances = new WeakSet(), _TokenListController_onNetworkControllerStateChange = 
+_a = TokenListController, _TokenListController_persistDebounceTimer = new WeakMap(), _TokenListController_persistInFlightPromise = new WeakMap(), _TokenListController_changedChainsToPersist = new WeakMap(), _TokenListController_chainsLoadedFromStorage = 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_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) {
+            // Skip persistence for chains that were just loaded from storage
+            // (they don't need to be written back immediately)
+            if (__classPrivateFieldGet(this, _TokenListController_chainsLoadedFromStorage, "f").has(chainId)) {
+                __classPrivateFieldGet(this, _TokenListController_chainsLoadedFromStorage, "f").delete(chainId); // Clean up - future updates should persist
+            }
+            else {
+                __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.
+ *
+ * If a persist operation is already in-flight, this method returns early
+ * and reschedules the debounce to ensure accumulated changes are retried
+ * after the current operation completes.
+ *
+ * @returns A promise that resolves when changed chains are persisted.
+ */
+async function _TokenListController_persistChangedChains() {
+    if (__classPrivateFieldGet(this, _TokenListController_persistInFlightPromise, "f")) {
+        // Reschedule debounce to retry accumulated changes after in-flight persist completes
+        if (__classPrivateFieldGet(this, _TokenListController_changedChainsToPersist, "f").size > 0) {
+            __classPrivateFieldGet(this, _TokenListController_instances, "m", _TokenListController_debouncePersist).call(this);
+        }
+        return;
+    }
+    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");
+    try {
+        await __classPrivateFieldGet(this, _TokenListController_persistInFlightPromise, "f");
+    }
+    finally {
+        __classPrivateFieldSet(this, _TokenListController_persistInFlightPromise, undefined, "f");
+    }
+}, _TokenListController_synchronizeCacheWithStorage = 
+/**
+ * Synchronize tokensChainsCache between state and storage bidirectionally.
+ *
+ * This method:
+ * 1. Loads cached chains from storage (per-chain files) in parallel
+ * 2. Merges loaded data into state (preferring existing state to avoid overwriting fresh data)
+ * 3. Persists any chains that exist in state but not in storage
+ *
+ * Called during initialization to ensure state and storage are consistent.
+ *
+ * @returns A promise that resolves when synchronization is complete.
+ */
+async function _TokenListController_synchronizeCacheWithStorage() {
+    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)}:`));
+        // 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) {
+            // Track which chains we're actually loading from storage
+            // These will be skipped in the next #onCacheChanged to avoid redundant writes
+            for (const chainId of Object.keys(loadedCache)) {
+                if (!this.state.tokensChainsCache[chainId]) {
+                    __classPrivateFieldGet(this, _TokenListController_chainsLoadedFromStorage, "f").add(chainId);
+                }
+            }
+            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;
+                    }
+                }
+            });
+            // Note: The update() call above only triggers #onCacheChanged if chains
+            // were actually added to state. If initial state already contains chains
+            // from storage, the update() is a no-op and #onCacheChanged is never called.
+        }
+        // Persist chains that exist in state but were not loaded from storage.
+        // This handles the case where initial state contains chains that don't exist
+        // in storage yet (e.g., fresh data from API). Without this, those chains
+        // would be lost on the next app restart.
+        const loadedChainIds = new Set(Object.keys(loadedCache));
+        const chainsInState = new Set(Object.keys(this.state.tokensChainsCache));
+        for (const chainId of chainsInState) {
+            if (!loadedChainIds.has(chainId)) {
+                __classPrivateFieldGet(this, _TokenListController_changedChainsToPersist, "f").add(chainId);
+            }
+        }
+        // Persist any chains that need to be saved
+        if (__classPrivateFieldGet(this, _TokenListController_changedChainsToPersist, "f").size > 0) {
+            __classPrivateFieldGet(this, _TokenListController_instances, "m", _TokenListController_debouncePersist).call(this);
+        }
+        __classPrivateFieldSet(this, _TokenListController_previousTokensChainsCache, { ...this.state.tokensChainsCache }, "f");
+    }
+    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 +526,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 +548,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