@pioneer-platform/pioneer-cache 1.1.4 → 1.1.6

package/.turbo/turbo-build.log

@@ -1 +1,2 @@
-$ tsc
+
+$ tsc

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @pioneer-platform/pioneer-cache
 
+## 1.1.6
+
+### Patch Changes
+
+- chore: chore: chore: 🔒 CRITICAL FIX: XRP destination tag validation
+
+## 1.1.5
+
+### Patch Changes
+
+- chore: chore: 🔒 CRITICAL FIX: XRP destination tag validation
+
 ## 1.1.4
 
 ### Patch Changes

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

@@ -2,6 +2,7 @@ import { BalanceCache } from '../stores/balance-cache';
 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 type { HealthCheckResult } from '../types';
 /**
  * Configuration for CacheManager
@@ -11,10 +12,12 @@ export interface CacheManagerConfig {
     redisQueue?: any;
     balanceModule?: any;
     markets?: any;
+    networkModules?: Map<string, any>;
     enableBalanceCache?: boolean;
     enablePriceCache?: boolean;
     enablePortfolioCache?: boolean;
     enableTransactionCache?: boolean;
+    enableStakingCache?: boolean;
     startWorkers?: boolean;
 }
 /**
@@ -27,6 +30,7 @@ export declare class CacheManager {
     private priceCache?;
     private portfolioCache?;
     private transactionCache?;
+    private stakingCache?;
     private workers;
     constructor(config: CacheManagerConfig);
     /**
@@ -52,11 +56,12 @@ export declare class CacheManager {
         price: PriceCache | undefined;
         portfolio: PortfolioCache | undefined;
         transaction: TransactionCache | undefined;
+        staking: StakingCache | undefined;
     };
     /**
      * Get specific cache by name
      */
-    getCache(name: 'balance' | 'price' | 'portfolio' | 'transaction'): BalanceCache | PriceCache | PortfolioCache | TransactionCache | undefined;
+    getCache(name: 'balance' | 'price' | 'portfolio' | 'transaction' | 'staking'): BalanceCache | PriceCache | PortfolioCache | TransactionCache | StakingCache | undefined;
     /**
      * Clear all caches (use with caution!)
      */
@@ -65,5 +70,6 @@ export declare class CacheManager {
         price?: number;
         portfolio?: number;
         transaction?: number;
+        staking?: number;
     }>;
 }

package/dist/core/cache-manager.js

@@ -11,6 +11,7 @@ const balance_cache_1 = require("../stores/balance-cache");
 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 refresh_worker_1 = require("../workers/refresh-worker");
 const log = require('@pioneer-platform/loggerdog')();
 const TAG = ' | CacheManager | ';
@@ -42,6 +43,11 @@ class CacheManager {
             this.transactionCache = new transaction_cache_1.TransactionCache(this.redis);
             log.info(TAG, '✅ Transaction cache initialized');
         }
