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

package/dist/services/accountService.js

@@ -0,0 +1,119 @@
+/**
+ * Account Service
+ *
+ * Handles account method calls through the worklet.
+ * This service provides a generic interface for calling account methods
+ * like getBalance, getTokenBalance, signMessage, signTransaction, etc.
+ */
+import { convertBigIntToString } from '../utils/balanceUtils';
+import { handleServiceError } from '../utils/errorHandling';
+import { safeStringify } from '../utils/jsonUtils';
+import { workletResponseSchema } from '../utils/schemas';
+import { requireInitialized } from '../utils/storeHelpers';
+import { validateAccountIndex, validateNetworkName } from '../utils/validation';
+/**
+ * Account Service
+ *
+ * Provides methods for calling account operations through the worklet.
+ */
+export class AccountService {
+    /**
+     * Call a method on a wallet account
+     * Generic method for calling any account method through the worklet
+     *
+     * The worklet should already have the correct wallet loaded via `initializeWDK`.
+     * Wallet switching is handled at the hook level before calling this service.
+     *
+     * @param network - Network name
+     * @param accountIndex - Account index
+     * @param methodName - Method name
+     * @param args - Optional arguments for the method
+     * @param walletId - Optional wallet identifier (for consistency, worklet should already have correct wallet loaded)
+     * @returns Promise with the method result
+     * @throws Error if validation fails
+     *
+     * @example
+     * ```typescript
+     * // Get balance
+     * const balance = await AccountService.callAccountMethod('ethereum', 0, 'getBalance', null)
+     *
+     * // Get token balance
+     * const tokenBalance = await AccountService.callAccountMethod(
+     *   'ethereum',
+     *   0,
+     *   'getTokenBalance',
+     *   '0x...'
+     * )
+     *
+     * // Sign a message
+     * const signature = await AccountService.callAccountMethod(
+     *   'ethereum',
+     *   0,
+     *   'signMessage',
+     *   { message: 'Hello World' }
+     * )
+     * ```
+     */
+    static async callAccountMethod(network, accountIndex, methodName, args, walletId) {
+        // Validate methodName parameter
+        if (typeof methodName !== 'string' || methodName.trim().length === 0) {
+            throw new Error('methodName must be a non-empty string');
+        }
+        // Validate inputs
+        validateNetworkName(network);
+        validateAccountIndex(accountIndex);
+        // Require initialized worklet
+        const hrpc = requireInitialized();
+        // Validate and sanitize args before stringification
+        let argsString = null;
+        if (args !== undefined && args !== null) {
+            // Validate structure and stringify safely
+            argsString = safeStringify(args);
+        }
+        try {
+            const response = await hrpc.callMethod({
+                methodName,
+                network,
+                accountIndex,
+                args: argsString,
+            });
+            // Validate response structure
+            const validatedResponse = workletResponseSchema.parse(response);
+            if (!validatedResponse.result) {
+                throw new Error(`Method ${methodName} returned no result`);
+            }
+            // Parse the result and handle BigInt values
+            let parsed;
+            try {
+                parsed = JSON.parse(validatedResponse.result);
+                // Basic validation: ensure parsed is not null/undefined
+                if (parsed === null || parsed === undefined) {
+                    throw new Error('Parsed result is null or undefined');
+                }
+            }
+            catch (error) {
+                if (error instanceof Error && error.message.includes('Parsed result is null')) {
+                    throw error;
+                }
+                throw new Error(`Failed to parse result from ${methodName}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            // Runtime type validation based on method type
+            if (methodName === 'getBalance' || methodName === 'getTokenBalance') {
+                // Validate balance format
+                if (typeof parsed !== 'string' || !/^\d+$/.test(parsed)) {
+                    throw new Error(`Invalid balance format: ${parsed}`);
+                }
+            }
+            // Recursively convert BigInt values to strings to prevent serialization errors
+            return convertBigIntToString(parsed);
+        }
+        catch (error) {
+            handleServiceError(error, 'AccountService', `callAccountMethod:${methodName}`, {
+                network,
+                accountIndex,
+                methodName,
+            });
+        }
+    }
+}
+//# sourceMappingURL=accountService.js.map

package/dist/services/accountService.js.map

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

package/dist/services/addressService.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Address Service
+ *
+ * Handles address retrieval and caching operations.
+ * This service is focused solely on address management.
+ */
+/**
+ * Address Service
+ *
+ * Provides methods for retrieving and caching wallet addresses.
+ */
+export declare class AddressService {
+    /**
+     * Get address for a specific network and account index
+     * Caches the address in walletStore for future use
+     *
+     * @param network - Network name
+     * @param accountIndex - Account index (default: 0)
+     * @param walletId - Optional wallet identifier (defaults to activeWalletId from store)
+     */
+    static getAddress(network: string, accountIndex?: number, walletId?: string): Promise<string>;
+}

package/dist/services/addressService.js

@@ -0,0 +1,110 @@
+/**
+ * Address Service
+ *
+ * Handles address retrieval and caching operations.
+ * This service is focused solely on address management.
+ */
+import { getWalletStore } from '../store/walletStore';
+import { handleServiceError } from '../utils/errorHandling';
+import { requireInitialized, resolveWalletId, updateAddressInState } from '../utils/storeHelpers';
+import { isValidAddress } from '../utils/typeGuards';
+import { validateAccountIndex, validateNetworkName } from '../utils/validation';
+/**
+ * Address Service
+ *
+ * Provides methods for retrieving and caching wallet addresses.
+ */
+export class AddressService {
+    /**
+     * Get address for a specific network and account index
+     * Caches the address in walletStore for future use
+     *
+     * @param network - Network name
+     * @param accountIndex - Account index (default: 0)
+     * @param walletId - Optional wallet identifier (defaults to activeWalletId from store)
+     */
+    static async getAddress(network, accountIndex = 0, walletId) {
+        // Validate inputs
+        validateNetworkName(network);
+        validateAccountIndex(accountIndex);
+        const walletStore = getWalletStore();
+        const walletState = walletStore.getState();
+        // Resolve walletId from parameter or store
+        const targetWalletId = resolveWalletId(walletId);
+        // Check cache first (per-wallet)
+        const cachedAddress = walletState.addresses[targetWalletId]?.[network]?.[accountIndex];
+        if (cachedAddress) {
+            // Validate cached address format
+            if (!isValidAddress(cachedAddress)) {
+                throw new Error(`Cached address for ${targetWalletId}:${network}:${accountIndex} has invalid format`);
+            }
+            return cachedAddress;
+        }
+        // Require initialized worklet
+        const hrpc = requireInitialized();
+        const loadingKey = `${network}-${accountIndex}`;
+        try {
+            // Update loading state (per-wallet)
+            walletStore.setState((prev) => ({
+                walletLoading: {
+                    ...prev.walletLoading,
+                    [targetWalletId]: {
+                        ...(prev.walletLoading[targetWalletId] || {}),
+                        [loadingKey]: true,
+                    },
+                },
+            }));
+            // Call getAddress method on the account
+            const response = await hrpc.callMethod({
+                methodName: 'getAddress',
+                network,
+                accountIndex,
+                args: null,
+            });
+            if (!response.result) {
+                throw new Error('Failed to get address from worklet');
+            }
+            let address;
+            try {
+                const parsed = JSON.parse(response.result);
+                if (typeof parsed !== 'string') {
+                    throw new Error('Address must be a string');
+                }
+                // Runtime validation of address format
+                if (!isValidAddress(parsed)) {
+                    throw new Error(`Address from worklet has invalid format: ${parsed}`);
+                }
+                address = parsed;
+            }
+            catch (error) {
+                throw new Error(`Failed to parse address from worklet response: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            // Cache the address using helper (per-wallet)
+            walletStore.setState((prev) => ({
+                ...updateAddressInState(prev, targetWalletId, network, accountIndex, address),
+                walletLoading: {
+                    ...prev.walletLoading,
+                    [targetWalletId]: {
+                        ...(prev.walletLoading[targetWalletId] || {}),
+                        [loadingKey]: false,
+                    },
+                },
+            }));
+            return address;
+        }
+        catch (error) {
+            // Update loading state on error (per-wallet)
+            walletStore.setState((prev) => ({
+                walletLoading: {
+                    ...prev.walletLoading,
+                    [targetWalletId]: {
+                        ...(prev.walletLoading[targetWalletId] || {}),
+                        [loadingKey]: false,
+                    },
+                },
+            }));
+            handleServiceError(error, 'AddressService', 'getAddress', { network, accountIndex, walletId: targetWalletId });
+        }
+    }
+}
+//# sourceMappingURL=addressService.js.map

package/dist/services/addressService.js.map

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

package/dist/services/balanceService.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Balance Service
+ *
+ * Handles balance operations: getting, setting, updating, and managing balance state.
+ * This service is focused solely on balance management.
+ *
+ * ## Storage Strategy - Single Source of Truth
+ *
+ * This service manages balances in the Zustand store (walletStore.balances), which is
+ * the **single source of truth** for all balance data.
+ *
+ * **Architecture**:
+ * - **Zustand Store (Single Source of Truth)**: Stores and persists balances across app restarts (via MMKV)
+ * - **TanStack Query (Fetching Layer)**: Handles fetching, caching, and refetching (reads from and updates Zustand)
+ *
+ * **Data Flow**:
+ * 1. TanStack Query reads initial data from Zustand (via `initialData` in useBalance hooks)
+ * 2. TanStack Query fetches fresh balance from worklet when needed
+ * 3. After successful fetch, TanStack Query updates Zustand via this service (single source of truth update)
+ * 4. Components read from TanStack Query, which ensures consistency with Zustand
+ *
+ * **Sync Guarantees**:
+ * - Zustand is always the source of truth - all reads and writes go through Zustand
+ * - TanStack Query updates Zustand directly after fetch (no separate sync step)
+ * - Initial data consistency - TanStack Query uses Zustand's persisted data on app start
+ * - No race conditions - all updates are atomic through Zustand
+ *
+ * **Usage**:
+ * - Direct access: Use `BalanceService.getBalance()` to read from Zustand directly (rare, prefer TanStack Query hooks)
+ * - Updates: TanStack Query calls `BalanceService.updateBalance()` after fetch (automatic)
+ * - Preferred: Use `useBalance()` hooks which handle Zustand integration automatically
+ */
+/**
+ * Balance Service
+ *
+ * Provides methods for managing wallet balances.
+ */
+export declare class BalanceService {
+    /**
+     * Validate wallet parameters and balance (if provided)
+     * Helper to reduce repetitive validation calls
+     */
+    private static validateBalanceParams;
+    /**
+     * Get token key from token address (native or token address)
+     */
+    private static getTokenKey;
+    /**
+     * Update balance for a specific wallet, network, and token
+     *
+     * @param accountIndex - Account index
+     * @param network - Network name
+     * @param tokenAddress - Token address (null for native)
+     * @param balance - Balance value
+     * @param walletId - Optional wallet identifier (defaults to activeWalletId from store)
+     */
+    static updateBalance(accountIndex: number, network: string, tokenAddress: string | null, balance: string, walletId?: string): void;
+    /**
+     * Get balance for a specific wallet, network, and token
+     *
+     * @param accountIndex - Account index
+     * @param network - Network name
+     * @param tokenAddress - Token address (null for native)
+     * @param walletId - Optional wallet identifier (defaults to activeWalletId from store)
+     */
+    static getBalance(accountIndex: number, network: string, tokenAddress: string | null, walletId?: string): string | null;
+    /**
+     * Get all balances for a specific wallet and network
+     *
+     * @param accountIndex - Account index
+     * @param network - Network name
+     * @param walletId - Optional wallet identifier (defaults to activeWalletId from store)
+     */
+    static getBalancesForWallet(accountIndex: number, network: string, walletId?: string): Record<string, string> | null;
+    /**
+     * Set balance loading state
+     *
+     * @param network - Network name
+     * @param accountIndex - Account index
+     * @param tokenAddress - Token address (null for native)
+     * @param loading - Loading state
+     * @param walletId - Optional wallet identifier (defaults to activeWalletId from store)
+     */
+    static setBalanceLoading(network: string, accountIndex: number, tokenAddress: string | null, loading: boolean, walletId?: string): void;
+    /**
+     * Check if balance is loading
+     *
+     * @param network - Network name
+     * @param accountIndex - Account index
+     * @param tokenAddress - Token address (null for native)
+     * @param walletId - Optional wallet identifier (defaults to activeWalletId from store)
+     */
+    static isBalanceLoading(network: string, accountIndex: number, tokenAddress: string | null, walletId?: string): boolean;
+    /**
+     * Update last balance update timestamp
+     *
+     * @param network - Network name
+     * @param accountIndex - Account index
+     * @param walletId - Optional wallet identifier (defaults to activeWalletId from store)
+     */
+    static updateLastBalanceUpdate(network: string, accountIndex: number, walletId?: string): void;
+    /**
+     * Get last balance update timestamp
+     *
+     * @param network - Network name
+     * @param accountIndex - Account index
+     * @param walletId - Optional wallet identifier (defaults to activeWalletId from store)
+     */
+    static getLastBalanceUpdate(network: string, accountIndex: number, walletId?: string): number | null;
+    /**
+     * Clear all balances (useful for wallet reset)
+     */
+    static clearBalances(): void;
+}

package/dist/services/balanceService.js

@@ -0,0 +1,208 @@
+/**
+ * Balance Service
+ *
+ * Handles balance operations: getting, setting, updating, and managing balance state.
+ * This service is focused solely on balance management.
+ *
+ * ## Storage Strategy - Single Source of Truth
+ *
+ * This service manages balances in the Zustand store (walletStore.balances), which is
+ * the **single source of truth** for all balance data.
+ *
+ * **Architecture**:
+ * - **Zustand Store (Single Source of Truth)**: Stores and persists balances across app restarts (via MMKV)
+ * - **TanStack Query (Fetching Layer)**: Handles fetching, caching, and refetching (reads from and updates Zustand)
+ *
+ * **Data Flow**:
+ * 1. TanStack Query reads initial data from Zustand (via `initialData` in useBalance hooks)
+ * 2. TanStack Query fetches fresh balance from worklet when needed
+ * 3. After successful fetch, TanStack Query updates Zustand via this service (single source of truth update)
+ * 4. Components read from TanStack Query, which ensures consistency with Zustand
+ *
+ * **Sync Guarantees**:
+ * - Zustand is always the source of truth - all reads and writes go through Zustand
+ * - TanStack Query updates Zustand directly after fetch (no separate sync step)
+ * - Initial data consistency - TanStack Query uses Zustand's persisted data on app start
+ * - No race conditions - all updates are atomic through Zustand
+ *
+ * **Usage**:
+ * - Direct access: Use `BalanceService.getBalance()` to read from Zustand directly (rare, prefer TanStack Query hooks)
+ * - Updates: TanStack Query calls `BalanceService.updateBalance()` after fetch (automatic)
+ * - Preferred: Use `useBalance()` hooks which handle Zustand integration automatically
+ */
+import { getWalletStore } from '../store/walletStore';
+import { resolveWalletId, updateBalanceInState, getNestedState } from '../utils/storeHelpers';
+import { NATIVE_TOKEN_KEY } from '../utils/constants';
+import { validateBalance, validateWalletParams } from '../utils/validation';
+/**
+ * Balance Service
+ *
+ * Provides methods for managing wallet balances.
+ */
+export class BalanceService {
+    /**
+     * Validate wallet parameters and balance (if provided)
+     * Helper to reduce repetitive validation calls
+     */
+    static validateBalanceParams(network, accountIndex, tokenAddress, balance) {
+        validateWalletParams(network, accountIndex, tokenAddress);
+        if (balance !== undefined) {
+            validateBalance(balance);
+        }
+    }
+    /**
+     * Get token key from token address (native or token address)
+     */
+    static getTokenKey(tokenAddress) {
+        return tokenAddress || NATIVE_TOKEN_KEY;
+    }
+    /**
+     * Update balance for a specific wallet, network, and token
+     *
+     * @param accountIndex - Account index
+     * @param network - Network name
+     * @param tokenAddress - Token address (null for native)
+     * @param balance - Balance value
+     * @param walletId - Optional wallet identifier (defaults to activeWalletId from store)
+     */
+    static updateBalance(accountIndex, network, tokenAddress, balance, walletId) {
+        this.validateBalanceParams(network, accountIndex, tokenAddress, balance);
+        const walletStore = getWalletStore();
+        const walletState = walletStore.getState();
+        const targetWalletId = resolveWalletId(walletId);
+        const tokenKey = this.getTokenKey(tokenAddress);
+        walletStore.setState((prev) => ({
+            ...updateBalanceInState(prev, targetWalletId, network, accountIndex, tokenKey, balance),
+        }));
+    }
+    /**
+     * Get balance for a specific wallet, network, and token
+     *
+     * @param accountIndex - Account index
+     * @param network - Network name
+     * @param tokenAddress - Token address (null for native)
+     * @param walletId - Optional wallet identifier (defaults to activeWalletId from store)
+     */
+    static getBalance(accountIndex, network, tokenAddress, walletId) {
+        this.validateBalanceParams(network, accountIndex, tokenAddress);
+        const walletStore = getWalletStore();
+        const walletState = walletStore.getState();
+        const targetWalletId = resolveWalletId(walletId);
+        const tokenKey = this.getTokenKey(tokenAddress);
+        return getNestedState(walletState.balances, [targetWalletId, network, accountIndex, tokenKey], null);
+    }
+    /**
+     * Get all balances for a specific wallet and network
+     *
+     * @param accountIndex - Account index
+     * @param network - Network name
+     * @param walletId - Optional wallet identifier (defaults to activeWalletId from store)
+     */
+    static getBalancesForWallet(accountIndex, network, walletId) {
+        // Validate inputs
+        validateWalletParams(network, accountIndex);
+        const walletStore = getWalletStore();
+        const walletState = walletStore.getState();
+        const targetWalletId = resolveWalletId(walletId);
+        return getNestedState(walletState.balances, [targetWalletId, network, accountIndex], null);
+    }
+    /**
+     * Set balance loading state
+     *
+     * @param network - Network name
+     * @param accountIndex - Account index
+     * @param tokenAddress - Token address (null for native)
+     * @param loading - Loading state
+     * @param walletId - Optional wallet identifier (defaults to activeWalletId from store)
+     */
+    static setBalanceLoading(network, accountIndex, tokenAddress, loading, walletId) {
+        this.validateBalanceParams(network, accountIndex, tokenAddress);
+        const walletStore = getWalletStore();
+        const walletState = walletStore.getState();
+        const targetWalletId = resolveWalletId(walletId);
+        const tokenKey = this.getTokenKey(tokenAddress);
+        const loadingKey = `${network}-${accountIndex}-${tokenKey}`;
+        walletStore.setState((prev) => ({
+            balanceLoading: {
+                ...prev.balanceLoading,
+                [targetWalletId]: loading
+                    ? { ...(prev.balanceLoading[targetWalletId] || {}), [loadingKey]: true }
+                    : Object.fromEntries(Object.entries(prev.balanceLoading[targetWalletId] || {}).filter(([key]) => key !== loadingKey)),
+            },
+        }));
+    }
+    /**
+     * Check if balance is loading
+     *
+     * @param network - Network name
+     * @param accountIndex - Account index
+     * @param tokenAddress - Token address (null for native)
+     * @param walletId - Optional wallet identifier (defaults to activeWalletId from store)
+     */
+    static isBalanceLoading(network, accountIndex, tokenAddress, walletId) {
+        this.validateBalanceParams(network, accountIndex, tokenAddress);
+        const walletStore = getWalletStore();
+        const walletState = walletStore.getState();
+        const targetWalletId = walletId || walletState.activeWalletId;
+        if (!targetWalletId) {
+            return false;
+        }
+        const tokenKey = this.getTokenKey(tokenAddress);
+        const loadingKey = `${network}-${accountIndex}-${tokenKey}`;
+        return getNestedState(walletState.balanceLoading, [targetWalletId, loadingKey], false);
+    }
+    /**
+     * Update last balance update timestamp
+     *
+     * @param network - Network name
+     * @param accountIndex - Account index
+     * @param walletId - Optional wallet identifier (defaults to activeWalletId from store)
+     */
+    static updateLastBalanceUpdate(network, accountIndex, walletId) {
+        // Validate inputs
+        validateWalletParams(network, accountIndex);
+        const walletStore = getWalletStore();
+        const walletState = walletStore.getState();
+        const targetWalletId = resolveWalletId(walletId);
+        const now = Date.now();
+        walletStore.setState((prev) => ({
+            lastBalanceUpdate: {
+                ...prev.lastBalanceUpdate,
+                [targetWalletId]: {
+                    ...(prev.lastBalanceUpdate[targetWalletId] || {}),
+                    [network]: {
+                        ...(prev.lastBalanceUpdate[targetWalletId]?.[network] || {}),
+                        [accountIndex]: now,
+                    },
+                },
+            },
+        }));
+    }
+    /**
+     * Get last balance update timestamp
+     *
+     * @param network - Network name
+     * @param accountIndex - Account index
+     * @param walletId - Optional wallet identifier (defaults to activeWalletId from store)
+     */
+    static getLastBalanceUpdate(network, accountIndex, walletId) {
+        // Validate inputs
+        validateWalletParams(network, accountIndex);
+        const walletStore = getWalletStore();
+        const walletState = walletStore.getState();
+        const targetWalletId = resolveWalletId(walletId);
+        return getNestedState(walletState.lastBalanceUpdate, [targetWalletId, network, accountIndex], null);
+    }
+    /**
+     * Clear all balances (useful for wallet reset)
+     */
+    static clearBalances() {
+        const walletStore = getWalletStore();
+        walletStore.setState({
+            balances: {},
+            balanceLoading: {},
+            lastBalanceUpdate: {},
+        });
+    }
+}
+//# sourceMappingURL=balanceService.js.map

package/dist/services/balanceService.js.map

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