# lightninglabs/neutrino architecture

> Architecture diagram of the GitHub repository lightninglabs/neutrino, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lightninglabs/neutrino
- Repository: https://github.com/lightninglabs/neutrino

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Actors
    FullNode["Full Bitcoin Node"]:::external
    Wallet["Mobile Wallet / Lightning Node"]:::external

    %% Core Orchestrator
    ChainService["ChainService"]:::core

    %% P2P Network Layer
    subgraph "P2P Network Layer"
        P2P["P2P Network"]:::core
    end

    %% Synchronizers
    subgraph "Synchronizers"
        HeaderSync["Header Synchronizer"]:::core
        FilterSync["Filter Synchronizer"]:::core
    end

    %% Block Manager
    BlockManager["Block Manager"]:::core

    %% Storage Layer
    subgraph "Storage Layer"
        HeaderFS["HeaderFS"]:::storage
        FilterDB["FilterDB"]:::storage
        MetadataDB["Optional Metadata DB"]:::storage
    end

    %% Cache Layer
    CacheLayer["Cache Layer (LRU)"]:::cache

    %% Query Engine
    subgraph "Query Engine"
        Rescan["Rescan"]:::query
        GetUtxo["GetUtxo"]:::query
        BatchReporter["BatchSpendReporter"]:::query
    end

    %% Notifications & Broadcasting & Ban
    Notifications["Notifications Manager"]:::notif
    Broadcaster["Transaction Broadcaster"]:::broad
    BanManager["Ban Manager"]:::ban

    %% Utilities
    subgraph "Utilities & Support"
        ChanUtils["chanutils"]:::util
        Verification["verification"]:::util
        ErrorsUtil["errors"]:::util
        Logging["logging"]:::util
    end

    %% Connections
    FullNode -->|connects| P2P
    Wallet -->|API Calls| ChainService
    ChainService -->|spawns| HeaderSync
    ChainService -->|spawns| FilterSync
    ChainService -->|uses| BlockManager
    ChainService -->|manages| Notifications
    ChainService -->|manages| Broadcaster
    ChainService -->|manages| BanManager

    P2P -->|fetch headers| HeaderSync
    P2P -->|fetch filters| FilterSync
    HeaderSync -->|persist headers| HeaderFS
    FilterSync -->|persist filters| FilterDB

    BlockManager -->|lazy block fetch| P2P
    BlockManager -->|cache blocks| CacheLayer

    CacheLayer -->|cache headers/filters| HeaderSync
    CacheLayer -->|cache headers/filters| FilterSync

    Rescan -->|query filters| FilterDB
    Rescan -->|block fetch on match| BlockManager
    GetUtxo -->|query filters| FilterDB
    GetUtxo -->|block fetch on match| BlockManager
    BatchReporter -->|aggregate| FilterDB

    Rescan -->|wrap results| ChainService
    GetUtxo -->|wrap results| ChainService
    BatchReporter -->|wrap results| ChainService

    HeaderFS -->|read/write| ChainService
    FilterDB -->|read/write| ChainService
    MetadataDB -->|read/write| ChainService

    HeaderSync -->|notify| Notifications
    FilterSync -->|notify| Notifications

    Broadcaster -->|broadcast TX| P2P
    Broadcaster -->|track responses| ChainService

    P2P -->|peer events| BanManager
    BanManager -->|update peers| P2P

    %% Utilities usages
    HeaderSync --> ChanUtils
    FilterSync --> ChanUtils
    BlockManager --> ChanUtils
    ChainService --> Verification
    ChainService --> ErrorsUtil
    ChainService --> Logging
    Notifications --> Logging

    %% Click Events
    click ChainService "https://github.com/lightninglabs/neutrino/blob/master/neutrino.go"
    click P2P "https://github.com/lightninglabs/neutrino/tree/master/chainsync/"
    click HeaderSync "https://github.com/lightninglabs/neutrino/blob/master/chainsync/filtercontrol.go"
    click FilterSync "https://github.com/lightninglabs/neutrino/blob/master/chainsync/filtercontrol.go"
    click BlockManager "https://github.com/lightninglabs/neutrino/blob/master/blockmanager.go"
    click HeaderFS "https://github.com/lightninglabs/neutrino/tree/master/headerfs/"
    click FilterDB "https://github.com/lightninglabs/neutrino/tree/master/filterdb/"
    click MetadataDB "https://github.com/lightninglabs/neutrino/tree/master/headerlist/"
    click CacheLayer "https://github.com/lightninglabs/neutrino/blob/master/cache/cache.go"
    click Rescan "https://github.com/lightninglabs/neutrino/blob/master/rescan.go"
    click GetUtxo "https://github.com/lightninglabs/neutrino/blob/master/utxoscanner.go"
    click BatchReporter "https://github.com/lightninglabs/neutrino/blob/master/batch_spend_reporter.go"
    click Notifications "https://github.com/lightninglabs/neutrino/tree/master/blockntfns/"
    click Broadcaster "https://github.com/lightninglabs/neutrino/tree/master/pushtx/"
    click BanManager "https://github.com/lightninglabs/neutrino/tree/master/banman/"
    click ChanUtils "https://github.com/lightninglabs/neutrino/tree/master/chanutils/"
    click Verification "https://github.com/lightninglabs/neutrino/blob/master/verification.go"
    click ErrorsUtil "https://github.com/lightninglabs/neutrino/blob/master/errors.go"
    click Logging "https://github.com/lightninglabs/neutrino/blob/master/log.go"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#0000FF
    classDef storage fill:#90EE90,stroke:#008000
    classDef cache fill:#FFA500,stroke:#FF8C00
    classDef external fill:#DDA0DD,stroke:#800080
    classDef query fill:#FFD700,stroke:#DAA520
    classDef notif fill:#FFB6C1,stroke:#FF69B4
    classDef broad fill:#FFDEAD,stroke:#DEB887
    classDef ban fill:#FFE4E1,stroke:#FF7F7F
    classDef util fill:#D3D3D3,stroke:#A9A9A9
```
