Mostro Mobile Client

March 20, 2026 · View on GitHub

Ask questions about this project using DeepWiki AI

A modern, secure mobile client for the Mostro peer-to-peer Bitcoin trading platform.

This is a fully-featured mobile application that enables secure, private, and decentralized Bitcoin trading over the Lightning Network using the Nostr protocol. Built with Flutter, it provides a native mobile experience for conducting peer-to-peer trades with advanced privacy features and modern UI/UX design.

🌟 Key Features

🛡️ Privacy-First Architecture: Advanced encryption with NIP-59 gift wrapping for all trade communications
🔑 Hierarchical Key Management: BIP-32/BIP-39 compliant key derivation with unique keys per trade
🌍 Multi-Language Support: Full internationalization in English, Spanish, and Italian
⚡ Lightning Network Integration: Seamless Bitcoin Lightning payments and invoicing
🔄 Real-Time Trading: Live order book updates and instant messaging with counterparts
🎨 Modern UI/UX: Card-based interfaces, smooth animations, and intuitive navigation
🔒 Secure Storage: Hardware-backed secure storage for cryptographic keys
📱 Cross-Platform: Native performance on both Android and iOS
🌐 Decentralized: No central authority, operates entirely on Nostr relays

📱 App Screenshots

Main Trading Interface

Order book with buy/sell orders and real-time trading interface

The heart of Mostro Mobile - browse available Bitcoin buy/sell orders with real-time updates, filter by currency and payment methods, and start trading with a single tap.

Secure Trade Execution

Take orders seamlessly with detailed trade information, Lightning invoice handling, and step-by-step guidance through the complete trade process.

Account

You can backup your identity writing down 12 secret words.

Modern Settings Interface

Configure your trading preferences, add relays, customize the interface, and control notifications through the intuitive settings panel.

Account & Profile Management

Check your App and Mostro node settings in about screen.

Prerequisites

For the Mobile Client

Install Flutter: Follow the official guide for your operating system.
Install Android Studio or Xcode (for iOS development)
Install VS Code (optional but recommended)

For Mostro Daemon

Install Rust
Install Docker

For Testing Environment

Install Polar: For simulating Lightning Network nodes

Installation

Clone the repository:

git clone https://github.com/MostroP2P/mobile.git
cd mobile

Install Flutter dependencies:
```
flutter pub get
```
Generate required files (REQUIRED STEP):
```
dart run build_runner build -d
```

⚠️ IMPORTANT: This step is mandatory and must be run after cloning the repository. It generates code files (*.g.dart, *.mocks.dart) required for the app to compile and run. These generated files are not committed to the repository and are automatically recreated in CI/CD pipelines.

You will need to run this command again whenever you:

Update localization files (lib/l10n/*.arb)

Modify files that use code generation (Riverpod providers, JSON serialization, etc.)

Pull changes that affect generated code

If you see compilation errors about missing files or imports, run this command again.

Running the App

On Emulator/Simulator

flutter run

On Physical Device

Connect your device and run:

flutter run

Linux Desktop

If you want to run it on a Linux Desktop install this dependencies (ubuntu):

sudo apt update
sudo apt install -y build-essential g++ gcc cmake ninja-build pkg-config libgtk-3-dev binutils libsecret-1-dev

Then run:

flutter run -d linux

Using Custom Mostro Public Key

By default, the app uses the production Mostro public key. For development or testing with a different Mostro daemon, you can specify a custom public key using the MOSTRO_PUB_KEY environment variable:

# For development/testing
flutter run --dart-define=MOSTRO_PUB_KEY=your_custom_mostro_public_key

# Example with a test key
flutter run --dart-define=MOSTRO_PUB_KEY=0a537332f2d569059add3fd2e376e1d6b8c1e1b9f7a999ac2592b4afbba74a00

This is particularly useful when:

Testing with a local Mostro daemon
Using different Mostro instances for development
Running integration tests with specific configurations

Setting up Mostro Daemon

Clone the Mostro repository:

git clone https://github.com/MostroP2P/mostro.git
cd mostro

Set up the configuration:
```
cp settings.tpl.toml settings.toml
```
Edit settings.toml with your specific configurations.
Run the Mostro daemon:
```
cargo run
```

See the README.md in the mostro repository for more details.

Setting up Polar for Testing

Launch Polar and create a new Lightning Network.
Configure at least one node (e.g., "alice").
Copy the necessary connection details (cert file, macaroon file) to your Mostro settings.toml.

Development Workflow

Ensure Polar is running with your test Lightning Network.
Start the Mostro daemon.
Run the Flutter app and connect it to your local Mostro instance.

🏗️ Architecture

Core Technologies

Flutter: Cross-platform mobile framework with native performance
Riverpod: Reactive state management for predictable app behavior
Nostr Protocol: Decentralized communication layer (NIPs 01, 06, 44, 59, 69)
Sembast: Local NoSQL database for data persistence
dart_nostr: Comprehensive Nostr protocol implementation

Security & Privacy

NIP-59 Gift Wrapping: Three-layer encryption (Rumor → Seal → Wrapper)
Hierarchical Deterministic Keys: BIP-32 key derivation with trade-specific keys
Forward Secrecy: Ephemeral keys for enhanced privacy protection
Secure Storage: Platform-native secure storage for sensitive data
Key Rotation: Automatic rotation prevents transaction linking

Communication Flow

Mobile App ←→ Nostr Relays ←→ Mostro Daemon ←→ Lightning Network
     ↓              ↓              ↓              ↓
  UI Layer    WebSocket Conn.  Order Matching  Bitcoin Payments

For detailed technical documentation, see docs/architecture/.

🔧 Development Commands

Essential Commands

# Install dependencies
flutter pub get

# Generate localization and code files (required after dependency changes)
dart run build_runner build -d

# Run the application
flutter run

# Code analysis and linting
flutter analyze

# Format code
flutter format .

# Run tests
flutter test
flutter test integration_test/

Code Quality

This project maintains zero Flutter analyze issues and follows modern Flutter best practices:

Updated to latest APIs (no deprecated warnings)
Comprehensive error handling with proper BuildContext usage
Immutable widgets with const constructors where possible
Proper async/await patterns with mounted checks

🎨 Recent UI/UX Improvements

Modern Interface Design

Card-based Settings: Clean, organized settings interface with visual hierarchy
Enhanced Account Screen: Streamlined user profile and preferences
Currency Integration: Visual currency flags for international trading
Improved Navigation: Smooth page transitions with consistent routing
Better Visual Feedback: Loading states, error handling, and user confirmations

Accessibility & Usability

Multi-language Support: Comprehensive localization with proper time formatting
Responsive Design: Optimized layouts for various screen sizes
Icon Improvements: Enhanced notification and app launcher icons
Touch Interactions: Improved button responses and gesture handling

📚 Documentation

User Guides

ADDING_NEW_LANGUAGE.md - Complete localization guide
CLAUDE.md - Development environment setup and project conventions

Technical Documentation

docs/architecture/ - Complete technical documentation and system architecture
Code Documentation: Inline documentation following Dart conventions