Skip to main content
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

Language & Tooling

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

Build Tools

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

Primary component library for Sovran
import { Button, Card } from 'heroui-native';
  • Native-first components
  • Theme integration
  • Hero transition animations

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

  • @noble/hashes - Hash functions
  • @scure/bip32 - HD key derivation
  • @scure/bip39 - Mnemonic generation

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 database
import * as SQLite from 'expo-sqlite';

// Cashu proof storage
// Transaction history
// Mint data caching

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

  • @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

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

Developer Tools

Code Quality

{
  "extends": [
    "expo",
    "prettier"
  ],
  "plugins": [
    "prettier",
    "unused-imports"
  ]
}
  • eslint 9.25.1
  • eslint-config-expo
  • eslint-config-prettier
  • eslint-plugin-unused-imports

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

Data Formatting

  • intl - Internationalization
  • number-flow-react-native - Animated numbers
  • unique-username-generator - Username generation

Platform-Specific

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

{
  "developmentClient": true,
  "distribution": "internal",
  "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

Build docs developers (and LLMs) love