@spacesops/wdk-react-native-core 1.0.0-beta.40

package/src/store/walletStore.ts

@@ -0,0 +1,301 @@
+/**
+ * Wallet Store - Source of Truth for Wallet Data
+ * 
+ * IMPORTANT: This is the ONLY place where addresses and balances are actually stored.
+ * 
+ * ## Store Boundaries
+ * 
+ * **walletStore** (this file):
+ * - Wallet addresses: { [walletId]: { [network]: { [accountIndex]: address } } }
+ * - Wallet balances: { [walletId]: { [network]: { [accountIndex]: { [tokenAddress]: balance } } } }
+ * - Address loading states: { [walletId]: { [network-accountIndex]: boolean } }
+ * - Balance loading states: { [walletId]: { [network-accountIndex-tokenAddress]: boolean } }
+ * - Last balance update timestamps: { [walletId]: { [network]: { [accountIndex]: timestamp } } }
+ * - Account list: { [walletId]: Array of account info }
+ * - Wallet list: Array of wallet info (multiple wallets)
+ * - Active wallet ID: Currently active wallet identifier
+ * 
+ * Note: Loading states for wallet list operations are managed locally in hooks
+ * (useWalletManager) since they're ephemeral and only used within those hooks.
+ * 
+ * **workletStore** (workletStore.ts):
+ * - Worklet lifecycle state (isWorkletStarted, isInitialized, etc.)
+ * - Worklet runtime instances (worklet, hrpc, ipc)
+ * - Worklet configuration
+ * 
+ * ## Separation of Concerns
+ * 
+ * - **walletStore**: Manages wallet data (addresses, balances) - derived/computed from worklet
+ * - **workletStore**: Manages worklet runtime and lifecycle
+ * 
+ * These stores are intentionally separate to:
+ * 1. Prevent cross-contamination of lifecycle and data concerns
+ * 2. Allow independent persistence strategies
+ * 3. Enable clear boundaries for testing and debugging
+ * 
+ * ## Important Notes
+ * 
+ * - Addresses: Stored in Zustand (derived/computed state, deterministic, no refetching needed)
+ * - Balances: Stored in Zustand (single source of truth), use TanStack Query via useBalance() hook for fetching
+ *   - Zustand is the single source of truth for balances
+ *   - TanStack Query reads from Zustand (initialData) and updates Zustand after fetch
+ *   - No sync logic needed - TanStack Query directly updates the source of truth
+ * - NEVER store worklet lifecycle state in walletStore
+ * - NEVER store worklet runtime instances in walletStore
+ * - All operations are handled by focused services (AddressService, BalanceService), not the store itself
+ */
+
+// External packages
+import { create } from 'zustand'
+import { persist, createJSONStorage, devtools } from 'zustand/middleware'
+
+// Local imports
+import type {
+  WalletAddressesByWallet,
+  WalletBalancesByWallet,
+  BalanceLoadingStates,
+} from '../types'
+import { createMMKVStorageAdapter } from '../storage/mmkvStorage'
+import { log, logError } from '../utils/logger'
+
+export interface WalletLoadingStates {
+  [key: string]: boolean
+}
+
+export interface AccountInfo {
+  /** Account index (0-based) */
+  accountIndex: number
+  /** Account address for each network */
+  addresses: Record<string, string>
+}
+
+export interface WalletInfo {
+  /** Wallet identifier (e.g., user email) */
+  identifier: string
+  /** Whether wallet exists in secure storage */
+  exists: boolean
+  /** Whether this wallet is currently active/initialized */
+  isActive: boolean
+}
+
+/**
+ * Wallet loading state - tracks the lifecycle of loading a specific wallet
+ * This is the single source of truth for wallet loading state
+ */
+export type WalletLoadingState =
+  | { type: 'not_loaded' }
+  | { type: 'checking'; identifier: string }
+  | { type: 'loading'; identifier: string; walletExists: boolean }
+  | { type: 'ready'; identifier: string }
+  | { type: 'error'; identifier: string | null; error: Error }
+
+export interface WalletState {
+  // SOURCE OF TRUTH - addresses stored ONLY here (per-wallet)
+  addresses: WalletAddressesByWallet  // walletId -> addresses
+  walletLoading: Record<string, WalletLoadingStates>  // walletId -> loading states
+  // SOURCE OF TRUTH - balances stored ONLY here (per-wallet)
+  balances: WalletBalancesByWallet  // walletId -> balances
+  // Maps walletId -> "network-accountIndex-tokenAddress" -> boolean
+  balanceLoading: Record<string, BalanceLoadingStates>  // walletId -> loading states
+  lastBalanceUpdate: Record<string, Record<string, Record<number, number>>>  // walletId -> network -> accountIndex -> timestamp
+  // Account list management (per-wallet)
+  accountList: Record<string, AccountInfo[]>  // walletId -> account list
+  // Wallet list management
+  walletList: WalletInfo[]
+  activeWalletId: string | null
+  // SOURCE OF TRUTH - wallet loading state (replaces React reducer)
+  walletLoadingState: WalletLoadingState
+  // Operation mutex - prevents concurrent wallet operations
+  isOperationInProgress: boolean
+  currentOperation: string | null  // Description of current operation
+}
+
+export type WalletStore = WalletState
+
+type WalletStoreInstance = ReturnType<ReturnType<typeof create<WalletStore>>>
+
+const initialState: WalletState = {
+  addresses: {},  // walletId -> addresses
+  walletLoading: {},  // walletId -> loading states
+  balances: {},  // walletId -> balances
+  balanceLoading: {},  // walletId -> loading states
+  lastBalanceUpdate: {},  // walletId -> network -> accountIndex -> timestamp
+  accountList: {},  // walletId -> account list
+  walletList: [],
+  activeWalletId: null,
+  walletLoadingState: { type: 'not_loaded' },
+  isOperationInProgress: false,
+  currentOperation: null,
+}
+
+const defaultStorageAdapter = createMMKVStorageAdapter()
+
+let walletStoreInstance: WalletStoreInstance | null = null
+
+/**
+ * Creates singleton wallet store instance.
+ * All operations are handled by focused services (AddressService, BalanceService), not the store itself.
+ */
+export function createWalletStore(): WalletStoreInstance {
+  if (walletStoreInstance) {
+    return walletStoreInstance
+  }
+
+  const store = create<WalletStore>()(
+    devtools(
+      persist(
+        (set, get) => ({
+          ...initialState,
+        }),
+        {
+          name: 'wallet-storage',
+          storage: createJSONStorage(() => defaultStorageAdapter),
+          partialize: (state: WalletState) => ({
+            addresses: state.addresses,
+            balances: state.balances,
+            balanceLoading: {},
+            lastBalanceUpdate: state.lastBalanceUpdate,
+            accountList: state.accountList,
+            walletList: state.walletList,
+            activeWalletId: state.activeWalletId,
+            // Don't persist loading state or operation mutex - these are runtime-only
+          }),
+          onRehydrateStorage: () => {
+            return (state: WalletState | undefined) => {
+              if (state) {
+                log('🔄 Rehydrating wallet state - resetting loading states')
+                state.walletLoading = {}
+                state.balanceLoading = {}
+                // Reset runtime-only state
+                state.walletLoadingState = { type: 'not_loaded' }
+                state.isOperationInProgress = false
+                state.currentOperation = null
+              }
+            }
+          },
+        }
+      ),
+      { name: 'WalletStore' }
+    )
+  )
+
+  walletStoreInstance = store
+  return store
+}
+
+export function getWalletStore() {
+  return createWalletStore()
+}
+
+/**
+ * Wallet state actions - helper functions for updating wallet loading state
+ * These provide a clean API for state transitions with validation
+ */
+
+/**
+ * Validate state transition
+ * Returns true if transition is valid, false otherwise
+ */
+function isValidStateTransition(
+  current: WalletLoadingState,
+  next: WalletLoadingState['type']
+): boolean {
+  // Allow reset from any state
+  if (next === 'not_loaded') return true
+  
+  // Allow error from any state
+  if (next === 'error') return true
+  
+  // After early returns, TypeScript narrows the type, but we need to check all transitions
+  // Use type assertion to tell TypeScript that 'not_loaded' and 'error' are still possible
+  // (even though they're handled by early returns, they're valid from all states)
+  const nextType = next as WalletLoadingState['type']
+  
+  switch (current.type) {
+    case 'not_loaded':
+      return nextType === 'checking' || nextType === 'loading'
+    case 'checking':
+      return nextType === 'loading' || nextType === 'error'
+    case 'loading':
+      return nextType === 'ready' || nextType === 'error'
+    case 'ready':
+      return nextType === 'not_loaded' || nextType === 'loading' || nextType === 'checking'
+    case 'error':
+      return nextType === 'not_loaded' || nextType === 'checking' || nextType === 'loading'
+    default:
+      return false
+  }
+}
+
+/**
+ * Update wallet loading state with validation
+ * Throws error if transition is invalid
+ * Logs state transitions for debugging
+ */
+export function updateWalletLoadingState(
+  state: WalletState,
+  newState: WalletLoadingState
+): Partial<WalletState> {
+  // Log state transition for debugging
+  if (state.walletLoadingState.type !== newState.type) {
+    log(`[WalletState] Transition: ${state.walletLoadingState.type} -> ${newState.type}`, {
+      from: state.walletLoadingState,
+      to: newState,
+    })
+  }
+  
+  if (!isValidStateTransition(state.walletLoadingState, newState.type)) {
+    const error = new Error(
+      `Invalid state transition from ${state.walletLoadingState.type} to ${newState.type}`
+    )
+    logError(`⚠️ Invalid state transition: ${error.message}`, {
+      currentState: state.walletLoadingState,
+      attemptedState: newState,
+    })
+    // In development, throw error. In production, log and allow transition
+    // Note: __DEV__ is a React Native global, may not be available in all environments
+    if (typeof __DEV__ !== 'undefined' && __DEV__) {
+      throw error
+    }
+  }
+  
+  return { walletLoadingState: newState }
+}
+
+/**
+ * Get wallet identifier from loading state
+ */
+export function getWalletIdFromLoadingState(state: WalletLoadingState): string | null {
+  switch (state.type) {
+    case 'checking':
+    case 'loading':
+    case 'ready':
+      return state.identifier
+    case 'error':
+      return state.identifier
+    case 'not_loaded':
+      return null
+  }
+}
+
+/**
+ * Check if wallet is in a loading state
+ */
+export function isWalletLoadingState(state: WalletLoadingState): boolean {
+  return state.type === 'checking' || state.type === 'loading'
+}
+
+/**
+ * Check if wallet is ready
+ */
+export function isWalletReadyState(state: WalletLoadingState): boolean {
+  return state.type === 'ready'
+}
+
+/**
+ * Check if wallet is in error state
+ */
+export function isWalletErrorState(state: WalletLoadingState): boolean {
+  return state.type === 'error'
+}
+

