Getting Started

Set up your development environment for Sovran

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:

yarn

git clone https://github.com/SovranBitcoin/Sovran.git
cd Sovran
yarn install

git clone https://github.com/SovranBitcoin/Sovran.git
cd Sovran
npm 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

yarn start

npm 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

yarn ios

npm run ios

Alternatively, to start the iOS emulator directly:

yarn

yarn start:emulator:ios

npm run start:emulator:ios

Run on Android

yarn

yarn android

npm run android

Alternatively, to start the Android emulator directly:

yarn

yarn start:emulator:android

npm run start:emulator:android

Prebuild Native Projects

If you need to regenerate the native iOS and Android projects (after adding native dependencies or plugins):

yarn

yarn prebuild

npm run 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

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

npm run lint
npm run type-check
npm run pretty:check
npm run knip
npm test

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

yarn pretty

npm run 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:

Domain	Documentation
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