How satoshiportal/bullbitcoin-mobile works
This project is a mobile wallet application (“Bull Bitcoin Mobile”) built using Flutter that supports self-custodial Bitcoin and Liquid Network functionality. In other words, it is a full-stack mobile wallet that integrates multiple Bitcoin protocols, swap features, fee estimations, payjoin, hardware wallet support, and even integration with exchange services. The codebase employs a well-organized separation of concerns with distinct layers (e.g., UI, domain, data, and external integrations) and utilizes patterns like BLoC for state management.
Main Components
• Mobile Client UI: Represented by the “lib/ui”, “lib/features” (onboarding, home, send, receive, settings, pin_code, etc.) directories. This layer includes all the widget definitions, screens, and presentation logic.
• Application/State Management Layer: With extensive use of BLoC in “lib/features/*/presentation/bloc”, this layer manages state and user interactions.
• Domain Layer: Found in “lib/core/*/domain” and “lib/features/*/domain”. This encompasses entities, use cases, and business logic (for wallet operations, fee estimation, coin selection, swap management, and more).
• External Services and Libraries: Dependencies such as bdk, bdk-flutter, lwk, boltz-dart, and integration with external APIs (mempool.space, electrum servers, etc.) are referenced both in documentation (README) and through dedicated directories (like “op”, “doc”, etc).
• Platform-Specific Integrations: The Android, iOS, linux, macos directories indicate platform-specific implementations and integration points provided by Flutter. This points to native code wrappers or integration layers used for device functionalities (like secure storage and network access).
• DevOps and CI/CD: Presence of the “.github/workflows”, build scripts, and configuration files that manage analysis, building, and release processes.
Relationships and Data Flow
• The UI (presentation layer) dispatches events (via BLoC) that invoke use cases in the domain layer.
• Use cases call repository interfaces implemented in the data layer, which in turn fetch data either from local storage (secure storage via Hive or similar under “lib/core/storage”) or remote external services (e.g., fee estimators, electrum servers).
• External libraries and dependencies (e.g., bdk-flutter for wallet operations) act as building blocks within the domain and data layers.
• The mobile client also interacts with external APIs for exchange rate data, blockchain data, and swap services. Represent these with external connectors.
• Platform-specific modules (android, ios, etc.) provide the necessary bridge or wrapper services to ensure the mobile app interacts securely with device resources.
Architectural Patterns and Principles
• Layered Architecture: Clear separation between UI, state management, domain logic, and data sources.
• Repository Pattern: Interfacing between domain and data layers, ensuring testability and abstraction over data sources.
• Use Case (Interactor) Pattern: Each operation (wallet creation, fee estimation, coin selection, payjoin processing, etc.) is encapsulated as a use case.
• Modularization: Features and core services are split into different directories (e.g., “lib/features” for UI and specific flows, “lib/core” for business logic and external integrations).
• State Management: The extensive use of the BLoC pattern to manage app state and facilitate UI updates.
Relevant Technologies and Integrations
• Flutter (UI framework) with platform-specific adaptations for Android, iOS, macOS, and Linux.
• BDK, BDK-Flutter, and LWK for wallet backend functionality.
• Boltz and boltz-dart for atomic swaps.
• External APIs for mempool fee estimation, electrum servers for blockchain data, and Bull Bitcoin exchange for fiat-to-BTC interactions.