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

package/dist/utils/perpsDiskPersistence.cjs

@@ -0,0 +1,252 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hydrateFromDiskSync = exports.persistUserEntriesToDisk = exports.persistMarketEntriesToDisk = exports.buildUserDataPayload = exports.buildMarketDataPayload = void 0;
+const perpsConfig_1 = require("../constants/perpsConfig.cjs");
+/**
+ * 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.
+ */
+function buildMarketDataPayload(markets, activeProvider, isTestnet, now) {
+    if (activeProvider === 'aggregated') {
+        const entriesByKey = new Map();
+        for (const market of markets) {
+            const providerId = market.providerId ?? perpsConfig_1.PROVIDER_CONFIG.DefaultProvider;
+            const key = (0, perpsConfig_1.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: (0, perpsConfig_1.buildProviderCacheKey)(activeProvider ?? perpsConfig_1.PROVIDER_CONFIG.DefaultProvider, isTestnet),
+        data: markets,
+        timestamp: now,
+    };
+}
+exports.buildMarketDataPayload = buildMarketDataPayload;
+/**
+ * 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.
+ */
+function buildUserDataPayload(positions, orders, accountState, address, activeProvider, isTestnet, now) {
+    if (activeProvider === 'aggregated') {
+        const entriesByKey = new Map();
+        const ensureEntry = (providerId) => {
+            const key = (0, perpsConfig_1.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 ?? perpsConfig_1.PROVIDER_CONFIG.DefaultProvider).positions.push(position);
+        }
+        for (const order of orders) {
+            ensureEntry(order.providerId ?? perpsConfig_1.PROVIDER_CONFIG.DefaultProvider).orders.push(order);
+        }
+        if (accountState) {
+            ensureEntry(accountState.providerId ?? perpsConfig_1.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: (0, perpsConfig_1.buildProviderCacheKey)(activeProvider ?? perpsConfig_1.PROVIDER_CONFIG.DefaultProvider, isTestnet),
+        address,
+        positions,
+        orders,
+        accountState,
+        timestamp: now,
+    };
+}
+exports.buildUserDataPayload = buildUserDataPayload;
+/**
+ * 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.
+ */
+function persistMarketEntriesToDisk(diskCache, entries) {
+    if (entries.length === 0) {
+        return;
+    }
+    const payload = entries.length === 1 ? entries[0] : { entries };
+    diskCache
+        .setItem(perpsConfig_1.PERPS_DISK_CACHE_MARKETS, JSON.stringify(payload))
+        .catch(() => {
+        // Disk persistence is best-effort and must never block preload.
+    });
+}
+exports.persistMarketEntriesToDisk = persistMarketEntriesToDisk;
+/**
+ * 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.
+ */
+function persistUserEntriesToDisk(diskCache, entries) {
+    if (entries.length === 0) {
+        return;
+    }
+    const payload = entries.length === 1 ? entries[0] : { entries };
+    diskCache
+        .setItem(perpsConfig_1.PERPS_DISK_CACHE_USER_DATA, JSON.stringify(payload))
+        .catch(() => {
+        // Disk persistence is best-effort and must never block preload.
+    });
+}
+exports.persistUserEntriesToDisk = persistUserEntriesToDisk;
+/**
+ * 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.
+ */
+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(perpsConfig_1.PERPS_DISK_CACHE_MARKETS);
+        const userRaw = diskCache.getItemSync(perpsConfig_1.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: perpsConfig_1.PERPS_CONSTANTS.FallbackPriceDisplay,
+                                change24h: perpsConfig_1.PERPS_CONSTANTS.FallbackDataDisplay,
+                                change24hPercent: perpsConfig_1.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,
+        },
+    };
+}
+exports.hydrateFromDiskSync = hydrateFromDiskSync;
+//# sourceMappingURL=perpsDiskPersistence.cjs.map

package/dist/utils/perpsDiskPersistence.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"perpsDiskPersistence.cjs","sourceRoot":"","sources":["../../src/utils/perpsDiskPersistence.ts"],"names":[],"mappings":"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","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"]}

package/dist/utils/perpsDiskPersistence.d.cts

