@tetherto/wdk-starter-react-native

Warning

Alpha Software

This starter template is currently in alpha stage and under active development. It may contain bugs, incomplete features, and breaking changes. Do not use in production environments or with real funds.

For production use, please wait for the stable release or use at your own risk in development/testing environments only.

An Expo + React Native starter demonstrating how to build a secure, multi-chain, non-custodial wallet using the WDK (Wallet Development Kit). Features BareKit worklets for cryptographic operations, secure secret management, and a complete wallet implementation with onboarding, transactions, and asset management.

Click below to see the wallet in action:

🔍 About WDK

This repository is part of the WDK (Wallet Development Kit) project, which empowers developers to build secure, non-custodial wallets with unified blockchain access, stateless architecture, and complete user control.

For detailed documentation about the complete WDK ecosystem, visit docs.wallet.tether.io.

🌟 Features

Multi-Chain Support

Bitcoin (SegWit): Native bitcoin transfers with SegWit addresses
Ethereum: EVM transactions with gas sponsorship support
Polygon: Low-cost EVM transactions with gas sponsorship
Arbitrum: Layer 2 scaling with gas sponsorship support
TON: Native TON blockchain transfers
Tron: TRC-20 token support with low fees
Solana: High-performance blockchain support

Multi-Token Support

BTC: Native Bitcoin on SegWit and Lightning networks
USD₮ (Tether USD): Multi-chain USD₮ support (Ethereum, Polygon, Arbitrum, TON, Tron, Solana)
XAU₮ (Tether Gold): Gold-backed stablecoin on Ethereum

Wallet Management

Secure Seed Generation: Cryptographically secure 12-word mnemonic generation
Seed Import: Import existing BIP39-compatible mnemonic phrases
Encrypted Storage: Secure key storage via native secure storage (iOS Keychain, Android KeyStore)
Biometric Authentication: Face ID/Touch ID for wallet unlock
Wallet Naming: Custom wallet names for better organization

Asset Management

Real-Time Balances: Live balance updates via WDK Indexer
Transaction History: Complete transaction tracking and history
Price Conversion: Real-time fiat pricing via Bitfinex integration
Multi-Asset View: Aggregate portfolio view across all tokens and chains
Asset Details: Detailed views for individual tokens with transaction history

User Experience

QR Code Scanner: Scan wallet addresses and payment requests via camera
Send Flows: Complete send flow with network and token selection
Receive Flows: Generate QR codes for receiving payments
Activity Feed: Real-time transaction monitoring with status updates
Settings: Wallet management, security, and app preferences
Dark Mode: Modern dark theme optimized for readability

🧱 Platform Prerequisites

Node.js 22+
iOS: Xcode toolchain
Android: SDK (see app.json build properties for version requirements)

⬇️ Installation

Clone this repository and install dependencies:

npm install

🔑 Environment Setup

Optional but Recommended: Configure API keys for balance, transaction data, and Tron network support:

# Copy the example environment file
cp .env.example .env

# Edit .env and configure the following:
# EXPO_PUBLIC_WDK_INDEXER_BASE_URL=https://wdk-api.tether.io
# EXPO_PUBLIC_WDK_INDEXER_API_KEY=your_wdk_api_key_here
# EXPO_PUBLIC_TRON_API_KEY=your_tron_api_key_here (optional, for Tron network)
# EXPO_PUBLIC_TRON_API_SECRET=your_tron_api_secret_here (optional, for Tron network)

Note: The WDK Indexer API key is used for balance and transaction API requests. While not mandatory for development, it enables full functionality. Tron API keys are optional and only needed if you want to use the Tron network. Get your free WDK Indexer API key in the WDK docs.

🔧 Provider Configuration (Recommended)

For Better Performance: The app uses public RPC endpoints by default, which may have rate limits and variable performance. For a better experience, customize provider URLs in src/config/get-chains-config.ts:

Customizable Endpoints

Edit src/config/get-chains-config.ts to update these provider URLs:

Ethereum

ethereum: {
  provider: 'https://eth.merkle.io',  // Replace with your Ethereum RPC URL
  bundlerUrl: 'https://api.candide.dev/public/v3/ethereum',
  paymasterUrl: 'https://api.candide.dev/public/v3/ethereum',
}

