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

package/src/utils/validation.ts

@@ -0,0 +1,174 @@
+/**
+ * Validation utilities for WDK provider props and inputs
+ * 
+ * These functions throw errors for invalid inputs.
+ * Uses Zod schemas for validation with better error messages.
+ * For type guards (boolean returns), see typeGuards.ts
+ */
+
+import { z } from 'zod'
+import {
+  networkConfigsSchema,
+  tokenConfigsSchema,
+  accountIndexSchema,
+  networkNameSchema,
+  balanceStringSchema,
+  ethereumAddressSchema,
+} from './schemas'
+import type { NetworkConfigs, TokenConfigs } from '../types'
+
+/**
+ * Extract error message from Zod error
+ */
+function getZodErrorMessage(error: unknown): string {
+  if (error instanceof z.ZodError) {
+    // Get the first error message for simplicity
+    const firstIssue = error.issues[0]
+    if (firstIssue) {
+      return firstIssue.message
+    }
+    return 'Validation failed'
+  }
+  if (error instanceof Error) {
+    return error.message
+  }
+  return String(error)
+}
+
+/**
+ * Validate network configuration
+ */
+export function validateNetworkConfigs(networkConfigs: NetworkConfigs): void {
+  try {
+    networkConfigsSchema.parse(networkConfigs)
+  } catch (error) {
+    throw new Error(`Invalid networkConfigs: ${getZodErrorMessage(error)}`)
+  }
+}
+
+/**
+ * Validate token configuration
+ */
+export function validateTokenConfigs(tokenConfigs: TokenConfigs): void {
+  try {
+    tokenConfigsSchema.parse(tokenConfigs)
+  } catch (error) {
+    throw new Error(`Invalid tokenConfigs: ${getZodErrorMessage(error)}`)
+  }
+}
+
+/**
+ * Validate balance refresh interval
+ */
+export function validateBalanceRefreshInterval(interval: number | undefined): void {
+  if (interval !== undefined) {
+    if (typeof interval !== 'number') {
+      throw new Error('balanceRefreshInterval must be a number')
+    }
+    if (interval < 0) {
+      throw new Error('balanceRefreshInterval must be a non-negative number')
+    }
+    if (!Number.isFinite(interval)) {
+      throw new Error('balanceRefreshInterval must be a finite number')
+    }
+  }
+}
+
+/**
+ * Validate that an object has required methods
+ * 
+ * @param obj - Object to validate
+ * @param requiredMethods - Array of required method names
+ * @param objectName - Name of the object for error messages
+ */
+export function validateRequiredMethods(
+  obj: unknown,
+  requiredMethods: string[],
+  objectName: string
+): void {
+  if (!obj || typeof obj !== 'object') {
+    throw new Error(`${objectName} must be an object`)
+  }
+
+  for (const methodName of requiredMethods) {
+    if (typeof (obj as Record<string, unknown>)[methodName] !== 'function') {
+      throw new Error(`${objectName} must have a ${methodName} method`)
+    }
+  }
+}
+
+/**
+ * Validate account index
+ */
+export function validateAccountIndex(accountIndex: number): void {
+  try {
+    accountIndexSchema.parse(accountIndex)
+  } catch (error) {
+    const message = getZodErrorMessage(error)
+    throw new Error(`Invalid accountIndex: ${message}`)
+  }
+}
+
+/**
+ * Validate network name
+ */
+export function validateNetworkName(network: string): void {
+  try {
+    networkNameSchema.parse(network)
+  } catch (error) {
+    const message = getZodErrorMessage(error)
+    // Provide a fallback message if Zod error doesn't have a clear message
+    if (message === 'Validation failed' || !message) {
+      throw new Error('network must be a non-empty string containing only alphanumeric characters, hyphens, and underscores')
+    }
+    throw new Error(`Invalid network name: ${message}`)
+  }
+}
+
+/**
+ * Validate token address (can be null for native tokens)
+ */
+export function validateTokenAddress(tokenAddress: string | null): void {
+  if (tokenAddress === null) {
+    return
+  }
+  try {
+    ethereumAddressSchema.parse(tokenAddress)
+  } catch (error) {
+    const message = getZodErrorMessage(error)
+    throw new Error(`Invalid tokenAddress: ${message}`)
+  }
+}
+
+/**
+ * Validate balance string
+ */
+export function validateBalance(balance: string): void {
+  try {
+    balanceStringSchema.parse(balance)
+  } catch (error) {
+    const message = getZodErrorMessage(error)
+    throw new Error(`Invalid balance: ${message}`)
+  }
+}
+
+/**
+ * Validate wallet parameters (network, accountIndex, optional tokenAddress)
+ * Convenience function to validate common wallet operation parameters
+ * 
+ * @param network - Network name
+ * @param accountIndex - Account index
+ * @param tokenAddress - Optional token address (null for native tokens)
+ */
+export function validateWalletParams(
+  network: string,
+  accountIndex: number,
+  tokenAddress?: string | null
+): void {
+  validateNetworkName(network)
+  validateAccountIndex(accountIndex)
+  if (tokenAddress !== undefined) {
+    validateTokenAddress(tokenAddress)
+  }
+}
+

