@metamask-previews/perps-controller 3.0.0-preview-e61cfa5 → 3.1.0-preview-548bdd1d9

package/dist/utils/perpsDiskPersistence.mjs

@@ -0,0 +1,244 @@
+import { buildProviderCacheKey, PERPS_CONSTANTS, PERPS_DISK_CACHE_MARKETS, PERPS_DISK_CACHE_USER_DATA, PROVIDER_CONFIG } from "../constants/perpsConfig.mjs";
+/**
+ * Multiplier applied to staleGuardMs (preloadGuardMs, currently 30s) to compute
+ * the staleness cap for disk-hydrated timestamps. A factor of 10 ensures hydrated
+ * data is always TTL-expired so the stream manager overwrites it with live data,
+ * while still being recent enough for a useful first paint.
+ */
+const DISK_HYDRATION_STALENESS_FACTOR = 10;
+/**
+ * Build the disk-cache payload for market data.
+ * In aggregated mode, groups markets by provider into separate entries.
+ *
+ * @param markets - Current market data snapshot.
+ * @param activeProvider - The active provider id (may be "aggregated").
+ * @param isTestnet - Global testnet flag.
+ * @param now - Timestamp to stamp entries with.
+ * @returns Payload ready for JSON serialization.
+ */
+export function buildMarketDataPayload(markets, activeProvider, isTestnet, now) {
+    if (activeProvider === 'aggregated') {
+        const entriesByKey = new Map();
+        for (const market of markets) {
+            const providerId = market.providerId ?? PROVIDER_CONFIG.DefaultProvider;
+            const key = buildProviderCacheKey(providerId, isTestnet);
+            const existing = entriesByKey.get(key);
+            if (existing) {
+                existing.data.push(market);
+            }
+            else {
+                entriesByKey.set(key, {
+                    providerNetworkKey: key,
+                    data: [market],
+                    timestamp: now,
+                });
+            }
+        }
+        const entries = Array.from(entriesByKey.values());
+        return entries.length === 1 ? entries[0] : { entries };
+    }
+    return {
+        providerNetworkKey: buildProviderCacheKey(activeProvider ?? PROVIDER_CONFIG.DefaultProvider, isTestnet),
+        data: markets,
+        timestamp: now,
+    };
+}
+/**
+ * Build the disk-cache payload for user data (positions, orders, account).
+ * In aggregated mode, groups entries by provider.
+ *
+ * @param positions - Current positions snapshot.
+ * @param orders - Current orders snapshot.
+ * @param accountState - Current account state snapshot.
+ * @param address - EVM account address.
+ * @param activeProvider - The active provider id (may be "aggregated").
+ * @param isTestnet - Global testnet flag.
+ * @param now - Timestamp to stamp entries with.
+ * @returns Payload ready for JSON serialization.
+ */
+export function buildUserDataPayload(positions, orders, accountState, address, activeProvider, isTestnet, now) {
+    if (activeProvider === 'aggregated') {
+        const entriesByKey = new Map();
+        const ensureEntry = (providerId) => {
+            const key = buildProviderCacheKey(providerId, isTestnet);
+            let entry = entriesByKey.get(key);
+            if (!entry) {
+                entry = {
+                    providerNetworkKey: key,
+                    address,
+                    positions: [],
+                    orders: [],
+                    accountState: null,
+                    timestamp: now,
+                };
+                entriesByKey.set(key, entry);
+            }
+            return entry;
+        };
+        for (const position of positions) {
+            ensureEntry(position.providerId ?? PROVIDER_CONFIG.DefaultProvider).positions.push(position);
+        }
+        for (const order of orders) {
+            ensureEntry(order.providerId ?? PROVIDER_CONFIG.DefaultProvider).orders.push(order);
+        }
+        if (accountState) {
+            ensureEntry(accountState.providerId ?? PROVIDER_CONFIG.DefaultProvider).accountState = accountState;
+        }
+        const entries = Array.from(entriesByKey.values()).filter((entry) => entry.positions.length > 0 ||
+            entry.orders.length > 0 ||
+            entry.accountState !== null);
+        return entries.length === 1 ? entries[0] : { entries };
+    }
+    return {
+        providerNetworkKey: buildProviderCacheKey(activeProvider ?? PROVIDER_CONFIG.DefaultProvider, isTestnet),
+        address,
+        positions,
+        orders,
+        accountState,
+        timestamp: now,
+    };
+}
+/**
+ * Write market entries to disk (best-effort, non-blocking).
+ *
+ * @param diskCache - Disk cache instance from controller infrastructure.
+ * @param entries - Pre-assembled market cache entries to persist.
+ */
+export function persistMarketEntriesToDisk(diskCache, entries) {
+    if (entries.length === 0) {
+        return;
+    }
+    const payload = entries.length === 1 ? entries[0] : { entries };
+    diskCache
+        .setItem(PERPS_DISK_CACHE_MARKETS, JSON.stringify(payload))
+        .catch(() => {
+        // Disk persistence is best-effort and must never block preload.
+    });
+}
+/**
+ * Write user data entries to disk (best-effort, non-blocking).
+ *
+ * @param diskCache - Disk cache instance from controller infrastructure.
+ * @param entries - Pre-assembled user cache entries to persist.
+ */
+export function persistUserEntriesToDisk(diskCache, entries) {
+    if (entries.length === 0) {
+        return;
+    }
+    const payload = entries.length === 1 ? entries[0] : { entries };
+    diskCache
+        .setItem(PERPS_DISK_CACHE_USER_DATA, JSON.stringify(payload))
+        .catch(() => {
+        // Disk persistence is best-effort and must never block preload.
+    });
+}
+/**
+ * Read disk-persisted cache snapshots and compute the state updates to apply.
+ * Returns plain objects rather than mutating state directly, so the caller
+ * can apply all changes in a single batched this.update() call.
+ *
+ * All returned timestamps are capped at DISK_HYDRATION_STALENESS_FACTOR * staleGuardMs
+ * in the past so the stream manager always overwrites disk data with fresh live data.
+ *
+ * @param diskCache - Disk cache instance from controller infrastructure.
+ * @param currentMarketCache - Current cachedMarketDataByProvider state.
+ * @param currentUserCache - Current cachedUserDataByProvider state.
+ * @param staleGuardMs - preloadGuardMs constant from the controller.
+ * @returns Updates to apply plus stats for debug logging.
+ */
+export function hydrateFromDiskSync(diskCache, currentMarketCache, currentUserCache, staleGuardMs) {
+    const hydrateT0 = Date.now();
+    const marketUpdates = {};
+    const userUpdates = {};
+    let marketCount = 0;
+    let userPositions = 0;
+    let userOrders = 0;
+    if (!diskCache.getItemSync) {
+        return {
+            marketUpdates,
+            userUpdates,
+            stats: { marketCount, userPositions, userOrders, durationMs: 0 },
+        };
+    }
+    const staleHydratedTimestamp = Date.now() - staleGuardMs * DISK_HYDRATION_STALENESS_FACTOR - 1;
+    try {
+        const marketsRaw = diskCache.getItemSync(PERPS_DISK_CACHE_MARKETS);
+        const userRaw = diskCache.getItemSync(PERPS_DISK_CACHE_USER_DATA);
+        if (marketsRaw) {
+            try {
+                const parsed = JSON.parse(marketsRaw);
+                const entries = Array.isArray(parsed.entries)
+                    ? parsed.entries
+                    : [parsed];
+                for (const entry of entries) {
+                    if (entry.providerNetworkKey && Array.isArray(entry.data)) {
+                        const existing = currentMarketCache[entry.providerNetworkKey];
+                        if (!existing || existing.timestamp < entry.timestamp) {
+                            const strippedData = entry.data.map((market) => ({
+                                ...market,
+                                price: PERPS_CONSTANTS.FallbackPriceDisplay,
+                                change24h: PERPS_CONSTANTS.FallbackDataDisplay,
+                                change24hPercent: PERPS_CONSTANTS.FallbackPercentageDisplay,
+                            }));
+                            marketUpdates[entry.providerNetworkKey] = {
+                                data: strippedData,
+                                // Disk-hydrated market snapshots are only for structural
+                                // first paint. Keep them TTL-stale so the stream manager
+                                // still fetches fresh prices on connect.
+                                timestamp: Math.min(entry.timestamp, staleHydratedTimestamp),
+                            };
+                            marketCount += strippedData.length;
+                        }
+                    }
+                }
+            }
+            catch {
+                // Corrupt JSON — silently ignore
+            }
+        }
+        if (userRaw) {
+            try {
+                const parsed = JSON.parse(userRaw);
+                const entries = Array.isArray(parsed.entries)
+                    ? parsed.entries
+                    : [parsed];
+                for (const entry of entries) {
+                    if (entry.providerNetworkKey && entry.address) {
+                        // Skip address check here — accounts may not be loaded yet at
+                        // constructor time. getCachedUserDataForActiveProvider validates
+                        // the address at read time, so stale-account data is never served.
+                        const existing = currentUserCache[entry.providerNetworkKey];
+                        if (!existing || existing.timestamp < entry.timestamp) {
+                            userUpdates[entry.providerNetworkKey] = {
+                                positions: entry.positions,
+                                orders: entry.orders,
+                                accountState: entry.accountState,
+                                timestamp: Math.min(entry.timestamp, staleHydratedTimestamp),
+                                address: entry.address,
+                            };
+                            userPositions += entry.positions.length;
+                            userOrders += entry.orders.length;
+                        }
+                    }
+                }
+            }
+            catch {
+                // Corrupt JSON — silently ignore
+            }
+        }
+    }
+    catch {
+        // Disk read failure — non-critical
+    }
+    return {
+        marketUpdates,
+        userUpdates,
+        stats: {
+            marketCount,
+            userPositions,
+            userOrders,
+            durationMs: Date.now() - hydrateT0,
+        },
+    };
+}
+//# sourceMappingURL=perpsDiskPersistence.mjs.map

