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

package/dist/services/walletSwitchingService.js

@@ -0,0 +1,143 @@
+/**
+ * Wallet Switching Service
+ *
+ * Handles wallet switching operations: checking wallet existence, loading credentials,
+ * and initializing WDK with the new wallet.
+ *
+ * Architecture:
+ * - This service is the single source of truth for wallet switching logic
+ * - Used by useWallet hook for automatic wallet switching
+ * - Can be used by other components that need to switch wallets programmatically
+ */
+import { WalletSetupService } from './walletSetupService';
+import { WorkletLifecycleService } from './workletLifecycleService';
+import { getWalletStore } from '../store/walletStore';
+import { updateWalletLoadingState, getWalletIdFromLoadingState } from '../store/walletStore';
+import { withOperationMutex } from '../utils/operationMutex';
+import { normalizeError } from '../utils/errorUtils';
+import { log, logError } from '../utils/logger';
+/**
+ * Wallet Switching Service
+ *
+ * Provides methods for switching between wallets.
+ */
+export class WalletSwitchingService {
+    /**
+     * Switch to a wallet by identifier
+     *
+     * This method:
+     * 1. Checks if the wallet exists (fail fast)
+     * 2. Ensures worklet is started
+     * 3. Loads credentials for the wallet
+     * 4. Initializes WDK with the credentials
+     * 5. Updates activeWalletId in the store
+     *
+     * @param walletId - Wallet identifier to switch to
+     * @param options - Optional configuration
+     * @param options.autoStartWorklet - If true, start worklet if not started (default: false)
+     * @throws Error if wallet doesn't exist or switching fails
+     *
+     * @example
+     * ```typescript
+     * await WalletSwitchingService.switchToWallet('user@example.com')
+     * ```
+     */
+    static async switchToWallet(walletId, options) {
+        return withOperationMutex(`switchToWallet:${walletId}`, async () => {
+            const walletStore = getWalletStore();
+            const activeWalletId = walletStore.getState().activeWalletId;
+            // Check if already on this wallet
+            if (activeWalletId === walletId) {
+                log('[WalletSwitchingService] Already on wallet', { walletId });
+                return;
+            }
+            try {
+                // Update loading state
+                walletStore.setState((prev) => updateWalletLoadingState(prev, {
+                    type: 'loading',
+                    identifier: walletId,
+                    walletExists: true,
+                }));
+                // Check if wallet exists first (fail fast)
+                const walletExists = await WalletSetupService.hasWallet(walletId);
+                if (!walletExists) {
+                    throw new Error(`Wallet with identifier "${walletId}" does not exist`);
+                }
+                // Ensure worklet is started
+                await WorkletLifecycleService.ensureWorkletStarted(undefined, {
+                    autoStart: options?.autoStartWorklet ?? false,
+                });
+                // Note: We don't clear previous wallet's credentials cache when switching
+                // The LRU eviction policy in workletStore will handle cache management
+                // This allows users to switch back to recently used wallets without re-authentication
+                if (activeWalletId !== null && activeWalletId !== walletId) {
+                    log('[WalletSwitchingService] Switching wallets', {
+                        from: activeWalletId,
+                        to: walletId,
+                    });
+                    // Cache is managed by LRU eviction - no need to clear here
+                }
+                // Load credentials for the wallet
+                const credentials = await WalletSetupService.loadExistingWallet(walletId);
+                // Switch worklet to this wallet
+                await WorkletLifecycleService.initializeWDK({
+                    encryptionKey: credentials.encryptionKey,
+                    encryptedSeed: credentials.encryptedSeed,
+                });
+                // Update activeWalletId in store and mark as ready
+                walletStore.setState((prev) => ({
+                    ...updateWalletLoadingState(prev, {
+                        type: 'ready',
+                        identifier: walletId,
+                    }),
+                    activeWalletId: walletId,
+                }));
+                log('[WalletSwitchingService] Successfully switched to wallet', { walletId });
+            }
+            catch (error) {
+                // Cleanup state on error
+                const normalizedError = normalizeError(error, false, {
+                    component: 'WalletSwitchingService',
+                    operation: 'switchToWallet',
+                    walletId,
+                });
+                logError('[WalletSwitchingService] Failed to switch wallet, cleaning up state', normalizedError);
+                walletStore.setState((prev) => {
+                    const currentWalletId = getWalletIdFromLoadingState(prev.walletLoadingState);
+                    // Only update error state if we were loading this wallet
+                    if (currentWalletId === walletId || prev.walletLoadingState.type === 'loading') {
+                        return updateWalletLoadingState(prev, {
+                            type: 'error',
+                            identifier: walletId,
+                            error: normalizedError,
+                        });
+                    }
+                    return prev;
+                });
+                throw normalizedError;
+            }
+        });
+    }
+    /**
+     * Check if a wallet can be switched to
+     *
+     * @param walletId - Wallet identifier to check
+     * @returns Promise resolving to true if wallet exists and can be switched to
+     */
+    static async canSwitchToWallet(walletId) {
+        try {
+            return await WalletSetupService.hasWallet(walletId);
+        }
+        catch (error) {
+            // Log error but don't throw - this is a non-critical check
+            const normalizedError = normalizeError(error, false, {
+                component: 'WalletSwitchingService',
+                operation: 'canSwitchToWallet',
+                walletId,
+            });
+            logError('[WalletSwitchingService] Failed to check wallet:', normalizedError);
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=walletSwitchingService.js.map

package/dist/services/walletSwitchingService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walletSwitchingService.js","sourceRoot":"","sources":["../../src/services/walletSwitchingService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AACzD,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAA;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AACrD,OAAO,EAAE,wBAAwB,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAA;AAC5F,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAE/C;;;;GAIG;AACH,MAAM,OAAO,sBAAsB;IACjC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,KAAK,CAAC,cAAc,CACzB,QAAgB,EAChB,OAAwC;QAExC,OAAO,kBAAkB,CAAC,kBAAkB,QAAQ,EAAE,EAAE,KAAK,IAAI,EAAE;YACjE,MAAM,WAAW,GAAG,cAAc,EAAE,CAAA;YACpC,MAAM,cAAc,GAAG,WAAW,CAAC,QAAQ,EAAE,CAAC,cAAc,CAAA;YAE5D,kCAAkC;YAClC,IAAI,cAAc,KAAK,QAAQ,EAAE,CAAC;gBAChC,GAAG,CAAC,4CAA4C,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAA;gBAC/D,OAAM;YACR,CAAC;YAED,IAAI,CAAC;gBACH,uBAAuB;gBACvB,WAAW,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,wBAAwB,CAAC,IAAI,EAAE;oBAC5D,IAAI,EAAE,SAAS;oBACf,UAAU,EAAE,QAAQ;oBACpB,YAAY,EAAE,IAAI;iBACnB,CAAC,CAAC,CAAA;gBAEH,2CAA2C;gBAC3C,MAAM,YAAY,GAAG,MAAM,kBAAkB,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAA;gBACjE,IAAI,CAAC,YAAY,EAAE,CAAC;oBAClB,MAAM,IAAI,KAAK,CAAC,2BAA2B,QAAQ,kBAAkB,CAAC,CAAA;gBACxE,CAAC;gBAED,4BAA4B;gBAC5B,MAAM,uBAAuB,CAAC,oBAAoB,CAAC,SAAS,EAAE;oBAC5D,SAAS,EAAE,OAAO,EAAE,gBAAgB,IAAI,KAAK;iBAC9C,CAAC,CAAA;gBAEF,0EAA0E;gBAC1E,uEAAuE;gBACvE,sFAAsF;gBACtF,IAAI,cAAc,KAAK,IAAI,IAAI,cAAc,KAAK,QAAQ,EAAE,CAAC;oBAC3D,GAAG,CAAC,4CAA4C,EAAE;wBAChD,IAAI,EAAE,cAAc;wBACpB,EAAE,EAAE,QAAQ;qBACb,CAAC,CAAA;oBACF,2DAA2D;gBAC7D,CAAC;gBAED,kCAAkC;gBAClC,MAAM,WAAW,GAAG,MAAM,kBAAkB,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAA;gBAEzE,gCAAgC;gBAChC,MAAM,uBAAuB,CAAC,aAAa,CAAC;oBAC1C,aAAa,EAAE,WAAW,CAAC,aAAa;oBACxC,aAAa,EAAE,WAAW,CAAC,aAAa;iBACzC,CAAC,CAAA;gBAEF,mDAAmD;gBACnD,WAAW,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;oBAC9B,GAAG,wBAAwB,CAAC,IAAI,EAAE;wBAChC,IAAI,EAAE,OAAO;wBACb,UAAU,EAAE,QAAQ;qBACrB,CAAC;oBACF,cAAc,EAAE,QAAQ;iBACzB,CAAC,CAAC,CAAA;gBACH,GAAG,CAAC,0DAA0D,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAA;YAC/E,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,yBAAyB;gBACzB,MAAM,eAAe,GAAG,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE;oBACnD,SAAS,EAAE,wBAAwB;oBACnC,SAAS,EAAE,gBAAgB;oBAC3B,QAAQ;iBACT,CAAC,CAAA;gBACF,QAAQ,CAAC,qEAAqE,EAAE,eAAe,CAAC,CAAA;gBAEhG,WAAW,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,EAAE;oBAC5B,MAAM,eAAe,GAAG,2BAA2B,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAA;oBAC5E,yDAAyD;oBACzD,IAAI,eAAe,KAAK,QAAQ,IAAI,IAAI,CAAC,kBAAkB,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;wBAC/E,OAAO,wBAAwB,CAAC,IAAI,EAAE;4BACpC,IAAI,EAAE,OAAO;4BACb,UAAU,EAAE,QAAQ;4BACpB,KAAK,EAAE,eAAe;yBACvB,CAAC,CAAA;oBACJ,CAAC;oBACD,OAAO,IAAI,CAAA;gBACb,CAAC,CAAC,CAAA;gBAEF,MAAM,eAAe,CAAA;YACvB,CAAC;QACH,CAAC,CAAC,CAAA;IACJ,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,QAAgB;QAC7C,IAAI,CAAC;YACH,OAAO,MAAM,kBAAkB,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAA;QACrD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,2DAA2D;YAC3D,MAAM,eAAe,GAAG,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE;gBACnD,SAAS,EAAE,wBAAwB;gBACnC,SAAS,EAAE,mBAAmB;gBAC9B,QAAQ;aACT,CAAC,CAAA;YACF,QAAQ,CAAC,kDAAkD,EAAE,eAAe,CAAC,CAAA;YAC7E,OAAO,KAAK,CAAA;QACd,CAAC;IACH,CAAC;CACF"}

package/dist/services/workletLifecycleService.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Worklet Lifecycle Service
+ *
+ * Handles worklet lifecycle operations: starting, initializing, and cleaning up worklets.
+ * This service is focused solely on worklet lifecycle management.
+ */
+import type { NetworkConfigs } from '../types';
+/**
+ * Worklet Lifecycle Service
+ *
+ * Provides methods for managing worklet lifecycle: start, initialize, cleanup, reset.
+ */
+export declare class WorkletLifecycleService {
+    /**
+     * Cleanup a resource by trying cleanup methods in order
+     * Handles cleanup gracefully, continuing even if individual steps fail
+     */
+    private static cleanupResource;
+    /**
+     * Cleanup worklet resources (HRPC and Worklet instances)
+     * Handles cleanup gracefully, continuing even if individual steps fail
+     */
+    private static cleanupWorkletResources;
+    /**
+     * Start the worklet with network configurations
+     */
+    static startWorklet(networkConfigs: NetworkConfigs): Promise<void>;
+    /**
+     * Ensure worklet is started, starting it if needed
+     *
+     * @param networkConfigs - Network configs (required if autoStart=true)
+     * @param options - Options
+     * @param options.autoStart - If true, start worklet if not started (default: false)
+     * @throws Error if worklet not started and autoStart=false or networkConfigs not provided
+     */
+    static ensureWorkletStarted(networkConfigs?: NetworkConfigs, options?: {
+        autoStart?: boolean;
+    }): Promise<void>;
+    /**
+     * Initialize WDK with encrypted seed (ONLY encrypted approach)
+     */
+    static initializeWDK(options: {
+        encryptionKey: string;
+        encryptedSeed: string;
+    }): Promise<void>;
+    /**
+     * Generate entropy and encrypt (for creating new wallets)
+     */
+    static generateEntropyAndEncrypt(wordCount?: 12 | 24): Promise<{
+        encryptionKey: string;
+        encryptedSeedBuffer: string;
+        encryptedEntropyBuffer: string;
+    }>;
+    /**
+     * Get mnemonic from encrypted entropy (for display purposes only - never stored)
+     */
+    static getMnemonicFromEntropy(encryptedEntropy: string, encryptionKey: string): Promise<{
+        mnemonic: string;
+    }>;
+    /**
+     * Get seed and entropy from mnemonic phrase (for importing existing wallets)
+     */
+    static getSeedAndEntropyFromMnemonic(mnemonic: string): Promise<{
+        encryptionKey: string;
+        encryptedSeedBuffer: string;
+        encryptedEntropyBuffer: string;
+    }>;
+    /**
+     * Initialize both worklet and WDK in one call (convenience method) - ONLY encrypted
+     */
+    static initializeWorklet(options: {
+        encryptionKey: string;
+        encryptedSeed: string;
+        networkConfigs: NetworkConfigs;
+    }): Promise<void>;
+    /**
+     * Handle error for methods that throw with a message prefix
+     * Normalizes error, logs it, and throws a new error with operation context
+     */
+    private static handleAndThrowError;
+    /**
+     * Handle error for methods that update store state
+     * Normalizes error, updates store state, and re-throws
+     */
+    private static handleErrorWithStateUpdate;
+    /**
+     * Extract WDK initialization result status
+     * Safely extracts status from result object
+     */
+    private static extractWdkInitResult;
+    /**
+     * Reset both worklet and wallet stores
+     */
+    private static resetStores;
+    /**
+     * Cleanup worklet resources
+     * Clears only addresses, seed, and WDK instance - does NOT terminate the worklet
+     * The worklet continues running for faster re-initialization
+     */
+    static cleanup(): Promise<void>;
+    /**
+     * Reset worklet state (synchronous)
+     * Clears only addresses, seed, and WDK instance - does NOT terminate the worklet
+     * The worklet continues running for faster re-initialization
+     * For async cleanup, use cleanup() instead
+     */
+    static reset(): void;
+    /**
+     * Clear error state
+     */
+    static clearError(): void;
+    /**
+     * Check if wallet is initialized
+     * Returns true if worklet is started and WDK is initialized
+     */
+    static isInitialized(): boolean;
+}