Skip to main content
Sovran is a React Native + Expo Router Bitcoin ecash wallet built with TypeScript, featuring Cashu protocol integration, Nostr identity, and NFC payments.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js (v18 or later recommended)
  • Yarn (v1.22.22 or later) - Package manager
  • Expo CLI - For running the development server
  • iOS Simulator (macOS only) or Android Emulator
  • Git - For version control

​
Installation

Clone the repository and install dependencies: 
git clone https://github.com/SovranBitcoin/Sovran.git
cd Sovran
yarn install

​
Post-Install

After installation, the postinstall script automatically runs patch-package to apply any necessary patches to dependencies.

​
Development Setup

​
Start Development Server

Launch the Expo development server: 
yarn start
This opens the Expo developer tools in your terminal, where you can:
  • Press i to open iOS simulator
  • Press a to open Android emulator
  • Scan the QR code with the Expo Go app on your physical device

​
Run on iOS

yarn ios
Alternatively, to start the iOS emulator directly: 
yarn start:emulator:ios

​
Run on Android

yarn android
Alternatively, to start the Android emulator directly: 
yarn start:emulator:android

​
Prebuild Native Projects

If you need to regenerate the native iOS and Android projects (after adding native dependencies or plugins): 
yarn prebuild
The prebuild command runs expo prebuild --clean, which clears existing native folders before generating new ones.

​
Code Quality Checks

Before committing any code, ensure all quality checks pass:

​
Run All Checks

yarn lint          # ESLint
yarn type-check    # TypeScript type checking
yarn pretty:check  # Prettier formatting check
yarn knip          # Find unused exports/dependencies
yarn test          # Jest tests
All five checks must pass before committing. This is enforced in the project’s contribution guidelines.

​
Format Code

Automatically format your code with Prettier: 
yarn pretty

​
Environment Configuration

​
Secure Storage

Sovran uses expo-secure-store for storing sensitive data like:
  • BIP-39 mnemonic seed phrases
  • Nostr private keys (derived via NIP-06)
  • Cashu wallet seeds
No additional configuration is required - secure storage works out of the box on both iOS and Android.

​
Deep Linking

The app supports two URL schemes:
  • cashu:// - For Cashu protocol URLs
  • sovran:// - For app-specific deep links
These are configured in app.json under the scheme property.

​
Development Best Practices

​
Code Structure

Follow the established architecture:
  • Routes go in app/ - keep screens thin, focus on orchestration
  • UI primitives go in components/ui/
  • Composed product UI goes in components/blocks/
  • Reusable hooks go in hooks/
  • Cashu-specific hooks go in hooks/coco/
  • Stateless utilities go in helper/
  • State management uses Zustand stores in stores/

​
Before You Code

Read the .cursor/rules/ documentation before working on specific domains:
DomainDocumentation
Popups, toasts, sheets.cursor/rules/popup-toast-sheet-guidelines.mdc
Secure storage, keys.cursor/rules/secure-storage-key-derivation.mdc
Text, typography.cursor/rules/text-typography-skeleton-guidelines.mdc
Theme, colors.cursor/rules/theme-system-architecture.mdc
Zustand stores.cursor/rules/zustand-store-scoping.mdc
Git workflow.cursor/rules/git-github-workflow.mdc

​
Security Guidelines

Never commit these files:
  • Mnemonics or seed phrases
  • nsec or private keys
  • API tokens or secrets
  • .env file contents
Always scan diffs before staging changes.

​
Next Steps

Project Structure

Understand the codebase organization

Tech Stack

Learn about the technologies used

Scripts Reference

Complete guide to all available scripts

API Reference

Explore the API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us