React Native Core
Hooks-based React Native library for building multi-chain wallet apps with WDK
React Native Core provides a hooks-based API for wallet management, balance fetching, account operations inside any React Native app.
This page documents @tetherto/wdk-react-native-core@1.0.0-beta.21.
Features
- Hooks-based architecture -
useWdkApp,useWalletManager,useAccount,useProtocol,useBalance,useBalancesForWallets, and more - Generic module API -
useModuleandModuleServiceexpose named worklet-module calls and events - TanStack Query caching - automatic balance fetching across one or many account indices, per-token fallback for modules without batch balance support, cache invalidation, and optimistic updates
- Zustand state management - persisted wallet inventory with MMKV storage; the active identity is cleared on rehydration
- Worklet runtime - runs WDK in an isolated Bare worklet
- Explicit wallet identity - your app chooses which wallet ID to create, restore, unlock, or switch to
- Multi-wallet support - create, restore, lock, unlock, switch, and delete wallets; guarded lifecycle operations use a fail-fast mutex
Core does not enforce biometrics or another authentication policy. Wallet identity is caller-owned. Pass an explicit wallet ID to unlock() and authenticate in your app before wallet operations or key access.
Quick Start
1. Install
Core requires expo-crypto >=55.0.0 <57.0.0 and react-native-bare-kit >=0.14.5 as peer dependencies. Use an Expo SDK whose expo-crypto version satisfies that range. In a bare React Native app, install and configure Expo modules before installing expo-crypto.
Install Core and its peer dependencies:
npm install @tetherto/wdk-react-native-core@1.0.0-beta.21 react-native-bare-kit
npx expo install expo-cryptoFor Community CLI or shallow Expo autolinking, follow the conditional Keychain installation step. Rebuild the native app after installing, including iOS pods for bare React Native projects. Expo apps need a development build with the native modules included.
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({
walletId,
authenticate,
}: {
walletId: string
authenticate: () => Promise<boolean>
}) {
const { state } = useWdkApp()
const { createWallet, unlock } = useWalletManager()
const { address, isLoading } = useAccount({ network: 'ethereum', accountIndex: 0 })
const create = async () => {
if (await authenticate()) await createWallet(walletId)
}
const open = async () => {
if (await authenticate()) await unlock(walletId)
}
switch (state.status) {
case 'INITIALIZING':
case 'REINITIALIZING':
return <Text>Loading...</Text>
case 'NO_WALLET':
return <Button title="Create Wallet" onPress={create} />
case 'LOCKED':
return <Button title="Unlock" onPress={open} />
case 'READY':
return <Text>Address: {address}</Text>
case 'ERROR':
return <Text>Error: {state.error.message}</Text>
}
}If startup reports an error, follow the quickstart troubleshooting steps.
For a full integration guide, see the React Native Quickstart.
Bundle Configuration
The WDK engine runs inside a Bare worklet. Generate an HRPC bundle with @tetherto/wdk-worklet-bundler and import it from the generated ./.wdk entrypoint.
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@1.0.0-beta.14
# 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 generateExample wdk.config.js:
module.exports = {
networks: {
ethereum: {
package: '@tetherto/wdk-wallet-evm-erc-4337'
},
polygon: {
package: '@tetherto/wdk-wallet-evm-erc-4337'
}
},
transport: 'hrpc'
}This file selects packages at build time. Pass chain IDs, providers, protocol settings, and any per-module runtime config through wdkConfigs on WdkAppProvider. The optional build-time modules map in the bundler is distinct from runtime wdkConfigs.modules; their names must match when generic-module support is available.
After running wdk-worklet-bundler generate, import and use the bundle:
import { bundle } from './.wdk'
<WdkAppProvider bundle={{ bundle }} wdkConfigs={configs}>
<App />
</WdkAppProvider>For the complete config and transport rules, see the Worklet Bundler configuration guide. @tetherto/pear-wrk-wdk provides the worklet transport/runtime layer; it does not export a pre-built WDK bundle.
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 and manual worklet reinitialization
+-- useWalletManager() - create, restore, switch, lock, unlock, delete wallets
+-- useAccount() - address, send, sign, verify, estimateFee
+-- useProtocol() - call bridge, swap, Swidge, lending, and fiat protocol methods
+-- useModule() - call named generic modules and subscribe to events
+-- useAddresses() - load and query addresses
+-- useBalance() - single balance with TanStack Query
+-- useBalancesForWallet() - bulk balance fetch for one account index
+-- useBalancesForWallets() - bulk balance fetch across account indices
+-- useRefreshBalance() - invalidate and refetch balancesAPI Reference
Complete reference for all hooks, components, types, and utilities
React Native Quickstart
Step-by-step integration guide for new and existing apps