How lightninglabs/neutrino works
Main components
a. ChainService (core orchestrator)
b. P2P Network Layer
c. Header Synchronizer
d. Filter Synchronizer
e. Block Manager
f. Storage Layer
• HeaderFS (file-system store for headers and indices)
• FilterDB (database of compact filter headers)
• Optional: LevelDB/BoltDB for other metadata
g. Cache Layer (in-memory LRU caches)
h. Query Engine
• Rescan
• GetUtxo
• BatchSpendReporter
i. Notifications Manager (blockntfns)
j. Transaction Broadcaster (pushtx)
k. Ban Manager (banman)
l. Utilities & Support Modules
• chanutils (batch writers & queues)
• verification, errors, logging
External actors / systems
• Full Bitcoin Nodes (peer connections)
• Mobile Wallet or Lightning Node (e.g., lnd) invoking ChainService API
Component relationships & data flow
• ChainService sits at the center.
• On Start, it spawns the Header Synchronizer and Filter Synchronizer.
• Both synchronizers talk to P2P Network Layer → fetch headers/filters → write to storage.
• Block Manager is called on demand to fetch full blocks lazily via P2P.
• Cache Layer wraps hot data (headers, filters, blocks) to reduce re-fetches.
• Storage Layer components (HeaderFS, FilterDB) persist data; Query Engine reads from both.
• Query Engine components:
• Rescan and GetUtxo issue queries against FilterDB + optionally block fetches via Block Manager.
• BatchSpendReporter aggregates results for wallet/contract scanning.
• Notifications Manager subscribes to new header and filter events to emit “block connected/disconnected” messages.
• Transaction Broadcaster (pushtx) receives API calls from wallet, broadcasts via P2P, and tracks responses.
• Ban Manager monitors peer behavior (via banman) and updates network layer peers.
Architectural patterns & principles
– Modular micro-services style within a single process (each Go package is a component).
– Concurrency via goroutines and channel pipelines (chanutils).
– Separation of concerns:
• Synchronization vs. storage vs. querying vs. notifications vs. broadcasting.
– Lazy loading: blocks and filters only fetched when needed.
– Abstraction interfaces for storage (store.go), logging, and peer banning.
Technology stack & libraries
– Go modules for dependency management (go.mod files)
– Bbolt/LevelDB (via filterdb) for filter headers
– File I/O in headerfs for fast header retrieval
– In-memory LRU caches under cache/lru
– Standard Go net.P2P primitives or btcd’s peer package underneath
– Testing harness in each package (XXX_test.go)