Arbitrum

arbitrum: {
  provider: 'https://arb1.arbitrum.io/rpc',  // Replace with your Arbitrum RPC URL
  bundlerUrl: 'https://api.candide.dev/public/v3/arbitrum',
  paymasterUrl: 'https://api.candide.dev/public/v3/arbitrum',
}

Do the same for other chains.

🚀 Run

Then start the app:

# iOS simulator
npm run ios

# Android emulator/device
npm run android

📁 Project Structure

src/
├── app/                         # App screens (Expo Router file-based routing)
│   ├── _layout.tsx              # Root layout with providers
│   ├── index.tsx                # Entry point & routing logic
│   ├── onboarding/              # Onboarding flow screens
│   ├── wallet-setup/            # Wallet creation/import flows
│   ├── wallet.tsx               # Main wallet dashboard
│   ├── assets.tsx               # Asset list screen
│   ├── activity.tsx             # Transaction history
│   ├── send/                    # Send flow screens
│   ├── receive/                 # Receive flow screens
│   ├── authorize.tsx            # Biometric authentication
│   ├── settings.tsx             # App settings
│   ├── scan-qr.tsx              # QR code scanner
│   └── token-details.tsx        # Individual token details
├── components/                  # Reusable UI components
│   ├── onboarding/              # Onboarding components
│   ├── ui/                      # Base UI components
│   └── *.tsx                    # Shared components
├── config/                      # Configuration files
│   ├── assets.ts                # Token/asset configurations
│   ├── avatar-options.ts        # Wallet avatar configurations
│   ├── networks.ts              # Network configurations
│   └── get-chains-config.ts     # Chain-specific settings & provider URLs
├── services/                    # Business logic & external services
│   └── pricing-service.ts       # Fiat pricing via Bitfinex
├── hooks/                       # Custom React hooks
│   ├── use-debounced-navigation.ts  # Debounced navigation to prevent rapid taps
│   ├── use-keyboard.ts          # Keyboard visibility detection
│   └── use-wallet-avatar.ts     # Wallet avatar management
└── utils/                       # Utility functions
    ├── gas-fee-calculator.ts    # Gas fee estimation & network utilities
    ├── format-amount.ts         # Amount formatting helpers
    ├── format-token-amount.ts   # Token-specific amount formatting
    ├── format-usd-value.ts      # USD value formatting
    ├── get-display-symbol.ts    # Token symbol display utilities
    ├── get-denomination-value.ts # Token denomination utilities
    ├── parse-worklet-error.ts   # Worklet error parsing for better UX
    └── recent-tokens.ts         # Recent token tracking

🏗️ Architecture & Key Flows

App Architecture

The app follows a clean architecture pattern with clear separation of concerns:

Providers Layer (_layout.tsx)
- WalletProvider: Manages wallet state, blockchain interactions, and WDK service
- ThemeProvider: Handles dark mode and custom theming
- NavigationThemeProvider: React Navigation theme configuration
Screen Layer (app/ directory)
- File-based routing via Expo Router
- Each screen is a self-contained React component
- Navigation handled automatically based on file structure
Business Logic (services/ directory)
- Pricing service for real-time fiat conversion
Configuration (config/ directory)
- Centralized network and asset configurations
- Chain-specific RPC endpoints and settings

User Flows

First-Time User (Create Wallet)

Onboarding → View welcome screen with app features
Wallet Setup → Choose "Create New Wallet"
Name Wallet → Set a custom wallet name
Secure Wallet → View and backup 12-word seed phrase
Confirm Phrase → Verify seed phrase knowledge
Complete → Wallet created and unlocked
Wallet Dashboard → Access main wallet interface

Returning User (Import Wallet)

Onboarding → View welcome screen
Wallet Setup → Choose "Import Existing Wallet"
Import Wallet → Enter 12-word seed phrase
Name Wallet → Set a custom wallet name
Complete → Wallet imported and unlocked
Wallet Dashboard → Access main wallet interface

Existing User (App Launch)

