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

package/README.md

@@ -0,0 +1,551 @@
+# @spacesops/wdk-react-native-core
+
+Core functionality for React Native wallets - wallet management, balance fetching, and worklet operations.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Installation](#installation)
+- [Core Concepts](#core-concepts)
+- [Usage Examples](#usage-examples)
+- [API Reference](#api-reference)
+- [Architecture](#architecture)
+- [Security](#security)
+- [Troubleshooting](#troubleshooting)
+- [Development](#development)
+
+## Quick Start
+
+```typescript
+import { WdkAppProvider, useWdkApp, useWallet, useBalance } from '@spacesops/wdk-react-native-core'
+import { createSecureStorage } from '@tetherto/wdk-react-native-secure-storage'
+
+function App() {
+  const secureStorage = createSecureStorage()
+  const networkConfigs = {
+    ethereum: { chainId: 1, blockchain: 'ethereum' }
+  }
+  const tokenConfigs = {
+    ethereum: {
+      native: { address: null, symbol: 'ETH', name: 'Ethereum', decimals: 18 },
+      tokens: []
+    }
+  }
+
+  return (
+    <WdkAppProvider
+      networkConfigs={networkConfigs}
+      tokenConfigs={tokenConfigs}
+    >
+      <WalletScreen />
+    </WdkAppProvider>
+  )
+}
+
+function WalletScreen() {
+  const { status, isReady } = useWdkApp()
+  const { addresses } = useWallet()
+  const { data: balance, isLoading } = useBalance({
+    network: 'ethereum',
+    accountIndex: 0,
+    tokenAddress: null
+  })
+
+  if (!isReady) return <Text>Loading...</Text>
+
+  return (
+    <View>
+      <Text>Address: {addresses.ethereum?.[0]}</Text>
+      <Text>Balance: {balance || '0'}</Text>
+      {isLoading && <Text>Updating...</Text>}
+    </View>
+  )
+}
+```
+
+## Installation
+
+### Step 1: Install Dependencies
+
+This package is part of the **Spacesops beta.40 pipeline**. Install matching peer/runtime versions in your host app:
+
+```bash
+npm install @spacesops/wdk-react-native-core@1.0.0-beta.40
+npm install @spacesops/pear-wrk-wdk@1.1.1-beta.40 @spacesops/react-native-bare-kit@0.11.0-beta.40
+npm install @tetherto/wdk-react-native-secure-storage
+npm install react@">=18.0.0" react-native@">=0.70.0"
+```
+
+**Host app notes (beta.40):**
+
+- You do **not** need `wire-worklet.js`, `relink-bare-addons.js`, or a direct `@spacesops/wdk-wallet-btc` dependency—bitcoin runs inside the pear worklet bundle.
+- On **Android**, configure **`keepDebugSymbols`** for `libbare*.so` in your Expo app or config plugin (see `@spacesops/react-native-bare-kit` README).
+- Include **`bitcoin`** in `networkConfigs` (electrum URLs, etc.) so it matches pear’s `networks: ["bitcoin"]`.
+
+### Step 2: Install from GitHub (if using source)
+
+```bash
+npm install https://github.com/spacesops/wdk-react-native-core.git
+```
+
+Or add to your `package.json`:
+
+```json
+{
+  "dependencies": {
+    "@spacesops/wdk-react-native-core": "1.0.0-beta.40",
+    "@spacesops/pear-wrk-wdk": "1.1.1-beta.40",
+    "@spacesops/react-native-bare-kit": "0.11.0-beta.40",
+    "@tetherto/wdk-react-native-secure-storage": "github:tetherto/wdk-react-native-secure-storage"
+  }
+}
+```
+
+## Core Concepts
+
+### WdkAppProvider
+
+The root provider that manages wallet initialization and worklet lifecycle. Wrap your app with it:
+
+```typescript
+<WdkAppProvider
+  networkConfigs={networkConfigs}
+  tokenConfigs={tokenConfigs}
+>
+  {children}
+</WdkAppProvider>
+```
+
+### Hooks
+
+- **`useWdkApp()`** - App-level initialization state (is app ready? what's the status?)
+- **`useWallet()`** - Wallet operations (addresses, account methods) - use AFTER initialization
+- **`useBalance()`** - Fetch and manage balances (uses TanStack Query)
+- **`useWalletManager()`** - Wallet lifecycle (create, load, import, delete) - use BEFORE operations
+- **`useWorklet()`** - Worklet state and operations (advanced use cases)
+
+## Which Hook Should I Use?
+
+### App Initialization State
+Use `useWdkApp()` to check if the app is ready:
+```typescript
+const { status, isReady, error } = useWdkApp()
+if (!isReady) return <LoadingScreen />
+```
+
+### Wallet Lifecycle (Create, Load, Import, Delete)
+Use `useWalletManager()` for wallet setup - this is the ONLY hook for wallet lifecycle:
+```typescript
+const { createWallet, loadWallet, importWallet, hasWallet, deleteWallet } = useWalletManager(networkConfigs)
+```
+
+### Wallet Operations (After Initialization)
+Use `useWallet()` for wallet data and operations:
+```typescript
+const { addresses, getAddress, callAccountMethod } = useWallet()
+```
+
+### Balance Fetching
+Use `useBalance()` for balances:
+```typescript
+const { data: balance, isLoading } = useBalance({ 
+  network: 'ethereum', 
+  accountIndex: 0, 
+  tokenAddress: null 
+})
+```
+
+### State Management
+
+- **Zustand Stores**: `workletStore` (worklet lifecycle), `walletStore` (wallet data)
+- **TanStack Query**: Balance fetching with automatic caching and refetching
+- **React State**: Component-level state via hooks
+
+## Usage Examples
+
+### Basic Wallet Setup
+
+```typescript
+import { WdkAppProvider, useWdkApp, useWalletManager } from '@spacesops/wdk-react-native-core'
+
+function App() {
+  return (
+    <WdkAppProvider networkConfigs={networkConfigs} tokenConfigs={tokenConfigs}>
+      <WalletSetup />
+    </WdkAppProvider>
+  )
+}
+
+function WalletSetup() {
+  const { status, isReady } = useWdkApp()
+  const { createWallet, loadWallet, hasWallet } = useWalletManager()
+
+  useEffect(() => {
+    const init = async () => {
+      const exists = await hasWallet()
+      if (exists) {
+        await loadWallet()
+      } else {
+        await createWallet()
+      }
+    }
+    if (isReady) init()
+  }, [isReady])
+
+  if (!isReady) return <LoadingScreen />
+
+  return <WalletApp />
+}
+```
+
+### Fetching Balances
+
+```typescript
+import { useBalance, useBalancesForWallet } from '@spacesops/wdk-react-native-core'
+
+function BalanceDisplay() {
+  // Single balance
+  const { data: balance, isLoading, error } = useBalance({
+    network: 'ethereum',
+    accountIndex: 0,
+    tokenAddress: null // null for native token
+  })
+
+  // All balances for a wallet
+  const { data: allBalances } = useBalancesForWallet({
+    accountIndex: 0,
+    networks: ['ethereum', 'spark']
+  })
+
+  return (
+    <View>
+      <Text>ETH Balance: {balance || '0'}</Text>
+      {isLoading && <Text>Loading...</Text>}
+      {error && <Text>Error: {error.message}</Text>}
+    </View>
+  )
+}
+```
+
+### Using Account Methods
+
+```typescript
+import { useWallet } from '@spacesops/wdk-react-native-core'
+
+function AccountOperations() {
+  const { callAccountMethod, isInitialized } = useWallet()
+
+  const handleGetBalance = async () => {
+    try {
+      const balance = await callAccountMethod(
+        'ethereum',
+        0,
+        'getBalance',
+        null
+      )
+      console.log('Balance:', balance)
+    } catch (error) {
+      console.error('Failed:', error)
+    }
+  }
+
+  const handleSignMessage = async (message: string) => {
+    try {
+      const signature = await callAccountMethod(
+        'ethereum',
+        0,
+        'signMessage',
+        { message }
+      )
+      console.log('Signature:', signature)
+    } catch (error) {
+      console.error('Failed:', error)
+    }
+  }
+
+  if (!isInitialized) return <Text>Not initialized</Text>
+
+  return (
+    <View>
+      <Button onPress={handleGetBalance}>Get Balance</Button>
+      <Button onPress={() => handleSignMessage('Hello')}>Sign Message</Button>
+    </View>
+  )
+}
+```
+
+### Multiple Wallets
+
+```typescript
+import { useWallet } from '@spacesops/wdk-react-native-core'
+
+function MultiWalletApp() {
+  const wallet1 = useWallet({ identifier: 'wallet-1' })
+  const wallet2 = useWallet({ identifier: 'wallet-2' })
+
+  return (
+    <View>
+      <Text>Wallet 1: {wallet1.addresses.ethereum?.[0]}</Text>
+      <Text>Wallet 2: {wallet2.addresses.ethereum?.[0]}</Text>
+    </View>
+  )
+}
+```
+
+### Refreshing Balances
+
+```typescript
+import { useRefreshBalance } from '@spacesops/wdk-react-native-core'
+
+function RefreshButton() {
+  const { mutate: refreshBalance } = useRefreshBalance()
+
+  const handleRefresh = () => {
+    refreshBalance({
+      network: 'ethereum',
+      accountIndex: 0,
+      tokenAddress: null
+    })
+  }
+
+  return <Button onPress={handleRefresh}>Refresh Balance</Button>
+}
+```
+
+## API Reference
+
+### WdkAppProvider
+
+```typescript
+interface WdkAppProviderProps {
+  networkConfigs: NetworkConfigs
+  tokenConfigs: TokenConfigs
+  children: React.ReactNode
+}
+```
+
+### useWdkApp()
+
+App-level initialization state. Use this to check if the app is ready.
+
+```typescript
+interface WdkAppContextValue {
+  status: AppStatus
+  isInitializing: boolean
+  isReady: boolean
+  workletStatus: InitializationStatus
+  workletState: { isReady: boolean; isLoading: boolean; error: string | null }
+  walletState: { status: string; identifier: string | null; error: Error | null }
+  activeWalletId: string | null
+  loadingWalletId: string | null
+  walletExists: boolean | null
+  error: Error | null
+  retry: () => void
+  // Note: Wallet lifecycle operations (create, load, import, delete) are available via useWalletManager()
+}
+```
+
+### useWallet()
+
+```typescript
+interface UseWalletResult {
+  addresses: WalletAddresses
+  isInitialized: boolean
+  isSwitchingWallet: boolean
+  switchWalletError: Error | null
+  isTemporaryWallet: boolean
+  getAddress: (network: string, accountIndex: number) => Promise<string>
+  callAccountMethod: <T = unknown>(
+    network: string,
+    accountIndex: number,
+    methodName: string,
+    args?: unknown
+  ) => Promise<T>
+}
+```
+
+### useBalance()
+
+```typescript
+function useBalance(options: {
+  network: string
+  accountIndex: number
+  tokenAddress: string | null
+  walletId?: string
+  enabled?: boolean
+  refetchInterval?: number
+  staleTime?: number
+}): {
+  data: string | null
+  isLoading: boolean
+  error: Error | null
+  refetch: () => void
+}
+```
+
+### useWalletManager()
+
+```typescript
+interface UseWalletManagerResult {
+  createWallet: (identifier?: string) => Promise<void>
+  loadWallet: (identifier?: string) => Promise<void>
+  importWallet: (mnemonic: string, identifier?: string) => Promise<void>
+  deleteWallet: (identifier: string) => Promise<void>
+  hasWallet: (identifier?: string) => Promise<boolean>
+  getWalletList: () => Wallet[]
+  activeWalletId: string | null
+}
+```
+
+### Allowed Account Methods
+
+For security, only these methods can be called via `callAccountMethod`:
+
+- `getAddress` - Get wallet address
+- `getBalance` - Get native token balance
+- `getTokenBalance` - Get ERC20 token balance
+- `signMessage` - Sign a message
+- `signTransaction` - Sign a transaction
+- `sendTransaction` - Send a transaction
+
+## Architecture
+
+```
+┌─────────────────────────────────────┐
+│         App Layer (Hooks)           │
+│  useWallet, useBalance, useWdkApp   │
+└──────────────┬──────────────────────┘
+               │
+┌──────────────▼──────────────────────┐
+│      Provider Layer                  │
+│      WdkAppProvider                  │
+│  (Consolidated state sync effect)    │
+└──────────────┬──────────────────────┘
+               │
+┌──────────────▼──────────────────────┐
+│      Service Layer                    │
+│  WorkletLifecycleService              │
+│  AddressService                       │
+│  AccountService                       │
+│  BalanceService                       │
+│  WalletSetupService                   │
+│  WalletSwitchingService               │
+└──────────────┬──────────────────────┘
+               │
+┌──────────────▼──────────────────────┐
+│      State Management                 │
+│  WorkletStore (Zustand)               │
+│  WalletStore (Zustand)                │
+│  TanStack Query (Balances)            │
+│  Operation Mutex (Race prevention)    │
+└──────────────┬──────────────────────┘
+               │
+┌──────────────▼──────────────────────┐
+│      Storage Layer                   │
+│  MMKV (non-sensitive)                │
+│  SecureStorage (sensitive)           │
+└─────────────────────────────────────┘
+```
+
+### State Synchronization
+
+The `WdkAppProvider` uses a **consolidated effect** for wallet state synchronization to prevent race conditions. Multiple interdependent state changes (activeWalletId, addresses, loadingState, errors) must be evaluated atomically in a single effect. See [WALLET_STATE_MACHINE.md](src/store/WALLET_STATE_MACHINE.md) for detailed state machine documentation.
+
+### Key Services
+
+- **WorkletLifecycleService**: Manages worklet lifecycle (start, initialize, cleanup)
+- **AddressService**: Handles address retrieval and caching
+- **AccountService**: Handles account method calls with whitelist validation
+- **BalanceService**: Manages balance operations
+- **WalletSetupService**: Handles wallet creation, import, and credential management
+
+## Security
+
+### Storage Encryption
+
+- **MMKV Storage**: Uses cryptographic key derivation for non-sensitive data
+- **Secure Storage**: Uses device keychain with biometric authentication for sensitive data
+- **Memory Management**: Sensitive data is automatically cleared when app is backgrounded
+
+### Security Features
+
+- ✅ Method whitelist validation (only approved methods can be called)
+- ✅ Input validation and sanitization
+- ✅ Error message sanitization (prevents information leakage)
+- ✅ Automatic credential cache expiration (TTL: 5 minutes, LRU eviction at 15 entries)
+- ✅ Safe JSON stringification (prevents prototype pollution)
+- ✅ Runtime type validation with Zod schemas
+- ✅ Operation mutex with timeout protection (prevents stuck operations)
+- ✅ Automatic sensitive data cleanup on app background
+
+### Best Practices
+
+1. Always use `WdkAppProvider` at app root
+2. Validate inputs before use (use provided validation utilities)
+3. Never log sensitive data
+4. Use error boundaries to handle errors gracefully
+5. Sensitive data is automatically cleared on app background
+
+## Troubleshooting
+
+### Wallet Initialization Fails
+
+**Symptoms**: `status` is `ERROR`, `error` is set
+
+**Solutions**:
+1. Check that `networkConfigs` are valid (use `validateNetworkConfigs()`)
+2. Verify `tokenConfigs` are properly configured
+3. Check console logs for detailed error messages
+4. Try calling `retry()` method from context
+
+**Common Errors**:
+- "WDK not initialized" → Worklet failed to start, check network configs
+- "Biometric authentication required" → User cancelled or device doesn't support biometrics
+- "Encryption key not found" → Secure storage issue, may need to recreate wallet
+
+### Balance Fetching Issues
+
+**Symptoms**: Balances not updating, `isLoading` stuck true
+
+**Solutions**:
+1. Verify `tokenConfigs` are properly configured
+2. Check network connectivity and RPC endpoint availability
+3. Ensure wallet is initialized (`status === 'READY'`)
+4. Check token addresses are valid Ethereum addresses
+
+### Type Validation Errors
+
+**Symptoms**: Runtime errors about invalid types
+
+**Solutions**:
+1. Use `validateNetworkConfigs()` and `validateTokenConfigs()` before passing to provider
+2. Ensure token addresses match Ethereum address format
+3. Verify account indices are non-negative integers
+4. Use type guards from exports for runtime validation
+
+## Development
+
+### Building
+
+```bash
+npm run build
+npm run build:strict  # Strict mode (fails on errors)
+```
+
+### Testing
+
+```bash
+npm test
+npm run test:coverage  # 100% coverage required
+npm run test:watch
+```
+
+### Type Checking
+
+```bash
+npm run typecheck
+```
+
+## License
+
+Apache-2.0

package/dist/__mocks__/react.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Mock React module for Jest tests
+ * Required by Zustand v5 which imports React
+ */
+export declare const useState: jest.Mock<any[], [initial: any], any>;
+export declare const useEffect: jest.Mock<any, any, any>;
+export declare const useCallback: jest.Mock<any, [fn: any], any>;
+export declare const useMemo: jest.Mock<any, [fn: any], any>;
+export declare const useRef: jest.Mock<{
+    current: any;
+}, [initial: any], any>;
+export declare const createContext: jest.Mock<{
+    Provider: ({ children }: any) => any;
+    Consumer: ({ children }: any) => any;
+}, [], any>;
+export declare const useContext: jest.Mock<any, any, any>;
+export declare const useReducer: jest.Mock<any[], [reducer: any, initial: any], any>;
+export declare class Component {
+}
+export declare const Fragment: ({ children }: any) => any;
+export declare const version = "18.0.0";
+declare const _default: {
+    useState: jest.Mock<any[], [initial: any], any>;
+    useEffect: jest.Mock<any, any, any>;
+    useCallback: jest.Mock<any, [fn: any], any>;
+    useMemo: jest.Mock<any, [fn: any], any>;
+    useRef: jest.Mock<{
+        current: any;
+    }, [initial: any], any>;
+    createContext: jest.Mock<{
+        Provider: ({ children }: any) => any;
+        Consumer: ({ children }: any) => any;
+    }, [], any>;
+    useContext: jest.Mock<any, any, any>;
+    useReducer: jest.Mock<any[], [reducer: any, initial: any], any>;
+    Component: typeof Component;
+    Fragment: ({ children }: any) => any;
+    version: string;
+};
+export default _default;

package/dist/__mocks__/react.js

@@ -0,0 +1,33 @@
+/**
+ * Mock React module for Jest tests
+ * Required by Zustand v5 which imports React
+ */
+export const useState = jest.fn((initial) => [initial, jest.fn()]);
+export const useEffect = jest.fn();
+export const useCallback = jest.fn((fn) => fn);
+export const useMemo = jest.fn((fn) => fn());
+export const useRef = jest.fn((initial) => ({ current: initial }));
+export const createContext = jest.fn(() => ({
+    Provider: ({ children }) => children,
+    Consumer: ({ children }) => children,
+}));
+export const useContext = jest.fn();
+export const useReducer = jest.fn((reducer, initial) => [initial, jest.fn()]);
+export class Component {
+}
+export const Fragment = ({ children }) => children;
+export const version = '18.0.0';
+export default {
+    useState,
+    useEffect,
+    useCallback,
+    useMemo,
+    useRef,
+    createContext,
+    useContext,
+    useReducer,
+    Component,
+    Fragment,
+    version,
+};
+//# sourceMappingURL=react.js.map

package/dist/__mocks__/react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.js","sourceRoot":"","sources":["../../src/__mocks__/react.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,CAAC,MAAM,QAAQ,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,OAAY,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,CAAA;AACvE,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,CAAC,EAAE,EAAE,CAAA;AAClC,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,EAAO,EAAE,EAAE,CAAC,EAAE,CAAC,CAAA;AACnD,MAAM,CAAC,MAAM,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,EAAO,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAA;AACjD,MAAM,CAAC,MAAM,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,OAAY,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,CAAA;AACvE,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IAC1C,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAO,EAAE,EAAE,CAAC,QAAQ;IACzC,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAO,EAAE,EAAE,CAAC,QAAQ;CAC1C,CAAC,CAAC,CAAA;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,CAAC,EAAE,EAAE,CAAA;AACnC,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,OAAY,EAAE,OAAY,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,CAAA;AACvF,MAAM,OAAO,SAAS;CAAG;AACzB,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,EAAE,QAAQ,EAAO,EAAE,EAAE,CAAC,QAAQ,CAAA;AACvD,MAAM,CAAC,MAAM,OAAO,GAAG,QAAQ,CAAA;AAE/B,eAAe;IACb,QAAQ;IACR,SAAS;IACT,WAAW;IACX,OAAO;IACP,MAAM;IACN,aAAa;IACb,UAAU;IACV,UAAU;IACV,SAAS;IACT,QAAQ;IACR,OAAO;CACR,CAAA"}

package/dist/__mocks__/secureStorage.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Mock SecureStorage for testing
+ *
+ * Supports identifier parameter for multi-wallet testing
+ */
+export declare const mockSecureStorage: {
+    authenticate: jest.Mock<Promise<boolean>, [], any>;
+    hasWallet: jest.Mock<Promise<boolean>, [identifier?: string | undefined], any>;
+    setEncryptionKey: jest.Mock<Promise<void>, [key: string, identifier?: string | undefined], any>;
+    getEncryptionKey: jest.Mock<Promise<string | null>, [identifier?: string | undefined], any>;
+    setEncryptedSeed: jest.Mock<Promise<void>, [seed: string, identifier?: string | undefined], any>;
+    getEncryptedSeed: jest.Mock<Promise<string | null>, [identifier?: string | undefined], any>;
+    setEncryptedEntropy: jest.Mock<Promise<void>, [entropy: string, identifier?: string | undefined], any>;
+    getEncryptedEntropy: jest.Mock<Promise<string | null>, [identifier?: string | undefined], any>;
+    getAllEncrypted: jest.Mock<Promise<{
+        encryptedSeed: string | null;
+        encryptedEntropy: string | null;
+        encryptionKey: string | null;
+    }>, [identifier?: string | undefined], any>;
+    clearAll: jest.Mock<Promise<void>, [], any>;
+    isBiometricAvailable: jest.Mock<Promise<boolean>, [], any>;
+    deleteWallet: jest.Mock<Promise<void>, [identifier?: string | undefined], any>;
+    cleanup: jest.Mock<any, any, any>;
+    _clearStorage: () => void;
+};
+export default mockSecureStorage;