package/src/utils/walletStateHelpers.ts

@@ -0,0 +1,104 @@
+/**
+ * Wallet State Helper Functions
+ * 
+ * Pure functions that determine wallet state transition decisions.
+ * These helpers are used by WdkAppProvider for wallet state synchronization logic.
+ * 
+ * These functions are extracted for:
+ * - Readability: Complex state logic separated from component orchestration
+ * - Testability: Pure functions can be tested in isolation
+ * - Reusability: Can be used elsewhere if needed
+ * 
+ * Note: The effect that uses these functions must remain consolidated to prevent race conditions.
+ */
+
+import type { WalletLoadingState } from '../store/walletStore'
+import { isWalletLoadingState } from '../store/walletStore'
+
+/**
+ * Determine if wallet state should be reset to not_loaded
+ * This happens when activeWalletId is cleared (null)
+ * 
+ * @param activeWalletId - Currently active wallet identifier (null if none)
+ * @param walletLoadingState - Current wallet loading state
+ * @returns true if state should be reset to not_loaded
+ */
+export function shouldResetToNotLoaded(
+  activeWalletId: string | null,
+  walletLoadingState: WalletLoadingState
+): boolean {
+  return !activeWalletId && walletLoadingState.type !== 'not_loaded'
+}
+
+/**
+ * Determine wallet switch decision when activeWalletId changes
+ * Returns whether a switch should occur and whether the new wallet should be marked ready
+ * 
+ * @param currentWalletId - Wallet ID currently tracked in loading state
+ * @param activeWalletId - New active wallet ID
+ * @param hasAddresses - Whether the new wallet has addresses available
+ * @returns Object with shouldSwitch and shouldMarkReady flags
+ */
+export function getWalletSwitchDecision(
+  currentWalletId: string | null,
+  activeWalletId: string | null,
+  hasAddresses: boolean
+): { shouldSwitch: boolean; shouldMarkReady: boolean } {
+  if (currentWalletId !== activeWalletId) {
+    return { shouldSwitch: true, shouldMarkReady: hasAddresses }
+  }
+  return { shouldSwitch: false, shouldMarkReady: false }
+}
+
+/**
+ * Determine if wallet should be marked as ready
+ * This checks if wallet is in loading/checking state, addresses exist, and worklet is initialized with seed
+ * 
+ * Note: If addresses exist but state is not_loaded, we need to go through loading first.
+ * This is handled by useWalletManager.initializeWallet() or useOnboarding.
+ * 
+ * @param walletLoadingState - Current wallet loading state
+ * @param hasAddresses - Whether wallet has addresses available
+ * @param currentWalletId - Wallet ID currently tracked in loading state
+ * @param activeWalletId - Currently active wallet identifier
+ * @param isWorkletInitialized - Whether the worklet is initialized with wallet credentials (seed loaded)
+ * @returns true if wallet should be marked as ready
+ */
+export function shouldMarkWalletAsReady(
+  walletLoadingState: WalletLoadingState,
+  hasAddresses: boolean,
+  currentWalletId: string | null,
+  activeWalletId: string | null,
+  isWorkletInitialized: boolean
+): boolean {
+  // Only allow ready transition from loading/checking states
+  // AND worklet must be initialized with seed (not just addresses cached)
+  // If addresses exist but state is not_loaded, we need to go through loading first
+  // This is handled by useWalletManager.initializeWallet() or useOnboarding
+  if (isWalletLoadingState(walletLoadingState) && currentWalletId === activeWalletId && hasAddresses && isWorkletInitialized) {
+    return true
+  }
+  return false
+}
+
+/**
+ * Determine if an error should be handled for the current wallet
+ * Only handle errors if they're for the wallet we're currently tracking
+ * 
+ * @param walletManagerError - Error message from wallet manager (null if no error)
+ * @param currentWalletId - Wallet ID currently tracked in loading state
+ * @param activeWalletId - Currently active wallet identifier
+ * @param walletLoadingState - Current wallet loading state
+ * @returns true if error should be handled for current wallet
+ */
+export function shouldHandleError(
+  walletManagerError: string | null,
+  currentWalletId: string | null,
+  activeWalletId: string | null,
+  walletLoadingState: WalletLoadingState
+): boolean {
+  if (!walletManagerError) return false
+  // Only update error if we're tracking this wallet
+  return currentWalletId === activeWalletId || walletLoadingState.type === 'not_loaded'
+}
+