Entry Point (index.tsx) → Check wallet status
Authorization → Biometric authentication (Face ID/Touch ID)
Wallet Dashboard → Access wallet after unlock

Send Flow

Wallet Dashboard → Tap "Send" button
Select Token → Choose token to send (BTC, USD₮, XAU₮)
Select Network → Choose blockchain network
Send Details → Enter recipient address, amount, and review fees
Confirm → Approve transaction
Transaction Submitted → View transaction status

Receive Flow

Wallet Dashboard → Tap "Receive" button
Select Token → Choose token to receive
Select Network → Choose blockchain network
Receive Details → View QR code and address, copy or share

🌐 Supported Networks & Operations

This starter supports the following blockchain networks and operations:

Network	Balance	History	Send	Receive	Gas Sponsorship
Bitcoin (SegWit)	✅	✅	✅	✅	N/A
Lightning	✅	✅	✅	✅	N/A
Ethereum	✅	✅	✅	✅	✅
Polygon	✅	✅	✅	✅	✅
Arbitrum	✅	✅	✅	✅	✅
TON	✅	✅	✅	✅	✅
Tron	✅	✅	✅	✅	✅
Solana	✅	✅	✅	✅	✅

Token Support

Token	Symbol	Networks
Bitcoin	BTC	Bitcoin (SegWit), Lightning
Tether USD	USD₮	Ethereum, Polygon, Arbitrum, TON, Tron, Solana
Tether Gold	XAU₮	Ethereum

Key Features

Gas Sponsorship: EVM networks (Ethereum, Polygon, Arbitrum) and other supported chains offer gasless transactions via paymasters
Multi-Network: Send the same token across different networks based on preference and fees
Real-Time Data: Live balance and transaction updates via WDK Indexer
QR Code Support: Generate and scan QR codes for easy address sharing

🔒 Security Features

This starter implements multiple layers of security for protecting user assets:

Secure Key Management

BareKit Worklets: Cryptographic operations run in isolated worklet context
Secret Manager: Keys stored encrypted using native secure storage (iOS Keychain, Android KeyStore)
No Key Exposure: Private keys never leave the secure context or device
BIP39 Compliant: Standard 12-word mnemonic seed phrase generation

Authentication

Biometric Lock: Face ID/Touch ID for wallet unlock
App Lock: Wallet locked on app background/close
Session Management: Secure session handling with automatic timeout

Transaction Security

User Confirmation: All transactions require explicit user approval
Amount Verification: Clear display of amounts and fees before signing
Address Validation: Input validation for recipient addresses
Network Selection: User must explicitly choose network to prevent errors

Best Practices

No Analytics: No user data or transaction info sent to third parties
Local Storage: All wallet data stored locally on device
Open Source: Fully auditable codebase
Non-Custodial: Users have complete control of their private keys

⚙️ Polyfills & Build Configuration

Node.js Polyfills

The app includes comprehensive Node.js polyfills for React Native compatibility via @tetherto/wdk-react-native-provider/metro-polyfills

Native Modules

Sodium: sodium-javascript (WebAssembly-based cryptography)
Random: react-native-get-random-values (secure randomness)
PBKDF2: react-native-fast-pbkdf2 (key derivation)
TCP: react-native-tcp-socket (for Bitcoin Electrum)

🧪 Available Scripts

Script	Description
`npm start`	Start Expo development server with dev client
`npm run ios`	Run on iOS simulator
`npm run android`	Run on Android emulator/device
`npm run web`	Run in web browser
`npm run prebuild`	Generate native project files
`npm run prebuild:clean`	Clean and regenerate native project files
`npm run lint`	Run ESLint to check code quality
`npm run lint:fix`	Run ESLint and auto-fix issues
`npm run format`	Format code with Prettier
`npm run format:check`	Check code formatting without making changes
`npm run typecheck`	Run TypeScript type checking

🔗 Version & Compatibility

Core Dependencies

Expo: ~54.0.8
React: 19.1.0
React Native: 0.81.4
TypeScript: ~5.9.2

Key Features

New Architecture: Enabled in app.json for improved performance
React Native Reanimated: ~4.1.0 for smooth animations
React Compiler: Enabled for automatic memoization

Platform Requirements

