Installation

Download and install Sovran on iOS and Android devices

Installation

Sovran is available for iOS and Android. Follow the instructions below to install on your device.

Requirements

iOS

• iOS 13.0 or later
• iPhone only (iPad not supported)
• Camera permission for QR code scanning
• Optional: NFC-capable device for tap-to-pay payments

Android

• Android 5.0 (API level 21) or later
• Camera permission for QR code scanning
• Optional: NFC support for contactless payments

Download

iOS App Store

Download for iPhone

Android Play Store

Download for Android

Sovran is currently in active development. Check the GitHub repository for the latest release information and beta builds.

iOS Installation

From App Store

1. Open App Store

   Navigate to the App Store on your iOS device.

2. Search for Sovran

   Search for “Sovran Bitcoin Wallet” or use the direct link above.

3. Download and Install

   Tap Get to download and install. You may need to authenticate with Face ID, Touch ID, or your Apple ID password.

4. Grant Permissions

   On first launch, Sovran will request:

   • Camera: Required for scanning QR codes for payments
   • Photo Library (optional): To import QR codes from images
   • Location (optional): For BTCMap merchant discovery and transaction location stamps
   • Motion (optional): For parallax visual effects
   • NFC (optional): For contactless tap-to-pay

   // From app.json — iOS permissions
   {
     "NSCameraUsageDescription": "Sovran uses your camera to scan QR codes for payments",
     "NSPhotoLibraryUsageDescription": "Choose images with QR codes to scan",
     "NSLocationWhenInUseUsageDescription": "Show nearby merchants and add location to transactions",
     "NSMotionUsageDescription": "Create subtle parallax and visual effects",
     "NFCReaderUsageDescription": "Send and receive contactless payments"
   }
   

Development Build (TestFlight)

For beta testing or development builds:

# Build iOS for development using EAS
yarn build:dev:ios

# Submit to App Store
yarn submit:ios

Development builds are not available in the App Store. Use EAS Build for internal testing or TestFlight distribution.

Android Installation

From Play Store

1. Open Play Store

   Navigate to Google Play Store on your Android device.

2. Search for Sovran

   Search for “Sovran Bitcoin Wallet” or use the direct link above.

3. Install

   Tap Install to download and install the app.

4. Grant Permissions

   On first launch, grant the following permissions:

   • Camera: Required for QR code scanning
   • NFC (optional): For contactless payments

   // From app.json — Android permissions
   {
     "permissions": [
       "android.permission.CAMERA",
       "android.permission.RECORD_AUDIO",
       "android.permission.NFC"
     ]
   }
   

APK Installation

For direct APK installation (advanced users):

# Build Android APK for preview
yarn build:android:apk

# Submit to Play Store
yarn submit:android

Direct APK installation requires enabling “Install from Unknown Sources” in your Android settings. This is not recommended for most users.

Building from Source

Advanced users can build Sovran from source code.

Prerequisites

# Required tools
- Node.js 18 or later
- Yarn 1.22.22 or later
- Expo CLI
- Xcode (iOS) or Android Studio (Android)

Clone and Install

# Clone the repository
git clone https://github.com/SovranBitcoin/Sovran.git
cd Sovran

# Install dependencies
yarn install

# Apply patches
yarn postinstall

Development

# Start Expo development server
yarn start

# Run on iOS simulator
yarn ios

# Run on Android emulator
yarn android

# Run on physical device
yarn start:emulator:ios    # iOS
yarn start:emulator:android # Android

Code Quality Checks

Before committing, ensure all checks pass:

# Run all checks
yarn lint          # ESLint
yarn type-check    # TypeScript
yarn pretty:check  # Prettier formatting
yarn knip          # Find unused exports/dependencies
yarn test          # Jest tests

All five checks must pass before any commit. See .cursor/rules/git-github-workflow.mdc for full git workflow requirements.

Production Builds

# Prebuild native projects
yarn prebuild

# Build for iOS (production)
yarn build:ios

