How sparrowwallet/sparrow works
Main components
• User Interface (UI) Layer:
– Built with JavaFX.
– FXML and CSS files in the resources (e.g., app.fxml, dialog.css, various FXML files in “com/sparrowwallet/sparrow/…”).
– Terminal and window/dialog components (e.g., controllers in terminal/wallet, AboutController, WelcomeController, etc.).
• Core Business Logic & Wallet Management:
– Packages like “com/sparrowwallet/sparrow/wallet”, “com/sparrowwallet/sparrow/transaction”, “com/sparrowwallet/sparrow/io”, and “com/sparrowwallet/sparrow/instance”.
– Domain classes managing transactions, keystores, wallet configurations, and handling the wallet’s life cycle.
• Networking & Blockchain Interaction:
– Network packages (“com/sparrowwallet/sparrow/net” and its subpackages including Electrum, Tor, and bitcoind integrations).
– Classes managing connectivity, fee rates, and event handling for blockchain (e.g., new block notifications).
• Hardware Wallet & External Device Integrations:
– Lots of “io” subpackages such as “ckcard”, “satochip”, “paynym” and others that encapsulate protocols for interfacing with hardware wallets.
– These components expose APIs that send commands to or receive data from external hardware devices.
• Persistence & Database:
– “io/db” package with DAO classes and mappers for wallet and transaction persistence.
– SQL scripts in “resources/com/sparrowwallet/sparrow/sql” marking the evolution of the database.
• Build and Deployment Infrastructure:
– Gradle build scripts, custom build tasks under “buildSrc” (especially for JavaFX handling), and deployment configurations found in “src/main/deploy” – which are responsible for packaging binaries for Linux, OS X, and Windows.
– Also, native libraries placed in “src/main/resources/native” are used to interact with platform-specific functions (such as JNI for Bitcoin Core connectivity, ZBar, etc.).
• Event Management & Services:
– An extensive events package (“com/sparrowwallet/sparrow/event”) that handles error/status/transaction notifications, ensuring decoupled communication between modules.
Relationships and interactions
• The UI Layer communicates with the Business Logic layer via controllers and event listeners.
• Business Logic interacts with Persistence (via DAOs) to store wallet details and transaction histories and with Networking services to request data from external Bitcoin nodes or Electrum servers.
• Dedicated modules handle hardware wallet communications and expose interfaces to the rest of the application.
• The build system, configured via Gradle scripts (with custom JavaFX plugins), integrates the overall project into native executables and installers and separates configurations for different networks (mainnet, testnet, etc.).
• The event system serves as the glue that decouples UI, network responses, and wallet updates, using directional events to signal state changes.
Architectural patterns and design principles
• Modular Design: Clearly separated packages for UI, core logic, networking, persistence, and hardware interfacing.
• MVC/MVVM Pattern: Controllers and FXML files suggest a typical JavaFX design pattern separating view logic from business logic.
• Event-Driven Architecture: Numerous event classes indicate observers and listeners are widely used for inter-module communication.
• Cross-Platform Deployment: Native resource directories and different deployment packages show that platform-specific concerns are abstracted away from core modules.
Technologies, frameworks, or libraries to note
• Java 22 (required runtime version) and JavaFX for the GUI.
• Gradle (with custom build scripts under “buildSrc”) for build automation and packaging (using jpackage, WiX for Windows installers, etc.).
• JDBC or similar persistence frameworks for database interactions, given the presence of SQL scripts and DAOs.
• External integrations such as Tor, Electrum servers, and hardware wallet API implementations.