+        // Initialize Staking Cache (with markets module for price enrichment)
+        if (config.enableStakingCache !== false && config.networkModules && config.networkModules.size > 0) {
+            this.stakingCache = new staking_cache_1.StakingCache(this.redis, config.networkModules, config.markets);
+            log.info(TAG, '✅ Staking cache initialized');
+        }
         // Auto-start workers if requested
         if (config.startWorkers) {
             setImmediate(() => {
@@ -68,6 +74,9 @@ class CacheManager {
             if (this.portfolioCache) {
                 cacheRegistry.set('portfolio', this.portfolioCache);
             }
+            if (this.stakingCache) {
+                cacheRegistry.set('staking', this.stakingCache);
+            }
             // 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
@@ -155,6 +164,17 @@ class CacheManager {
                     stats: txStats
                 };
             }
+            // Check staking cache
+            if (this.stakingCache) {
+                const stakingHealth = await this.stakingCache.getHealth(forceRefresh);
+                checks.staking = stakingHealth;
+                if (stakingHealth.status === 'unhealthy') {
+                    issues.push(...stakingHealth.issues.map(i => `Staking: ${i}`));
+                }
+                else if (stakingHealth.status === 'degraded') {
+                    warnings.push(...stakingHealth.warnings.map(w => `Staking: ${w}`));
+                }
+            }
             // Check workers
             for (const worker of this.workers) {
                 const workerStats = await worker.getStats();
@@ -215,7 +235,8 @@ class CacheManager {
             balance: this.balanceCache,
             price: this.priceCache,
             portfolio: this.portfolioCache,
-            transaction: this.transactionCache
+            transaction: this.transactionCache,
+            staking: this.stakingCache
         };
     }
     /**
@@ -231,6 +252,8 @@ class CacheManager {
                 return this.portfolioCache;
             case 'transaction':
                 return this.transactionCache;
+            case 'staking':
+                return this.stakingCache;
             default:
                 return undefined;
         }
@@ -254,6 +277,9 @@ class CacheManager {
             if (this.transactionCache) {
                 result.transaction = await this.transactionCache.clearAll();
             }
+            if (this.stakingCache) {
+                result.staking = await this.stakingCache.clearAll();
+            }
             log.info(tag, 'Cleared all caches:', result);
             return result;
         }

package/dist/index.d.ts

@@ -4,10 +4,12 @@ export { BalanceCache } from './stores/balance-cache';
 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 { 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 { 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.TransactionCache = exports.PortfolioCache = exports.PriceCache = exports.BalanceCache = exports.CacheManager = exports.BaseCache = void 0;
+exports.startUnifiedWorker = exports.RefreshWorker = 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; } });
@@ -21,6 +21,8 @@ var portfolio_cache_1 = require("./stores/portfolio-cache");
 Object.defineProperty(exports, "PortfolioCache", { enumerable: true, get: function () { return portfolio_cache_1.PortfolioCache; } });
 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; } });
 // 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/staking-cache.d.ts

@@ -0,0 +1,75 @@
+import { BaseCache } from '../core/base-cache';
+import type { CacheConfig } from '../types';
+/**
+ * Staking position data structure
+ */
+export interface StakingPosition {
+    type: 'delegation' | 'reward' | 'unbonding';
+    chart: 'staking';
+    context: string;
+    contextType: string;
+    caip: string;
+    networkId: string;
+    pubkey: string;
+    validatorAddress?: string;
+    validator?: string;
+    balance: number;
+    denom: string;
+    ticker: string;
+    symbol: string;
+    name: string;
+    icon: string;
+    status: 'active' | 'claimable' | 'unbonding';
+    completionTime?: string;
+    shares?: string;
+    priceUsd?: number;
+    valueUsd?: number;
+    updated: number;
+}
+/**
+ * Network module interface for staking
+ */
+interface NetworkModule {
+    getStakingPositions(address: string): Promise<StakingPosition[]>;
+}
+/**
+ * StakingCache - Caches Cosmos staking positions (delegations, rewards, unbonding)
+ */
+export declare class StakingCache extends BaseCache<StakingPosition[]> {
+    private networkModules;
+    private markets;
+    constructor(redis: any, networkModules: Map<string, NetworkModule>, markets?: any, config?: Partial<CacheConfig>);
+    /**
+     * Build Redis key for staking data
+     * Format: staking_v1:networkId:address
+     */
+    protected buildKey(params: Record<string, any>): string;
+    /**
+     * Fetch staking positions from blockchain via network module
+     * and enrich with pricing data from markets module
+     */
+    protected fetchFromSource(params: Record<string, any>): Promise<StakingPosition[]>;
+    /**
+     * Enrich staking positions with USD pricing
+     * Uses the markets module to fetch prices for the native tokens
+     */
+    private enrichPositionsWithPricing;
+    /**
+     * No legacy cache format for staking (new feature)
+     */
+    protected getLegacyCached(params: Record<string, any>): Promise<StakingPosition[] | null>;
+    /**
+     * Get staking positions for a specific network and address
+     * Convenience method that wraps base get()
+     */
+    getStakingPositions(networkId: string, address: string, waitForFresh?: boolean): Promise<StakingPosition[]>;
+    /**
+     * Get staking positions for multiple addresses (batch operation)
+     * OPTIMIZED: Uses Redis MGET for single round-trip
+     */
+    getBatchStakingPositions(items: Array<{
+        networkId: string;
+        address: string;
+    }>, waitForFresh?: boolean): Promise<Map<string, StakingPosition[]>>;
+}
+export {};

package/dist/stores/staking-cache.js

@@ -0,0 +1,229 @@
+"use strict";
+/*
+    StakingCache - Staking position cache implementation
+
+    Extends BaseCache with staking-specific logic for Cosmos-based chains.
+    Caches delegation, reward, and unbonding positions.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StakingCache = void 0;
+const base_cache_1 = require("../core/base-cache");
+const log = require('@pioneer-platform/loggerdog')();
+const TAG = ' | StakingCache | ';
+/**
+ * StakingCache - Caches Cosmos staking positions (delegations, rewards, unbonding)
+ */
+class StakingCache extends base_cache_1.BaseCache {
+    constructor(redis, networkModules, markets, config) {
+        const defaultConfig = {
+            name: 'staking',
+            keyPrefix: 'staking_v1:',
+            ttl: 5 * 60 * 1000, // 5 minutes - staking changes slowly
+            staleThreshold: 2 * 60 * 1000, // Refresh after 2 minutes
+            enableTTL: true, // Enable expiration
+            queueName: 'cache-refresh',
+            enableQueue: true,
+            maxRetries: 3,
+            retryDelay: 10000,
+            blockOnMiss: false, // Return [] immediately, fetch async
+            enableLegacyFallback: false, // No legacy format
+            defaultValue: [], // Empty array for no positions
+            maxConcurrentJobs: 10,
+            apiTimeout: 30000, // 30s timeout for blockchain API
+            logCacheHits: false,
+            logCacheMisses: true,
+            logRefreshJobs: true
+        };
+        super(redis, { ...defaultConfig, ...config });
+        this.networkModules = networkModules;
+        this.markets = markets;
+    }
+    /**
+     * Build Redis key for staking data
+     * Format: staking_v1:networkId:address
+     */
+    buildKey(params) {
+        const { networkId, address } = params;
+        if (!networkId || !address) {
+            throw new Error('StakingCache.buildKey: networkId and address required');
+        }
+        const normalizedNetworkId = networkId.toLowerCase();
+        const normalizedAddress = address.toLowerCase();
+        return `${this.config.keyPrefix}${normalizedNetworkId}:${normalizedAddress}`;
+    }
+    /**
+     * Fetch staking positions from blockchain via network module
+     * and enrich with pricing data from markets module
+     */
+    async fetchFromSource(params) {
+        const tag = this.TAG + 'fetchFromSource | ';
+        try {
+            const { networkId, address } = params;
+            log.debug(tag, `Fetching staking positions for ${address} on ${networkId}`);
+            // Get the appropriate network module
+            const networkModule = this.networkModules.get(networkId);
+            if (!networkModule) {
+                log.warn(tag, `No network module found for ${networkId}`);
+                return [];
+            }
+            // Fetch staking positions from network module (raw blockchain data)
+            const positions = await networkModule.getStakingPositions(address);
+            if (!positions || !Array.isArray(positions)) {
+                log.warn(tag, `Invalid positions returned for ${networkId}/${address}`);
+                return [];
+            }
+            log.info(tag, `Found ${positions.length} staking positions for ${networkId}/${address}`);
+            // Enrich with pricing data if markets module is available
+            if (this.markets && positions.length > 0) {
+                await this.enrichPositionsWithPricing(positions);
+            }
+            else if (!this.markets) {
+                log.warn(tag, 'Markets module not available, positions will have no pricing');
+            }
+            return positions;
+        }
+        catch (error) {
+            log.error(tag, 'Error fetching staking positions:', error);
+            // Return empty array instead of throwing - staking is optional
+            return [];
+        }
+    }
+    /**
+     * Enrich staking positions with USD pricing
+     * Uses the markets module to fetch prices for the native tokens
+     */
+    async enrichPositionsWithPricing(positions) {
+        const tag = TAG + 'enrichPositionsWithPricing | ';
+        try {
+            // Collect unique CAIPs from all positions
+            const uniqueCAIPs = [...new Set(positions.map(p => p.caip))];
+            log.debug(tag, `Fetching prices for ${uniqueCAIPs.length} unique assets:`, uniqueCAIPs);
+            // Batch fetch prices from markets module
+            const prices = {};
+            for (const caip of uniqueCAIPs) {
+                try {
+                    const price = await this.markets.getAssetPriceByCaip(caip);
+                    prices[caip] = price || 0;
+                    log.debug(tag, `Price for ${caip}: $${price}`);
+                }
+                catch (priceError) {
+                    log.error(tag, `Error fetching price for ${caip}:`, priceError);
+                    prices[caip] = 0;
+                }
+            }
+            // Enrich each position with its price
+            for (const position of positions) {
+                const priceUsd = prices[position.caip] || 0;
+                position.priceUsd = priceUsd;
+                position.valueUsd = position.balance * priceUsd;
+                log.debug(tag, `Enriched ${position.type} position:`, {
+                    caip: position.caip,
+                    balance: position.balance,
+                    priceUsd,
+                    valueUsd: position.valueUsd
+                });
+            }
+            log.info(tag, `✅ Enriched ${positions.length} positions with pricing data`);
+        }
+        catch (error) {
+            log.error(tag, 'Error enriching positions with pricing:', error);
+            // Don't throw - positions are still valid without pricing
+        }
+    }
+    /**
+     * No legacy cache format for staking (new feature)
+     */
+    async getLegacyCached(params) {
+        return null;
+    }
+    /**
+     * Get staking positions for a specific network and address
+     * Convenience method that wraps base get()
+     */
+    async getStakingPositions(networkId, address, waitForFresh) {
+        const result = await this.get({ networkId, address }, waitForFresh);
+        return result.value || this.config.defaultValue;
+    }
+    /**
+     * Get staking positions for multiple addresses (batch operation)
+     * OPTIMIZED: Uses Redis MGET for single round-trip
+     */
+    async getBatchStakingPositions(items, waitForFresh) {
+        const tag = this.TAG + 'getBatchStakingPositions | ';
+        const startTime = Date.now();
+        try {
+            // If waitForFresh=true, skip cache and fetch fresh data
+            if (waitForFresh) {
+                log.info(tag, `FORCE REFRESH: Bypassing cache for ${items.length} addresses`);
+                const fetchStart = Date.now();
+                const results = new Map();
+                const fetchPromises = items.map(async (item) => {
+                    try {
+                        const freshData = await this.fetchFresh({ networkId: item.networkId, address: item.address });
+                        const key = `${item.networkId}:${item.address}`;
+                        results.set(key, freshData);
+                    }
+                    catch (error) {
+                        log.error(tag, `Failed to fetch fresh ${item.networkId}/${item.address}:`, error);
+                        const key = `${item.networkId}:${item.address}`;
+                        results.set(key, []);
+                    }
+                });
+                await Promise.all(fetchPromises);
+                log.info(tag, `Force refresh completed: fetched ${items.length} addresses in ${Date.now() - fetchStart}ms`);
+                return results;
+            }
+            // Normal flow: Check cache first
+            log.info(tag, `Batch request for ${items.length} addresses using Redis MGET`);
+            // Build all Redis keys
+            const keys = items.map(item => this.buildKey({ networkId: item.networkId, address: item.address }));
+            // PERF: Use MGET to fetch all keys in ONE Redis round-trip
+            const cachedValues = await this.redis.mget(...keys);
+            // Process results
+            const results = new Map();
+            const missedItems = [];
+            for (let i = 0; i < items.length; i++) {
+                const item = items[i];
+                const cached = cachedValues[i];
+                const itemKey = `${item.networkId}:${item.address}`;
+                if (cached) {
+                    try {
+                        const parsed = JSON.parse(cached);
+                        if (parsed.value && Array.isArray(parsed.value)) {
+                            results.set(itemKey, parsed.value);
+                            continue;
+                        }
+                    }
+                    catch (e) {
+                        log.warn(tag, `Failed to parse cached value for ${keys[i]}`);
+                    }
+                }
+                // Cache miss - record for fetching
+                missedItems.push({ ...item, index: i });
+                results.set(itemKey, []); // Placeholder
+            }
+            const responseTime = Date.now() - startTime;
+            const hitRate = ((items.length - missedItems.length) / items.length * 100).toFixed(1);
+            log.info(tag, `MGET completed: ${items.length} keys in ${responseTime}ms (${hitRate}% hit rate)`);
+            // If we have cache misses, trigger background refresh (non-blocking)
+            if (missedItems.length > 0) {
+                log.info(tag, `Triggering background refresh for ${missedItems.length} cache misses`);
+                missedItems.forEach(item => {
+                    this.triggerAsyncRefresh({ networkId: item.networkId, address: item.address }, 'high');
+                });
+            }
+            return results;
+        }
+        catch (error) {
+            log.error(tag, 'Error in batch staking request:', error);
+            // Return empty arrays for all items
+            const results = new Map();
+            items.forEach(item => {
+                const key = `${item.networkId}:${item.address}`;
+                results.set(key, []);
+            });
+            return results;
+        }
+    }
+}
+exports.StakingCache = StakingCache;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pioneer-platform/pioneer-cache",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "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

@@ -9,6 +9,7 @@ import { BalanceCache } from '../stores/balance-cache';
 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 { RefreshWorker, startUnifiedWorker } from '../workers/refresh-worker';
 import type { BaseCache } from './base-cache';
 import type { HealthCheckResult } from '../types';
@@ -24,10 +25,12 @@ export interface CacheManagerConfig {
     redisQueue?: any;                      // Dedicated Redis client for blocking queue operations (brpop, etc.)
     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)
     enableBalanceCache?: boolean;
     enablePriceCache?: boolean;
     enablePortfolioCache?: boolean;
     enableTransactionCache?: boolean;
+    enableStakingCache?: boolean;
     startWorkers?: boolean;                // Auto-start workers on initialization
 }
 
@@ -41,6 +44,7 @@ export class CacheManager {
     private priceCache?: PriceCache;
     private portfolioCache?: PortfolioCache;
     private transactionCache?: TransactionCache;
+    private stakingCache?: StakingCache;
     private workers: RefreshWorker[] = [];
 
     constructor(config: CacheManagerConfig) {
@@ -71,6 +75,12 @@ export class CacheManager {
             log.info(TAG, '✅ Transaction cache initialized');
         }
 
+        // Initialize Staking Cache (with markets module for price enrichment)
+        if (config.enableStakingCache !== false && config.networkModules && config.networkModules.size > 0) {
+            this.stakingCache = new StakingCache(this.redis, config.networkModules, config.markets);
+            log.info(TAG, '✅ Staking cache initialized');
+        }
+
         // Auto-start workers if requested
         if (config.startWorkers) {
             setImmediate(() => {
@@ -105,6 +115,10 @@ export class CacheManager {
                 cacheRegistry.set('portfolio', this.portfolioCache);
             }
 
+            if (this.stakingCache) {
+                cacheRegistry.set('staking', this.stakingCache);
+            }
+
             // Start unified worker if we have any caches with queues
             if (cacheRegistry.size > 0) {
                 const worker = await startUnifiedWorker(
@@ -207,6 +221,18 @@ export class CacheManager {
                 };
             }
 
+            // Check staking cache
+            if (this.stakingCache) {
+                const stakingHealth = await this.stakingCache.getHealth(forceRefresh);
+                checks.staking = stakingHealth;
+
+                if (stakingHealth.status === 'unhealthy') {
+                    issues.push(...stakingHealth.issues.map(i => `Staking: ${i}`));
+                } else if (stakingHealth.status === 'degraded') {
+                    warnings.push(...stakingHealth.warnings.map(w => `Staking: ${w}`));
+                }
+            }
+
             // Check workers
             for (const worker of this.workers) {
                 const workerStats = await worker.getStats();
@@ -270,14 +296,15 @@ export class CacheManager {
             balance: this.balanceCache,
             price: this.priceCache,
             portfolio: this.portfolioCache,
-            transaction: this.transactionCache
+            transaction: this.transactionCache,
+            staking: this.stakingCache
         };
     }
 
     /**
      * Get specific cache by name
      */
-    getCache(name: 'balance' | 'price' | 'portfolio' | 'transaction') {
+    getCache(name: 'balance' | 'price' | 'portfolio' | 'transaction' | 'staking') {
         switch (name) {
             case 'balance':
                 return this.balanceCache;
@@ -287,6 +314,8 @@ export class CacheManager {
                 return this.portfolioCache;
             case 'transaction':
                 return this.transactionCache;
+            case 'staking':
+                return this.stakingCache;
             default:
                 return undefined;
         }
@@ -295,7 +324,7 @@ export class CacheManager {
     /**
      * Clear all caches (use with caution!)
      */
-    async clearAll(): Promise<{ balance?: number; price?: number; portfolio?: number; transaction?: number }> {
+    async clearAll(): Promise<{ balance?: number; price?: number; portfolio?: number; transaction?: number; staking?: number }> {
         const tag = TAG + 'clearAll | ';
 
         try {
@@ -317,6 +346,10 @@ export class CacheManager {
                 result.transaction = await this.transactionCache.clearAll();
             }
 
+            if (this.stakingCache) {
+                result.staking = await this.stakingCache.clearAll();
+            }
+
             log.info(tag, 'Cleared all caches:', result);
             return result;
 

package/src/index.ts

@@ -14,6 +14,7 @@ export { BalanceCache } from './stores/balance-cache';
 export { PriceCache } from './stores/price-cache';
 export { PortfolioCache } from './stores/portfolio-cache';
 export { TransactionCache } from './stores/transaction-cache';
+export { StakingCache } from './stores/staking-cache';
 
 // Worker exports
 export { RefreshWorker, startUnifiedWorker } from './workers/refresh-worker';
@@ -32,6 +33,7 @@ export type {
 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';
 
 // Config type export
 export type { CacheManagerConfig } from './core/cache-manager';

package/src/stores/staking-cache.ts

@@ -0,0 +1,302 @@
+/*
+    StakingCache - Staking position cache implementation
+
+    Extends BaseCache with staking-specific logic for Cosmos-based chains.
+    Caches delegation, reward, and unbonding positions.
+*/
+
+import { BaseCache } from '../core/base-cache';
+import type { CacheConfig } from '../types';
+
+const log = require('@pioneer-platform/loggerdog')();
+const TAG = ' | StakingCache | ';
+
+/**
+ * Staking position data structure
+ */
+export interface StakingPosition {
+    type: 'delegation' | 'reward' | 'unbonding';
+    chart: 'staking';
+    context: string;
+    contextType: string;
+    caip: string;
+    networkId: string;
+    pubkey: string;
+    validatorAddress?: string;
+    validator?: string;
+    balance: number;
+    denom: string;
+    ticker: string;
+    symbol: string;
+    name: string;
+    icon: string;
+    status: 'active' | 'claimable' | 'unbonding';
+    completionTime?: string;  // For unbonding
+    shares?: string;          // For delegations
+    priceUsd?: number;
+    valueUsd?: number;
+    updated: number;
+}
+
+/**
+ * Network module interface for staking
+ */
+interface NetworkModule {
+    getStakingPositions(address: string): Promise<StakingPosition[]>;
+}
+
+/**
+ * StakingCache - Caches Cosmos staking positions (delegations, rewards, unbonding)
+ */
+export class StakingCache extends BaseCache<StakingPosition[]> {
+    private networkModules: Map<string, NetworkModule>;
+    private markets: any;
+
+    constructor(redis: any, networkModules: Map<string, NetworkModule>, markets?: any, config?: Partial<CacheConfig>) {
+        const defaultConfig: CacheConfig = {
+            name: 'staking',
+            keyPrefix: 'staking_v1:',
+            ttl: 5 * 60 * 1000,                // 5 minutes - staking changes slowly
+            staleThreshold: 2 * 60 * 1000,     // Refresh after 2 minutes
+            enableTTL: true,                   // Enable expiration
+            queueName: 'cache-refresh',
+            enableQueue: true,
+            maxRetries: 3,
+            retryDelay: 10000,
+            blockOnMiss: false,                // Return [] immediately, fetch async
+            enableLegacyFallback: false,       // No legacy format
+            defaultValue: [],                  // Empty array for no positions
+            maxConcurrentJobs: 10,
+            apiTimeout: 30000,                 // 30s timeout for blockchain API
+            logCacheHits: false,
+            logCacheMisses: true,
+            logRefreshJobs: true
+        };
+
+        super(redis, { ...defaultConfig, ...config });
+        this.networkModules = networkModules;
+        this.markets = markets;
+    }
+
+    /**
+     * Build Redis key for staking data
+     * Format: staking_v1:networkId:address
+     */
+    protected buildKey(params: Record<string, any>): string {
+        const { networkId, address } = params;
+        if (!networkId || !address) {
+            throw new Error('StakingCache.buildKey: networkId and address required');
+        }
+
+        const normalizedNetworkId = networkId.toLowerCase();
+        const normalizedAddress = address.toLowerCase();
+
+        return `${this.config.keyPrefix}${normalizedNetworkId}:${normalizedAddress}`;
+    }
+
+    /**
+     * Fetch staking positions from blockchain via network module
+     * and enrich with pricing data from markets module
+     */
+    protected async fetchFromSource(params: Record<string, any>): Promise<StakingPosition[]> {
+        const tag = this.TAG + 'fetchFromSource | ';
+
+        try {
+            const { networkId, address } = params;
+
+            log.debug(tag, `Fetching staking positions for ${address} on ${networkId}`);
+
+            // Get the appropriate network module
+            const networkModule = this.networkModules.get(networkId);
+            if (!networkModule) {
+                log.warn(tag, `No network module found for ${networkId}`);
+                return [];
+            }
+
+            // Fetch staking positions from network module (raw blockchain data)
+            const positions = await networkModule.getStakingPositions(address);
+
+            if (!positions || !Array.isArray(positions)) {
+                log.warn(tag, `Invalid positions returned for ${networkId}/${address}`);
+                return [];
+            }
+
+            log.info(tag, `Found ${positions.length} staking positions for ${networkId}/${address}`);
+
+            // Enrich with pricing data if markets module is available
+            if (this.markets && positions.length > 0) {
+                await this.enrichPositionsWithPricing(positions);
+            } else if (!this.markets) {
+                log.warn(tag, 'Markets module not available, positions will have no pricing');
+            }
+
+            return positions;
+
+        } catch (error) {
+            log.error(tag, 'Error fetching staking positions:', error);
+            // Return empty array instead of throwing - staking is optional
+            return [];
+        }
+    }
+
+    /**
+     * Enrich staking positions with USD pricing
+     * Uses the markets module to fetch prices for the native tokens
+     */
+    private async enrichPositionsWithPricing(positions: StakingPosition[]): Promise<void> {
+        const tag = TAG + 'enrichPositionsWithPricing | ';
+
+        try {
+            // Collect unique CAIPs from all positions
+            const uniqueCAIPs = [...new Set(positions.map(p => p.caip))];
+            log.debug(tag, `Fetching prices for ${uniqueCAIPs.length} unique assets:`, uniqueCAIPs);
+
+            // Batch fetch prices from markets module
+            const prices: Record<string, number> = {};
+
+            for (const caip of uniqueCAIPs) {
+                try {
+                    const price = await this.markets.getAssetPriceByCaip(caip);
+                    prices[caip] = price || 0;
+                    log.debug(tag, `Price for ${caip}: $${price}`);
+                } catch (priceError) {
+                    log.error(tag, `Error fetching price for ${caip}:`, priceError);
+                    prices[caip] = 0;
+                }
+            }
+
+            // Enrich each position with its price
+            for (const position of positions) {
+                const priceUsd = prices[position.caip] || 0;
+                position.priceUsd = priceUsd;
+                position.valueUsd = position.balance * priceUsd;
+
+                log.debug(tag, `Enriched ${position.type} position:`, {
+                    caip: position.caip,
+                    balance: position.balance,
+                    priceUsd,
+                    valueUsd: position.valueUsd
+                });
+            }
+
+            log.info(tag, `✅ Enriched ${positions.length} positions with pricing data`);
+
+        } catch (error) {
+            log.error(tag, 'Error enriching positions with pricing:', error);
+            // Don't throw - positions are still valid without pricing
+        }
+    }
+
+    /**
+     * No legacy cache format for staking (new feature)
+     */
+    protected async getLegacyCached(params: Record<string, any>): Promise<StakingPosition[] | null> {
+        return null;
+    }
+
+    /**
+     * Get staking positions for a specific network and address
+     * Convenience method that wraps base get()
+     */
+    async getStakingPositions(networkId: string, address: string, waitForFresh?: boolean): Promise<StakingPosition[]> {
+        const result = await this.get({ networkId, address }, waitForFresh);
+        return result.value || this.config.defaultValue;
+    }
+
+    /**
+     * Get staking positions for multiple addresses (batch operation)
+     * OPTIMIZED: Uses Redis MGET for single round-trip
+     */
+    async getBatchStakingPositions(
+        items: Array<{ networkId: string; address: string }>,
+        waitForFresh?: boolean
+    ): Promise<Map<string, StakingPosition[]>> {
+        const tag = this.TAG + 'getBatchStakingPositions | ';
+        const startTime = Date.now();
+
+        try {
+            // If waitForFresh=true, skip cache and fetch fresh data
+            if (waitForFresh) {
+                log.info(tag, `FORCE REFRESH: Bypassing cache for ${items.length} addresses`);
+                const fetchStart = Date.now();
+
+                const results = new Map<string, StakingPosition[]>();
+                const fetchPromises = items.map(async (item) => {
+                    try {
+                        const freshData = await this.fetchFresh({ networkId: item.networkId, address: item.address });
+                        const key = `${item.networkId}:${item.address}`;
+                        results.set(key, freshData);
+                    } catch (error) {
+                        log.error(tag, `Failed to fetch fresh ${item.networkId}/${item.address}:`, error);
+                        const key = `${item.networkId}:${item.address}`;
+                        results.set(key, []);
+                    }
+                });
+
+                await Promise.all(fetchPromises);
+                log.info(tag, `Force refresh completed: fetched ${items.length} addresses in ${Date.now() - fetchStart}ms`);
+                return results;
+            }
+
+            // Normal flow: Check cache first
+            log.info(tag, `Batch request for ${items.length} addresses using Redis MGET`);
+
+            // Build all Redis keys
+            const keys = items.map(item => this.buildKey({ networkId: item.networkId, address: item.address }));
+
+            // PERF: Use MGET to fetch all keys in ONE Redis round-trip
+            const cachedValues = await this.redis.mget(...keys);
+
+            // Process results
+            const results = new Map<string, StakingPosition[]>();
+            const missedItems: Array<{ networkId: string; address: string; index: number }> = [];
+
+            for (let i = 0; i < items.length; i++) {
+                const item = items[i];
+                const cached = cachedValues[i];
+                const itemKey = `${item.networkId}:${item.address}`;
+
+                if (cached) {
+                    try {
+                        const parsed = JSON.parse(cached);
+                        if (parsed.value && Array.isArray(parsed.value)) {
+                            results.set(itemKey, parsed.value);
+                            continue;
+                        }
+                    } catch (e) {
+                        log.warn(tag, `Failed to parse cached value for ${keys[i]}`);
+                    }
+                }
+
+                // Cache miss - record for fetching
+                missedItems.push({ ...item, index: i });
+                results.set(itemKey, []); // Placeholder
+            }
+
+            const responseTime = Date.now() - startTime;
+            const hitRate = ((items.length - missedItems.length) / items.length * 100).toFixed(1);
+            log.info(tag, `MGET completed: ${items.length} keys in ${responseTime}ms (${hitRate}% hit rate)`);
+
+            // If we have cache misses, trigger background refresh (non-blocking)
+            if (missedItems.length > 0) {
+                log.info(tag, `Triggering background refresh for ${missedItems.length} cache misses`);
+
+                missedItems.forEach(item => {
+                    this.triggerAsyncRefresh({ networkId: item.networkId, address: item.address }, 'high');
+                });
+            }
+
+            return results;
+
+        } catch (error) {
+            log.error(tag, 'Error in batch staking request:', error);
+            // Return empty arrays for all items
+            const results = new Map<string, StakingPosition[]>();
+            items.forEach(item => {
+                const key = `${item.networkId}:${item.address}`;
+                results.set(key, []);
+            });
+            return results;
+        }
+    }
+}