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

package/src/types/hrpc.ts

@@ -0,0 +1,78 @@
+/**
+ * HRPC Type Extensions
+ * 
+ * Type definitions for HRPC methods that may not be in the @spacesops/pear-wrk-wdk types yet.
+ * These types extend the HRPC interface to provide proper type safety.
+ */
+
+import type { HRPC } from '@spacesops/pear-wrk-wdk'
+
+/**
+ * Extended HRPC interface with additional methods
+ */
+export interface ExtendedHRPC extends HRPC {
+  /**
+   * Initialize WDK with encrypted seed
+   */
+  initializeWDK: (options: {
+    encryptionKey: string
+    encryptedSeed: string
+    config: string
+  }) => Promise<{ status?: string | null }>
+
+  /**
+   * Generate entropy and encrypt it
+   */
+  generateEntropyAndEncrypt: (options: {
+    wordCount: number
+  }) => Promise<{
+    encryptionKey: string
+    encryptedSeedBuffer: string
+    encryptedEntropyBuffer: string
+  }>
+
+  /**
+   * Get mnemonic from encrypted entropy
+   */
+  getMnemonicFromEntropy: (options: {
+    encryptedEntropy: string
+    encryptionKey: string
+  }) => Promise<{
+    mnemonic: string
+  }>
+
+  /**
+   * Get seed and entropy from mnemonic phrase
+   */
+  getSeedAndEntropyFromMnemonic: (options: {
+    mnemonic: string
+  }) => Promise<{
+    encryptionKey: string
+    encryptedSeedBuffer: string
+    encryptedEntropyBuffer: string
+  }>
+}
+
+/**
+ * Type guard to check if HRPC instance has extended methods
+ */
+export function isExtendedHRPC(hrpc: HRPC): hrpc is ExtendedHRPC {
+  return (
+    typeof (hrpc as unknown as Record<string, unknown>).initializeWDK === 'function' &&
+    typeof (hrpc as unknown as Record<string, unknown>).generateEntropyAndEncrypt === 'function' &&
+    typeof (hrpc as unknown as Record<string, unknown>).getMnemonicFromEntropy === 'function' &&
+    typeof (hrpc as unknown as Record<string, unknown>).getSeedAndEntropyFromMnemonic === 'function'
+  )
+}
+
+/**
+ * Safely cast HRPC to ExtendedHRPC
+ * Throws if the HRPC instance doesn't have the required methods
+ */
+export function asExtendedHRPC(hrpc: HRPC): ExtendedHRPC {
+  if (!isExtendedHRPC(hrpc)) {
+    throw new Error('HRPC instance does not have required extended methods')
+  }
+  return hrpc
+}
+

package/src/types.ts

