@pioneer-platform/pioneer-cache 1.1.2 → 1.1.3

package/.turbo/turbo-build.log

@@ -0,0 +1 @@
+$ tsc

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @pioneer-platform/pioneer-cache
 
+## 1.1.3
+
+### Patch Changes
+
+- bump
+
 ## 1.1.1
 
 ### Patch Changes

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

@@ -26,6 +26,7 @@ export declare abstract class BaseCache<T> {
     /**
      * Update cache with new value
      * FIX #2: Always includes TTL
+     * CRITICAL FIX: Never overwrite existing valid price with $0 (API failure protection)
      */
     updateCache(key: string, value: T, metadata?: Record<string, any>): Promise<void>;
     /**

package/dist/core/base-cache.js

@@ -8,6 +8,26 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseCache = void 0;
 const log = require('@pioneer-platform/loggerdog')();
+// CRITICAL: Major cryptocurrencies that should NEVER have $0 prices cached as "fresh"
+// If cache has $0 for these, it's an API failure and we should immediately retry
+const MAJOR_CRYPTO_WHITELIST = new Set([
+    'bip122:000000000019d6689c085ae165831e93/slip44:0', // Bitcoin
+    'eip155:1/slip44:60', // Ethereum
+    'eip155:56/slip44:60', // BNB Chain
+    'eip155:137/slip44:60', // Polygon
+    'eip155:42161/slip44:60', // Arbitrum
+    'eip155:10/slip44:60', // Optimism
+    'eip155:8453/slip44:60', // Base
+    'cosmos:cosmoshub-4/slip44:118', // Cosmos
+    'cosmos:osmosis-1/slip44:118', // Osmosis
+    'cosmos:thorchain-mainnet-v1/slip44:931', // Thorchain
+    'cosmos:mayachain-mainnet-v1/slip44:931', // Mayachain
+    'ripple:4109c6f2045fc7eff4cde8f9905d19c2/slip44:144', // XRP
+    'bip122:12a765e31ffd4059bada1e25190f6e98/slip44:2', // Litecoin
+    'bip122:00000000001a91e3dace36e2be3bf030/slip44:3', // Dogecoin
+    'bip122:000007d91d1254d60e2dd1ae58038307/slip44:5', // Dash
+    'bip122:000000000000000000651ef99cb9fcbe/slip44:145', // Bitcoin Cash
+]);
 class BaseCache {
     constructor(redis, config) {
         this.queueInitialized = false;
@@ -70,6 +90,27 @@ class BaseCache {
                 if (this.config.logCacheHits) {
                     log.debug(tag, `Cache hit: ${key} (${responseTime}ms, age: ${age}ms)`);
                 }
+                // CRITICAL FIX: Treat zero prices for major cryptocurrencies as ALWAYS STALE
+                // Zero price for BTC/ETH/etc means API failure, not actual price
+                // Must immediately retry to get real price
+                const normalizedCaip = params.caip?.toLowerCase();
+                const isInvalidMajorCryptoPrice = (this.config.name === 'price' &&
+                    cachedValue.value.price === 0 &&
+                    normalizedCaip &&
+                    Array.from(MAJOR_CRYPTO_WHITELIST).some(wl => wl.toLowerCase() === normalizedCaip));
+                if (isInvalidMajorCryptoPrice) {
+                    log.warn(tag, `🚨 Zero price cached for major cryptocurrency: ${params.caip} - triggering HIGH PRIORITY refresh`);
+                    this.triggerAsyncRefresh(params, 'high');
+                    // Still return the cached zero, but mark as not fresh
+                    return {
+                        success: true,
+                        value: cachedValue.value,
+                        cached: true,
+                        fresh: false, // NOT FRESH - force UI to show loading state
+                        age,
+                        invalidPrice: true
+                    };
+                }
                 // Check staleness async (don't wait)
                 if (this.config.staleThreshold && age > this.config.staleThreshold) {
                     this.triggerAsyncRefresh(params, 'normal');
@@ -164,8 +205,10 @@ class BaseCache {
             // Validate structure - Check for undefined/null, NOT falsy values!
             // CRITICAL: Balance "0", empty arrays [], and empty objects {} are VALID!
             if (parsed.value === undefined || parsed.value === null || typeof parsed.timestamp !== 'number') {
-                log.warn(tag, `Invalid cache structure for ${key}, removing`);
-                await this.redis.del(key);
+                log.error(tag, `Invalid cache structure for ${key} - KEEPING key and triggering refresh`);
+                log.error(tag, `Corrupted data: ${JSON.stringify(parsed).substring(0, 200)}`);
+                // NEVER DELETE: Keep the key, return null to trigger async refresh
+                // The refresh will overwrite the corrupted data
                 return null;
             }
             log.debug(tag, `Cache hit: ${key}`);
@@ -179,10 +222,21 @@ class BaseCache {
     /**
      * Update cache with new value
      * FIX #2: Always includes TTL
+     * CRITICAL FIX: Never overwrite existing valid price with $0 (API failure protection)
      */
     async updateCache(key, value, metadata) {
         const tag = this.TAG + 'updateCache | ';
         try {
+            // CRITICAL: Never overwrite existing non-zero price with $0
+            // This protects against API failures/rate limits overwriting good cached prices
+            if (this.config.name === 'price' && value.price === 0) {
+                const existingCache = await this.getCached(key);
+                if (existingCache && existingCache.value.price > 0) {
+                    log.warn(tag, `🛡️  Refusing to overwrite $${existingCache.value.price} with $0 for ${key}`);
+                    log.warn(tag, `   Keeping existing price - likely API failure/rate limit`);
+                    return; // Do NOT overwrite - keep the old good price
+                }
+            }
             const cachedValue = {
                 value,
                 timestamp: Date.now(),

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

@@ -14,6 +14,9 @@ export interface BalanceData {
     networkId?: string;
     type?: string;
     isNative?: boolean;
+    fetchedAt?: number;
+    fetchedAtISO?: string;
+    dataSource?: string;
 }
 /**
  * BalanceCache - Caches blockchain balance data
@@ -47,6 +50,9 @@ export declare class BalanceCache extends BaseCache<BalanceData> {
     /**
      * Get balances for multiple assets (batch operation)
      * OPTIMIZED: Uses Redis MGET for single round-trip instead of N individual GETs
+     *
+     * CRITICAL FIX: When waitForFresh=true (forceRefresh), bypass cache entirely
+     * and fetch fresh blockchain data for ALL items, not just cache misses
      */
     getBatchBalances(items: Array<{
         caip: string;

package/dist/stores/balance-cache.js

@@ -106,10 +106,13 @@ class BalanceCache extends base_cache_1.BaseCache {
             const balanceInfo = await this.balanceModule.getBalance(asset, owner);
             if (!balanceInfo || !balanceInfo.balance) {
                 log.warn(tag, `No balance returned for ${caip}/${sanitizePubkey(pubkey)}`);
+                const now = Date.now();
                 return {
                     caip,
                     pubkey,
-                    balance: '0'
+                    balance: '0',
+                    fetchedAt: now,
+                    fetchedAtISO: new Date(now).toISOString()
                 };
             }
             // Get asset metadata
@@ -117,13 +120,44 @@ class BalanceCache extends base_cache_1.BaseCache {
             const { caipToNetworkId } = require('@pioneer-platform/pioneer-caip');
             const assetInfo = assetData[caip.toUpperCase()] || assetData[caip.toLowerCase()] || {};
             const networkId = caipToNetworkId(caip);
+            // Use actual node URL if available, otherwise construct generic description
+            let dataSource = 'Unknown';
+            if (balanceInfo.nodeUrl) {
+                // Actual node URL returned from network module
+                dataSource = balanceInfo.nodeUrl;
+            }
+            else {
+                // Fallback to generic description if nodeUrl not available
+                const chainName = assetInfo.name || 'Unknown Chain';
+                if (caip.startsWith('bip122:')) {
+                    dataSource = `${chainName} (Blockbook API)`;
+                }
+                else if (caip.startsWith('eip155:')) {
+                    const isToken = caip.includes('/erc20:');
+                    dataSource = isToken ? `${chainName} (RPC - ERC20)` : `${chainName} (RPC)`;
+                }
+                else if (caip.startsWith('cosmos:')) {
+                    dataSource = `${chainName} (LCD API)`;
+                }
+                else if (caip.startsWith('ripple:')) {
+                    dataSource = `${chainName} (JSON-RPC)`;
+                }
+                else {
+                    dataSource = `${chainName} (API)`;
+                }
+            }
+            // Capture fetch timestamp for freshness tracking
+            const now = Date.now();
             return {
                 caip,
                 pubkey,
                 balance: balanceInfo.balance,
                 symbol: assetInfo.symbol,
                 name: assetInfo.name,
-                networkId
+                networkId,
+                fetchedAt: now,
+                fetchedAtISO: new Date(now).toISOString(),
+                dataSource
             };
         }
         catch (error) {
@@ -171,11 +205,42 @@ class BalanceCache extends base_cache_1.BaseCache {
     /**
      * Get balances for multiple assets (batch operation)
      * OPTIMIZED: Uses Redis MGET for single round-trip instead of N individual GETs
+     *
+     * CRITICAL FIX: When waitForFresh=true (forceRefresh), bypass cache entirely
+     * and fetch fresh blockchain data for ALL items, not just cache misses
      */
     async getBatchBalances(items, waitForFresh) {
         const tag = this.TAG + 'getBatchBalances | ';
         const startTime = Date.now();
         try {
+            // CRITICAL FIX: If waitForFresh=true, skip cache entirely and fetch fresh data
+            if (waitForFresh) {
+                log.info(tag, `🔄 FORCE REFRESH: Bypassing cache for ${items.length} balances - fetching fresh blockchain data`);
+                const fetchStart = Date.now();
+                // Fetch all items fresh in parallel
+                const fetchPromises = items.map(async (item) => {
+                    try {
+                        // Use fetchFresh to get blockchain data and update cache
+                        const freshData = await this.fetchFresh({ caip: item.caip, pubkey: item.pubkey });
+                        return freshData;
+                    }
+                    catch (error) {
+                        log.error(tag, `Failed to fetch fresh ${item.caip}/${item.pubkey}:`, error);
+                        const now = Date.now();
+                        return {
+                            caip: item.caip,
+                            pubkey: item.pubkey,
+                            balance: '0',
+                            fetchedAt: now,
+                            fetchedAtISO: new Date(now).toISOString()
+                        };
+                    }
+                });
+                const results = await Promise.all(fetchPromises);
+                log.info(tag, `✅ Force refresh completed: fetched ${items.length} fresh balances in ${Date.now() - fetchStart}ms`);
+                return results;
+            }
+            // Normal flow: Check cache first
             log.info(tag, `Batch request for ${items.length} balances using Redis MGET`);
             // Build all Redis keys
             const keys = items.map(item => this.buildKey({ caip: item.caip, pubkey: item.pubkey }));
@@ -208,7 +273,7 @@ class BalanceCache extends base_cache_1.BaseCache {
             log.info(tag, `MGET completed: ${items.length} keys in ${responseTime}ms (${hitRate}% hit rate)`);
             // If we have cache misses and blocking is enabled, fetch them
             if (missedItems.length > 0) {
-                const shouldBlock = waitForFresh !== undefined ? waitForFresh : this.config.blockOnMiss;
+                const shouldBlock = this.config.blockOnMiss;
                 if (shouldBlock) {
                     log.info(tag, `Fetching ${missedItems.length} cache misses...`);
                     const fetchStart = Date.now();
@@ -221,7 +286,14 @@ class BalanceCache extends base_cache_1.BaseCache {
                         }
                         catch (error) {
                             log.error(tag, `Failed to fetch ${item.caip}/${item.pubkey}:`, error);
-                            results[item.index] = { caip: item.caip, pubkey: item.pubkey, balance: '0' };
+                            const now = Date.now();
+                            results[item.index] = {
+                                caip: item.caip,
+                                pubkey: item.pubkey,
+                                balance: '0',
+                                fetchedAt: now,
+                                fetchedAtISO: new Date(now).toISOString()
+                            };
                         }
                     });
                     await Promise.all(fetchPromises);
@@ -239,10 +311,13 @@ class BalanceCache extends base_cache_1.BaseCache {
         catch (error) {
             log.error(tag, 'Error in batch balance request:', error);
             // Return defaults for all items
+            const now = Date.now();
             return items.map(item => ({
                 caip: item.caip,
                 pubkey: item.pubkey,
-                balance: '0'
+                balance: '0',
+                fetchedAt: now,
+                fetchedAtISO: new Date(now).toISOString()
             }));
         }
     }

package/dist/types/index.d.ts

@@ -41,6 +41,7 @@ export interface CacheResult<T> {
     fresh: boolean;
     age?: number;
     error?: string;
+    invalidPrice?: boolean;
 }
 /**
  * Health check result

package/package.json

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

package/src/core/base-cache.ts

@@ -19,6 +19,27 @@ import type {
 
 const log = require('@pioneer-platform/loggerdog')();
 
+// CRITICAL: Major cryptocurrencies that should NEVER have $0 prices cached as "fresh"
+// If cache has $0 for these, it's an API failure and we should immediately retry
+const MAJOR_CRYPTO_WHITELIST = new Set([
+    'bip122:000000000019d6689c085ae165831e93/slip44:0',  // Bitcoin
+    'eip155:1/slip44:60',                                 // Ethereum
+    'eip155:56/slip44:60',                                // BNB Chain
+    'eip155:137/slip44:60',                               // Polygon
+    'eip155:42161/slip44:60',                             // Arbitrum
+    'eip155:10/slip44:60',                                // Optimism
+    'eip155:8453/slip44:60',                              // Base
+    'cosmos:cosmoshub-4/slip44:118',                      // Cosmos
+    'cosmos:osmosis-1/slip44:118',                        // Osmosis
+    'cosmos:thorchain-mainnet-v1/slip44:931',             // Thorchain
+    'cosmos:mayachain-mainnet-v1/slip44:931',             // Mayachain
+    'ripple:4109c6f2045fc7eff4cde8f9905d19c2/slip44:144', // XRP
+    'bip122:12a765e31ffd4059bada1e25190f6e98/slip44:2',   // Litecoin
+    'bip122:00000000001a91e3dace36e2be3bf030/slip44:3',   // Dogecoin
+    'bip122:000007d91d1254d60e2dd1ae58038307/slip44:5',   // Dash
+    'bip122:000000000000000000651ef99cb9fcbe/slip44:145', // Bitcoin Cash
+]);
+
 export abstract class BaseCache<T> {
     protected redis: any;
     protected redisQueue: any;
@@ -94,6 +115,32 @@ export abstract class BaseCache<T> {
                     log.debug(tag, `Cache hit: ${key} (${responseTime}ms, age: ${age}ms)`);
                 }
 
+                // CRITICAL FIX: Treat zero prices for major cryptocurrencies as ALWAYS STALE
+                // Zero price for BTC/ETH/etc means API failure, not actual price
+                // Must immediately retry to get real price
+                const normalizedCaip = params.caip?.toLowerCase();
+                const isInvalidMajorCryptoPrice = (
+                    this.config.name === 'price' && 
+                    (cachedValue.value as any).price === 0 &&
+                    normalizedCaip &&
+                    Array.from(MAJOR_CRYPTO_WHITELIST).some(wl => wl.toLowerCase() === normalizedCaip)
+                );
+
+                if (isInvalidMajorCryptoPrice) {
+                    log.warn(tag, `🚨 Zero price cached for major cryptocurrency: ${params.caip} - triggering HIGH PRIORITY refresh`);
+                    this.triggerAsyncRefresh(params, 'high');
+                    
+                    // Still return the cached zero, but mark as not fresh
+                    return {
+                        success: true,
+                        value: cachedValue.value,
+                        cached: true,
+                        fresh: false,  // NOT FRESH - force UI to show loading state
+                        age,
+                        invalidPrice: true
+                    };
+                }
+
                 // Check staleness async (don't wait)
                 if (this.config.staleThreshold && age > this.config.staleThreshold) {
                     this.triggerAsyncRefresh(params, 'normal');
@@ -201,8 +248,10 @@ export abstract class BaseCache<T> {
             // Validate structure - Check for undefined/null, NOT falsy values!
             // CRITICAL: Balance "0", empty arrays [], and empty objects {} are VALID!
             if (parsed.value === undefined || parsed.value === null || typeof parsed.timestamp !== 'number') {
-                log.warn(tag, `Invalid cache structure for ${key}, removing`);
-                await this.redis.del(key);
+                log.error(tag, `Invalid cache structure for ${key} - KEEPING key and triggering refresh`);
+                log.error(tag, `Corrupted data: ${JSON.stringify(parsed).substring(0, 200)}`);
+                // NEVER DELETE: Keep the key, return null to trigger async refresh
+                // The refresh will overwrite the corrupted data
                 return null;
             }
 
@@ -218,11 +267,23 @@ export abstract class BaseCache<T> {
     /**
      * Update cache with new value
      * FIX #2: Always includes TTL
+     * CRITICAL FIX: Never overwrite existing valid price with $0 (API failure protection)
      */
     async updateCache(key: string, value: T, metadata?: Record<string, any>): Promise<void> {
         const tag = this.TAG + 'updateCache | ';
 
         try {
+            // CRITICAL: Never overwrite existing non-zero price with $0
+            // This protects against API failures/rate limits overwriting good cached prices
+            if (this.config.name === 'price' && (value as any).price === 0) {
+                const existingCache = await this.getCached(key);
+                if (existingCache && (existingCache.value as any).price > 0) {
+                    log.warn(tag, `🛡️  Refusing to overwrite $${(existingCache.value as any).price} with $0 for ${key}`);
+                    log.warn(tag, `   Keeping existing price - likely API failure/rate limit`);
+                    return; // Do NOT overwrite - keep the old good price
+                }
+            }
+
             const cachedValue: CachedValue<T> = {
                 value,
                 timestamp: Date.now(),

package/src/stores/balance-cache.ts

@@ -57,6 +57,9 @@ export interface BalanceData {
     networkId?: string;
     type?: string;        // ✅ PHASE 1: Asset type (native, token, unknown)
     isNative?: boolean;   // ✅ PHASE 1: Whether asset is native to chain (backward compat)
+    fetchedAt?: number;   // Unix timestamp when balance was fetched from blockchain
+    fetchedAtISO?: string; // ISO 8601 string for display (e.g., "2025-01-11T12:34:56.789Z")
+    dataSource?: string;  // Data source description (e.g., "Bitcoin Blockbook", "Ethereum RPC")
 }
 
 /**
@@ -136,10 +139,13 @@ export class BalanceCache extends BaseCache<BalanceData> {
 
             if (!balanceInfo || !balanceInfo.balance) {
                 log.warn(tag, `No balance returned for ${caip}/${sanitizePubkey(pubkey)}`);
+                const now = Date.now();
                 return {
                     caip,
                     pubkey,
-                    balance: '0'
+                    balance: '0',
+                    fetchedAt: now,
+                    fetchedAtISO: new Date(now).toISOString()
                 };
             }
 
@@ -150,13 +156,41 @@ export class BalanceCache extends BaseCache<BalanceData> {
             const assetInfo = assetData[caip.toUpperCase()] || assetData[caip.toLowerCase()] || {};
             const networkId = caipToNetworkId(caip);
 
+            // Use actual node URL if available, otherwise construct generic description
+            let dataSource = 'Unknown';
+            if (balanceInfo.nodeUrl) {
+                // Actual node URL returned from network module
+                dataSource = balanceInfo.nodeUrl;
+            } else {
+                // Fallback to generic description if nodeUrl not available
+                const chainName = assetInfo.name || 'Unknown Chain';
+                if (caip.startsWith('bip122:')) {
+                    dataSource = `${chainName} (Blockbook API)`;
+                } else if (caip.startsWith('eip155:')) {
+                    const isToken = caip.includes('/erc20:');
+                    dataSource = isToken ? `${chainName} (RPC - ERC20)` : `${chainName} (RPC)`;
+                } else if (caip.startsWith('cosmos:')) {
+                    dataSource = `${chainName} (LCD API)`;
+                } else if (caip.startsWith('ripple:')) {
+                    dataSource = `${chainName} (JSON-RPC)`;
+                } else {
+                    dataSource = `${chainName} (API)`;
+                }
+            }
+
+            // Capture fetch timestamp for freshness tracking
+            const now = Date.now();
+
             return {
                 caip,
                 pubkey,
                 balance: balanceInfo.balance,
                 symbol: assetInfo.symbol,
                 name: assetInfo.name,
-                networkId
+                networkId,
+                fetchedAt: now,
+                fetchedAtISO: new Date(now).toISOString(),
+                dataSource
             };
 
         } catch (error) {
@@ -211,12 +245,45 @@ export class BalanceCache extends BaseCache<BalanceData> {
     /**
      * Get balances for multiple assets (batch operation)
      * OPTIMIZED: Uses Redis MGET for single round-trip instead of N individual GETs
+     * 
+     * CRITICAL FIX: When waitForFresh=true (forceRefresh), bypass cache entirely
+     * and fetch fresh blockchain data for ALL items, not just cache misses
      */
     async getBatchBalances(items: Array<{ caip: string; pubkey: string }>, waitForFresh?: boolean): Promise<BalanceData[]> {
         const tag = this.TAG + 'getBatchBalances | ';
         const startTime = Date.now();
 
         try {
+            // CRITICAL FIX: If waitForFresh=true, skip cache entirely and fetch fresh data
+            if (waitForFresh) {
+                log.info(tag, `🔄 FORCE REFRESH: Bypassing cache for ${items.length} balances - fetching fresh blockchain data`);
+                const fetchStart = Date.now();
+                
+                // Fetch all items fresh in parallel
+                const fetchPromises = items.map(async (item) => {
+                    try {
+                        // Use fetchFresh to get blockchain data and update cache
+                        const freshData = await this.fetchFresh({ caip: item.caip, pubkey: item.pubkey });
+                        return freshData;
+                    } catch (error) {
+                        log.error(tag, `Failed to fetch fresh ${item.caip}/${item.pubkey}:`, error);
+                        const now = Date.now();
+                        return {
+                            caip: item.caip,
+                            pubkey: item.pubkey,
+                            balance: '0',
+                            fetchedAt: now,
+                            fetchedAtISO: new Date(now).toISOString()
+                        };
+                    }
+                });
+                
+                const results = await Promise.all(fetchPromises);
+                log.info(tag, `✅ Force refresh completed: fetched ${items.length} fresh balances in ${Date.now() - fetchStart}ms`);
+                return results;
+            }
+
+            // Normal flow: Check cache first
             log.info(tag, `Batch request for ${items.length} balances using Redis MGET`);
 
             // Build all Redis keys
@@ -256,7 +323,7 @@ export class BalanceCache extends BaseCache<BalanceData> {
 
             // If we have cache misses and blocking is enabled, fetch them
             if (missedItems.length > 0) {
-                const shouldBlock = waitForFresh !== undefined ? waitForFresh : this.config.blockOnMiss;
+                const shouldBlock = this.config.blockOnMiss;
                 
                 if (shouldBlock) {
                     log.info(tag, `Fetching ${missedItems.length} cache misses...`);
@@ -270,7 +337,14 @@ export class BalanceCache extends BaseCache<BalanceData> {
                             results[item.index] = freshData;
                         } catch (error) {
                             log.error(tag, `Failed to fetch ${item.caip}/${item.pubkey}:`, error);
-                            results[item.index] = { caip: item.caip, pubkey: item.pubkey, balance: '0' };
+                            const now = Date.now();
+                            results[item.index] = {
+                                caip: item.caip,
+                                pubkey: item.pubkey,
+                                balance: '0',
+                                fetchedAt: now,
+                                fetchedAtISO: new Date(now).toISOString()
+                            };
                         }
                     });
                     
@@ -289,10 +363,13 @@ export class BalanceCache extends BaseCache<BalanceData> {
         } catch (error) {
             log.error(tag, 'Error in batch balance request:', error);
             // Return defaults for all items
+            const now = Date.now();
             return items.map(item => ({
                 caip: item.caip,
                 pubkey: item.pubkey,
-                balance: '0'
+                balance: '0',
+                fetchedAt: now,
+                fetchedAtISO: new Date(now).toISOString()
             }));
         }
     }

package/src/stores/balance-cache.ts.bak

@@ -0,0 +1,345 @@
+/*
+    BalanceCache - Balance-specific cache implementation
+
+    Extends BaseCache with balance-specific logic.
+    All common logic is inherited from BaseCache.
+*/
+
+import { BaseCache } from '../core/base-cache';
+import type { CacheConfig } from '../types';
+import crypto from 'crypto';
+
+const log = require('@pioneer-platform/loggerdog')();
+
+/**
+ * Hash pubkey/xpub for privacy-protecting cache keys
+ * Uses SHA-256 for fast, deterministic, one-way hashing
+ */
+function hashPubkey(pubkey: string, salt: string = ''): string {
+    // Detect if this is an xpub (don't lowercase) or regular address (lowercase)
+    const isXpub = pubkey.match(/^[xyz]pub[1-9A-HJ-NP-Za-km-z]{100,}/);
+    const normalized = isXpub ? pubkey.trim() : pubkey.trim().toLowerCase();
+
+    const hash = crypto.createHash('sha256');
+    hash.update(normalized);
+    if (salt) hash.update(salt);
+
+    // Return first 128 bits (32 hex chars) for shorter Redis keys
+    return hash.digest('hex').substring(0, 32);
+}
+
+/**
+ * Sanitize pubkey for safe logging
+ */
+function sanitizePubkey(pubkey: string): string {
+    if (!pubkey || pubkey.length < 12) return '[invalid]';
+
+    // Check if xpub (show first 8, last 8)
+    if (pubkey.match(/^[xyz]pub/)) {
+        return `${pubkey.substring(0, 8)}...${pubkey.substring(pubkey.length - 8)}`;
+    }
+
+    // Regular address (show first 6, last 4)
+    return `${pubkey.substring(0, 6)}...${pubkey.substring(pubkey.length - 4)}`;
+}
+
+/**
+ * Balance data structure
+ */
+export interface BalanceData {
+    caip: string;
+    pubkey: string;
+    balance: string;
+    priceUsd?: string;
+    valueUsd?: string;
+    symbol?: string;
+    name?: string;
+    networkId?: string;
+    type?: string;        // ✅ PHASE 1: Asset type (native, token, unknown)
+    isNative?: boolean;   // ✅ PHASE 1: Whether asset is native to chain (backward compat)
+    fetchedAt?: number;   // Unix timestamp when balance was fetched
+    fetchedAtISO?: string; // ISO 8601 timestamp
+    fetchedAt?: number;   // Unix timestamp when balance was fetched from blockchain
+    fetchedAtISO?: string; // ISO 8601 string for display (e.g., "2025-01-11T12:34:56.789Z")
+    dataSource?: string;  // Data source description (e.g., "Bitcoin Blockbook", "Ethereum RPC")
+}
+
+/**
+ * BalanceCache - Caches blockchain balance data
+ */
+export class BalanceCache extends BaseCache<BalanceData> {
+    private balanceModule: any;
+
+    constructor(redis: any, balanceModule: any, config?: Partial<CacheConfig>) {
+        const defaultConfig: CacheConfig = {
+            name: 'balance',
+            keyPrefix: 'balance_v2:',
+            ttl: 0,                                // Ignored when enableTTL: false
+            staleThreshold: 5 * 60 * 1000,         // 5 minutes - triggers background refresh
+            enableTTL: false,                      // NEVER EXPIRE - data persists forever
+            queueName: 'cache-refresh',
+            enableQueue: true,
+            maxRetries: 3,
+            retryDelay: 10000,
+            blockOnMiss: true,                     // Wait for fresh data on first request - users need real balances!
+            enableLegacyFallback: true,
+            defaultValue: {
+                caip: '',
+                pubkey: '',
+                balance: '0',
+            },
+            maxConcurrentJobs: 10,
+            apiTimeout: 15000,
+            logCacheHits: false,
+            logCacheMisses: true,
+            logRefreshJobs: true
+        };
+
+        super(redis, { ...defaultConfig, ...config });
+        this.balanceModule = balanceModule;
+    }
+
+    /**
+     * Build Redis key for balance data
+     * Format: balance_v2:caip:hashedPubkey
+     *
+     * PRIVACY: Uses SHA-256 hash of pubkey/xpub instead of plaintext
+     * - One-way: cannot recover pubkey from hash
+     * - Deterministic: same pubkey always produces same key
+     * - Fast: ~0.02ms per hash
+     */
+    protected buildKey(params: Record<string, any>): string {
+        const { caip, pubkey } = params;
+        if (!caip || !pubkey) {
+            throw new Error('BalanceCache.buildKey: caip and pubkey required');
+        }
+
+        const normalizedCaip = caip.toLowerCase();
+
+        // Hash pubkey for privacy protection
+        const hashedPubkey = hashPubkey(pubkey, caip);
+
+        return `${this.config.keyPrefix}${normalizedCaip}:${hashedPubkey}`;
+    }
+
+    /**
+     * Fetch balance from blockchain via balance module
+     */
+    protected async fetchFromSource(params: Record<string, any>): Promise<BalanceData> {
+        const tag = this.TAG + 'fetchFromSource | ';
+
+        try {
+            const { caip, pubkey } = params;
+
+            // Log sanitized pubkey for debugging
+            log.debug(tag, `Fetching balance for ${caip}/${sanitizePubkey(pubkey)}`);
+
+            // Fetch balance using balance module (still uses real pubkey)
+            const asset = { caip };
+            const owner = { pubkey };
+            const balanceInfo = await this.balanceModule.getBalance(asset, owner);
+
+            if (!balanceInfo || !balanceInfo.balance) {
+                log.warn(tag, `No balance returned for ${caip}/${sanitizePubkey(pubkey)}`);
+                const now = Date.now();
+                return {
+                    caip,
+                    pubkey,
+                    balance: '0',
+                    fetchedAt: now,
+                    fetchedAtISO: new Date(now).toISOString()
+                };
+            }
+
+            // Get asset metadata
+            const assetData = require('@pioneer-platform/pioneer-discovery').assetData;
+            const { caipToNetworkId } = require('@pioneer-platform/pioneer-caip');
+
+            const assetInfo = assetData[caip.toUpperCase()] || assetData[caip.toLowerCase()] || {};
+            const networkId = caipToNetworkId(caip);
+
+            // Use actual node URL if available, otherwise construct generic description
+            let dataSource = 'Unknown';
+            if (balanceInfo.nodeUrl) {
+                // Actual node URL returned from network module
+                dataSource = balanceInfo.nodeUrl;
+            } else {
+                // Fallback to generic description if nodeUrl not available
+                const chainName = assetInfo.name || 'Unknown Chain';
+                if (caip.startsWith('bip122:')) {
+                    dataSource = `${chainName} (Blockbook API)`;
+                } else if (caip.startsWith('eip155:')) {
+                    const isToken = caip.includes('/erc20:');
+                    dataSource = isToken ? `${chainName} (RPC - ERC20)` : `${chainName} (RPC)`;
+                } else if (caip.startsWith('cosmos:')) {
+                    dataSource = `${chainName} (LCD API)`;
+                } else if (caip.startsWith('ripple:')) {
+                    dataSource = `${chainName} (JSON-RPC)`;
+                } else {
+                    dataSource = `${chainName} (API)`;
+                }
+            }
+
+            // Capture fetch timestamp for freshness tracking
+            const now = Date.now();
+
+            return {
+                caip,
+                pubkey,
+                balance: balanceInfo.balance,
+                symbol: assetInfo.symbol,
+                name: assetInfo.name,
+                networkId,
+                fetchedAt: now,
+                fetchedAtISO: new Date(now).toISOString(),
+                dataSource
+            };
+
+        } catch (error) {
+            log.error(tag, 'Error fetching balance:', error);
+            throw error;
+        }
+    }
+
+    /**
+     * Try to get balance from legacy cache format
+     */
+    protected async getLegacyCached(params: Record<string, any>): Promise<BalanceData | null> {
+        const tag = this.TAG + 'getLegacyCached | ';
+
+        try {
+            const { caip, pubkey } = params;
+            const { caipToNetworkId } = require('@pioneer-platform/pioneer-caip');
+            const networkId = caipToNetworkId(caip);
+
+            // Try legacy format: cache:balance:pubkey:asset
+            const legacyKey = `cache:balance:${pubkey}:${networkId}`;
+            const legacyData = await this.redis.get(legacyKey);
+
+            if (legacyData) {
+                const parsed = JSON.parse(legacyData);
+                if (parsed.balance !== undefined) {
+                    return {
+                        caip,
+                        pubkey,
+                        balance: typeof parsed.balance === 'string' ? parsed.balance : String(parsed.balance)
+                    };
+                }
+            }
+
+            return null;
+
+        } catch (error) {
+            log.error(tag, 'Error getting legacy cached balance:', error);
+            return null;
+        }
+    }
+
+    /**
+     * Get balance for a specific asset and pubkey
+     * Convenience method that wraps base get()
+     */
+    async getBalance(caip: string, pubkey: string, waitForFresh?: boolean): Promise<BalanceData> {
+        const result = await this.get({ caip, pubkey }, waitForFresh);
+        return result.value || this.config.defaultValue;
+    }
+
+    /**
+     * Get balances for multiple assets (batch operation)
+     * OPTIMIZED: Uses Redis MGET for single round-trip instead of N individual GETs
+     */
+    async getBatchBalances(items: Array<{ caip: string; pubkey: string }>, waitForFresh?: boolean): Promise<BalanceData[]> {
+        const tag = this.TAG + 'getBatchBalances | ';
+        const startTime = Date.now();
+
+        try {
+            log.info(tag, `Batch request for ${items.length} balances using Redis MGET`);
+
+            // Build all Redis keys
+            const keys = items.map(item => this.buildKey({ caip: item.caip, pubkey: item.pubkey }));
+
+            // PERF: Use MGET to fetch all keys in ONE Redis round-trip
+            const cachedValues = await this.redis.mget(...keys);
+
+            // Process results
+            const results: BalanceData[] = [];
+            const missedItems: Array<{ caip: string; pubkey: string; index: number }> = [];
+
+            for (let i = 0; i < items.length; i++) {
+                const item = items[i];
+                const cached = cachedValues[i];
+
+                if (cached) {
+                    try {
+                        const parsed = JSON.parse(cached);
+                        if (parsed.value && parsed.value.caip && parsed.value.pubkey) {
+                            results[i] = 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[i] = this.config.defaultValue; // 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 and blocking is enabled, fetch them
+            if (missedItems.length > 0) {
+                const shouldBlock = waitForFresh !== undefined ? waitForFresh : this.config.blockOnMiss;
+                
+                if (shouldBlock) {
+                    log.info(tag, `Fetching ${missedItems.length} cache misses...`);
+                    const fetchStart = Date.now();
+                    
+                    // Fetch all misses in parallel
+                    const fetchPromises = missedItems.map(async (item) => {
+                        try {
+                            // Use fetchFresh to ensure Redis is updated and requests are deduplicated
+                            const freshData = await this.fetchFresh({ caip: item.caip, pubkey: item.pubkey });
+                            results[item.index] = freshData;
+                        } catch (error) {
+                            log.error(tag, `Failed to fetch ${item.caip}/${item.pubkey}:`, error);
+                            const now = Date.now();
+                            results[item.index] = {
+                                caip: item.caip,
+                                pubkey: item.pubkey,
+                                balance: '0',
+                                fetchedAt: now,
+                                fetchedAtISO: new Date(now).toISOString()
+                            };
+                        }
+                    });
+                    
+                    await Promise.all(fetchPromises);
+                    log.info(tag, `Fetched ${missedItems.length} misses in ${Date.now() - fetchStart}ms`);
+                } else {
+                    // Non-blocking: trigger background refresh for misses
+                    missedItems.forEach(item => {
+                        this.triggerAsyncRefresh({ caip: item.caip, pubkey: item.pubkey }, 'high');
+                    });
+                }
+            }
+
+            return results;
+
+        } catch (error) {
+            log.error(tag, 'Error in batch balance request:', error);
+            // Return defaults for all items
+            const now = Date.now();
+            return items.map(item => ({
+                caip: item.caip,
+                pubkey: item.pubkey,
+                balance: '0',
+                fetchedAt: now,
+                fetchedAtISO: new Date(now).toISOString()
+            }));
+        }
+    }
+}

package/src/types/index.ts

@@ -58,6 +58,7 @@ export interface CacheResult<T> {
     fresh: boolean;                        // Is value fresh (not stale)?
     age?: number;                          // Age of cached value in ms
     error?: string;
+    invalidPrice?: boolean;                // For price cache: indicates $0 for major crypto (API failure)
 }
 
 /**