@pioneer-platform/pioneer-cache 1.6.0 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @pioneer-platform/pioneer-cache
 
+## 1.8.0
+
+### Minor Changes
+
+- chore: chore: chore: chore: chore: chore: feat(pioneer): implement end-to-end Solana transaction signing
+
+## 1.7.0
+
+### Minor Changes
+
+- chore: chore: chore: chore: chore: feat(pioneer): implement end-to-end Solana transaction signing
+
 ## 1.6.0
 
 ### Minor Changes

package/dist/core/cache-manager.d.ts

@@ -3,6 +3,7 @@ import { PriceCache } from '../stores/price-cache';
 import { PortfolioCache } from '../stores/portfolio-cache';
 import { TransactionCache } from '../stores/transaction-cache';
 import { StakingCache } from '../stores/staking-cache';
+import { ZapperCache } from '../stores/zapper-cache';
 import type { HealthCheckResult } from '../types';
 /**
  * Configuration for CacheManager
@@ -13,11 +14,13 @@ export interface CacheManagerConfig {
     balanceModule?: any;
     markets?: any;
     networkModules?: Map<string, any>;
+    zapperClient?: any;
     enableBalanceCache?: boolean;
     enablePriceCache?: boolean;
     enablePortfolioCache?: boolean;
     enableTransactionCache?: boolean;
     enableStakingCache?: boolean;
+    enableZapperCache?: boolean;
     startWorkers?: boolean;
 }
 /**
@@ -31,6 +34,7 @@ export declare class CacheManager {
     private portfolioCache?;
     private transactionCache?;
     private stakingCache?;
+    private zapperCache?;
     private workers;
     constructor(config: CacheManagerConfig);
     /**
@@ -57,11 +61,12 @@ export declare class CacheManager {
         portfolio: PortfolioCache | undefined;
         transaction: TransactionCache | undefined;
         staking: StakingCache | undefined;
+        zapper: ZapperCache | undefined;
     };
     /**
      * Get specific cache by name
      */
-    getCache(name: 'balance' | 'price' | 'portfolio' | 'transaction' | 'staking'): BalanceCache | PriceCache | PortfolioCache | TransactionCache | StakingCache | undefined;
+    getCache(name: 'balance' | 'price' | 'portfolio' | 'transaction' | 'staking' | 'zapper'): BalanceCache | PriceCache | PortfolioCache | TransactionCache | StakingCache | ZapperCache | undefined;
     /**
      * Clear all caches (use with caution!)
      */
@@ -71,5 +76,6 @@ export declare class CacheManager {
         portfolio?: number;
         transaction?: number;
         staking?: number;
+        zapper?: number;
     }>;
 }

package/dist/core/cache-manager.js

@@ -12,6 +12,7 @@ const price_cache_1 = require("../stores/price-cache");
 const portfolio_cache_1 = require("../stores/portfolio-cache");
 const transaction_cache_1 = require("../stores/transaction-cache");
 const staking_cache_1 = require("../stores/staking-cache");
+const zapper_cache_1 = require("../stores/zapper-cache");
 const refresh_worker_1 = require("../workers/refresh-worker");
 const log = require('@pioneer-platform/loggerdog')();
 const TAG = ' | CacheManager | ';
@@ -48,6 +49,11 @@ class CacheManager {
             this.stakingCache = new staking_cache_1.StakingCache(this.redis, config.networkModules, config.markets);
             log.info(TAG, '✅ Staking cache initialized');
         }