@@ -0,0 +1,188 @@
+/**
+ * Core Type Definitions
+ * 
+ * All network, token, and wallet type definitions for the WDK React Native Core library.
+ */
+
+/**
+ * Network Configuration
+ * 
+ * Defines the configuration for a blockchain network.
+ */
+export interface NetworkConfig {
+  /** Chain ID for the network */
+  chainId: number
+  /** Blockchain name (e.g., "ethereum", "polygon") */
+  blockchain: string
+  /** Optional RPC provider URL */
+  provider?: string
+  /** Optional bundler URL for account abstraction */
+  bundlerUrl?: string
+  /** Optional paymaster URL for account abstraction */
+  paymasterUrl?: string
+  /** Optional paymaster contract address */
+  paymasterAddress?: string
+  /** Optional entry point contract address */
+  entryPointAddress?: string
+  /** Optional maximum fee for transfers */
+  transferMaxFee?: number
+}
+
+/**
+ * Network Configurations
+ * 
+ * Maps network names to their configurations.
+ */
+export type NetworkConfigs = Record<string, NetworkConfig>
+
+/**
+ * Token Configuration
+ * 
+ * Defines the configuration for a token (native or ERC20).
+ */
+export interface TokenConfig {
+  /** Token symbol (e.g., "ETH", "USDT") */
+  symbol: string
+  /** Token name (e.g., "Ethereum", "Tether") */
+  name: string
+  /** Number of decimals (0-18) */
+  decimals: number
+  /** Token contract address (null for native tokens) */
+  address: string | null
+}
+
+/**
+ * Network Tokens
+ * 
+ * Defines the tokens available for a network (native + ERC20 tokens).
+ */
+export interface NetworkTokens {
+  /** Native token configuration */
+  native: TokenConfig
+  /** Array of ERC20 token configurations */
+  tokens: TokenConfig[]
+}
+
+/**
+ * Token Configurations
+ * 
+ * Maps network names to their token configurations.
+ */
+export type TokenConfigs = Record<string, NetworkTokens>
+
+/**
+ * Wallet
+ * 
+ * Represents a wallet instance with metadata.
+ */
+export interface Wallet {
+  /** Account index (0-based) */
+  accountIndex: number
+  /** Unique wallet identifier */
+  identifier: string
+  /** Wallet display name */
+  name: string
+  /** Timestamp when wallet was created */
+  createdAt: number
+  /** Timestamp when wallet was last updated */
+  updatedAt: number
+}
+
+/**
+ * Wallet Addresses
+ * 
+ * Maps network -> accountIndex -> address
+ * Structure: { [network]: { [accountIndex]: address } }
+ */
+export type WalletAddresses = Record<string, Record<number, string>>
+
+/**
+ * Wallet Addresses by Wallet Identifier
+ * 
+ * Maps walletId -> network -> accountIndex -> address
+ * Structure: { [walletId]: { [network]: { [accountIndex]: address } } }
+ */
+export type WalletAddressesByWallet = Record<string, WalletAddresses>
+
+/**
+ * Wallet Balances
+ * 
+ * Maps network -> accountIndex -> tokenAddress -> balance
+ * Structure: { [network]: { [accountIndex]: { [tokenAddress]: balance } } }
+ * Note: balance is stored as a string to handle BigInt values
+ */
+export type WalletBalances = Record<string, Record<number, Record<string, string>>>
+
+/**
+ * Wallet Balances by Wallet Identifier
+ * 
+ * Maps walletId -> network -> accountIndex -> tokenAddress -> balance
+ * Structure: { [walletId]: { [network]: { [accountIndex]: { [tokenAddress]: balance } } } }
+ */
+export type WalletBalancesByWallet = Record<string, WalletBalances>
+
+/**
+ * Balance Loading States
+ * 
+ * Maps "network-accountIndex-tokenAddress" -> boolean
+ * Used to track which balances are currently being fetched.
+ */
+export type BalanceLoadingStates = Record<string, boolean>
+
+/**
+ * Balance Fetch Result
+ * 
+ * Result of a balance fetch operation.
+ */
+export interface BalanceFetchResult {
+  /** Whether the fetch was successful */
+  success: boolean
+  /** Network name */
+  network: string
+  /** Account index */
+  accountIndex: number
+  /** Token address (null for native tokens) */
+  tokenAddress: string | null
+  /** Balance as a string (null if fetch failed) */
+  balance: string | null
+  /** Error message (only present if success is false) */
+  error?: string
+}
+
+/**
+ * Token Config Provider
+ * 
+ * Either a TokenConfigs object or a function that returns TokenConfigs.
+ * Allows for dynamic token configuration.
+ */
+export type TokenConfigProvider = TokenConfigs | (() => TokenConfigs)
+
+/**
+ * Token Helpers
+ * 
+ * Helper functions for working with token configurations.
+ */
+export interface TokenHelpers {
+  /** Get all tokens (native + ERC20) for a network */
+  getTokensForNetwork: (network: string) => TokenConfig[]
+  /** Get all supported network names */
+  getSupportedNetworks: () => string[]
+}
+
+/**
+ * Wallet Store Interface
+ * 
+ * Interface for wallet store implementations that provide account methods
+ * and wallet initialization status.
+ */
+export interface WalletStore {
+  /** Call a method on a wallet account */
+  callAccountMethod: <T = unknown>(
+    network: string,
+    accountIndex: number,
+    methodName: string,
+    args?: unknown
+  ) => Promise<T>
+  /** Check if the wallet is initialized */
+  isWalletInitialized: () => boolean
+}

package/src/utils/balanceUtils.ts

