@pioneer-platform/pioneer-cache 1.7.0 → 1.10.0

package/ACTUAL_CACHE_CONFIG_AUDIT.md

@@ -0,0 +1,319 @@
+# Actual Cache Configuration Audit
+**Date**: 2025-12-27
+**Location**: `/modules/pioneer/pioneer-cache/src/stores/`
+
+## Cache Configuration Reality Check
+
+### Balance Cache (CRITICAL - Your Issue)
+**File**: `balance-cache.ts:77-79`
+
+```typescript
+ttl: 0,                                // Ignored when enableTTL: false
+staleThreshold: 5 * 60 * 1000,         // 5 minutes - triggers background refresh
+enableTTL: false,                      // NEVER EXPIRE - data persists forever
+```
+
+**Reality**:
+- ✅ **Stale threshold**: 5 minutes (triggers background refresh)
+- ❌ **TTL**: DISABLED (no hard expiry)
+- ⚠️  **Risk**: If background refresh fails, data becomes **infinitely stale**
+
+**Your Case**:
+- Balance is 22.5 hours old (1,350 minutes)
+- Should have refreshed 270 times already (every 5 minutes)
+- Background refresh **completely broken**
+
+---
+
+### Price Cache
+**File**: `price-cache.ts:32-34`
+
+```typescript
+ttl: 0,                                // Ignored when enableTTL: false
+staleThreshold: 30 * 60 * 1000,        // 30 minutes - triggers background refresh
+enableTTL: false,                      // NEVER EXPIRE - data persists forever
+```
+
+**Reality**:
+- ✅ **Stale threshold**: 30 minutes
+- ❌ **TTL**: DISABLED
+- ⚠️  **Risk**: Stale prices can persist indefinitely
+
+---
+
+### Portfolio Cache
+**File**: `portfolio-cache.ts:57-59`
+
+```typescript
+ttl: 0,                                // Ignored when enableTTL: false
+staleThreshold: 5 * 60 * 1000,         // 5 minutes - triggers background refresh
+enableTTL: false,                      // NEVER EXPIRE - data persists forever
+```
+
+**Reality**:
+- ✅ **Stale threshold**: 5 minutes
+- ❌ **TTL**: DISABLED
+- ⚠️  **Risk**: Same as balance cache
+
+---
+
+### Staking Cache (ONLY ONE WITH TTL!)
+**File**: `staking-cache.ts:59-61`
+
+```typescript
+ttl: 5 * 60 * 1000,                // 5 minutes - staking changes slowly
+staleThreshold: 2 * 60 * 1000,     // Refresh after 2 minutes
+enableTTL: true,                   // Enable expiration ✅
+```
+
+**Reality**:
+- ✅ **Stale threshold**: 2 minutes (soft refresh)
+- ✅ **TTL**: 5 minutes (hard expiry) ✅
+- ✅ **Safety net**: Even if background refresh fails, data expires in 5 minutes
+
+---
+
+### Zapper Cache (Most Expensive)
+**File**: `zapper-cache.ts:123-125`
+
+```typescript
+ttl: 0,                                     // Ignored when enableTTL: false
+staleThreshold: 24 * 60 * 60 * 1000,        // 24 hours - ONLY refresh after this
+enableTTL: false,                           // NEVER EXPIRE - data persists forever
+```
+
+**Reality**:
+- ✅ **Stale threshold**: 24 hours (expensive API)
+- ❌ **TTL**: DISABLED
+- ⚠️  **Risk**: If refresh fails, could be stale for days/weeks
+
+---
+
+## The Pattern
+
+**All caches except Staking**:
+```
+enableTTL: false  → No hard expiry, relies 100% on background refresh
+```
+
+**Design Intent**: "Stale-while-revalidate" pattern
+1. Return stale data instantly (fast UX)
+2. Trigger background refresh if older than threshold
+3. Cache persists forever for instant loads
+
+**Critical Flaw**: **NO SAFETY NET** if background refresh breaks!
+
+---
+
+## Why Background Refresh is Broken
+
+### The Queue System
+**File**: `base-cache.ts:334-347`
+
+```typescript
+protected triggerAsyncRefresh(params, priority = 'normal'): void {
+    if (!this.config.enableQueue) {
+        return;  // Queue disabled
+    }
+
+    if (!this.queueInitialized || !this.redisQueue) {
+        log.error(tag, `❌ QUEUE NOT INITIALIZED! Cannot refresh`);
+        log.error(tag, `Background refresh is BROKEN - cache will NOT update!`);
+        return;  // ← SILENT FAILURE (logs only, no alerts)
+    }
+
+    // Queue the refresh job...
+}
+```
+
+**Possible Failures**:
+1. ❌ Queue never initialized at startup
+2. ❌ Workers never started
+3. ❌ Workers started but crashed
+4. ❌ Jobs queued but never processed
+5. ❌ Redis connection issues
+
+**Current Visibility**: ZERO (only logs, no monitoring)
+
+---
+
+## Recommended TTL Values (Safety Net)
+
+### Balance Cache
+```typescript
+ttl: 15 * 60 * 1000,                   // 15 minutes - reasonable balance freshness
+staleThreshold: 5 * 60 * 1000,         // 5 minutes - trigger soft refresh
+enableTTL: true,                        // Enable safety net ✅
+```
+
+**Reasoning**:
+- Background refresh should hit at 5 minutes
+- TTL expires at 15 minutes if refresh fails
+- Max staleness: 15 minutes (vs current: infinite)
+
+### Price Cache
+```typescript
+ttl: 60 * 60 * 1000,                   // 60 minutes - prices don't change that fast
+staleThreshold: 30 * 60 * 1000,        // 30 minutes - trigger soft refresh
+enableTTL: true,                        // Enable safety net ✅
+```
+
+**Reasoning**:
+- Crypto prices don't change drastically in 1 hour
+- Background refresh at 30 minutes
+- Max staleness: 60 minutes
+
+### Portfolio Cache
+```typescript
+ttl: 15 * 60 * 1000,                   // 15 minutes - same as balance
+staleThreshold: 5 * 60 * 1000,         // 5 minutes - trigger soft refresh
+enableTTL: true,                        // Enable safety net ✅
+```
+
+### Zapper Cache
+```typescript
+ttl: 48 * 60 * 60 * 1000,              // 48 hours - expensive API
+staleThreshold: 24 * 60 * 60 * 1000,   // 24 hours - trigger soft refresh
+enableTTL: true,                        // Enable safety net ✅
+```
+
+**Reasoning**:
+- Expensive API, minimize calls
+- Background refresh at 24 hours
+- Max staleness: 48 hours (vs current: infinite)
+
+---
+
+## Critical Discord Alerts Needed
+
+### 1. Queue Initialization Failure (CRITICAL)
+```typescript
+if (!this.queueInitialized) {
+    await discord.alert({
+        severity: 'critical',
+        title: '🚨 Cache Queue Failed to Initialize',
+        message: `Cache: ${this.config.name}\nBackground refresh BROKEN!`
+    });
+}
+```
+
+### 2. High Staleness Rate (WARNING)
+```typescript
+// Monitor every 5 minutes
+if (stats.stalenessRate > 50) {
+    await discord.alert({
+        severity: 'warning',
+        title: '⚠️ High Cache Staleness',
+        message: `${this.config.name}: ${stats.stalenessRate}% stale\nWorkers may be failing`
+    });
+}
+```
+
+### 3. Excessive Cache Age (CRITICAL)
+```typescript
+// Check max age in cache
+const maxAge = Math.max(...Object.values(stats.ages));
+const maxAgeHours = maxAge / (60 * 60 * 1000);
+
+if (maxAgeHours > 1) {  // More than 1 hour old
+    await discord.alert({
+        severity: 'critical',
+        title: '🚨 Extremely Stale Cache Data',
+        message: `${this.config.name}: Data ${maxAgeHours.toFixed(1)}h old!\nRefresh completely broken`
+    });
+}
+```
+
+### 4. Worker Crash Detection
+```typescript
+// On worker exit
+process.on('exit', async () => {
+    await discord.alert({
+        severity: 'critical',
+        title: '🚨 Cache Worker Crashed',
+        message: 'Background refresh workers stopped unexpectedly'
+    });
+});
+```
+
+---
+
+## Action Items
+
+### Immediate (Today)
+1. ✅ Add TTL to balance cache (15 min)
+2. ✅ Add TTL to portfolio cache (15 min)
+3. ✅ Add Discord alerts to queue failures
+4. ✅ Clear your stale Bitcoin balance
+
+### Short-term (This Week)
+1. Diagnose why workers aren't running
+2. Add health monitoring (check staleness every 5 min)
+3. Add startup validation (fail fast if queue doesn't init)
+4. Test with cleared cache to verify refresh works
+
+### Long-term (Next Sprint)
+1. Implement comprehensive cache monitoring dashboard
+2. Add Prometheus metrics for cache health
+3. Document cache incident runbook
+4. Consider Redis TTL fallback for all caches
+
+---
+
+## Testing the Fix
+
+### Step 1: Clear Stale Cache
+```bash
+redis-cli DEL "balance_v2:bip122:000000000019d6689c085ae165831e93/slip44:0:d66c81ddb395633630fbd6949e5cb0b4"
+```
+
+### Step 2: Fetch Fresh Balance
+```bash
+curl -X POST http://localhost:9001/api/balances \
+  -H "Content-Type: application/json" \
+  -d '{
+    "pubkeys": [{
+      "caip": "bip122:000000000019d6689c085ae165831e93/slip44:0",
+      "pubkey": "zpub6rPBGeYJtMkALyZgM9AQ8cYQnFprAfetXQeDrSjWpCEPnhfC8tpTDoVzdTrLKg7box2zncYFptaWPCaR8wW4FCiULBU6y77RtqFaGjs9mN6"
+    }]
+  }'
+```
+
+### Step 3: Verify Balance Correct
+```json
+{
+  "balance": "0.00002285",  // ✅ Should be correct now
+  "valueUsd": "2.00",
+  "fetchedAt": 1735346400000  // ✅ Should be recent
+}
+```
+
+### Step 4: Wait 16 Minutes
+- At 5min: Background refresh should trigger
+- At 15min: If refresh failed, TTL expires and forces refetch
+
+### Step 5: Check Cache Age
+```bash
+redis-cli GET "balance_v2:bip122:000000000019d6689c085ae165831e93/slip44:0:d66c81ddb395633630fbd6949e5cb0b4"
+```
+
+Should be <15 minutes old, or not exist (expired via TTL).
+
+---
+
+## Summary
+
+**Current State**:
+- Balance cache: NO TTL, relies 100% on background refresh
+- Background refresh: COMPLETELY BROKEN (22.5 hours stale)
+- Alerts: NONE (silent failures)
+
+**Proposed State**:
+- Balance cache: 15-minute TTL as safety net
+- Background refresh: 5-minute soft refresh
+- Alerts: Discord alerts on all failures
+- Monitoring: Health checks every 5 minutes
+
+**Max Staleness**:
+- Current: **INFINITE** (if refresh fails)
+- Proposed: **15 minutes** (TTL safety net)

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @pioneer-platform/pioneer-cache
 
+## 1.10.0
+
+### Minor Changes
+
+- chore: Merge pull request #10 from coinmastersguild/feature/fix-blockbook-websocket-subscriptions
+
+## 1.9.0
+
+### Minor Changes
+
+- Merge pull request #10 from coinmastersguild/feature/fix-blockbook-websocket-subscriptions
+
+## 1.8.1
+
+### Patch Changes
+
+- fix: Filter xpubs from Blockbook WebSocket subscriptions
+
+## 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

package/dist/core/base-cache.js

@@ -293,6 +293,17 @@ class BaseCache {
                 const key = this.buildKey(params);
                 log.error(tag, `❌ QUEUE NOT INITIALIZED! Cannot refresh ${key}`);
                 log.error(tag, `Background refresh is BROKEN - cache will NOT update!`);
+                // Send Discord alert for queue failure (if handler configured)
+                if (this.config.alertHandler?.onQueueFailure) {
+                    this.config.alertHandler.onQueueFailure(this.config.name, {
+                        key,
+                        queueInitialized: this.queueInitialized,
+                        redisQueue: !!this.redisQueue,
+                        enableQueue: this.config.enableQueue
+                    }).catch(err => {
+                        log.error(tag, 'Failed to send queue failure alert:', err);
+                    });
+                }
                 // FIX #4: Synchronous fallback for high-priority (only if useSyncFallback is enabled)
                 // Default: use sync fallback only for blocking caches (blockOnMiss=true)
                 const shouldUseSyncFallback = this.config.useSyncFallback !== undefined

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

@@ -3,7 +3,9 @@ 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';
+import type { CacheAlertHandler } from '../types';
 /**
  * Configuration for CacheManager
  */
@@ -13,11 +15,14 @@ export interface CacheManagerConfig {
     balanceModule?: any;
     markets?: any;
     networkModules?: Map<string, any>;
+    zapperClient?: any;
+    alertHandler?: CacheAlertHandler;
     enableBalanceCache?: boolean;
     enablePriceCache?: boolean;
     enablePortfolioCache?: boolean;
     enableTransactionCache?: boolean;
     enableStakingCache?: boolean;
+    enableZapperCache?: boolean;
     startWorkers?: boolean;
 }
 /**
@@ -31,8 +36,14 @@ export declare class CacheManager {
     private portfolioCache?;
     private transactionCache?;
     private stakingCache?;
+    private zapperCache?;
     private workers;
     constructor(config: CacheManagerConfig);
+    /**
+     * Purge all pending jobs from the cache refresh queue
+     * Used in local dev to clear stale jobs on startup
+     */
+    purgeQueue(queueName?: string): Promise<void>;
     /**
      * Start background refresh workers for all caches
      */
@@ -57,11 +68,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 +83,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 | ';
@@ -25,17 +26,23 @@ class CacheManager {
         this.redisQueue = config.redisQueue || config.redis; // Fallback to main redis if not provided
         // Initialize Balance Cache
         if (config.enableBalanceCache !== false && config.balanceModule) {
-            this.balanceCache = new balance_cache_1.BalanceCache(this.redis, config.balanceModule);
+            this.balanceCache = new balance_cache_1.BalanceCache(this.redis, config.balanceModule, {
+                alertHandler: config.alertHandler
+            });
             log.info(TAG, '✅ Balance cache initialized');
         }
         // Initialize Price Cache
         if (config.enablePriceCache !== false && config.markets) {
-            this.priceCache = new price_cache_1.PriceCache(this.redis, config.markets);
+            this.priceCache = new price_cache_1.PriceCache(this.redis, config.markets, {
+                alertHandler: config.alertHandler
+            });
             log.info(TAG, '✅ Price cache initialized');
         }
         // Initialize Portfolio Cache
         if (config.enablePortfolioCache !== false && config.balanceModule && config.markets) {
-            this.portfolioCache = new portfolio_cache_1.PortfolioCache(this.redis, config.balanceModule, config.markets);
+            this.portfolioCache = new portfolio_cache_1.PortfolioCache(this.redis, config.balanceModule, config.markets, {
+                alertHandler: config.alertHandler
+            });
             log.info(TAG, '✅ Portfolio cache initialized');
         }
         // Initialize Transaction Cache
@@ -45,17 +52,57 @@ class CacheManager {
         }
         // 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);
+            this.stakingCache = new staking_cache_1.StakingCache(this.redis, config.networkModules, config.markets, {
+                alertHandler: config.alertHandler
+            });
             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, {
+                alertHandler: config.alertHandler
+            });
+            log.info(TAG, '✅ Zapper cache initialized');
+        }
         // Auto-start workers if requested
         if (config.startWorkers) {
-            setImmediate(() => {
-                this.startWorkers();
+            setImmediate(async () => {
+                try {
+                    await this.startWorkers();
+                }
+                catch (error) {
+                    log.error(TAG, '❌ CRITICAL: Failed to start cache workers:', error);
+                    // Send alert if handler configured
+                    if (config.alertHandler?.onQueueFailure) {
+                        await config.alertHandler.onQueueFailure('CacheManager', {
+                            error: error instanceof Error ? error.message : String(error),
+                            stage: 'worker_startup'
+                        }).catch(alertErr => {
+                            log.error(TAG, 'Failed to send worker startup failure alert:', alertErr);
+                        });
+                    }
+                }
             });
         }
         log.info(TAG, '✅ CacheManager initialized');
     }
+    /**
+     * Purge all pending jobs from the cache refresh queue
+     * Used in local dev to clear stale jobs on startup
+     */
+    async purgeQueue(queueName = 'cache-refresh') {
+        const tag = TAG + 'purgeQueue | ';
+        try {
+            log.info(tag, `Purging queue: ${queueName}...`);
+            // Delete the entire queue (Redis list)
+            const deleted = await this.redis.del(queueName);
+            log.info(tag, `✅ Queue purged: ${queueName} (${deleted} keys deleted)`);
+        }
+        catch (error) {
+            log.error(tag, `❌ Failed to purge queue ${queueName}:`, error);
+            throw error;
+        }
+    }
     /**
      * Start background refresh workers for all caches
      */
@@ -77,6 +124,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 +225,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 +297,8 @@ class CacheManager {
             price: this.priceCache,
             portfolio: this.portfolioCache,
             transaction: this.transactionCache,
-            staking: this.stakingCache
+            staking: this.stakingCache,
+            zapper: this.zapperCache
         };
     }
     /**
@@ -254,6 +316,8 @@ class CacheManager {
                 return this.transactionCache;
             case 'staking':
                 return this.stakingCache;
+            case 'zapper':
+                return this.zapperCache;
             default:
                 return undefined;
         }
@@ -280,6 +344,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 { CacheConfig, CachedValue, CacheResult, RefreshJob, HealthCheckResult, CacheStats, CacheAlertHandler } 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/balance-cache.d.ts

@@ -19,6 +19,8 @@ export interface BalanceData {
     fetchedAt?: number;
     fetchedAtISO?: string;
     dataSource?: string;
+    derivedAddresses?: string[];
+    tokens?: any[];
 }
 /**
  * BalanceCache - Caches blockchain balance data

package/dist/stores/balance-cache.js

@@ -169,7 +169,10 @@ class BalanceCache extends base_cache_1.BaseCache {
                 precision: assetInfo.decimals, // Set precision to decimals for compatibility
                 fetchedAt: now,
                 fetchedAtISO: new Date(now).toISOString(),
-                dataSource
+                dataSource,
+                // CRITICAL: Pass through derived addresses and tokens from balance module for xpub subscription
+                derivedAddresses: balanceInfo.derivedAddresses,
+                tokens: balanceInfo.tokens
             };
         }
         catch (error) {