Mostro Mobile Client

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

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

1. Clone the repository:

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

2. Install Flutter dependencies:

   flutter pub get

3. 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

1. Clone the Mostro repository:

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

2. Set up the configuration:

   cp settings.tpl.toml settings.toml

   Edit settings.toml with your specific configurations.

3. Run the Mostro daemon:

   cargo run

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

Setting up Polar for Testing

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

Development Workflow

1. Ensure Polar is running with your test Lightning Network.
2. Start the Mostro daemon.
3. 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/
# Run tests and produce a coverage report
flutter test --coverage
dart run tool/coverage_report.dart

🧪 Test Coverage

Current line coverage: 33.00% (6,498 of 19,689 lines), across 952 tests.

The figure comes from the LCOV records, that is, from every non-generated file flutter test --coverage instrumented. Generated sources (lib/generated/**, *.g.dart, *.freezed.dart, *.mocks.dart) are excluded because build_runner re-creates them on every build; counting them would distort the number.

Checking coverage yourself

flutter pub get
dart run build_runner build -d # generates mocks and localization
flutter test --coverage # writes coverage/lcov.info
dart run tool/coverage_report.dart # prints the summary

tool/coverage_report.dart reads coverage/lcov.info and prints total line coverage, the number of files measured, and any lib/ file that no test ever loaded. Those untouched files are listed as a warning so they are visible instead of vanishing the way a plain lcov summary would hide them. They carry no instrumented lines, so they are not part of the percentage: --min can pass while they remain unmeasured. Import a file from a test to bring it into the measured set.

Useful flags:

# List the files with the most uncovered lines
dart run tool/coverage_report.dart --top 20
# Fail with a non-zero exit code below a threshold (handy in CI)
dart run tool/coverage_report.dart --min 33

For an annotated HTML report, lcov works on the same file:

genhtml coverage/lcov.info -o coverage/html && open coverage/html/index.html

What is and is not covered

• Well covered: protocol models and payloads, enums, the order state machine (MostroFSM, OrderState), relay models, shared utilities, and most presentational widgets plus the settings, logs and wallet screens.
• Thin or uncovered: main.dart and platform bootstrap, background and push-notification services, Firebase glue, the restore manager, and the long-lived Nostr/subscription notifiers. These need a live relay, a platform channel, or a substantial mocking harness, so they are exercised by integration_test/ rather than by unit tests.

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

🚀 Contributing

We welcome contributions of all sizes! Here's how to get started:

Development Setup

1. Read CLAUDE.md for project conventions and development commands
2. Ensure flutter analyze returns zero issues before submitting
3. Run tests to verify your changes don't break existing functionality
4. Follow existing code patterns and architectural decisions

Adding New Features

• Study existing features in lib/features/ for implementation patterns
• Use Riverpod for state management and dependency injection
• Implement proper localization for all user-facing strings
• Add appropriate tests for new functionality

Language Support

📖 ADDING_NEW_LANGUAGE.md - Step-by-step instructions for adding new language support

Currently supported languages:

• English (en) - Base language
• Spanish (es) - Complete translation
• Italian (it) - Complete translation

License

This project is licensed under the MIT License. See the LICENSE file for details.

✅ Feature Progress

🎯 Core Trading Features

• Order Management: Create, display, and manage buy/sell orders
• Order Execution: Take orders with full buy/sell flow support
• Real-Time Updates: Live order book updates via Nostr subscriptions
• Lightning Integration: Lightning address support for seamless payments
• Trade Lifecycle: Complete order-to-completion flow management
• Order Cancellation: Maker cancellation and cooperative cancellation

💬 Communication & Chat

• Peer-to-Peer Messaging: Secure direct messaging with trade counterparts
• Trade Chat: Integrated chat for each trading session
• Real-Time Chat: Live messaging with message delivery confirmation
• Encrypted Communications: NIP-59 gift wrapping for all trade messages

🔐 Security & Privacy

• Hierarchical Key Management: BIP-32/BIP-39 compliant key derivation
• Trade-Specific Keys: Unique key pairs for each trading session
• Secure Storage: Hardware-backed storage for cryptographic keys
• Privacy Controls: Configurable privacy settings and reputation tracking

🌐 User Experience

• Multi-Language Support: English, Spanish, and Italian localization
• Modern UI Design: Card-based interfaces with smooth animations
• Settings Management: Comprehensive settings and preferences
• User Rating System: Rate counterparts after successful trades
• Push Notifications: Real-time trade and message notifications
• Enhanced Icons: Improved app launcher and notification icons

🛠️ Technical Achievements

• Zero Analyzer Issues: Clean codebase following Flutter best practices
• Modern APIs: Updated to latest Flutter APIs, no deprecated warnings
• Comprehensive Testing: Unit and integration test coverage
• Code Generation: Automated localization and mock generation
• Background Services: Reliable background processing for notifications

🚧 Planned Features

• Invoice Recovery: Add new invoice if payment fails
• Multi-Relay Support: Advanced relay management and failover
• Dispute Resolution: User-initiated dispute flow
• Admin Tools: Dispute management interface for administrators
• Tor Integration: Anonymous relay connections

📊 Platform Status

• ✅ Android: Full feature support with native performance
• ✅ iOS: Complete iOS implementation with platform-specific optimizations
• ✅ Security: Production-ready cryptographic implementation
• ✅ Localization: Complete translation coverage for supported languages
• ✅ Documentation: Comprehensive technical and user documentation