@@ -0,0 +1,96 @@
+/**
+ * Balance utility functions
+ */
+
+import { logError } from './logger'
+
+/**
+ * Convert a value to string, handling BigInt values
+ */
+export function convertBalanceToString(value: unknown): string {
+  if (typeof value === 'bigint') {
+    return value.toString()
+  }
+  if (typeof value === 'string') {
+    return value
+  }
+  if (typeof value === 'number') {
+    return value.toString()
+  }
+  // Fallback: try to convert to string
+  return String(value)
+}
+
+/**
+ * Recursively convert BigInt values to strings in objects/arrays
+ * Prevents serialization errors when BigInt values are present
+ * 
+ * @param value - Value that may contain BigInt values
+ * @returns Value with all BigInt values converted to strings
+ */
+export function convertBigIntToString(value: unknown): unknown {
+  if (typeof value === 'bigint') {
+    return value.toString()
+  }
+  if (Array.isArray(value)) {
+    return value.map(convertBigIntToString)
+  }
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, val]) => [key, convertBigIntToString(val)])
+    )
+  }
+  return value
+}
+
+/**
+ * Format a balance from wei/smallest unit to readable format
+ *
+ * @param balance - Balance as string (from wei/smallest unit)
+ * @param decimals - Number of decimals for the token (e.g., 18 for ETH, 6 for USDT)
+ * @returns Formatted balance string (e.g., "1.5" or "1000")
+ *
+ * @example
+ * ```ts
+ * formatBalance("1500000000000000000", 18) // "1.5"
+ * formatBalance("1000000", 6) // "1"
+ * formatBalance("1000001", 6) // "1.000001"
+ * ```
+ */
+export function formatBalance(balance: string | null, decimals: number): string {
+  if (!balance || balance === '0' || balance === 'null') {
+    return '0'
+  }
+  
+  // Validate that balance is a valid numeric string before attempting BigInt conversion
+  // BigInt accepts: digits only, or digits with optional leading minus sign
+  if (!/^-?\d+$/.test(balance.trim())) {
+    // Invalid format - return as-is (for backwards compatibility with test expectations)
+    return balance
+  }
+  
+  try {
+    const balanceBigInt = BigInt(balance)
+    const divisor = BigInt(10 ** decimals)
+    const wholePart = balanceBigInt / divisor
+    const fractionalPart = balanceBigInt % divisor
+
+    if (fractionalPart === BigInt(0)) {
+      return wholePart.toString()
+    }
+
+    // Format fractional part with leading zeros if needed
+    const fractionalStr = fractionalPart.toString().padStart(decimals, '0')
+    // Remove trailing zeros
+    const fractionalTrimmed = fractionalStr.replace(/0+$/, '')
+
+    if (fractionalTrimmed === '') {
+      return wholePart.toString()
+    }
+
+    return `${wholePart}.${fractionalTrimmed}`
+  } catch (error) {
+    logError('Error formatting balance:', error)
+    return balance
+  }
+}

package/src/utils/constants.ts