package/dist/utils/perpsDiskPersistence.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"perpsDiskPersistence.mjs","sourceRoot":"","sources":["../../src/utils/perpsDiskPersistence.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,wBAAwB,EACxB,0BAA0B,EAC1B,eAAe,EAChB,qCAAiC;AAGlC;;;;;GAKG;AACH,MAAM,+BAA+B,GAAG,EAAE,CAAC;AAmC3C;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAA0B,EAC1B,cAAsB,EACtB,SAAkB,EAClB,GAAW;IAEX,IAAI,cAAc,KAAK,YAAY,EAAE,CAAC;QACpC,MAAM,YAAY,GAAG,IAAI,GAAG,EAAgC,CAAC;QAC7D,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,IAAI,eAAe,CAAC,eAAe,CAAC;YACxE,MAAM,GAAG,GAAG,qBAAqB,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;YACzD,MAAM,QAAQ,GAAG,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACvC,IAAI,QAAQ,EAAE,CAAC;gBACb,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC7B,CAAC;iBAAM,CAAC;gBACN,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE;oBACpB,kBAAkB,EAAE,GAAG;oBACvB,IAAI,EAAE,CAAC,MAAM,CAAC;oBACd,SAAS,EAAE,GAAG;iBACf,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QACD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC;QAClD,OAAO,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;IACzD,CAAC;IACD,OAAO;QACL,kBAAkB,EAAE,qBAAqB,CACvC,cAAc,IAAI,eAAe,CAAC,eAAe,EACjD,SAAS,CACV;QACD,IAAI,EAAE,OAAO;QACb,SAAS,EAAE,GAAG;KACf,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,oBAAoB,CAClC,SAAqB,EACrB,MAAe,EACf,YAAiC,EACjC,OAAe,EACf,cAAsB,EACtB,SAAkB,EAClB,GAAW;IAEX,IAAI,cAAc,KAAK,YAAY,EAAE,CAAC;QACpC,MAAM,YAAY,GAAG,IAAI,GAAG,EAA8B,CAAC;QAC3D,MAAM,WAAW,GAAG,CAAC,UAAkB,EAAsB,EAAE;YAC7D,MAAM,GAAG,GAAG,qBAAqB,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;YACzD,IAAI,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAClC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,KAAK,GAAG;oBACN,kBAAkB,EAAE,GAAG;oBACvB,OAAO;oBACP,SAAS,EAAE,EAAE;oBACb,MAAM,EAAE,EAAE;oBACV,YAAY,EAAE,IAAI;oBAClB,SAAS,EAAE,GAAG;iBACf,CAAC;gBACF,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YAC/B,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC,CAAC;QAEF,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,WAAW,CACT,QAAQ,CAAC,UAAU,IAAI,eAAe,CAAC,eAAe,CACvD,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC7B,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,WAAW,CACT,KAAK,CAAC,UAAU,IAAI,eAAe,CAAC,eAAe,CACpD,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;QACD,IAAI,YAAY,EAAE,CAAC;YACjB,WAAW,CACT,YAAY,CAAC,UAAU,IAAI,eAAe,CAAC,eAAe,CAC3D,CAAC,YAAY,GAAG,YAAY,CAAC;QAChC,CAAC;QAED,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CACtD,CAAC,KAAK,EAAE,EAAE,CACR,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC;YAC1B,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;YACvB,KAAK,CAAC,YAAY,KAAK,IAAI,CAC9B,CAAC;QACF,OAAO,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;IACzD,CAAC;IACD,OAAO;QACL,kBAAkB,EAAE,qBAAqB,CACvC,cAAc,IAAI,eAAe,CAAC,eAAe,EACjD,SAAS,CACV;QACD,OAAO;QACP,SAAS;QACT,MAAM;QACN,YAAY;QACZ,SAAS,EAAE,GAAG;KACf,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CACxC,SAAyB,EACzB,OAA+B;IAE/B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO;IACT,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;IAChE,SAAS;SACN,OAAO,CAAC,wBAAwB,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;SAC1D,KAAK,CAAC,GAAG,EAAE;QACV,gEAAgE;IAClE,CAAC,CAAC,CAAC;AACP,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CACtC,SAAyB,EACzB,OAA6B;IAE7B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO;IACT,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;IAChE,SAAS;SACN,OAAO,CAAC,0BAA0B,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;SAC5D,KAAK,CAAC,GAAG,EAAE;QACV,gEAAgE;IAClE,CAAC,CAAC,CAAC;AACP,CAAC;AAuBD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAAyB,EACzB,kBAAyD,EACzD,gBAAuD,EACvD,YAAoB;IAEpB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,MAAM,aAAa,GAA2C,EAAE,CAAC;IACjE,MAAM,WAAW,GAAyC,EAAE,CAAC;IAC7D,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,IAAI,aAAa,GAAG,CAAC,CAAC;IACtB,IAAI,UAAU,GAAG,CAAC,CAAC;IAEnB,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC;QAC3B,OAAO;YACL,aAAa;YACb,WAAW;YACX,KAAK,EAAE,EAAE,WAAW,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC,EAAE;SACjE,CAAC;IACJ,CAAC;IAED,MAAM,sBAAsB,GAC1B,IAAI,CAAC,GAAG,EAAE,GAAG,YAAY,GAAG,+BAA+B,GAAG,CAAC,CAAC;IAElE,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,SAAS,CAAC,WAAW,CAAC,wBAAwB,CAAC,CAAC;QACnE,MAAM,OAAO,GAAG,SAAS,CAAC,WAAW,CAAC,0BAA0B,CAAC,CAAC;QAElE,IAAI,UAAU,EAAE,CAAC;YACf,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAEG,CAAC;gBACxC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAE,MAAgC,CAAC,OAAO,CAAC;oBACtE,CAAC,CAAE,MAA8C,CAAC,OAAO;oBACzD,CAAC,CAAC,CAAC,MAA8B,CAAC,CAAC;gBAErC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;oBAC5B,IAAI,KAAK,CAAC,kBAAkB,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;wBAC1D,MAAM,QAAQ,GAAG,kBAAkB,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;wBAC9D,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;4BACtD,MAAM,YAAY,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;gCAC/C,GAAG,MAAM;gCACT,KAAK,EAAE,eAAe,CAAC,oBAAoB;gCAC3C,SAAS,EAAE,eAAe,CAAC,mBAAmB;gCAC9C,gBAAgB,EAAE,eAAe,CAAC,yBAAyB;6BAC5D,CAAC,CAAC,CAAC;4BACJ,aAAa,CAAC,KAAK,CAAC,kBAAkB,CAAC,GAAG;gCACxC,IAAI,EAAE,YAAY;gCAClB,yDAAyD;gCACzD,yDAAyD;gCACzD,yCAAyC;gCACzC,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE,sBAAsB,CAAC;6BAC7D,CAAC;4BACF,WAAW,IAAI,YAAY,CAAC,MAAM,CAAC;wBACrC,CAAC;oBACH,CAAC;gBACH,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,iCAAiC;YACnC,CAAC;QACH,CAAC;QAED,IAAI,OAAO,EAAE,CAAC;YACZ,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAEI,CAAC;gBACtC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAE,MAAgC,CAAC,OAAO,CAAC;oBACtE,CAAC,CAAE,MAA4C,CAAC,OAAO;oBACvD,CAAC,CAAC,CAAC,MAA4B,CAAC,CAAC;gBAEnC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;oBAC5B,IAAI,KAAK,CAAC,kBAAkB,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;wBAC9C,8DAA8D;wBAC9D,iEAAiE;wBACjE,mEAAmE;wBACnE,MAAM,QAAQ,GAAG,gBAAgB,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;wBAC5D,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;4BACtD,WAAW,CAAC,KAAK,CAAC,kBAAkB,CAAC,GAAG;gCACtC,SAAS,EAAE,KAAK,CAAC,SAAS;gCAC1B,MAAM,EAAE,KAAK,CAAC,MAAM;gCACpB,YAAY,EAAE,KAAK,CAAC,YAAY;gCAChC,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE,sBAAsB,CAAC;gCAC5D,OAAO,EAAE,KAAK,CAAC,OAAO;6BACvB,CAAC;4BACF,aAAa,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC;4BACxC,UAAU,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;wBACpC,CAAC;oBACH,CAAC;gBACH,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,iCAAiC;YACnC,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,mCAAmC;IACrC,CAAC;IAED,OAAO;QACL,aAAa;QACb,WAAW;QACX,KAAK,EAAE;YACL,WAAW;YACX,aAAa;YACb,UAAU;YACV,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;SACnC;KACF,CAAC;AACJ,CAAC","sourcesContent":["import {\n  buildProviderCacheKey,\n  PERPS_CONSTANTS,\n  PERPS_DISK_CACHE_MARKETS,\n  PERPS_DISK_CACHE_USER_DATA,\n  PROVIDER_CONFIG,\n} from '../constants/perpsConfig';\nimport type { AccountState, Order, PerpsMarketData, Position } from '../types';\n\n/**\n * Multiplier applied to staleGuardMs (preloadGuardMs, currently 30s) to compute\n * the staleness cap for disk-hydrated timestamps. A factor of 10 ensures hydrated\n * data is always TTL-expired so the stream manager overwrites it with live data,\n * while still being recent enough for a useful first paint.\n */\nconst DISK_HYDRATION_STALENESS_FACTOR = 10;\n\n/** Minimal disk cache interface required by persistence utilities. */\nexport type PerpsDiskCache = {\n  getItem(key: string): Promise<string | null>;\n  getItemSync?(key: string): string | null;\n  setItem(key: string, value: string): Promise<void>;\n};\n\n/** Shape of a single market entry persisted to disk cache. */\nexport type DiskCacheMarketEntry = {\n  providerNetworkKey: string;\n  data: PerpsMarketData[];\n  timestamp: number;\n};\n\n/** Shape of a single user-data entry persisted to disk cache. */\nexport type DiskCacheUserEntry = {\n  providerNetworkKey: string;\n  address: string;\n  positions: Position[];\n  orders: Order[];\n  accountState: AccountState | null;\n  timestamp: number;\n};\n\n/** Disk payload shape — either a single entry or a multi-provider wrapper. */\nexport type DiskCacheMarketPayload =\n  | DiskCacheMarketEntry\n  | { entries: DiskCacheMarketEntry[] };\n\nexport type DiskCacheUserPayload =\n  | DiskCacheUserEntry\n  | { entries: DiskCacheUserEntry[] };\n\n/**\n * Build the disk-cache payload for market data.\n * In aggregated mode, groups markets by provider into separate entries.\n *\n * @param markets - Current market data snapshot.\n * @param activeProvider - The active provider id (may be \"aggregated\").\n * @param isTestnet - Global testnet flag.\n * @param now - Timestamp to stamp entries with.\n * @returns Payload ready for JSON serialization.\n */\nexport function buildMarketDataPayload(\n  markets: PerpsMarketData[],\n  activeProvider: string,\n  isTestnet: boolean,\n  now: number,\n): DiskCacheMarketPayload {\n  if (activeProvider === 'aggregated') {\n    const entriesByKey = new Map<string, DiskCacheMarketEntry>();\n    for (const market of markets) {\n      const providerId = market.providerId ?? PROVIDER_CONFIG.DefaultProvider;\n      const key = buildProviderCacheKey(providerId, isTestnet);\n      const existing = entriesByKey.get(key);\n      if (existing) {\n        existing.data.push(market);\n      } else {\n        entriesByKey.set(key, {\n          providerNetworkKey: key,\n          data: [market],\n          timestamp: now,\n        });\n      }\n    }\n    const entries = Array.from(entriesByKey.values());\n    return entries.length === 1 ? entries[0] : { entries };\n  }\n  return {\n    providerNetworkKey: buildProviderCacheKey(\n      activeProvider ?? PROVIDER_CONFIG.DefaultProvider,\n      isTestnet,\n    ),\n    data: markets,\n    timestamp: now,\n  };\n}\n\n/**\n * Build the disk-cache payload for user data (positions, orders, account).\n * In aggregated mode, groups entries by provider.\n *\n * @param positions - Current positions snapshot.\n * @param orders - Current orders snapshot.\n * @param accountState - Current account state snapshot.\n * @param address - EVM account address.\n * @param activeProvider - The active provider id (may be \"aggregated\").\n * @param isTestnet - Global testnet flag.\n * @param now - Timestamp to stamp entries with.\n * @returns Payload ready for JSON serialization.\n */\nexport function buildUserDataPayload(\n  positions: Position[],\n  orders: Order[],\n  accountState: AccountState | null,\n  address: string,\n  activeProvider: string,\n  isTestnet: boolean,\n  now: number,\n): DiskCacheUserPayload {\n  if (activeProvider === 'aggregated') {\n    const entriesByKey = new Map<string, DiskCacheUserEntry>();\n    const ensureEntry = (providerId: string): DiskCacheUserEntry => {\n      const key = buildProviderCacheKey(providerId, isTestnet);\n      let entry = entriesByKey.get(key);\n      if (!entry) {\n        entry = {\n          providerNetworkKey: key,\n          address,\n          positions: [],\n          orders: [],\n          accountState: null,\n          timestamp: now,\n        };\n        entriesByKey.set(key, entry);\n      }\n      return entry;\n    };\n\n    for (const position of positions) {\n      ensureEntry(\n        position.providerId ?? PROVIDER_CONFIG.DefaultProvider,\n      ).positions.push(position);\n    }\n    for (const order of orders) {\n      ensureEntry(\n        order.providerId ?? PROVIDER_CONFIG.DefaultProvider,\n      ).orders.push(order);\n    }\n    if (accountState) {\n      ensureEntry(\n        accountState.providerId ?? PROVIDER_CONFIG.DefaultProvider,\n      ).accountState = accountState;\n    }\n\n    const entries = Array.from(entriesByKey.values()).filter(\n      (entry) =>\n        entry.positions.length > 0 ||\n        entry.orders.length > 0 ||\n        entry.accountState !== null,\n    );\n    return entries.length === 1 ? entries[0] : { entries };\n  }\n  return {\n    providerNetworkKey: buildProviderCacheKey(\n      activeProvider ?? PROVIDER_CONFIG.DefaultProvider,\n      isTestnet,\n    ),\n    address,\n    positions,\n    orders,\n    accountState,\n    timestamp: now,\n  };\n}\n\n/**\n * Write market entries to disk (best-effort, non-blocking).\n *\n * @param diskCache - Disk cache instance from controller infrastructure.\n * @param entries - Pre-assembled market cache entries to persist.\n */\nexport function persistMarketEntriesToDisk(\n  diskCache: PerpsDiskCache,\n  entries: DiskCacheMarketEntry[],\n): void {\n  if (entries.length === 0) {\n    return;\n  }\n  const payload = entries.length === 1 ? entries[0] : { entries };\n  diskCache\n    .setItem(PERPS_DISK_CACHE_MARKETS, JSON.stringify(payload))\n    .catch(() => {\n      // Disk persistence is best-effort and must never block preload.\n    });\n}\n\n/**\n * Write user data entries to disk (best-effort, non-blocking).\n *\n * @param diskCache - Disk cache instance from controller infrastructure.\n * @param entries - Pre-assembled user cache entries to persist.\n */\nexport function persistUserEntriesToDisk(\n  diskCache: PerpsDiskCache,\n  entries: DiskCacheUserEntry[],\n): void {\n  if (entries.length === 0) {\n    return;\n  }\n  const payload = entries.length === 1 ? entries[0] : { entries };\n  diskCache\n    .setItem(PERPS_DISK_CACHE_USER_DATA, JSON.stringify(payload))\n    .catch(() => {\n      // Disk persistence is best-effort and must never block preload.\n    });\n}\n\n/** Computed updates returned by hydrateFromDiskSync. */\nexport type HydrateFromDiskResult = {\n  marketUpdates: Record<string, { data: PerpsMarketData[]; timestamp: number }>;\n  userUpdates: Record<\n    string,\n    {\n      positions: Position[];\n      orders: Order[];\n      accountState: AccountState | null;\n      timestamp: number;\n      address: string;\n    }\n  >;\n  stats: {\n    marketCount: number;\n    userPositions: number;\n    userOrders: number;\n    durationMs: number;\n  };\n};\n\n/**\n * Read disk-persisted cache snapshots and compute the state updates to apply.\n * Returns plain objects rather than mutating state directly, so the caller\n * can apply all changes in a single batched this.update() call.\n *\n * All returned timestamps are capped at DISK_HYDRATION_STALENESS_FACTOR * staleGuardMs\n * in the past so the stream manager always overwrites disk data with fresh live data.\n *\n * @param diskCache - Disk cache instance from controller infrastructure.\n * @param currentMarketCache - Current cachedMarketDataByProvider state.\n * @param currentUserCache - Current cachedUserDataByProvider state.\n * @param staleGuardMs - preloadGuardMs constant from the controller.\n * @returns Updates to apply plus stats for debug logging.\n */\nexport function hydrateFromDiskSync(\n  diskCache: PerpsDiskCache,\n  currentMarketCache: Record<string, { timestamp: number }>,\n  currentUserCache: Record<string, { timestamp: number }>,\n  staleGuardMs: number,\n): HydrateFromDiskResult {\n  const hydrateT0 = Date.now();\n  const marketUpdates: HydrateFromDiskResult['marketUpdates'] = {};\n  const userUpdates: HydrateFromDiskResult['userUpdates'] = {};\n  let marketCount = 0;\n  let userPositions = 0;\n  let userOrders = 0;\n\n  if (!diskCache.getItemSync) {\n    return {\n      marketUpdates,\n      userUpdates,\n      stats: { marketCount, userPositions, userOrders, durationMs: 0 },\n    };\n  }\n\n  const staleHydratedTimestamp =\n    Date.now() - staleGuardMs * DISK_HYDRATION_STALENESS_FACTOR - 1;\n\n  try {\n    const marketsRaw = diskCache.getItemSync(PERPS_DISK_CACHE_MARKETS);\n    const userRaw = diskCache.getItemSync(PERPS_DISK_CACHE_USER_DATA);\n\n    if (marketsRaw) {\n      try {\n        const parsed = JSON.parse(marketsRaw) as\n          | DiskCacheMarketEntry\n          | { entries: DiskCacheMarketEntry[] };\n        const entries = Array.isArray((parsed as { entries?: unknown }).entries)\n          ? (parsed as { entries: DiskCacheMarketEntry[] }).entries\n          : [parsed as DiskCacheMarketEntry];\n\n        for (const entry of entries) {\n          if (entry.providerNetworkKey && Array.isArray(entry.data)) {\n            const existing = currentMarketCache[entry.providerNetworkKey];\n            if (!existing || existing.timestamp < entry.timestamp) {\n              const strippedData = entry.data.map((market) => ({\n                ...market,\n                price: PERPS_CONSTANTS.FallbackPriceDisplay,\n                change24h: PERPS_CONSTANTS.FallbackDataDisplay,\n                change24hPercent: PERPS_CONSTANTS.FallbackPercentageDisplay,\n              }));\n              marketUpdates[entry.providerNetworkKey] = {\n                data: strippedData,\n                // Disk-hydrated market snapshots are only for structural\n                // first paint. Keep them TTL-stale so the stream manager\n                // still fetches fresh prices on connect.\n                timestamp: Math.min(entry.timestamp, staleHydratedTimestamp),\n              };\n              marketCount += strippedData.length;\n            }\n          }\n        }\n      } catch {\n        // Corrupt JSON — silently ignore\n      }\n    }\n\n    if (userRaw) {\n      try {\n        const parsed = JSON.parse(userRaw) as\n          | DiskCacheUserEntry\n          | { entries: DiskCacheUserEntry[] };\n        const entries = Array.isArray((parsed as { entries?: unknown }).entries)\n          ? (parsed as { entries: DiskCacheUserEntry[] }).entries\n          : [parsed as DiskCacheUserEntry];\n\n        for (const entry of entries) {\n          if (entry.providerNetworkKey && entry.address) {\n            // Skip address check here — accounts may not be loaded yet at\n            // constructor time. getCachedUserDataForActiveProvider validates\n            // the address at read time, so stale-account data is never served.\n            const existing = currentUserCache[entry.providerNetworkKey];\n            if (!existing || existing.timestamp < entry.timestamp) {\n              userUpdates[entry.providerNetworkKey] = {\n                positions: entry.positions,\n                orders: entry.orders,\n                accountState: entry.accountState,\n                timestamp: Math.min(entry.timestamp, staleHydratedTimestamp),\n                address: entry.address,\n              };\n              userPositions += entry.positions.length;\n              userOrders += entry.orders.length;\n            }\n          }\n        }\n      } catch {\n        // Corrupt JSON — silently ignore\n      }\n    }\n  } catch {\n    // Disk read failure — non-critical\n  }\n\n  return {\n    marketUpdates,\n    userUpdates,\n    stats: {\n      marketCount,\n      userPositions,\n      userOrders,\n      durationMs: Date.now() - hydrateT0,\n    },\n  };\n}\n"]}