munin-bitcoin/docs/build-notes.md

Munin Bitcoin Build Notes

Current version

0.1.0

Completed

Milestone 1 — Working StartOS service

• StartOS package builds successfully
• Docker container starts correctly
• Service installs on physical StartOS server
• Web interface is served by nginx
• UTF-8 support verified
• Repository cleaned and structured

Milestone 2 — Fulcrum connectivity and live service status

• Fulcrum is configured as a StartOS dependency
• Munin receives the Fulcrum endpoint from StartOS
• Munin performs a real Electrum server.version connectivity check
• Status API reports Fulcrum configuration and connection state
• Verified status API response with fulcrum.connected: true
• Web interface displays Fulcrum (Electrum server)
• Web interface displays the Fulcrum connection status and endpoint
• Web interface displays wallet, label, transaction, and last-scan status
• Status can be refreshed from the web interface
• TypeScript check passes
• JavaScript bundle builds successfully
• Docker image builds successfully
• S9PK package builds successfully
• S9PK package was sideloaded and installed on the physical StartOS server
• Munin starts successfully after installation

Milestone 3 — Query Bitcoin data through Fulcrum

• Query blockchain data through the Fulcrum Electrum server
• Verify address and transaction queries
• Build the backend foundation for wallet monitoring
• Query current blockchain height through blockchain.headers.subscribe
• Display Fulcrum server version and blockchain height through the status API
• Display the current blockchain height in the Munin web interface
• Verify live blockchain height from the physical StartOS server
• Verify blockchain height display after rebuilding and reinstalling the S9PK package

Milestone 4 — Authentication and access control

• Add user authentication for the Munin web interface
• Require authentication before accessing wallet and monitoring data
• Add password management through StartOS Actions & Config
• Store the Munin admin password in the persistent StartOS main volume
• Pass the stored admin password to the Munin container through MUNIN_ADMIN_PASSWORD
• Protect the status API from unauthenticated access
• Use secure, HTTP-only, SameSite session cookies
• Use cryptographically random session tokens
• Use constant-time password comparison
• Expire sessions after 24 hours
• Clean up expired sessions periodically
• Display a login form in the web interface
• Display authentication errors in the web interface
• Verify authentication on the physical StartOS server
• Verify that the configured password survives a package update
• Verify that authenticated access to the status API continues to work after the package update
• Verify that the existing password remains valid after rebuilding and reinstalling the S9PK package

Current architecture

• StartOS package
• Alpine Linux container
• nginx serving the web interface
• Node.js status API
• Static dashboard in web/index.html
• Fulcrum provided as a StartOS dependency
• Electrum protocol connectivity check from Munin to Fulcrum
• Blockchain height queried through Fulcrum
• Blockchain height displayed in the web interface
• StartOS main volume used for persistent Munin data
• Admin password stored persistently in the StartOS main volume
• Session-based authentication for the web interface

Current status

Munin Bitcoin is running as a StartOS service and can verify connectivity to the configured Fulcrum Electrum server.

Munin can query the current Bitcoin blockchain height through Fulcrum and display it in the web interface.

The Munin web interface is protected by password authentication.

The admin password can be configured through StartOS Actions & Config and is stored in the persistent main volume so that it survives package updates and reinstallations.

Authentication and password persistence have been verified on the physical StartOS server, including verification that an existing password remains valid after rebuilding and reinstalling the package.

Bitcoin Core RPC is not currently used by Munin.

Wallet configuration, label storage, transaction scanning, and notification functionality are not yet implemented.

Next steps

Milestone 5 — Address watchlist

• Add watch-only Bitcoin addresses
• Store monitored addresses persistently
• Display address activity and UTXOs
• Display transaction history

Milestone 6 — xpub watch-only wallets

• Import xpub-based watch-only wallets
• Derive addresses for monitoring
• Support common extended public key formats
• Track wallet activity without private keys

Milestone 7 — BSMS multisig wallets

• Import BSMS wallet files
• Support multisig wallet/watch-only configuration
• Monitor multisig wallet addresses and transactions
• Keep private signing material out of Munin

Milestone 8 — BIP-329 labels

• Import BIP-329 labels
• Export BIP-329 labels
• Store and manage labels persistently
• Associate labels with relevant Bitcoin objects

Milestone 9 — Notifications

• Add NTFY notifications
• Add email notifications through SMTP
• Allow notification settings to be configured per wallet
• Support notifications for new transactions
• Support notifications for relevant wallet/UTXO changes
• Use the NTFY documentation and Start9 SMTP packaging examples as implementation references

Milestone 10 — PWA

• Make the web interface a fully installable PWA
• Add responsive desktop and mobile layouts
• Add service worker and application manifest
• Improve offline application-shell behaviour
• Polish wallet, transaction, label, and notification views