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 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
- 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.17, wallet identity is caller-owned and the library no longer auto-unlocks a persisted wallet. The current release does not enforce biometrics or another authentication policy. Pass an explicit wallet ID to unlock(), and perform your app's authentication check before calling lifecycle or key-access methods.
The v1.0.0-beta.18 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/. TypeScript must use moduleResolution: "bundler" with customConditions: ["react-native"], and Metro must retain the react-native export 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@1.0.0-beta.18 react-native-bare-kit
npx expo install expo-cryptoBeta.18 requires expo-crypto >=55.0.0 <57.0.0 and react-native-bare-kit >=0.14.5 as peer dependencies. Confirm that the version selected by npx expo install is inside the package range and matches the app's Expo SDK. If the SDK requires a version outside the range, do not force the peer installation; use compatible releases instead. In a bare React Native app, install and configure Expo modules before installing expo-crypto.
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>
}
}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 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