# Build for Android (APK preview)
yarn build:android:apk

Configuration

App Metadata

From app.json:

{
  "expo": {
    "name": "Sovran",
    "slug": "sovran",
    "version": "0.0.61",
    "scheme": ["sovran", "cashu"],
    "userInterfaceStyle": "dark",
    "ios": {
      "bundleIdentifier": "com.sovranbitcoin",
      "buildNumber": "1"
    },
    "android": {
      "package": "com.sovranbitcoin",
      "versionCode": 2
    }
  }
}

Deep Link Schemes

Sovran supports two URI schemes for deep linking:

• sovran:// - Sovran-specific deep links
• cashu:// - Cashu token standard

// File: hooks/useDeeplink.ts
// Processes cashu:// and sovran:// URLs
// Automatically routes to appropriate screen

Post-Installation

First Launch

On first launch, Sovran will:

1. Generate a BIP-39 seed phrase
2. Store it securely using expo-secure-store
3. Derive Nostr keys via NIP-06
4. Show terms and conditions
5. Present onboarding carousel

// File: components/blocks/AppGate.tsx
// Gate order: Terms → Onboarding → Keys → App

Data Storage

Sovran stores data locally:

• Secure Store: Seed phrase, Nostr private keys (encrypted)
• AsyncStorage: Settings, preferences, transaction history
• SQLite: Cashu proofs and wallet state (via coco-cashu-expo-sqlite)

// From package.json
{
  "dependencies": {
    "expo-secure-store": "~55.0.8",
    "@react-native-async-storage/async-storage": "2.2.0",
    "expo-sqlite": "~55.0.10",
    "coco-cashu-expo-sqlite": "1.1.2-rc.47"
  }
}

All data is stored locally on your device. Sovran does not transmit your seed phrase, private keys, or transaction data to any server.

Troubleshooting

iOS Installation Issues

Error: “Untrusted Developer”

If installing a development build:

1. Go to Settings → General → VPN & Device Management
2. Trust the developer certificate

Camera Permission Denied

1. Go to Settings → Sovran
2. Enable Camera permission

Android Installation Issues

Error: “App not installed”

• Ensure you have enough storage space
• Check that “Install from Unknown Sources” is enabled (APK only)
• Uninstall any previous versions first

NFC Not Working

Some Android devices require:

1. Settings → Connected devices → Connection preferences
2. Enable NFC

Build Issues

Metro bundler errors

# Clear Metro cache
npx expo start --clear

# Reset node_modules
rm -rf node_modules
yarn install

Native build errors

# Clean prebuild
yarn prebuild --clean

# iOS: Clean build folder
cd ios && xcodebuild clean && cd ..

# Android: Clean gradle
cd android && ./gradlew clean && cd ..

System Requirements

Minimum Hardware

• RAM: 2GB minimum, 4GB recommended
• Storage: 200MB for app, additional space for transaction data
• Network: Internet connection required for Lightning payments and Nostr features

Supported Features by Platform

Feature	iOS	Android
Cashu Ecash	✅	✅
Lightning	✅	✅
Nostr DMs	✅	✅
NFC Payments	✅	✅
QR Scanning	✅	✅
Biometric Lock	✅	✅
Background Fetch	✅	Limited

Version Information

From package.json:

{
  "name": "Sovran",
  "version": "1.0.0",
  "dependencies": {
    "expo": "^55.0.4",
    "react-native": "0.83.2",
    "coco-cashu-core": "^1.1.2-rc.47",
    "@nostr-dev-kit/ndk-mobile": "^0.2.2"
  }
}

Current Version: 0.0.61 (build 1 for iOS, versionCode 2 for Android)

Next Steps

After installation, proceed to the Quick Start Guide to set up your wallet and make your first payment.

Quick Start

Set up your wallet in minutes

Security Guide

Learn how to keep your Bitcoin safe

GitHub Issues

Report bugs or request features

Community

Join the Sovran community