+        // Initialize Zapper Cache
+        if (config.enableZapperCache !== false && config.zapperClient) {
+            this.zapperCache = new zapper_cache_1.ZapperCache(this.redis, config.zapperClient);
+            log.info(TAG, '✅ Zapper cache initialized');
+        }
         // Auto-start workers if requested
         if (config.startWorkers) {
             setImmediate(() => {
@@ -77,6 +83,9 @@ class CacheManager {
             if (this.stakingCache) {
                 cacheRegistry.set('staking', this.stakingCache);
             }
+            if (this.zapperCache) {
+                cacheRegistry.set('zapper', this.zapperCache);
+            }
             // Start unified worker if we have any caches with queues
             if (cacheRegistry.size > 0) {
                 const worker = await (0, refresh_worker_1.startUnifiedWorker)(this.redisQueue, // Use dedicated queue client for blocking operations
@@ -175,6 +184,17 @@ class CacheManager {
                     warnings.push(...stakingHealth.warnings.map(w => `Staking: ${w}`));
                 }
             }
+            // Check zapper cache
+            if (this.zapperCache) {
+                const zapperHealth = await this.zapperCache.getHealth(forceRefresh);
+                checks.zapper = zapperHealth;
+                if (zapperHealth.status === 'unhealthy') {
+                    issues.push(...zapperHealth.issues.map(i => `Zapper: ${i}`));
+                }
+                else if (zapperHealth.status === 'degraded') {
+                    warnings.push(...zapperHealth.warnings.map(w => `Zapper: ${w}`));
+                }
+            }
             // Check workers
             for (const worker of this.workers) {
                 const workerStats = await worker.getStats();
@@ -236,7 +256,8 @@ class CacheManager {
             price: this.priceCache,
             portfolio: this.portfolioCache,
             transaction: this.transactionCache,
-            staking: this.stakingCache
+            staking: this.stakingCache,
+            zapper: this.zapperCache
         };
     }
     /**
@@ -254,6 +275,8 @@ class CacheManager {
                 return this.transactionCache;
             case 'staking':
                 return this.stakingCache;
+            case 'zapper':
+                return this.zapperCache;
             default:
                 return undefined;
         }
@@ -280,6 +303,9 @@ class CacheManager {
             if (this.stakingCache) {
                 result.staking = await this.stakingCache.clearAll();
             }
+            if (this.zapperCache) {
+                result.zapper = await this.zapperCache.clearAll();
+            }
             log.info(tag, 'Cleared all caches:', result);
             return result;
         }

package/dist/index.d.ts

@@ -5,11 +5,13 @@ export { PriceCache } from './stores/price-cache';
 export { PortfolioCache } from './stores/portfolio-cache';
 export { TransactionCache } from './stores/transaction-cache';
 export { StakingCache } from './stores/staking-cache';
+export { ZapperCache } from './stores/zapper-cache';
 export { RefreshWorker, startUnifiedWorker } from './workers/refresh-worker';
 export type { CacheConfig, CachedValue, CacheResult, RefreshJob, HealthCheckResult, CacheStats } from './types';
 export type { BalanceData } from './stores/balance-cache';
 export type { PriceData } from './stores/price-cache';
 export type { PortfolioData, ChartData } from './stores/portfolio-cache';
 export type { StakingPosition } from './stores/staking-cache';
+export type { ZapperPortfolioData, ZapperNFTData, ZapperAppsData, ZapperTotalsData } from './stores/zapper-cache';
 export type { CacheManagerConfig } from './core/cache-manager';
 export type { WorkerConfig } from './workers/refresh-worker';

package/dist/index.js

@@ -6,7 +6,7 @@
     Provides stale-while-revalidate caching with TTL, background refresh, and health monitoring.
 */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.startUnifiedWorker = exports.RefreshWorker = exports.StakingCache = exports.TransactionCache = exports.PortfolioCache = exports.PriceCache = exports.BalanceCache = exports.CacheManager = exports.BaseCache = void 0;
+exports.startUnifiedWorker = exports.RefreshWorker = exports.ZapperCache = exports.StakingCache = exports.TransactionCache = exports.PortfolioCache = exports.PriceCache = exports.BalanceCache = exports.CacheManager = exports.BaseCache = void 0;
 // Core exports
 var base_cache_1 = require("./core/base-cache");
 Object.defineProperty(exports, "BaseCache", { enumerable: true, get: function () { return base_cache_1.BaseCache; } });
@@ -23,6 +23,8 @@ var transaction_cache_1 = require("./stores/transaction-cache");
 Object.defineProperty(exports, "TransactionCache", { enumerable: true, get: function () { return transaction_cache_1.TransactionCache; } });
 var staking_cache_1 = require("./stores/staking-cache");
 Object.defineProperty(exports, "StakingCache", { enumerable: true, get: function () { return staking_cache_1.StakingCache; } });
+var zapper_cache_1 = require("./stores/zapper-cache");
+Object.defineProperty(exports, "ZapperCache", { enumerable: true, get: function () { return zapper_cache_1.ZapperCache; } });
 // Worker exports
 var refresh_worker_1 = require("./workers/refresh-worker");
 Object.defineProperty(exports, "RefreshWorker", { enumerable: true, get: function () { return refresh_worker_1.RefreshWorker; } });

package/dist/stores/zapper-cache.d.ts

@@ -0,0 +1,163 @@
+import { BaseCache } from '../core/base-cache';
+import type { CacheConfig } from '../types';
+/**
+ * Zapper portfolio data structure
+ */
+export interface ZapperPortfolioData {
+    address: string;
+    balances: Array<{
+        balance: string;
+        chain: string;
+        networkId: string;
+        symbol: string;
+        ticker: string;
+        name: string;
+        caip: string;
+        tokenAddress?: string;
+        tokenType: string;
+        priceUsd: string;
+        valueUsd: string;
+        icon?: string;
+        display?: string[];
+        decimals?: number;
+        appId?: string;
+        groupId?: string;
+        metaType?: string;
+        pubkey?: string;
+    }>;
+    tokens?: any[];
+    nfts: any[];
+    totalNetWorth: number;
+    totalBalanceUsdTokens: number;
+    totalBalanceUSDApp: number;
+    nftUsdNetWorth: {
+        [address: string]: string;
+    };
+}
+/**
+ * Zapper NFT data structure
+ */
+export interface ZapperNFTData {
+    items: Array<{
+        tokenId: string;
+        name: string;
+        description?: string;
+        collection: {
+            address: string;
+            name: string;
+            network: string;
+            type: string;
+        };
+        estimatedValue: {
+            valueUsd: number;
+        };
+        mediasV3: {
+            images: {
+                edges: Array<{
+                    node: {
+                        originalUri: string;
+                        thumbnail: string;
+                    };
+                }>;
+            };
+        };
+    }>;
+    totalCount: number;
+    totalBalanceUSD: number;
+}
+/**
+ * Zapper apps data structure
+ */
+export interface ZapperAppsData {
+    edges: Array<{
+        node: {
+            balanceUSD: number;
+            app: {
+                slug: string;
+                displayName: string;
+            };
+            network: {
+                name: string;
+            };
+        };
+    }>;
+}
+/**
+ * Zapper totals data structure
+ */
+export interface ZapperTotalsData {
+    totalNetWorth: number;
+    fetchedAt: number;
+}
+/**
+ * ZapperCache - Caches Zapper API responses with 24-hour refresh cycle
+ *
+ * CRITICAL: Zapper API is EXPENSIVE - minimize calls!
+ * - First request: Blocks and waits for Zapper API
+ * - Cached data NEVER expires from Redis
+ * - Data stays fresh for 24 hours
+ * - After 24 hours: Returns cached data + triggers background refresh
+ * - Maximum 1 API call per address per day
+ */
+export declare class ZapperCache extends BaseCache<ZapperPortfolioData | ZapperNFTData | ZapperAppsData | ZapperTotalsData> {
+    private zapperClient;
+    constructor(redis: any, zapperClient: any, config?: Partial<CacheConfig>);
+    /**
+     * Build Redis key for Zapper data
+     *
+     * Key strategy: zapper_v1:{dataType}:{address}
+     *
+     * Examples:
+     * - zapper_v1:portfolio:0x1234...
+     * - zapper_v1:nfts:0x1234...
+     * - zapper_v1:apps:0x1234...
+     * - zapper_v1:totals:0x1234...
+     */
+    protected buildKey(params: Record<string, any>): string;
+    /**
+     * Fetch data from Zapper API
+     *
+     * CRITICAL: This is an EXPENSIVE operation!
+     * Only called on:
+     * 1. First request (cache miss)
+     * 2. Background refresh after 24 hours
+     */
+    protected fetchFromSource(params: Record<string, any>): Promise<any>;
+    /**
+     * Legacy cache fallback (not applicable for Zapper)
+     */
+    protected getLegacyCached(params: Record<string, any>): Promise<any | null>;
+    /**
+     * Get portfolio data for an address
+     */
+    getPortfolio(address: string, forceRefresh?: boolean): Promise<ZapperPortfolioData>;
+    /**
+     * Get NFT data for an address
+     */
+    getNFTs(address: string, forceRefresh?: boolean): Promise<ZapperNFTData>;
+    /**
+     * Get DeFi app positions for an address
+     */
+    getApps(address: string, forceRefresh?: boolean): Promise<ZapperAppsData>;
+    /**
+     * Get portfolio totals for an address
+     */
+    getTotals(address: string, forceRefresh?: boolean): Promise<ZapperTotalsData>;
+    /**
+     * Clear cache for an address
+     * @param address - Ethereum address
+     * @param dataType - Optional: specific data type to clear, or all if omitted
+     */
+    clearAddress(address: string, dataType?: string): Promise<number>;
+    /**
+     * Get cache statistics for an address
+     */
+    getAddressStats(address: string): Promise<{
+        address: string;
+        cached: string[];
+        ages: {
+            [key: string]: number;
+        };
+        staleThreshold: number;
+    }>;
+}

package/dist/stores/zapper-cache.js

@@ -0,0 +1,239 @@
+"use strict";
+/*
+    ZapperCache - Zapper portfolio data cache implementation
+
+    Extends BaseCache with Zapper-specific logic.
+
+    CRITICAL: This is an EXPENSIVE API - minimize calls!
+    - Data NEVER expires (enableTTL: false)
+    - 24-hour stale threshold before background refresh
+    - Maximum 1 API call per address per day
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZapperCache = void 0;
+const base_cache_1 = require("../core/base-cache");
+const log = require('@pioneer-platform/loggerdog')();
+/**
+ * ZapperCache - Caches Zapper API responses with 24-hour refresh cycle
+ *
+ * CRITICAL: Zapper API is EXPENSIVE - minimize calls!
+ * - First request: Blocks and waits for Zapper API
+ * - Cached data NEVER expires from Redis
+ * - Data stays fresh for 24 hours
+ * - After 24 hours: Returns cached data + triggers background refresh
+ * - Maximum 1 API call per address per day
+ */
+class ZapperCache extends base_cache_1.BaseCache {
+    constructor(redis, zapperClient, config) {
+        const defaultConfig = {
+            name: 'zapper',
+            keyPrefix: 'zapper_v1:',
+            ttl: 0, // Ignored when enableTTL: false
+            staleThreshold: 24 * 60 * 60 * 1000, // 24 hours - ONLY refresh after this
+            enableTTL: false, // NEVER EXPIRE - data persists forever
+            queueName: 'cache-refresh',
+            enableQueue: true,
+            maxRetries: 3,
+            retryDelay: 5000,
+            blockOnMiss: true, // BLOCK on first request (no cached data yet)
+            enableLegacyFallback: false, // No legacy Zapper cache format
+            defaultValue: {
+                balances: [],
+                tokens: [],
+                nfts: [],
+                totalNetWorth: 0,
+                totalBalanceUsdTokens: 0,
+                totalBalanceUSDApp: 0,
+                nftUsdNetWorth: {}
+            },
+            useSyncFallback: false,
+            maxConcurrentJobs: 2, // Limit concurrent Zapper API calls
+            apiTimeout: 30000, // 30s timeout for Zapper API
+            logCacheHits: true,
+            logCacheMisses: true,
+            logRefreshJobs: true
+        };
+        super(redis, { ...defaultConfig, ...config });
+        if (!zapperClient) {
+            throw new Error('ZapperCache requires zapperClient');
+        }
+        this.zapperClient = zapperClient;
+    }
+    /**
+     * Build Redis key for Zapper data
+     *
+     * Key strategy: zapper_v1:{dataType}:{address}
+     *
+     * Examples:
+     * - zapper_v1:portfolio:0x1234...
+     * - zapper_v1:nfts:0x1234...
+     * - zapper_v1:apps:0x1234...
+     * - zapper_v1:totals:0x1234...
+     */
+    buildKey(params) {
+        const { address, dataType } = params;
+        if (!address) {
+            throw new Error('ZapperCache.buildKey: address required');
+        }
+        if (!dataType) {
+            throw new Error('ZapperCache.buildKey: dataType required (portfolio, nfts, apps, totals)');
+        }
+        // Normalize address to lowercase
+        const normalizedAddress = address.toLowerCase();
+        // Validate Ethereum address format
+        if (!normalizedAddress.match(/^0x[a-f0-9]{40}$/)) {
+            throw new Error(`ZapperCache.buildKey: invalid Ethereum address format: ${address}`);
+        }
+        return `${this.config.keyPrefix}${dataType}:${normalizedAddress}`;
+    }
+    /**
+     * Fetch data from Zapper API
+     *
+     * CRITICAL: This is an EXPENSIVE operation!
+     * Only called on:
+     * 1. First request (cache miss)
+     * 2. Background refresh after 24 hours
+     */
+    async fetchFromSource(params) {
+        const tag = this.TAG + 'fetchFromSource | ';
+        const { address, dataType } = params;
+        try {
+            log.info(tag, `🌐 Fetching ${dataType} from Zapper API for ${address} (EXPENSIVE!)`);
+            let result;
+            switch (dataType) {
+                case 'portfolio':
+                    result = await this.zapperClient.getPortfolio(address);
+                    result.address = address;
+                    break;
+                case 'nfts':
+                    result = await this.zapperClient.getNFTs(address);
+                    break;
+                case 'apps':
+                    result = await this.zapperClient.getTokens(address);
+                    break;
+                case 'totals':
+                    const totalNetWorth = await this.zapperClient.getTotalNetworth(address);
+                    result = {
+                        totalNetWorth,
+                        fetchedAt: Date.now()
+                    };
+                    break;
+                default:
+                    throw new Error(`Unknown dataType: ${dataType}`);
+            }
+            log.info(tag, `✅ Successfully fetched ${dataType} for ${address} from Zapper`);
+            return result;
+        }
+        catch (error) {
+            log.error(tag, `❌ Failed to fetch ${dataType} from Zapper for ${address}:`, error);
+            throw error;
+        }
+    }
+    /**
+     * Legacy cache fallback (not applicable for Zapper)
+     */
+    async getLegacyCached(params) {
+        // No legacy Zapper cache format exists
+        return null;
+    }
+    /**
+     * Get portfolio data for an address
+     */
+    async getPortfolio(address, forceRefresh) {
+        const result = await this.get({ address, dataType: 'portfolio' }, forceRefresh);
+        return result.value;
+    }
+    /**
+     * Get NFT data for an address
+     */
+    async getNFTs(address, forceRefresh) {
+        const result = await this.get({ address, dataType: 'nfts' }, forceRefresh);
+        return result.value;
+    }
+    /**
+     * Get DeFi app positions for an address
+     */
+    async getApps(address, forceRefresh) {
+        const result = await this.get({ address, dataType: 'apps' }, forceRefresh);
+        return result.value;
+    }
+    /**
+     * Get portfolio totals for an address
+     */
+    async getTotals(address, forceRefresh) {
+        const result = await this.get({ address, dataType: 'totals' }, forceRefresh);
+        return result.value;
+    }
+    /**
+     * Clear cache for an address
+     * @param address - Ethereum address
+     * @param dataType - Optional: specific data type to clear, or all if omitted
+     */
+    async clearAddress(address, dataType) {
+        const tag = this.TAG + 'clearAddress | ';
+        try {
+            const normalizedAddress = address.toLowerCase();
+            let cleared = 0;
+            if (dataType) {
+                // Clear specific data type
+                const key = this.buildKey({ address: normalizedAddress, dataType });
+                cleared = await this.redis.del(key);
+                log.info(tag, `Cleared ${dataType} cache for ${address}`);
+            }
+            else {
+                // Clear all data types for this address
+                const pattern = `${this.config.keyPrefix}*:${normalizedAddress}`;
+                const keys = await this.redis.keys(pattern);
+                if (keys.length > 0) {
+                    cleared = await this.redis.del(...keys);
+                }
+                log.info(tag, `Cleared ${cleared} cache entries for ${address}`);
+            }
+            return cleared;
+        }
+        catch (error) {
+            log.error(tag, `Error clearing cache for ${address}:`, error);
+            return 0;
+        }
+    }
+    /**
+     * Get cache statistics for an address
+     */
+    async getAddressStats(address) {
+        const tag = this.TAG + 'getAddressStats | ';
+        try {
+            const normalizedAddress = address.toLowerCase();
+            const pattern = `${this.config.keyPrefix}*:${normalizedAddress}`;
+            const keys = await this.redis.keys(pattern);
+            const cached = [];
+            const ages = {};
+            for (const key of keys) {
+                // Extract data type from key (e.g., "zapper_v1:portfolio:0x123..." -> "portfolio")
+                const parts = key.split(':');
+                const dataType = parts[1];
+                const data = await this.redis.get(key);
+                if (data) {
+                    const parsed = JSON.parse(data);
+                    cached.push(dataType);
+                    ages[dataType] = Math.round((Date.now() - parsed.timestamp) / 1000);
+                }
+            }
+            return {
+                address: normalizedAddress,
+                cached,
+                ages,
+                staleThreshold: this.config.staleThreshold || 0
+            };
+        }
+        catch (error) {
+            log.error(tag, `Error getting stats for ${address}:`, error);
+            return {
+                address: address.toLowerCase(),
+                cached: [],
+                ages: {},
+                staleThreshold: this.config.staleThreshold || 0
+            };
+        }
+    }
+}
+exports.ZapperCache = ZapperCache;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pioneer-platform/pioneer-cache",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Unified caching system for Pioneer platform with Redis backend",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/core/cache-manager.ts

@@ -10,6 +10,7 @@ import { PriceCache } from '../stores/price-cache';
 import { PortfolioCache } from '../stores/portfolio-cache';
 import { TransactionCache } from '../stores/transaction-cache';
 import { StakingCache } from '../stores/staking-cache';
+import { ZapperCache } from '../stores/zapper-cache';
 import { RefreshWorker, startUnifiedWorker } from '../workers/refresh-worker';
 import type { BaseCache } from './base-cache';
 import type { HealthCheckResult } from '../types';
@@ -26,11 +27,13 @@ export interface CacheManagerConfig {
     balanceModule?: any;                   // Optional: if not provided, balance cache won't be initialized
     markets?: any;                         // Optional: if not provided, price cache won't be initialized
     networkModules?: Map<string, any>;     // Optional: network modules for staking cache (keyed by networkId)
+    zapperClient?: any;                    // Optional: Zapper API client for portfolio data
     enableBalanceCache?: boolean;
     enablePriceCache?: boolean;
     enablePortfolioCache?: boolean;
     enableTransactionCache?: boolean;
     enableStakingCache?: boolean;
+    enableZapperCache?: boolean;
     startWorkers?: boolean;                // Auto-start workers on initialization
 }
 
@@ -45,6 +48,7 @@ export class CacheManager {
     private portfolioCache?: PortfolioCache;
     private transactionCache?: TransactionCache;
     private stakingCache?: StakingCache;
+    private zapperCache?: ZapperCache;
     private workers: RefreshWorker[] = [];
 
     constructor(config: CacheManagerConfig) {
@@ -81,6 +85,12 @@ export class CacheManager {
             log.info(TAG, '✅ Staking cache initialized');
         }
 
+        // Initialize Zapper Cache
+        if (config.enableZapperCache !== false && config.zapperClient) {
+            this.zapperCache = new ZapperCache(this.redis, config.zapperClient);
+            log.info(TAG, '✅ Zapper cache initialized');
+        }
+
         // Auto-start workers if requested
         if (config.startWorkers) {
             setImmediate(() => {
@@ -119,6 +129,10 @@ export class CacheManager {
                 cacheRegistry.set('staking', this.stakingCache);
             }
 
+            if (this.zapperCache) {
+                cacheRegistry.set('zapper', this.zapperCache);
+            }
+
             // Start unified worker if we have any caches with queues
             if (cacheRegistry.size > 0) {
                 const worker = await startUnifiedWorker(
@@ -233,6 +247,18 @@ export class CacheManager {
                 }
             }
 
+            // Check zapper cache
+            if (this.zapperCache) {
+                const zapperHealth = await this.zapperCache.getHealth(forceRefresh);
+                checks.zapper = zapperHealth;
+
+                if (zapperHealth.status === 'unhealthy') {
+                    issues.push(...zapperHealth.issues.map(i => `Zapper: ${i}`));
+                } else if (zapperHealth.status === 'degraded') {
+                    warnings.push(...zapperHealth.warnings.map(w => `Zapper: ${w}`));
+                }
+            }
+
             // Check workers
             for (const worker of this.workers) {
                 const workerStats = await worker.getStats();
@@ -297,14 +323,15 @@ export class CacheManager {
             price: this.priceCache,
             portfolio: this.portfolioCache,
             transaction: this.transactionCache,
-            staking: this.stakingCache
+            staking: this.stakingCache,
+            zapper: this.zapperCache
         };
     }
 
     /**
      * Get specific cache by name
      */
-    getCache(name: 'balance' | 'price' | 'portfolio' | 'transaction' | 'staking') {
+    getCache(name: 'balance' | 'price' | 'portfolio' | 'transaction' | 'staking' | 'zapper') {
         switch (name) {
             case 'balance':
                 return this.balanceCache;
@@ -316,6 +343,8 @@ export class CacheManager {
                 return this.transactionCache;
             case 'staking':
                 return this.stakingCache;
+            case 'zapper':
+                return this.zapperCache;
             default:
                 return undefined;
         }
@@ -324,7 +353,7 @@ export class CacheManager {
     /**
      * Clear all caches (use with caution!)
      */
-    async clearAll(): Promise<{ balance?: number; price?: number; portfolio?: number; transaction?: number; staking?: number }> {
+    async clearAll(): Promise<{ balance?: number; price?: number; portfolio?: number; transaction?: number; staking?: number; zapper?: number }> {
         const tag = TAG + 'clearAll | ';
 
         try {
@@ -350,6 +379,10 @@ export class CacheManager {
                 result.staking = await this.stakingCache.clearAll();
             }
 
+            if (this.zapperCache) {
+                result.zapper = await this.zapperCache.clearAll();
+            }
+
             log.info(tag, 'Cleared all caches:', result);
             return result;
 

package/src/index.ts

@@ -15,6 +15,7 @@ export { PriceCache } from './stores/price-cache';
 export { PortfolioCache } from './stores/portfolio-cache';
 export { TransactionCache } from './stores/transaction-cache';
 export { StakingCache } from './stores/staking-cache';
+export { ZapperCache } from './stores/zapper-cache';
 
 // Worker exports
 export { RefreshWorker, startUnifiedWorker } from './workers/refresh-worker';
@@ -34,6 +35,7 @@ export type { BalanceData } from './stores/balance-cache';
 export type { PriceData } from './stores/price-cache';
 export type { PortfolioData, ChartData } from './stores/portfolio-cache';
 export type { StakingPosition } from './stores/staking-cache';
+export type { ZapperPortfolioData, ZapperNFTData, ZapperAppsData, ZapperTotalsData } from './stores/zapper-cache';
 
 // Config type export
 export type { CacheManagerConfig } from './core/cache-manager';

package/src/stores/zapper-cache.ts

@@ -0,0 +1,368 @@
+/*
+    ZapperCache - Zapper portfolio data cache implementation
+
+    Extends BaseCache with Zapper-specific logic.
+
+    CRITICAL: This is an EXPENSIVE API - minimize calls!
+    - Data NEVER expires (enableTTL: false)
+    - 24-hour stale threshold before background refresh
+    - Maximum 1 API call per address per day
+*/
+
+import { BaseCache } from '../core/base-cache';
+import type { CacheConfig } from '../types';
+
+const log = require('@pioneer-platform/loggerdog')();
+
+/**
+ * Zapper portfolio data structure
+ */
+export interface ZapperPortfolioData {
+    address: string;
+    balances: Array<{
+        balance: string;
+        chain: string;
+        networkId: string;
+        symbol: string;
+        ticker: string;
+        name: string;
+        caip: string;
+        tokenAddress?: string;
+        tokenType: string;
+        priceUsd: string;
+        valueUsd: string;
+        icon?: string;
+        display?: string[];
+        decimals?: number;
+        appId?: string;
+        groupId?: string;
+        metaType?: string;
+        pubkey?: string;
+    }>;
+    tokens?: any[];
+    nfts: any[];
+    totalNetWorth: number;
+    totalBalanceUsdTokens: number;
+    totalBalanceUSDApp: number;
+    nftUsdNetWorth: { [address: string]: string };
+}
+
+/**
+ * Zapper NFT data structure
+ */
+export interface ZapperNFTData {
+    items: Array<{
+        tokenId: string;
+        name: string;
+        description?: string;
+        collection: {
+            address: string;
+            name: string;
+            network: string;
+            type: string;
+        };
+        estimatedValue: { valueUsd: number };
+        mediasV3: {
+            images: {
+                edges: Array<{
+                    node: {
+                        originalUri: string;
+                        thumbnail: string;
+                    }
+                }>
+            }
+        }
+    }>;
+    totalCount: number;
+    totalBalanceUSD: number;
+}
+
+/**
+ * Zapper apps data structure
+ */
+export interface ZapperAppsData {
+    edges: Array<{
+        node: {
+            balanceUSD: number;
+            app: {
+                slug: string;
+                displayName: string;
+            };
+            network: {
+                name: string;
+            };
+        }
+    }>;
+}
+
+/**
+ * Zapper totals data structure
+ */
+export interface ZapperTotalsData {
+    totalNetWorth: number;
+    fetchedAt: number;
+}
+
+/**
+ * ZapperCache - Caches Zapper API responses with 24-hour refresh cycle
+ *
+ * CRITICAL: Zapper API is EXPENSIVE - minimize calls!
+ * - First request: Blocks and waits for Zapper API
+ * - Cached data NEVER expires from Redis
+ * - Data stays fresh for 24 hours
+ * - After 24 hours: Returns cached data + triggers background refresh
+ * - Maximum 1 API call per address per day
+ */
+export class ZapperCache extends BaseCache<ZapperPortfolioData | ZapperNFTData | ZapperAppsData | ZapperTotalsData> {
+    private zapperClient: any;
+
+    constructor(redis: any, zapperClient: any, config?: Partial<CacheConfig>) {
+        const defaultConfig: CacheConfig = {
+            name: 'zapper',
+            keyPrefix: 'zapper_v1:',
+            ttl: 0,                                     // Ignored when enableTTL: false
+            staleThreshold: 24 * 60 * 60 * 1000,        // 24 hours - ONLY refresh after this
+            enableTTL: false,                           // NEVER EXPIRE - data persists forever
+            queueName: 'cache-refresh',
+            enableQueue: true,
+            maxRetries: 3,
+            retryDelay: 5000,
+            blockOnMiss: true,                          // BLOCK on first request (no cached data yet)
+            enableLegacyFallback: false,                // No legacy Zapper cache format
+            defaultValue: {
+                balances: [],
+                tokens: [],
+                nfts: [],
+                totalNetWorth: 0,
+                totalBalanceUsdTokens: 0,
+                totalBalanceUSDApp: 0,
+                nftUsdNetWorth: {}
+            },
+            useSyncFallback: false,
+            maxConcurrentJobs: 2,                       // Limit concurrent Zapper API calls
+            apiTimeout: 30000,                          // 30s timeout for Zapper API
+            logCacheHits: true,
+            logCacheMisses: true,
+            logRefreshJobs: true
+        };
+
+        super(redis, { ...defaultConfig, ...config });
+
+        if (!zapperClient) {
+            throw new Error('ZapperCache requires zapperClient');
+        }
+        this.zapperClient = zapperClient;
+    }
+
+    /**
+     * Build Redis key for Zapper data
+     *
+     * Key strategy: zapper_v1:{dataType}:{address}
+     *
+     * Examples:
+     * - zapper_v1:portfolio:0x1234...
+     * - zapper_v1:nfts:0x1234...
+     * - zapper_v1:apps:0x1234...
+     * - zapper_v1:totals:0x1234...
+     */
+    protected buildKey(params: Record<string, any>): string {
+        const { address, dataType } = params;
+
+        if (!address) {
+            throw new Error('ZapperCache.buildKey: address required');
+        }
+
+        if (!dataType) {
+            throw new Error('ZapperCache.buildKey: dataType required (portfolio, nfts, apps, totals)');
+        }
+
+        // Normalize address to lowercase
+        const normalizedAddress = address.toLowerCase();
+
+        // Validate Ethereum address format
+        if (!normalizedAddress.match(/^0x[a-f0-9]{40}$/)) {
+            throw new Error(`ZapperCache.buildKey: invalid Ethereum address format: ${address}`);
+        }
+
+        return `${this.config.keyPrefix}${dataType}:${normalizedAddress}`;
+    }
+
+    /**
+     * Fetch data from Zapper API
+     *
+     * CRITICAL: This is an EXPENSIVE operation!
+     * Only called on:
+     * 1. First request (cache miss)
+     * 2. Background refresh after 24 hours
+     */
+    protected async fetchFromSource(params: Record<string, any>): Promise<any> {
+        const tag = this.TAG + 'fetchFromSource | ';
+        const { address, dataType } = params;
+
+        try {
+            log.info(tag, `🌐 Fetching ${dataType} from Zapper API for ${address} (EXPENSIVE!)`);
+
+            let result: any;
+
+            switch (dataType) {
+                case 'portfolio':
+                    result = await this.zapperClient.getPortfolio(address);
+                    result.address = address;
+                    break;
+
+                case 'nfts':
+                    result = await this.zapperClient.getNFTs(address);
+                    break;
+
+                case 'apps':
+                    result = await this.zapperClient.getTokens(address);
+                    break;
+
+                case 'totals':
+                    const totalNetWorth = await this.zapperClient.getTotalNetworth(address);
+                    result = {
+                        totalNetWorth,
+                        fetchedAt: Date.now()
+                    };
+                    break;
+
+                default:
+                    throw new Error(`Unknown dataType: ${dataType}`);
+            }
+
+            log.info(tag, `✅ Successfully fetched ${dataType} for ${address} from Zapper`);
+            return result;
+
+        } catch (error) {
+            log.error(tag, `❌ Failed to fetch ${dataType} from Zapper for ${address}:`, error);
+            throw error;
+        }
+    }
+
+    /**
+     * Legacy cache fallback (not applicable for Zapper)
+     */
+    protected async getLegacyCached(params: Record<string, any>): Promise<any | null> {
+        // No legacy Zapper cache format exists
+        return null;
+    }
+
+    /**
+     * Get portfolio data for an address
+     */
+    async getPortfolio(address: string, forceRefresh?: boolean): Promise<ZapperPortfolioData> {
+        const result = await this.get({ address, dataType: 'portfolio' }, forceRefresh);
+        return result.value as ZapperPortfolioData;
+    }
+
+    /**
+     * Get NFT data for an address
+     */
+    async getNFTs(address: string, forceRefresh?: boolean): Promise<ZapperNFTData> {
+        const result = await this.get({ address, dataType: 'nfts' }, forceRefresh);
+        return result.value as ZapperNFTData;
+    }
+
+    /**
+     * Get DeFi app positions for an address
+     */
+    async getApps(address: string, forceRefresh?: boolean): Promise<ZapperAppsData> {
+        const result = await this.get({ address, dataType: 'apps' }, forceRefresh);
+        return result.value as ZapperAppsData;
+    }
+
+    /**
+     * Get portfolio totals for an address
+     */
+    async getTotals(address: string, forceRefresh?: boolean): Promise<ZapperTotalsData> {
+        const result = await this.get({ address, dataType: 'totals' }, forceRefresh);
+        return result.value as ZapperTotalsData;
+    }
+
+    /**
+     * Clear cache for an address
+     * @param address - Ethereum address
+     * @param dataType - Optional: specific data type to clear, or all if omitted
+     */
+    async clearAddress(address: string, dataType?: string): Promise<number> {
+        const tag = this.TAG + 'clearAddress | ';
+
+        try {
+            const normalizedAddress = address.toLowerCase();
+            let cleared = 0;
+
+            if (dataType) {
+                // Clear specific data type
+                const key = this.buildKey({ address: normalizedAddress, dataType });
+                cleared = await this.redis.del(key);
+                log.info(tag, `Cleared ${dataType} cache for ${address}`);
+            } else {
+                // Clear all data types for this address
+                const pattern = `${this.config.keyPrefix}*:${normalizedAddress}`;
+                const keys = await this.redis.keys(pattern);
+
+                if (keys.length > 0) {
+                    cleared = await this.redis.del(...keys);
+                }
+                log.info(tag, `Cleared ${cleared} cache entries for ${address}`);
+            }
+
+            return cleared;
+
+        } catch (error) {
+            log.error(tag, `Error clearing cache for ${address}:`, error);
+            return 0;
+        }
+    }
+
+    /**
+     * Get cache statistics for an address
+     */
+    async getAddressStats(address: string): Promise<{
+        address: string;
+        cached: string[];
+        ages: { [key: string]: number };
+        staleThreshold: number;
+    }> {
+        const tag = this.TAG + 'getAddressStats | ';
+
+        try {
+            const normalizedAddress = address.toLowerCase();
+            const pattern = `${this.config.keyPrefix}*:${normalizedAddress}`;
+            const keys = await this.redis.keys(pattern);
+
+            const cached: string[] = [];
+            const ages: { [key: string]: number } = {};
+
+            for (const key of keys) {
+                // Extract data type from key (e.g., "zapper_v1:portfolio:0x123..." -> "portfolio")
+                const parts = key.split(':');
+                const dataType = parts[1];
+
+                const data = await this.redis.get(key);
+
+                if (data) {
+                    const parsed = JSON.parse(data);
+                    cached.push(dataType);
+                    ages[dataType] = Math.round((Date.now() - parsed.timestamp) / 1000);
+                }
+            }
+
+            return {
+                address: normalizedAddress,
+                cached,
+                ages,
+                staleThreshold: this.config.staleThreshold || 0
+            };
+
+        } catch (error) {
+            log.error(tag, `Error getting stats for ${address}:`, error);
+            return {
+                address: address.toLowerCase(),
+                cached: [],
+                ages: {},
+                staleThreshold: this.config.staleThreshold || 0
+            };
+        }
+    }
+}