@@ -0,0 +1,108 @@
+import type { AccountState, Order, PerpsMarketData, Position } from "../types/index.cjs";
+/** Minimal disk cache interface required by persistence utilities. */
+export type PerpsDiskCache = {
+    getItem(key: string): Promise<string | null>;
+    getItemSync?(key: string): string | null;
+    setItem(key: string, value: string): Promise<void>;
+};
+/** Shape of a single market entry persisted to disk cache. */
+export type DiskCacheMarketEntry = {
+    providerNetworkKey: string;
+    data: PerpsMarketData[];
+    timestamp: number;
+};
+/** Shape of a single user-data entry persisted to disk cache. */
+export type DiskCacheUserEntry = {
+    providerNetworkKey: string;
+    address: string;
+    positions: Position[];
+    orders: Order[];
+    accountState: AccountState | null;
+    timestamp: number;
+};
+/** Disk payload shape — either a single entry or a multi-provider wrapper. */
+export type DiskCacheMarketPayload = DiskCacheMarketEntry | {
+    entries: DiskCacheMarketEntry[];
+};
+export type DiskCacheUserPayload = DiskCacheUserEntry | {
+    entries: DiskCacheUserEntry[];
+};
+/**
+ * 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 declare function buildMarketDataPayload(markets: PerpsMarketData[], activeProvider: string, isTestnet: boolean, now: number): DiskCacheMarketPayload;
+/**
+ * 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 declare function buildUserDataPayload(positions: Position[], orders: Order[], accountState: AccountState | null, address: string, activeProvider: string, isTestnet: boolean, now: number): DiskCacheUserPayload;
+/**
+ * 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 declare function persistMarketEntriesToDisk(diskCache: PerpsDiskCache, entries: DiskCacheMarketEntry[]): void;
+/**
+ * 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 declare function persistUserEntriesToDisk(diskCache: PerpsDiskCache, entries: DiskCacheUserEntry[]): void;
+/** Computed updates returned by hydrateFromDiskSync. */
+export type HydrateFromDiskResult = {
+    marketUpdates: Record<string, {
+        data: PerpsMarketData[];
+        timestamp: number;
+    }>;
+    userUpdates: Record<string, {
+        positions: Position[];
+        orders: Order[];
+        accountState: AccountState | null;
+        timestamp: number;
+        address: string;
+    }>;
+    stats: {
+        marketCount: number;
+        userPositions: number;
+        userOrders: number;
+        durationMs: number;
+    };
+};
+/**
+ * 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 declare function hydrateFromDiskSync(diskCache: PerpsDiskCache, currentMarketCache: Record<string, {
+    timestamp: number;
+}>, currentUserCache: Record<string, {
+    timestamp: number;
+}>, staleGuardMs: number): HydrateFromDiskResult;
+//# sourceMappingURL=perpsDiskPersistence.d.cts.map

package/dist/utils/perpsDiskPersistence.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"perpsDiskPersistence.d.cts","sourceRoot":"","sources":["../../src/utils/perpsDiskPersistence.ts"],"names":[],"mappings":"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"}

package/dist/utils/perpsDiskPersistence.d.mts

@@ -0,0 +1,108 @@
+import type { AccountState, Order, PerpsMarketData, Position } from "../types/index.mjs";
+/** Minimal disk cache interface required by persistence utilities. */
+export type PerpsDiskCache = {
+    getItem(key: string): Promise<string | null>;
+    getItemSync?(key: string): string | null;
+    setItem(key: string, value: string): Promise<void>;
+};
+/** Shape of a single market entry persisted to disk cache. */
+export type DiskCacheMarketEntry = {
+    providerNetworkKey: string;
+    data: PerpsMarketData[];
+    timestamp: number;
+};
+/** Shape of a single user-data entry persisted to disk cache. */
+export type DiskCacheUserEntry = {
+    providerNetworkKey: string;
+    address: string;
+    positions: Position[];
+    orders: Order[];
+    accountState: AccountState | null;
+    timestamp: number;
+};
+/** Disk payload shape — either a single entry or a multi-provider wrapper. */
+export type DiskCacheMarketPayload = DiskCacheMarketEntry | {
+    entries: DiskCacheMarketEntry[];
+};
+export type DiskCacheUserPayload = DiskCacheUserEntry | {
+    entries: DiskCacheUserEntry[];
+};
+/**
+ * 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 declare function buildMarketDataPayload(markets: PerpsMarketData[], activeProvider: string, isTestnet: boolean, now: number): DiskCacheMarketPayload;
+/**
+ * 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 declare function buildUserDataPayload(positions: Position[], orders: Order[], accountState: AccountState | null, address: string, activeProvider: string, isTestnet: boolean, now: number): DiskCacheUserPayload;
+/**
+ * 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 declare function persistMarketEntriesToDisk(diskCache: PerpsDiskCache, entries: DiskCacheMarketEntry[]): void;
+/**
+ * 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 declare function persistUserEntriesToDisk(diskCache: PerpsDiskCache, entries: DiskCacheUserEntry[]): void;
+/** Computed updates returned by hydrateFromDiskSync. */
+export type HydrateFromDiskResult = {
+    marketUpdates: Record<string, {
+        data: PerpsMarketData[];
+        timestamp: number;
+    }>;
+    userUpdates: Record<string, {
+        positions: Position[];
+        orders: Order[];
+        accountState: AccountState | null;
+        timestamp: number;
+        address: string;
+    }>;
+    stats: {
+        marketCount: number;
+        userPositions: number;
+        userOrders: number;
+        durationMs: number;
+    };
+};
+/**
+ * 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 declare function hydrateFromDiskSync(diskCache: PerpsDiskCache, currentMarketCache: Record<string, {
+    timestamp: number;
+}>, currentUserCache: Record<string, {
+    timestamp: number;
+}>, staleGuardMs: number): HydrateFromDiskResult;
+//# sourceMappingURL=perpsDiskPersistence.d.mts.map

package/dist/utils/perpsDiskPersistence.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"perpsDiskPersistence.d.mts","sourceRoot":"","sources":["../../src/utils/perpsDiskPersistence.ts"],"names":[],"mappings":"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"}