Tech Stack

Technologies and frameworks powering 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

Primary component library for Sovran

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

• Native-first components
• Theme integration
• Hero transition animations

RN Primitives

Low-level accessible primitives

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

• Checkbox component
• Accessibility built-in

Expo UI

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

Core

import { CashuWallet, CashuMint } from 'coco-cashu-core';

// Source of truth for Cashu types and logic
// Never import from @cashu/cashu-ts directly

import { useWallet, useProofs } from 'coco-cashu-react';

// React integration hooks

import { SQLiteStorage } from 'coco-cashu-expo-sqlite';

// Expo SQLite adapter for proof storage

import { NPCPlugin } from 'coco-cashu-plugin-npc';

// Nostr Payment Code plugin

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

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

Lightning

• @gandlaf21/bolt11-decode - BOLT11 invoice parsing
• Lightning Network payment support
• Invoice generation and payment

QR Codes

• 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

expo-sqlite - Local SQL database

import * as SQLite from 'expo-sqlite';

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

AsyncStorage

@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

Navigation

React Navigation

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

Bottom Sheets

@gorhom/bottom-sheet 5.2.8

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

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

Action Sheet

@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

{
  "extends": [
    "expo",
    "prettier"
  ],
  "plugins": [
    "prettier",
    "unused-imports"
  ]
}

• eslint 9.25.1
• eslint-config-expo
• eslint-config-prettier
• eslint-plugin-unused-imports

Prettier

{
  "plugins": [
    "prettier-plugin-tailwindcss"
  ]
}

• Auto-formatting
• Tailwind class sorting

Knip

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

{
  "developmentClient": true,
  "distribution": "internal",
  "autoIncrement": true
}

Preview

{
  "distribution": "internal",
  "autoIncrement": true
}

Production

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