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
• Verify live blockchain height from the physical StartOS server

Milestone 4 — Authentication and access control

• Add password authentication for the Munin web interface
• Require authentication before accessing the status API
• Store the configured admin password through the StartOS package configuration
• Pass the configured admin password to the service through MUNIN_ADMIN_PASSWORD
• Create cryptographically random session tokens
• Store active sessions in memory with a 24-hour expiration
• Protect sessions with an HttpOnly, Secure, SameSite=Strict cookie
• Compare passwords using a timing-safe comparison
• Return HTTP 401 when the status API is accessed without a valid session
• Provide a web login form for authentication
• Verify successful login and authenticated status API access on the physical StartOS server
• Verify the authentication-protected S9PK package contains the authentication backend and updated web interface

Current architecture

• StartOS package
• Alpine Linux container
• nginx serving the web interface
• Node.js status API
• Static dashboard in web/index.html
• Password authentication and session handling in server/auth.js
• Fulcrum provided as a StartOS dependency
• Electrum protocol connectivity check from Munin to Fulcrum
• Blockchain height queried through Fulcrum
• Admin password provided to the service through the StartOS package environment

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.

The Munin web interface now requires password authentication before the protected status API can be accessed.

Authenticated sessions use a temporary in-memory session token with a 24-hour lifetime.

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