React Native Core

React Native Core provides a hooks-based API for wallet management, balance fetching, account operations inside any React Native app.

Features

Hooks-based architecture - useWdkApp, useWalletManager, useAccount, useBalance, and more
TanStack Query caching - automatic balance fetching, cache invalidation, and optimistic updates
Zustand state management - persisted wallet state with MMKV storage
Worklet runtime - runs WDK in an isolated Bare worklet
Biometric authentication - secure storage with device biometrics
Multi-wallet support - create, restore, switch, lock, unlock, and delete wallets
TypeScript-first - full type safety with exported types and interfaces

Quick Start

1. Install

npm install @tetherto/wdk-react-native-core

2. Wrap Your App

import { WdkAppProvider } from '@tetherto/wdk-react-native-core'
import { bundle } from './.wdk' // See Bundle Configuration below

export default function App() {
  return (
    <WdkAppProvider bundle={{ bundle }} wdkConfigs={configs}>
      <YourApp />
    </WdkAppProvider>
  )
}

3. Use Hooks

import { useWdkApp, useWalletManager, useAccount } from '@tetherto/wdk-react-native-core'

function WalletScreen() {
  const { state } = useWdkApp()
  const { createWallet, unlock } = useWalletManager()
  const { address, isLoading } = useAccount({ network: 'ethereum', accountIndex: 0 })

  switch (state.status) {
    case 'INITIALIZING':
      return <Text>Loading...</Text>
    case 'NO_WALLET':
      return <Button title="Create Wallet" onPress={() => createWallet('my-wallet')} />
    case 'LOCKED':
      return <Button title="Unlock" onPress={() => unlock()} />
    case 'READY':
      return <Text>Address: {address}</Text>
    case 'ERROR':
      return <Text>Error: {state.error.message}</Text>
  }
}

For a full integration guide, see the React Native Quickstart.

Bundle Configuration

The WDK engine runs inside a Bare worklet. You need to provide a bundle - there are two approaches:

Custom Bundle (Recommended)

Use the @tetherto/wdk-worklet-bundler CLI to generate a bundle with only the blockchain modules you need:

# 1. Install the bundler CLI
npm install -g @tetherto/wdk-worklet-bundler

# 2. Initialize configuration in your React Native project
wdk-worklet-bundler init

# 3. Edit wdk.config.js to configure your networks (see example below)

# 4. Install required WDK modules
npm install @tetherto/wdk @tetherto/wdk-wallet-evm-erc-4337

# 5. Generate the bundle
wdk-worklet-bundler generate

Example wdk.config.js:

module.exports = {
  modules: {
    core: '@tetherto/wdk',
    erc4337: '@tetherto/wdk-wallet-evm-erc-4337',
  },
  networks: {
    ethereum: {
      module: 'erc4337',
      chainId: 1,
      blockchain: 'ethereum',
      provider: 'https://eth.drpc.org',
    },
    polygon: {
      module: 'erc4337',
      chainId: 137,
      blockchain: 'polygon',
      provider: 'https://polygon.drpc.org',
    },
  },
}

After running wdk-worklet-bundler generate, import and use the bundle:

import { bundle } from './.wdk'

<WdkAppProvider bundle={{ bundle }} wdkConfigs={configs}>
  <App />
</WdkAppProvider>

For full bundler documentation, see wdk-worklet-bundler.

Pre-built Bundle

For quick prototyping, use the pre-built bundle from @tetherto/pear-wrk-wdk which includes all blockchain modules:

import { bundle } from '@tetherto/pear-wrk-wdk'

<WdkAppProvider bundle={{ bundle }} wdkConfigs={configs}>
  <App />
</WdkAppProvider>

The pre-built bundle includes all blockchain modules, resulting in a larger bundle size. For production apps, generate a custom bundle with only the modules you need.

Architecture

WdkAppProvider
+-- QueryClientProvider (TanStack Query)
+-- Worklet Runtime (react-native-bare-kit)
|   +-- WDK engine (runs in isolated Bare worklet)
+-- Zustand Stores
|   +-- workletStore - worklet lifecycle, initialization state
|   +-- walletStore - addresses, balances, wallet list (persisted to MMKV)
+-- Hooks (public API)
    +-- useWdkApp()         - app state (INITIALIZING, NO_WALLET, LOCKED, READY, ERROR)
    +-- useWalletManager()  - create, restore, lock, unlock, delete wallets
    +-- useAccount()        - address, send, sign, verify, estimateFee
    +-- useAddresses()      - load and query addresses
    +-- useBalance()        - single balance with TanStack Query
    +-- useBalancesForWallet() - bulk balance fetch
    +-- useRefreshBalance() - invalidate and refetch balances