@@ -0,0 +1,84 @@
+/**
+ * Application constants
+ * 
+ * Centralized location for magic numbers and configuration values
+ * to improve maintainability and documentation.
+ */
+
+/**
+ * Default balance refresh interval in milliseconds
+ * 
+ * How often to automatically refresh wallet balances when auto-fetch is enabled.
+ * 30 seconds provides a good balance between freshness and performance.
+ */
+export const DEFAULT_BALANCE_REFRESH_INTERVAL_MS = 30000
+
+/**
+ * Valid mnemonic word counts
+ * 
+ * BIP-39 standard supports 12-word (128 bits) and 24-word (256 bits) mnemonics.
+ */
+export const MNEMONIC_WORD_COUNTS = {
+  /** 12-word mnemonic (128 bits of entropy) */
+  TWELVE: 12,
+  /** 24-word mnemonic (256 bits of entropy) */
+  TWENTY_FOUR: 24,
+} as const
+
+/**
+ * Default mnemonic word count
+ * 
+ * 12 words is the most common choice, providing 128 bits of entropy
+ * which is sufficient for most use cases.
+ */
+export const DEFAULT_MNEMONIC_WORD_COUNT = MNEMONIC_WORD_COUNTS.TWELVE
+
+/**
+ * Account method names for balance operations
+ */
+export const ACCOUNT_METHOD_GET_BALANCE = 'getBalance'
+export const ACCOUNT_METHOD_GET_TOKEN_BALANCE = 'getTokenBalance'
+
+/**
+ * Wallet identifier constants
+ */
+export const WALLET_IDENTIFIER_PREFIX = 'wallet-'
+export const MAIN_WALLET_NAME = 'Main Wallet'
+export const WALLET_NAME_PREFIX = 'Wallet '
+
+/**
+ * Token key for native tokens in balance storage
+ */
+export const NATIVE_TOKEN_KEY = 'native'
+
+/**
+ * Default query stale time in milliseconds
+ * 
+ * How long data is considered fresh before TanStack Query refetches it.
+ * 30 seconds provides a good balance between freshness and performance.
+ */
+export const DEFAULT_QUERY_STALE_TIME_MS = 30 * 1000
+
+/**
+ * Default query garbage collection time in milliseconds
+ * 
+ * How long unused query data is kept in cache before being garbage collected.
+ * 5 minutes provides a good balance between cache efficiency and memory usage.
+ */
+export const DEFAULT_QUERY_GC_TIME_MS = 5 * 60 * 1000
+
+/**
+ * Allowed account methods whitelist
+ * Only these methods can be called through AccountService for security
+ */
+export const ALLOWED_ACCOUNT_METHODS = [
+  'getAddress',
+  'getBalance',
+  'getTokenBalance',
+  'signMessage',
+  'signTransaction',
+  'sendTransaction',
+] as const
+
+export type AllowedAccountMethod = typeof ALLOWED_ACCOUNT_METHODS[number]
+

package/src/utils/errorHandling.md

@@ -0,0 +1,163 @@
+# Error Handling Guidelines
+
+This document outlines the standardized error handling patterns used across the wdk-react-native-core module.
+
+## Principles
+
+1. **Always normalize errors**: Use `normalizeError()` to convert any error-like value to a proper Error instance
+2. **Sanitize in production**: Always sanitize error messages in production to prevent information leakage
+3. **Provide context**: Include component and operation context when normalizing errors
+4. **Log before throwing**: Log errors before re-throwing them for debugging
+5. **Handle gracefully**: Don't crash the app - handle errors gracefully with user-friendly messages
+
+## Standard Pattern
+
+```typescript
+import { normalizeError } from '../utils/errorUtils'
+import { logError } from '../utils/logger'
+
+try {
+  // Operation that might fail
+  await someOperation()
+} catch (error) {
+  const normalizedError = normalizeError(error, true, {
+    component: 'ServiceName',
+    operation: 'operationName'
+  })
+  logError('[ServiceName] Failed to perform operation:', normalizedError)
+  throw normalizedError
+}
+```
+
+## Error Recovery Strategies
+
+### 1. Retryable Operations
+For operations that might fail due to transient issues (network, temporary unavailability):
+
+```typescript
+try {
+  await operation()
+} catch (error) {
+  // Log error
+  const normalizedError = normalizeError(error, true, { component: 'Service', operation: 'operation' })
+  logError('[Service] Operation failed:', normalizedError)
+  
+  // Store error for UI to display retry option
+  setError(normalizedError)
+  // Don't throw - allow user to retry
+}
+```
+
+### 2. Critical Operations
+For operations that must succeed (initialization, critical state changes):
+
+```typescript
+try {
+  await criticalOperation()
+} catch (error) {
+  const normalizedError = normalizeError(error, true, { component: 'Service', operation: 'criticalOperation' })
+  logError('[Service] Critical operation failed:', normalizedError)
+  // Throw to prevent proceeding with invalid state
+  throw normalizedError
+}
+```
+
+### 3. Non-Critical Operations
+For operations that can fail without breaking the app (caching, optional features):
+
+```typescript
+try {
+  await optionalOperation()
+} catch (error) {
+  // Log but don't throw - operation is optional
+  logWarn('[Service] Optional operation failed:', error)
+  // Continue execution
+}
+```
+
+## Error Context
+
+Always provide context when normalizing errors:
+
+```typescript
+normalizeError(error, true, {
+  component: 'ServiceName',      // Which component/service
+  operation: 'operationName',     // What operation was being performed
+  network?: string,              // Optional: which network
+  accountIndex?: number          // Optional: which account
+})
+```
+
+## Error Sanitization
+
+Error sanitization is handled automatically by `normalizeError()` when `sanitize` is `true` (default in production). This:
+- Removes sensitive data (keys, seeds, mnemonics)
+- Masks file paths
+- Preserves error type information
+- Allows detailed errors in development mode
+
+## Async Operations
+
+For async operations, always:
+1. Check abort signals if provided
+2. Handle cancellation gracefully
+3. Clean up resources on error
+
+```typescript
+async function operation(signal?: AbortSignal): Promise<void> {
+  if (signal?.aborted) {
+    throw new Error('Operation cancelled')
+  }
+
+  try {
+    await doWork()
+    
+    // Check again after async operation
+    if (signal?.aborted) {
+      throw new Error('Operation cancelled')
+    }
+  } catch (error) {
+    if (signal?.aborted) {
+      // Don't log cancellation errors
+      throw error
+    }
+    
+    const normalizedError = normalizeError(error, true, { component: 'Service', operation: 'operation' })
+    logError('[Service] Operation failed:', normalizedError)
+    throw normalizedError
+  }
+}
+```
+
+## Service-Specific Patterns
+
+### AddressService
+- Always validate inputs before operations
+- Throw errors for invalid addresses
+- Log all failures with network and account context
+
+### BalanceService
+- Non-critical operations can fail silently
+- Log warnings for balance fetch failures
+- Store errors in state for UI display
+
+### WorkletLifecycleService
+- Critical operations must throw
+- Log all failures with full context
+- Clean up resources on error
+
+### WalletSetupService
+- Require biometric authentication
+- Throw errors for authentication failures
+- Log all setup operations
+
+## Testing Error Handling
+
+When testing error handling:
+1. Test error normalization
+2. Test error sanitization
+3. Test error recovery
+4. Test error context preservation
+5. Test abort signal handling
+
+

