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.
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 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
- Typed React Native source API - exported hook and service types are available through the package's React Native source condition
Starting in v1.0.0-beta.14, React Native Core pins a Pear Worklet version with the HRPC methods required by useModule() and ModuleService. Beta.15 pins Pear Worklet beta.10.
The v1.0.0-beta.15 npm artifact includes the React Native source entry at src/index.ts, but it does not include the declared default JavaScript or type declaration files under dist/. Use a React Native resolver that selects the package's react-native condition. Resolvers that select default or types target files that are not present in this artifact.
Quick Start
1. Install
npm install @tetherto/wdk-react-native-core react-native-bare-kitStarting in beta.14, react-native-bare-kit is a peer dependency with a supported range of >=0.14.5, so the app must install it explicitly.
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. 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
# 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 (INITIALIZING, NO_WALLET, LOCKED, READY, ERROR)
+-- useWalletManager() - create, restore, 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