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

package/dist/storage/mmkvStorage.js

@@ -0,0 +1,348 @@
+import { createMMKV } from 'react-native-mmkv';
+import { getMMKVKey } from '../utils/mmkvKeyManager';
+import { logWarn } from '../utils/logger';
+/**
+ * Maximum number of storage instances to cache before evicting least recently used
+ * This prevents unbounded memory growth while maintaining performance
+ */
+const MAX_STORAGE_CACHE_SIZE = 10;
+/**
+ * Cache for MMKV storage instances to avoid recreating them
+ * Uses LRU (Least Recently Used) eviction policy to limit memory usage
+ */
+const storageCache = new Map();
+const storageAccessOrder = new Map();
+let storageAccessCounter = 0;
+/**
+ * Evict least recently used storage instance from cache when limit is reached
+ */
+function evictLRUStorage() {
+    if (storageCache.size < MAX_STORAGE_CACHE_SIZE) {
+        return;
+    }
+    // Find the least recently used storage
+    let oldestKey = null;
+    let oldestAccess = Infinity;
+    for (const [key, accessTime] of storageAccessOrder.entries()) {
+        if (accessTime < oldestAccess) {
+            oldestAccess = accessTime;
+            oldestKey = key;
+        }
+    }
+    // Remove the least recently used storage
+    if (oldestKey !== null) {
+        storageCache.delete(oldestKey);
+        storageAccessOrder.delete(oldestKey);
+    }
+}
+/**
+ * Create MMKV storage instance for the wallet
+ *
+ * SECURITY NOTE: MMKV stores files in the app's document directory, which is app-scoped.
+ * Two different apps will NOT share data because each app has its own isolated document directory.
+ *
+ * This is for non-sensitive data persistence (wallet metadata, balances, addresses).
+ * For sensitive data (encrypted seeds, keys), use SecureStorage from wdk-react-native-secure-storage.
+ *
+ * The encryption key is derived from a device/app identifier to ensure each app instance
+ * has a unique encryption key. If no account identifier is provided, a default app-scoped
+ * identifier is used.
+ *
+ * @param accountIdentifier - Optional account identifier for per-account encryption keys.
+ *                            If not provided, uses a default app-scoped identifier.
+ * @returns Promise that resolves to MMKV storage instance
+ */
+export async function createMMKVStorage(accountIdentifier) {
+    // Use account identifier if provided, otherwise use a default app-scoped identifier
+    // This ensures each app instance has a unique key while allowing per-account keys
+    const identifier = accountIdentifier || 'wdk-app-default';
+    // Check cache first
+    const cachedStorage = storageCache.get(identifier);
+    if (cachedStorage !== undefined) {
+        // Update access time for LRU tracking
+        storageAccessCounter++;
+        storageAccessOrder.set(identifier, storageAccessCounter);
+        return cachedStorage;
+    }
+    // Evict LRU storage if cache is full
+    evictLRUStorage();
+    // Derive encryption key asynchronously
+    const encryptionKey = await getMMKVKey(identifier);
+    const storage = createMMKV({
+        id: 'wallet-storage',
+        encryptionKey,
+    });
+    // Cache the storage instance
+    storageAccessCounter++;
+    storageCache.set(identifier, storage);
+    storageAccessOrder.set(identifier, storageAccessCounter);
+    return storage;
+}
+/**
+ * Maximum number of storage adapters to cache before evicting least recently used
+ * This prevents unbounded memory growth while maintaining performance
+ */
+const MAX_ADAPTER_CACHE_SIZE = 10;
+/**
+ * Storage adapter cache - stores initialized adapters by identifier
+ * Uses LRU (Least Recently Used) eviction policy to limit memory usage
+ */
+const adapterCache = new Map();
+const adapterAccessOrder = new Map();
+let adapterAccessCounter = 0;
+/**
+ * Evict least recently used adapter from cache when limit is reached
+ */
+function evictLRUAdapter() {
+    if (adapterCache.size < MAX_ADAPTER_CACHE_SIZE) {
+        return;
+    }
+    // Find the least recently used adapter
+    let oldestKey = null;
+    let oldestAccess = Infinity;
+    for (const [key, accessTime] of adapterAccessOrder.entries()) {
+        if (accessTime < oldestAccess) {
+            oldestAccess = accessTime;
+            oldestKey = key;
+        }
+    }
+    // Remove the least recently used adapter
+    if (oldestKey !== null) {
+        adapterCache.delete(oldestKey);
+        adapterAccessOrder.delete(oldestKey);
+    }
+}
+/**
+ * Storage initialization state
+ */
+var StorageInitState;
+(function (StorageInitState) {
+    StorageInitState["NOT_STARTED"] = "NOT_STARTED";
+    StorageInitState["INITIALIZING"] = "INITIALIZING";
+    StorageInitState["READY"] = "READY";
+    StorageInitState["ERROR"] = "ERROR";
+})(StorageInitState || (StorageInitState = {}));
+/**
+ * Storage adapter factory for Zustand persistence
+ * This allows Zustand stores to use MMKV for persistence
+ *
+ * Uses lazy async initialization with synchronous API.
+ * Storage is initialized asynchronously when first accessed, then cached.
+ * Operations are queued during initialization to prevent race conditions.
+ *
+ * IMPORTANT: The synchronous API (getItem) may return null during initialization.
+ * This is expected behavior - Zustand will handle missing data gracefully on first load.
+ * Subsequent operations will be queued and processed once storage is ready.
+ *
+ * @param accountIdentifier - Optional account identifier for per-account encryption keys.
+ *                            If not provided, uses a default app-scoped identifier.
+ * @returns StorageAdapter with lazy async initialization
+ */
+export function createMMKVStorageAdapter(accountIdentifier) {
+    const identifier = accountIdentifier || 'wdk-app-default';
+    // Return cached adapter if available
+    const cachedAdapter = adapterCache.get(identifier);
+    if (cachedAdapter !== undefined) {
+        // Update access time for LRU tracking
+        adapterAccessCounter++;
+        adapterAccessOrder.set(identifier, adapterAccessCounter);
+        return cachedAdapter;
+    }
+    // Evict LRU adapter if cache is full
+    evictLRUAdapter();
+    let storageInstance = null;
+    let storagePromise = null;
+    let initState = StorageInitState.NOT_STARTED;
+    let initError = null;
+    const pendingOperations = [];
+    // Process queued operations after storage is ready
+    const processPendingOperations = (storage) => {
+        // Process all pending operations in order
+        const operations = [...pendingOperations];
+        pendingOperations.length = 0; // Clear the array
+        for (const op of operations) {
+            try {
+                switch (op.type) {
+                    case 'get':
+                        const value = storage.getString(op.key);
+                        op.resolve(value ?? null);
+                        break;
+                    case 'set':
+                        if (op.value !== undefined) {
+                            storage.set(op.key, op.value);
+                            op.resolve(null);
+                        }
+                        break;
+                    case 'remove':
+                        ;
+                        storage.delete(op.key);
+                        op.resolve(null);
+                        break;
+                }
+            }
+            catch (error) {
+                op.reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        }
+    };
+    // Initialize storage asynchronously
+    const ensureStorage = async () => {
+        // Return immediately if already ready
+        if (storageInstance && initState === StorageInitState.READY) {
+            return storageInstance;
+        }
+        // Return existing promise if initializing
+        if (storagePromise && initState === StorageInitState.INITIALIZING) {
+            return storagePromise;
+        }
+        // If we're in error state, throw the error
+        if (initState === StorageInitState.ERROR && initError) {
+            throw initError;
+        }
+        // Start initialization
+        if (initState === StorageInitState.NOT_STARTED) {
+            initState = StorageInitState.INITIALIZING;
+            initError = null;
+            storagePromise = createMMKVStorage(identifier)
+                .then((storage) => {
+                storageInstance = storage;
+                initState = StorageInitState.READY;
+                initError = null;
+                // Process all pending operations
+                processPendingOperations(storage);
+                return storage;
+            })
+                .catch((error) => {
+                const err = error instanceof Error ? error : new Error(String(error));
+                initState = StorageInitState.ERROR;
+                initError = err;
+                storagePromise = null;
+                // Reject all pending operations
+                const operations = [...pendingOperations];
+                pendingOperations.length = 0;
+                for (const op of operations) {
+                    op.reject(err);
+                }
+                throw err;
+            });
+        }
+        // At this point, storagePromise should be set
+        if (!storagePromise) {
+            const err = new Error('Failed to initialize storage: promise not created');
+            initState = StorageInitState.ERROR;
+            initError = err;
+            throw err;
+        }
+        return storagePromise;
+    };
+    // Start initialization immediately in the background
+    // This helps reduce the window where operations need to be queued
+    ensureStorage().catch((error) => {
+        // Error is stored in initError and will be thrown on next access
+        // This prevents unhandled promise rejections
+    });
+    const adapter = {
+        getItem: (name) => {
+            // If storage is ready, read directly
+            if (storageInstance && initState === StorageInitState.READY) {
+                try {
+                    const value = storageInstance.getString(name);
+                    return value ?? null;
+                }
+                catch (error) {
+                    // If read fails, return null (Zustand will handle gracefully)
+                    return null;
+                }
+            }
+            // If we're in error state, return null (Zustand will handle gracefully)
+            // The error will be thrown on next write operation
+            if (initState === StorageInitState.ERROR) {
+                return null;
+            }
+            // LIMITATION: During initialization, we cannot return values synchronously
+            // because storage initialization is async. Zustand's StorageAdapter interface
+            // requires synchronous getItem, so we must return null during initialization.
+            // 
+            // This is expected behavior:
+            // - On first load during initialization: returns null, Zustand uses default state
+            // - After initialization: subsequent getItem calls will work correctly
+            // - Zustand handles null gracefully and will rehydrate on next read after init
+            //
+            // We don't queue get operations because we can't fulfill them synchronously.
+            // Instead, we ensure storage is initializing and return null immediately.
+            ensureStorage().catch(() => {
+                // Errors are handled in ensureStorage and stored in initError
+            });
+            // Return null during initialization - Zustand handles this gracefully
+            // The actual value will be available on next read after initialization completes
+            return null;
+        },
+        setItem: (name, value) => {
+            // If storage is ready, write directly
+            if (storageInstance && initState === StorageInitState.READY) {
+                try {
+                    storageInstance.set(name, value);
+                    return;
+                }
+                catch (error) {
+                    // If write fails, queue it to retry later
+                    // This handles edge cases where storage becomes unavailable
+                }
+            }
+            // Queue the write operation
+            pendingOperations.push({
+                type: 'set',
+                key: name,
+                value,
+                resolve: () => {
+                    // Operation completed successfully
+                },
+                reject: (error) => {
+                    // Log error but don't throw - this is non-critical data
+                    // In production, you might want to log this to error tracking
+                    logWarn('[MMKVStorageAdapter] Failed to set item:', name, error);
+                },
+            });
+            // Ensure storage is initializing
+            ensureStorage().catch((error) => {
+                // Error is stored and will be thrown when processing pending operations
+                // This ensures queued operations fail appropriately
+            });
+        },
+        removeItem: (name) => {
+            // If storage is ready, delete directly
+            if (storageInstance && initState === StorageInitState.READY) {
+                try {
+                    ;
+                    storageInstance.delete(name);
+                    return;
+                }
+                catch (error) {
+                    // If delete fails, queue it to retry later
+                }
+            }
+            // Queue the delete operation
+            pendingOperations.push({
+                type: 'remove',
+                key: name,
+                resolve: () => {
+                    // Operation completed successfully
+                },
+                reject: (error) => {
+                    // Log error but don't throw - this is non-critical data
+                    logWarn('[MMKVStorageAdapter] Failed to remove item:', name, error);
+                },
+            });
+            // Ensure storage is initializing
+            ensureStorage().catch((error) => {
+                // Error is stored and will be thrown when processing pending operations
+            });
+        },
+    };
+    // Cache the adapter
+    adapterAccessCounter++;
+    adapterCache.set(identifier, adapter);
+    adapterAccessOrder.set(identifier, adapterAccessCounter);
+    return adapter;
+}
+//# sourceMappingURL=mmkvStorage.js.map

package/dist/storage/mmkvStorage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mmkvStorage.js","sourceRoot":"","sources":["../../src/storage/mmkvStorage.ts"],"names":[],"mappings":"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"}

package/dist/store/walletStore.d.ts

@@ -0,0 +1,130 @@
+/**
+ * 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
+ */
+import { create } from 'zustand';
+import type { WalletAddressesByWallet, WalletBalancesByWallet, BalanceLoadingStates } from '../types';
+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 {
+    addresses: WalletAddressesByWallet;
+    walletLoading: Record<string, WalletLoadingStates>;
+    balances: WalletBalancesByWallet;
+    balanceLoading: Record<string, BalanceLoadingStates>;
+    lastBalanceUpdate: Record<string, Record<string, Record<number, number>>>;
+    accountList: Record<string, AccountInfo[]>;
+    walletList: WalletInfo[];
+    activeWalletId: string | null;
+    walletLoadingState: WalletLoadingState;
+    isOperationInProgress: boolean;
+    currentOperation: string | null;
+}
+export type WalletStore = WalletState;
+type WalletStoreInstance = ReturnType<ReturnType<typeof create<WalletStore>>>;
+/**
+ * Creates singleton wallet store instance.
+ * All operations are handled by focused services (AddressService, BalanceService), not the store itself.
+ */
+export declare function createWalletStore(): WalletStoreInstance;
+export declare function getWalletStore(): import("zustand").UseBoundStore<import("zustand").StoreApi<WalletState>>;
+/**
+ * Update wallet loading state with validation
+ * Throws error if transition is invalid
+ * Logs state transitions for debugging
+ */
+export declare function updateWalletLoadingState(state: WalletState, newState: WalletLoadingState): Partial<WalletState>;
+/**
+ * Get wallet identifier from loading state
+ */
+export declare function getWalletIdFromLoadingState(state: WalletLoadingState): string | null;
+/**
+ * Check if wallet is in a loading state
+ */
+export declare function isWalletLoadingState(state: WalletLoadingState): boolean;
+/**
+ * Check if wallet is ready
+ */
+export declare function isWalletReadyState(state: WalletLoadingState): boolean;
+/**
+ * Check if wallet is in error state
+ */
+export declare function isWalletErrorState(state: WalletLoadingState): boolean;
+export {};