package/src/utils/errorHandling.ts

@@ -0,0 +1,61 @@
+/**
+ * Error handling utilities for services
+ * 
+ * Provides consistent error handling patterns across all services
+ * to reduce code duplication and improve maintainability.
+ * 
+ * ## Usage Guidelines
+ * 
+ * **For Services**: Use `handleServiceError()` - this provides consistent normalization
+ * and logging for service-layer errors. Errors are NOT sanitized (sanitizeLevel: false)
+ * because services log internally and need full error details for debugging.
+ * 
+ * **For Hooks/UI**: Use `normalizeError()` directly with appropriate sanitization level.
+ * Hooks should sanitize errors before exposing them to UI components.
+ * 
+ * @example Service usage:
+ * ```typescript
+ * try {
+ *   await someOperation()
+ * } catch (error) {
+ *   handleServiceError(error, 'AddressService', 'getAddress', { network, accountIndex })
+ * }
+ * ```
+ * 
+ * @example Hook/UI usage:
+ * ```typescript
+ * try {
+ *   await someOperation()
+ * } catch (error) {
+ *   const normalized = normalizeError(error, true, { component: 'MyHook', operation: 'fetchData' })
+ *   setError(normalized.message)
+ * }
+ * ```
+ */
+
+import { normalizeError } from './errorUtils'
+import { logError } from './logger'
+
+/**
+ * Handle service errors with consistent normalization and logging
+ * 
+ * **Use this in services** - provides consistent error handling with full error details
+ * (no sanitization) for internal logging and debugging.
+ * 
+ * @param error - Error to handle
+ * @param component - Component/service name where error occurred
+ * @param operation - Operation name that failed
+ * @param context - Additional context for error
+ * @throws Normalized error
+ */
+export function handleServiceError(
+  error: unknown,
+  component: string,
+  operation: string,
+  context?: Record<string, unknown>
+): never {
+  const normalized = normalizeError(error, false, { component, operation, ...context })
+  logError(`[${component}] ${operation} failed:`, normalized)
+  throw normalized
+}
+