package/src/store/workletStore.ts

@@ -0,0 +1,340 @@
+/**
+ * Worklet Store - Source of Truth for Worklet Lifecycle
+ * 
+ * This store manages worklet lifecycle state (initialization, configuration, runtime instances).
+ * 
+ * ## Store Boundaries
+ * 
+ * **workletStore** (this file):
+ * - Worklet lifecycle state (isWorkletStarted, isInitialized, isLoading)
+ * - Worklet runtime instances (worklet, hrpc, ipc)
+ * - Worklet configuration (networkConfigs)
+ * - Worklet initialization results (workletStartResult, wdkInitResult)
+ * - Encrypted credentials in memory (encryptedSeed, encryptionKey) - for active wallet
+ * - Multi-wallet credential cache (credentialsCache) - for multiple wallets
+ * 
+ * **walletStore** (walletStore.ts):
+ * - Wallet data (addresses, balances)
+ * - Wallet loading states
+ * - Balance loading states
+ * - Last balance update timestamps
+ * 
+ * ## Separation of Concerns
+ * 
+ * - **workletStore**: Manages the worklet runtime and its lifecycle
+ * - **walletStore**: Manages wallet data derived from the worklet
+ * 
+ * These stores are intentionally separate to:
+ * 1. Prevent cross-contamination of lifecycle and data concerns
+ * 2. Allow independent persistence strategies
+ * 3. Enable clear boundaries for testing and debugging
+ * 
+ * ## Important Notes
+ * 
+ * - NEVER store wallet data (addresses, balances) in workletStore
+ * - NEVER store worklet lifecycle state in walletStore
+ * - All worklet state is runtime-only - state resets completely on app restart
+ * - Worklets must be recreated when the app restarts
+ * - Encrypted credentials are runtime-only (loaded from secure storage when needed)
+ * - All operations are handled by WorkletLifecycleService, not the store itself
+ */
+
+// External packages
+import { create } from 'zustand'
+import { devtools } from 'zustand/middleware'
+import { Worklet } from '@spacesops/react-native-bare-kit'
+import { HRPC } from '@spacesops/pear-wrk-wdk'
+import type { WorkletStartResponse } from '@spacesops/pear-wrk-wdk/types/rpc'
+
+// Local imports
+import type {
+  NetworkConfigs,
+} from '../types'
+import { log } from '../utils/logger'
+
+/**
+ * Maximum number of credentials to cache before evicting least recently used
+ * This prevents unbounded memory growth while maintaining performance
+ * Recommended: 10-20 wallets for typical use cases
+ * 
+ * Cache Management:
+ * - Size Limit: When cache exceeds MAX_CREDENTIALS_CACHE_SIZE, LRU entries are evicted
+ * - TTL (Time To Live): Each credential has an expiration timestamp (default: 5 minutes)
+ * - Automatic Expiration: Expired credentials are removed on access
+ * - LRU Eviction: Least recently used credentials are evicted when size limit is reached
+ * 
+ * These safeguards ensure:
+ * 1. Memory usage remains bounded
+ * 2. Credentials don't persist indefinitely in memory
+ * 3. Frequently used wallets remain cached for better UX
+ */
+const MAX_CREDENTIALS_CACHE_SIZE = 15
+
+/**
+ * Cached credentials interface for multi-wallet support
+ * Credentials are cached in workletStore to avoid repeated biometric prompts
+ */
+export interface CachedCredentials {
+  encryptionKey?: string
+  encryptedSeed?: string
+  encryptedEntropy?: string
+  expiresAt: number  // TTL timestamp
+}
+
+/**
+ * Access tracking for LRU eviction
+ * Tracks when each credential was last accessed
+ */
+const credentialsAccessOrder = new Map<string, number>()
+let credentialsAccessCounter = 0
+
+export interface WorkletState {
+  worklet: Worklet | null
+  hrpc: HRPC | null
+  ipc: unknown | null
+  isWorkletStarted: boolean
+  isInitialized: boolean
+  isLoading: boolean
+  error: string | null
+  encryptedSeed: string | null
+  encryptionKey: string | null
+  // seedPhrase is never stored - we only use encrypted approach
+  // encryptedEntropy is stored in secure storage but not in runtime state
+  // It's only needed when retrieving mnemonic, so it's loaded from secure storage on demand
+  networkConfigs: NetworkConfigs | null
+  workletStartResult: WorkletStartResponse | null
+  wdkInitResult: { status?: string | null } | null
+  // Multi-wallet credential cache (replaces static Map in WalletSetupService)
+  // Each entry has a TTL (expiresAt timestamp) and is automatically evicted when:
+  // 1. Cache size exceeds MAX_CREDENTIALS_CACHE_SIZE (LRU eviction)
+  // 2. Credential is accessed after expiration (automatic cleanup)
+  credentialsCache: Record<string, CachedCredentials>
+  // Cache TTL configuration (time to live in milliseconds)
+  // Default: 5 minutes - credentials expire after this time
+  credentialsCacheTTL: number
+}
+
+export type WorkletStore = WorkletState
+
+type WorkletStoreInstance = ReturnType<ReturnType<typeof create<WorkletStore>>>
+
+const initialState: WorkletState = {
+  worklet: null,
+  hrpc: null,
+  ipc: null,
+  isWorkletStarted: false,
+  isInitialized: false,
+  isLoading: false,
+  error: null,
+  encryptedSeed: null,
+  encryptionKey: null,
+  networkConfigs: null,
+  workletStartResult: null,
+  wdkInitResult: null,
+  credentialsCache: {},
+  credentialsCacheTTL: 5 * 60 * 1000, // 5 minutes
+}
+
+let workletStoreInstance: WorkletStoreInstance | null = null
+
+/**
+ * Creates singleton worklet store instance.
+ * 
+ * This store is runtime-only - all state resets on app restart.
+ * All operations are handled by WorkletLifecycleService, not the store itself.
+ */
+export function createWorkletStore(): WorkletStoreInstance {
+  if (workletStoreInstance) {
+    return workletStoreInstance
+  }
+
+  const store = create<WorkletStore>()(
+    devtools(
+      () => ({
+        ...initialState,
+      }),
+      { name: 'WorkletStore' }
+    )
+  )
+
+  workletStoreInstance = store
+  return store
+}
+
+export function getWorkletStore() {
+  return createWorkletStore()
+}
+
+/**
+ * Evict least recently used credentials from cache when limit is reached
+ * Logs eviction for monitoring
+ */
+function evictLRUCredentials(): void {
+  const store = getWorkletStore()
+  const state = store.getState()
+  const cacheSize = Object.keys(state.credentialsCache).length
+  
+  if (cacheSize < MAX_CREDENTIALS_CACHE_SIZE) {
+    return
+  }
+
+  // Find the least recently used credential
+  let oldestIdentifier: string | null = null
+  let oldestAccess = Infinity
+
+  for (const [identifier, accessTime] of credentialsAccessOrder.entries()) {
+    if (accessTime < oldestAccess && state.credentialsCache[identifier]) {
+      oldestAccess = accessTime
+      oldestIdentifier = identifier
+    }
+  }
+
+  // Remove the least recently used credential
+  if (oldestIdentifier !== null) {
+    const { [oldestIdentifier]: _, ...rest } = state.credentialsCache
+    credentialsAccessOrder.delete(oldestIdentifier)
+    store.setState({ credentialsCache: rest })
+    log(`[WorkletStore] Evicted LRU credentials cache entry: ${oldestIdentifier} (cache size: ${cacheSize}/${MAX_CREDENTIALS_CACHE_SIZE})`)
+  }
+}
+
+/**
+ * Log cache size if it exceeds warning threshold (50% of max)
+ * Useful for monitoring cache growth in production
+ */
+function logCacheSizeIfNeeded(cacheSize: number): void {
+  const warningThreshold = Math.ceil(MAX_CREDENTIALS_CACHE_SIZE * 0.5)
+  if (cacheSize >= warningThreshold) {
+    log(`[WorkletStore] Credentials cache size: ${cacheSize}/${MAX_CREDENTIALS_CACHE_SIZE} (${Math.round(cacheSize / MAX_CREDENTIALS_CACHE_SIZE * 100)}% full)`)
+  }
+}
+
+/**
+ * Get cached credentials for a wallet identifier
+ * Returns null if not cached or expired
+ * Updates access time for LRU tracking
+ */
+export function getCachedCredentials(identifier: string): CachedCredentials | null {
+  const store = getWorkletStore()
+  const state = store.getState()
+  const cached = state.credentialsCache[identifier]
+  
+  if (!cached) return null
+  
+  // Check expiration
+  if (Date.now() > cached.expiresAt) {
+    // Remove expired entry
+    const { [identifier]: _, ...rest } = state.credentialsCache
+    credentialsAccessOrder.delete(identifier)
+    store.setState({
+      credentialsCache: rest,
+    })
+    return null
+  }
+  
+  // Update access time for LRU tracking
+  credentialsAccessCounter++
+  credentialsAccessOrder.set(identifier, credentialsAccessCounter)
+  
+  return cached
+}
+
+/**
+ * Set cached credentials for a wallet identifier
+ * Evicts LRU entries if cache size limit is reached
+ * Logs cache size for monitoring
+ */
+export function setCachedCredentials(
+  identifier: string,
+  credentials: Partial<CachedCredentials>
+): void {
+  const store = getWorkletStore()
+  const state = store.getState()
+  const existing = state.credentialsCache[identifier] || {}
+  
+  // Evict LRU credentials if needed before adding new entry
+  // Check if we're adding a new entry (not just updating existing)
+  const isNewEntry = !state.credentialsCache[identifier]
+  if (isNewEntry) {
+    evictLRUCredentials()
+  }
+  
+  // Update access time for LRU tracking
+  credentialsAccessCounter++
+  credentialsAccessOrder.set(identifier, credentialsAccessCounter)
+  
+  store.setState({
+    credentialsCache: {
+      ...state.credentialsCache,
+      [identifier]: {
+        ...existing,
+        ...credentials,
+        expiresAt: Date.now() + state.credentialsCacheTTL,
+      }
+    }
+  })
+
+  // Log cache size for monitoring (after state update)
+  const newCacheSize = Object.keys(store.getState().credentialsCache).length
+  logCacheSizeIfNeeded(newCacheSize)
+}
+
+/**
+ * Clear credentials cache for a specific wallet or all wallets
+ * Also clears access tracking
+ */
+export function clearCredentialsCache(identifier?: string): void {
+  const store = getWorkletStore()
+  const state = store.getState()
+  
+  if (identifier) {
+    // Clear specific wallet
+    const { [identifier]: _, ...rest } = state.credentialsCache
+    credentialsAccessOrder.delete(identifier)
+    store.setState({ credentialsCache: rest })
+  } else {
+    // Clear all
+    credentialsAccessOrder.clear()
+    credentialsAccessCounter = 0
+    store.setState({ credentialsCache: {} })
+  }
+}
+
+/**
+ * Clear all sensitive data from memory (active wallet credentials + cache)
+ * This should be called when sensitive data is no longer needed
+ * to minimize exposure in memory dumps or debugging
+ * 
+ * Note: In JavaScript, we cannot overwrite memory. Setting to null and clearing
+ * references allows garbage collection, but the old values may remain in memory
+ * until GC runs. This is a JavaScript limitation.
+ */
+export function clearAllSensitiveData(): void {
+  const store = getWorkletStore()
+  credentialsAccessOrder.clear()
+  credentialsAccessCounter = 0
+  store.setState({
+    encryptedSeed: null,
+    encryptionKey: null,
+    credentialsCache: {},
+  })
+}
+
+/**
+ * Reset the worklet store instance (useful for testing)
+ * Also resets access tracking
+ */
+export function resetWorkletStore(): void {
+  credentialsAccessOrder.clear()
+  credentialsAccessCounter = 0
+  workletStoreInstance = null
+}
+
+/**
+ * Get current credentials cache size
+ * Useful for monitoring and debugging
+ */
+export function getCredentialsCacheSize(): number {
+  const store = getWorkletStore()
+  return Object.keys(store.getState().credentialsCache).length
+}