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

package/src/services/accountService.ts

@@ -0,0 +1,134 @@
+/**
+ * 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<T = unknown>(
+    network: string,
+    accountIndex: number,
+    methodName: string,
+    args?: unknown,
+    walletId?: string
+  ): Promise<T> {
+    // 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: string | null = 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: T
+      try {
+        parsed = JSON.parse(validatedResponse.result) as T
+        // 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) as T
+    } catch (error) {
+      handleServiceError(error, 'AccountService', `callAccountMethod:${methodName}`, {
+        network,
+        accountIndex,
+        methodName,
+      })
+    }
+  }
+}
+

package/src/services/addressService.ts

@@ -0,0 +1,125 @@
+/**
+ * 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: string,
+    accountIndex = 0,
+    walletId?: string
+  ): Promise<string> {
+    // 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: string
+      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 })
+    }
+  }
+}
+

package/src/services/balanceService.ts

@@ -0,0 +1,291 @@
+/**
+ * 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
+   */
+  private static validateBalanceParams(
+    network: string,
+    accountIndex: number,
+    tokenAddress?: string | null,
+    balance?: string
+  ): void {
+    validateWalletParams(network, accountIndex, tokenAddress)
+    if (balance !== undefined) {
+      validateBalance(balance)
+    }
+  }
+
+  /**
+   * Get token key from token address (native or token address)
+   */
+  private static getTokenKey(tokenAddress: string | null): string {
+    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: number,
+    network: string,
+    tokenAddress: string | null,
+    balance: string,
+    walletId?: string
+  ): void {
+    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: number,
+    network: string,
+    tokenAddress: string | null,
+    walletId?: string
+  ): string | null {
+    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: number,
+    network: string,
+    walletId?: string
+  ): Record<string, string> | null {
+    // 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: string,
+    accountIndex: number,
+    tokenAddress: string | null,
+    loading: boolean,
+    walletId?: string
+  ): void {
+    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: string,
+    accountIndex: number,
+    tokenAddress: string | null,
+    walletId?: string
+  ): boolean {
+    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: string,
+    accountIndex: number,
+    walletId?: string
+  ): void {
+    // 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: string,
+    accountIndex: number,
+    walletId?: string
+  ): number | null {
+    // 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(): void {
+    const walletStore = getWalletStore()
+    
+    walletStore.setState({
+      balances: {},
+      balanceLoading: {},
+      lastBalanceUpdate: {},
+    })
+  }
+}
+
+