Sovran is built with modern React Native technologies and specialized Bitcoin/Nostr libraries. This guide covers the complete technical stack.
Core Framework
React Native & Expo
React 19.2.0
Latest React with concurrent features
React Native 0.83.2
Native iOS and Android support
Expo SDK 55
Managed workflow with EAS Build
Expo Router 55
File-based navigation system
Key Features:
- Typed routes via Expo Router
- React Compiler enabled for optimizations
- Metro bundler with Terser minification
TypeScript
{
"compilerOptions": {
"strict": true,
"jsx": "react-jsx",
"baseUrl": ".",
"paths": {
"@/*": ["./*"]
}
}
}
- Version: TypeScript 5.9.2
- Configuration: Extends
expo/tsconfig.base
- Path Aliases:
@/* for absolute imports
- Strict Mode: Enabled for type safety
Babel
Transpilation with module resolver
Metro
React Native bundler
EAS Build
Cloud build service
UI & Styling
Styling System
Uniwind - Tailwind CSS v4 for React Native
import { View, Text } from 'uniwind';
<View className="flex-1 bg-background p-4">
<Text className="text-xl font-bold text-foreground">
Styled with Tailwind
</Text>
</View>
NativeWind - Used alongside Uniwind for enhanced styling
- Zero-runtime Tailwind for React Native
- Platform-specific class names
- Dark mode support
UI Libraries
HeroUI Native
RN Primitives
Expo UI
Primary component library for Sovranimport { Button, Card } from 'heroui-native';
- Native-first components
- Theme integration
- Hero transition animations
Low-level accessible primitivesimport { Checkbox } from '@rn-primitives/checkbox';
- Checkbox component
- Accessibility built-in
Expo’s UI component libraryimport { View } from '@expo/ui';
Icons & Graphics
- Monicon - Icon system for React Native
- Metro integration:
@monicon/metro
- Native icons:
@monicon/native
- Expo Symbols - SF Symbols support
- React Native SVG - SVG rendering
Animation
React Native Reanimated 4.2.1
// Shared element transitions enabled
{
"reanimated": {
"staticFeatureFlags": {
"ENABLE_SHARED_ELEMENT_TRANSITIONS": true
}
}
}
- Worklets for 60fps animations
- Hero transitions between screens
- Gesture-driven interactions via
react-native-gesture-handler
State Management
Zustand (Primary)
import { create } from 'zustand';
import { persist } from 'zustand/middleware';
import AsyncStorage from '@react-native-async-storage/async-storage';
const useSettingsStore = create(
persist(
(set) => ({
displayCurrency: 'USD',
setDisplayCurrency: (currency) => set({ displayCurrency: currency }),
}),
{
name: 'settings-storage',
storage: AsyncStorage,
}
)
);
Features:
- Lightweight and fast
- AsyncStorage persistence
- Profile-scoped stores
- TypeScript-first
Redux (Legacy)
The app is migrating from Redux to Zustand. Avoid adding new Redux code.
redux 5.0.1
react-redux 9.1.2
redux-persist 6.0.0
redux-thunk 3.1.0
Bitcoin & Cashu
Cashu Protocol
Coco-Cashu - Complete Cashu implementation
import { CashuWallet, CashuMint } from 'coco-cashu-core';
// Source of truth for Cashu types and logic
// Never import from @cashu/cashu-ts directly
Supported NUTs:
- NUT-00 through NUT-13 (Core protocol)
- NUT-17 (WebSocket subscriptions)
- NUT-18 (Payment requests)
- NUT-23 (Backup and restore)
Bitcoin Utilities
Cryptography
Lightning
QR Codes
@noble/hashes - Hash functions
@scure/bip32 - HD key derivation
@scure/bip39 - Mnemonic generation
@gandlaf21/bolt11-decode - BOLT11 invoice parsing
- Lightning Network payment support
- Invoice generation and payment
react-native-qrcode-svg - QR generation
expo-camera - QR scanning with scanFromURLAsync
@gandlaf21/bc-ur - UR code support (multi-frame)
Know Your Mint
import { cashu-kym } from 'cashu-kym';
// Audit data from Cashu Auditor
// Community ratings via Nostr
// Success rates and swap times
Nostr Integration
NDK (Nostr Development Kit)
@nostr-dev-kit/ndk-mobile - Mobile-optimized NDK
import NDK from '@nostr-dev-kit/ndk-mobile';
// Nostr relay management
// Event publishing and subscriptions
// Profile data fetching
Nostr Utilities
nostr-tools 2.10.4
import { nip19, nip44, nip06 } from 'nostr-tools';
// NIP-04: Encrypted DMs (legacy)
// NIP-05: DNS-based verification
// NIP-06: BIP39 → Nostr keys
// NIP-17: Gift-wrapped DMs
// NIP-19: Bech32 encoding (npub, nsec, note)
// NIP-44: Encryption v2
// NIP-59: Gift wrap protocol
Implemented NIPs:
- NIP-04, NIP-05, NIP-06, NIP-17, NIP-19, NIP-44, NIP-59
- Kind 38000 events for mint recommendations
- Social graph for contact discovery
npubcash SDK
import { npubcash-sdk } from 'npubcash-sdk';
// Lightning address claiming
// Username availability checking
// Domain selection (npubx.cash, sovran.money)
Storage & Persistence
Secure Storage
expo-secure-store - Encrypted keychain storage
import * as SecureStore from 'expo-secure-store';
// BIP-39 mnemonic seeds
// Nostr private keys (nsec)
// Cashu wallet seeds
// Biometric authentication support
Databases
expo-sqlite - Local SQL databaseimport * as SQLite from 'expo-sqlite';
// Cashu proof storage
// Transaction history
// Mint data caching
@react-native-async-storage/async-storageimport AsyncStorage from '@react-native-async-storage/async-storage';
// Zustand persistence
// Settings storage
// Cache management
Native Features
Camera & Scanning
expo-camera 55.0.9
import { Camera, scanFromURLAsync } from 'expo-camera';
// QR code scanning
// Photo library QR import
// Multi-frame UR code support
// Torch control
NFC
react-native-nfc-manager 3.14.12
import NfcManager, { NfcTech } from 'react-native-nfc-manager';
// NDEF Type 4 Tag protocol
// Contactless payments
// NFC tag reading/writing
Configuration (app.json):
{
"selectIdentifiers": [
"D2760000850100",
"D2760000850101",
"5361746f63617368"
]
}
Location
expo-location 55.1.2
import * as Location from 'expo-location';
// GPS location stamping
// Transaction location privacy
// BTCMap nearby merchants
Other Native APIs
Haptics
expo-haptics - Tactile feedback
Clipboard
expo-clipboard - Copy/paste
Sharing
expo-sharing - Native share sheet
Biometrics
Via expo-secure-store
Maps & Geolocation
BTCMap Integration
expo-maps 55.0.9
import { MapView } from 'expo-maps';
import Supercluster from 'supercluster';
// Merchant discovery
// Category filtering
// Marker clustering (Supercluster)
// LRU cluster cache (max 3 entries)
Features:
- 24-hour merchant data TTL
- Viewport-based rendering
- Efficient clustering algorithm
AI Integration
Routstr
OpenAI SDK 6.9.1
import OpenAI from 'openai';
// Pay-per-use AI chat
// Multiple model providers
// Ecash-funded balance
// Sats-per-token pricing
Features:
- Session management
- Model switching
- Anonymous mode
- No subscription required
UI Components & Libraries
Navigation
React Navigation
Bottom Sheets
Action Sheet
@react-navigation/native 7.1.8
@react-navigation/native-stack 7.3.16
@react-navigation/drawer 7.3.9
@react-navigation/elements 2.6.3
@gorhom/bottom-sheet 5.2.8import BottomSheet from '@gorhom/bottom-sheet';
// Smooth gesture-based sheets
// Snap points
// Backdrop support
@expo/react-native-action-sheetimport { useActionSheet } from '@expo/react-native-action-sheet';
// Native action sheets
// iOS and Android support
Lists & Data Display
@legendapp/list - High-performance virtualized lists
import { List } from '@legendapp/list';
// Virtualized transaction list
// Date grouping
// Smooth scrolling
Visual Effects
Blur
expo-blur - Native blur effects
Gradient
expo-linear-gradient - Linear gradients
Liquid Glass
expo-liquid-glass-native - Glass morphism
Image Colors
react-native-image-colors - Color extraction
Theme System
Theme Configuration
37 Built-in Themes
// themes.ts
export const themes = [
// Color palette themes
{ name: 'Orange', colors: { ... } },
{ name: 'Purple', colors: { ... } },
// Background image themes
{ name: 'Nature', backgroundImage: require('...') },
// ... 37 total themes
];
Features:
- Dynamic color system
- Background image wallpapers
- Instant theme switching
- Dark mode by default
Styling Utilities
class-variance-authority - Variant-based styling
tailwind-variants - Tailwind variant utilities
tailwind-merge - Merge Tailwind classes
clsx - Class name composition
polished - Color manipulation
hex-color-opacity - Hex color with alpha
Code Quality
{
"extends": [
"expo",
"prettier"
],
"plugins": [
"prettier",
"unused-imports"
]
}
eslint 9.25.1
eslint-config-expo
eslint-config-prettier
eslint-plugin-unused-imports
{
"plugins": [
"prettier-plugin-tailwindcss"
]
}
- Auto-formatting
- Tailwind class sorting
Find unused exports and dependencies:
Testing
Jest
Unit testing with jest-expo
Maestro
E2E UI testing framework
Utility Libraries
General Utilities
- lodash - Utility functions
- neverthrow - Result type for error handling
- semver - Semantic versioning
- usehooks-ts - TypeScript React hooks
- buffer - Node.js Buffer API
- process - Process polyfill
- intl - Internationalization
- number-flow-react-native - Animated numbers
- unique-username-generator - Username generation
iOS
- Widgets - Home screen widgets via
expo-widgets
- SF Symbols - Via
expo-symbols
- Apple Targets - Multi-target support via
@bacons/apple-targets
Android
- NFC Permissions - Configured in
app.json
- Adaptive Icons - Configured in
app.json
Build Configuration
app.json
{
"expo": {
"name": "Sovran",
"slug": "sovran",
"version": "0.0.61",
"scheme": ["sovran", "cashu"],
"experiments": {
"typedRoutes": true,
"reactCompiler": true
}
}
}
EAS Build Profiles
Development
Preview
Production
{
"developmentClient": true,
"distribution": "internal",
"autoIncrement": true
}
{
"distribution": "internal",
"autoIncrement": true
}
{
"ios": {
"credentialsSource": "remote"
},
"autoIncrement": true
}
Next Steps
Getting Started
Set up your development environment
Project Structure
Understand the codebase organization
Scripts Reference
Complete guide to all available scripts
API Reference
Explore the API documentation