Android: minSdkVersion 29, compileSdkVersion 36
iOS: Latest Xcode toolchain recommended
Node.js: 22+ required

WDK Packages

@tetherto/wdk-react-native-provider: Main wallet provider
@tetherto/wdk-uikit-react-native: UI components library
@tetherto/wdk-pricing-provider: Fiat pricing integration
@tetherto/wdk-pricing-bitfinex-http: Bitfinex price data provider
@tetherto/pear-wrk-wdk: BareKit worklets runtime

🎨 Customization Guide

Adding New Tokens

Add token configuration in src/config/assets.ts:

export const assetConfig: Record<string, AssetConfig> = {
  newtoken: {
    name: 'New Token',
    icon: require('../../assets/images/tokens/newtoken-logo.png'),
    color: '#YOUR_COLOR',
    supportedNetworks: [NetworkType.ETHEREUM],
  },
};

Add token icon to assets/images/tokens/

Adding New Networks

Add network configuration in src/config/networks.ts:

[NetworkType.NEW_NETWORK]: {
  id: 'new-network',
  name: 'New Network',
  gasLevel: 'Low',
  gasColor: '#34C759',
  icon: require('../../assets/images/chains/new-network-logo.png'),
  color: '#YOUR_COLOR',
}

Add chain configuration in src/config/get-chains-config.ts:

newnetwork: {
  chainId: YOUR_CHAIN_ID,
  blockchain: 'newnetwork',
  provider: 'https://your-rpc-url.com',
  // Add other chain-specific configuration
}

Add chain logo to assets/images/chains/

Customizing Theme & Brand

Update the brand configuration in src/app/_layout.tsx:

<ThemeProvider
  defaultMode="dark"
  brandConfig={{
    primaryColor: '#YOUR_BRAND_COLOR',
  }}
>

🐛 Troubleshooting

Common Issues

Metro bundler cache issues

npx expo start -c

Native build issues

npm run prebuild:clean
cd ios && pod install
cd android && ./gradlew clean

Type errors after updates

npm run typecheck

Development Tips

Use Expo Dev Client for faster development cycles
Enable Fast Refresh for instant UI updates
Check Metro bundler logs for build issues
Use React DevTools for component debugging
Monitor network requests in browser DevTools (web) or Reactotron (native)

📜 License

This project is licensed under the Apache-2.0 - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Read the code of conduct
See contributing guide

🆘 Support

For support, please:

Check the WDK documentation
Open an issue on the GitHub repository
Join the WDK developer community

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
.github		.github
assets		assets
plugins		plugins
src		src
types		types
.env.example		.env.example
.gitignore		.gitignore
.nvmrc		.nvmrc
.prettierignore		.prettierignore
.prettierrc.js		.prettierrc.js
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
app.json		app.json
eslint.config.js		eslint.config.js
metro.config.js		metro.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

License

tetherto/wdk-starter-react-native

Folders and files

Latest commit

History

Repository files navigation

@tetherto/wdk-starter-react-native

🔍 About WDK

🌟 Features

Multi-Chain Support

Multi-Token Support

Wallet Management

Asset Management

User Experience

🧱 Platform Prerequisites

⬇️ Installation

🔑 Environment Setup

🔧 Provider Configuration (Recommended)

Customizable Endpoints

🚀 Run

📁 Project Structure

🏗️ Architecture & Key Flows

App Architecture

User Flows

First-Time User (Create Wallet)

Returning User (Import Wallet)

Existing User (App Launch)

Send Flow

Receive Flow

🌐 Supported Networks & Operations

Token Support

Key Features

🔒 Security Features

Secure Key Management

Authentication

Transaction Security

Best Practices

⚙️ Polyfills & Build Configuration

Node.js Polyfills

Native Modules

🧪 Available Scripts

🔗 Version & Compatibility

Core Dependencies

Key Features

Platform Requirements

WDK Packages

🎨 Customization Guide

Adding New Tokens

Adding New Networks

Customizing Theme & Brand

🐛 Troubleshooting

Common Issues

Development Tips

📜 License

🤝 Contributing

🆘 Support

About

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 3

Uh oh!

Languages

Packages