Tech Stack - Sovran

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

HeroUI Native
RN Primitives
Expo UI

Primary component library for Sovran

import { Button, Card } from 'heroui-native';

Native-first components
Theme integration
Hero transition animations

Low-level accessible primitives

import { Checkbox } from '@rn-primitives/checkbox';

Checkbox component
Accessibility built-in

Expo’s UI component library

import { 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

SQLite
AsyncStorage

expo-sqlite - Local SQL database

import * as SQLite from 'expo-sqlite';

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

@react-native-async-storage/async-storage

import 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

React Navigation
Bottom Sheets
Action Sheet

@gorhom/bottom-sheet 5.2.8

import BottomSheet from '@gorhom/bottom-sheet';

// Smooth gesture-based sheets
// Snap points
// Backdrop support

@expo/react-native-action-sheet

import { 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

Developer Tools

Code Quality

ESLint
Prettier
Knip

{
  "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:

yarn knip

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

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

Development

Architecture

Protocol Support

Contributing

Documentation Index

​Core Framework

​React Native & Expo

React 19.2.0

React Native 0.83.2

Expo SDK 55

Expo Router 55

​Language & Tooling

​TypeScript

​Build Tools

Babel

Metro

EAS Build

​UI & Styling

​Styling System

​UI Libraries

​Icons & Graphics

​Animation

​State Management

​Zustand (Primary)

​Redux (Legacy)

​Bitcoin & Cashu

​Cashu Protocol

​Bitcoin Utilities

​Know Your Mint

​Nostr Integration

​NDK (Nostr Development Kit)

​Nostr Utilities

​npubcash SDK

​Storage & Persistence

​Secure Storage

​Databases

​Native Features

​Camera & Scanning

​NFC

​Location

​Other Native APIs

Haptics

Clipboard

Sharing

Biometrics

​Maps & Geolocation

​BTCMap Integration

​AI Integration

​Routstr

​UI Components & Libraries

​Navigation

​Lists & Data Display

​Visual Effects

Blur

Gradient

Liquid Glass

Image Colors

​Theme System

​Theme Configuration

​Styling Utilities

​Developer Tools

​Code Quality

​Testing

Jest

Maestro

​Utility Libraries

​General Utilities

​Data Formatting

​Platform-Specific

​iOS

​Android

​Build Configuration

​app.json

​EAS Build Profiles

​Next Steps

Getting Started

Project Structure

Scripts Reference

API Reference

Core Framework

React Native & Expo

Language & Tooling

TypeScript

Build Tools

UI & Styling

Styling System

UI Libraries

Icons & Graphics

Animation

State Management

Zustand (Primary)

Redux (Legacy)

Bitcoin & Cashu

Cashu Protocol

Bitcoin Utilities

Know Your Mint

Nostr Integration

NDK (Nostr Development Kit)

Nostr Utilities

npubcash SDK

Storage & Persistence

Secure Storage

Databases

Native Features

Camera & Scanning

NFC

Location

Other Native APIs

Maps & Geolocation

BTCMap Integration

AI Integration

Routstr

UI Components & Libraries

Navigation

Lists & Data Display

Visual Effects

Theme System

Theme Configuration

Styling Utilities

Developer Tools

Code Quality

Testing

Utility Libraries

General Utilities

Data Formatting

Platform-Specific

iOS

Android

Build Configuration

app.json

EAS Build Profiles

Next Steps