package/src/utils/walletUtils.ts

@@ -0,0 +1,107 @@
+/**
+ * Wallet Utilities
+ * 
+ * Helper functions for working with wallets and retrieving addresses from walletStore.
+ */
+
+import { AccountService } from '../services/accountService'
+import { getWalletStore } from '../store/walletStore'
+import { getWorkletStore } from '../store/workletStore'
+import type { WalletStore as WalletStoreType } from '../store/walletStore'
+import type { WalletStore } from '../types'
+
+/**
+ * Get addresses for a wallet from walletStore
+ * 
+ * This helper function retrieves addresses for a specific accountIndex from the walletStore.
+ * Addresses are stored in walletStore as: { [network]: { [accountIndex]: address } }
+ * This converts them to: { [network]: address } for a specific accountIndex
+ * 
+ * NOTE: walletStore is the ONLY place where addresses are actually stored.
+ * This function simply retrieves/looks up addresses from walletStore.
+ * 
+ * @param walletStore - The wallet store instance (Zustand store) - the source of truth for addresses
+ * @param accountIndex - The account index to get addresses for
+ * @returns Record of network -> address for the given accountIndex
+ */
+export function getWalletAddresses(
+  walletStore: { getState: () => WalletStoreType },
+  accountIndex: number
+): Record<string, string> {
+  const state = walletStore.getState()
+  const addresses: Record<string, string> = {}
+  
+  // Get active wallet ID or use all wallets
+  const activeWalletId = state.activeWalletId
+  
+  // Retrieve addresses for this accountIndex from walletStore
+  // state.addresses is WalletAddressesByWallet: { [walletId]: { [network]: { [accountIndex]: address } } }
+  if (activeWalletId && state.addresses[activeWalletId]) {
+    // Use active wallet if available
+    const walletAddresses = state.addresses[activeWalletId]
+    // walletAddresses is WalletAddresses: { [network]: { [accountIndex]: address } }
+    Object.entries(walletAddresses).forEach(([network, networkAddresses]) => {
+      if (networkAddresses && typeof networkAddresses === 'object') {
+        const address = networkAddresses[accountIndex]
+        if (address) {
+          addresses[network] = address
+        }
+      }
+    })
+  } else {
+    // Fallback: iterate over all wallets (for backward compatibility or when no active wallet)
+    Object.values(state.addresses).forEach((walletAddresses) => {
+      if (walletAddresses && typeof walletAddresses === 'object') {
+        // walletAddresses is WalletAddresses: { [network]: { [accountIndex]: address } }
+        Object.entries(walletAddresses).forEach(([network, networkAddresses]) => {
+          if (networkAddresses && typeof networkAddresses === 'object') {
+            const address = networkAddresses[accountIndex]
+            if (address) {
+              addresses[network] = address
+            }
+          }
+        })
+      }
+    })
+  }
+  
+  return addresses
+}
+
+/**
+ * Create a base wallet store that wraps the worklet and wallet stores
+ * 
+ * This provides the worklet methods (callAccountMethod, isWalletInitialized)
+ * and helper functions for retrieving addresses from walletStore.
+ * Apps should extend this with their own wallet metadata and balance management.
+ * 
+ * Always uses the default MMKV storage adapter.
+ * 
+ * @returns Base wallet store implementation
+ */
+export function createBaseWalletStore(): Pick<WalletStore, 'callAccountMethod' | 'isWalletInitialized'> & {
+  getWalletAddresses: (accountIndex: number) => Record<string, string>
+} {
+  const workletStore = getWorkletStore()
+  const walletStore = getWalletStore()
+  
+  return {
+    callAccountMethod: async <T = unknown>(
+      network: string,
+      accountIndex: number,
+      methodName: string,
+      args?: unknown
+    ): Promise<T> => {
+      return AccountService.callAccountMethod<T>(network, accountIndex, methodName, args)
+    },
+
+    isWalletInitialized: () => {
+      return workletStore.getState().isInitialized
+    },
+
+    getWalletAddresses: (accountIndex: number) => {
+      return getWalletAddresses(walletStore, accountIndex)
+    },
+  }
+}
+