# lnp-wg/lnp-node architecture

> Architecture diagram of the GitHub repository lnp-wg/lnp-node, 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/lnp-wg/lnp-node
- Repository: https://github.com/lnp-wg/lnp-node

## Overview

##### Project type and purpose
- This is a Rust-based, microservice-oriented Lightning Network node (“LNP Node”) implementation.
- It is composed of a suite of daemons/microservices (peerd, channeld, lnpd, routed, watchd, signd) plus a CLI and RPC client library.

##### File structure
- Top-level crates and folders:
- cli/ – command-line client talking over RPC
- rpc/ – RPC client library
- src/ – main node code, subdivided into subdirectories for each daemon (peerd, channeld, lnpd, routed, watchd, signd)
- Each daemon follows a common pattern: opts.rs (configuration), runtime.rs (lifecycle and ZMQ sockets), automata/ (state machines), storage modules, error definitions.
- Communication is via ZeroMQ: RPC interfaces between CLI/RPC library and daemons, P2P/Noise_XK for peer networking, internal ESB (event-bus) for inter-daemon messaging.

##### README for additional insights
- Microservice architecture: daemons can run as separate processes (in Docker containers), threads in a monolith, or distributed geographically.
- External services: Bitcoin blockchain, Lightning peers, Tor, ZeroMQ brokers if used.

##### Main components
a. User/Application layer
- CLI tool (lnp-cli)
- RPC client library (rpc crate)
b. Microservices layer
- lnpd – channel/connection initializer
- peerd – Lightning peer manager (P2P over Noise_XK)
- channeld – channel management (Bifrost extensions, HTLCs/PTLCs, state machines)
- routed – route discovery & gossip
- watchd – on-chain watcher (monitors funding/commitment TXs)
- signd – key management and signing
c. Service bus & IPC
- ZeroMQ RPC bus for CLI ↔ daemons
- Internal ESB (ZeroMQ pub/sub or RPC) for inter-daemon messaging
d. External networks
- Bitcoin full node or Electrum (for on-chain data)
- Lightning Network peers (BOLT-compliant P2P)
- Tor/TCP/IP/UDP transports

##### Relationships and interactions
- CLI → (ZeroMQ RPC) → lnpd/peerd/channeld/routed/watchd/signd
- lnpd launches channels, writes to storage, notifies channeld via ESB
- peerd ↔ new remote peers over P2P bus (Noise_XK encrypted)
- channeld manages channel state machines, interacts with signd for signatures
- routed subscribes to gossip events (pub/sub) from peerd and publishes route updates
- watchd monitors blockchain events and pushes notifications to channeld/lnpd
- signd provides signing service to channeld and lnpd

##### Architectural patterns and principles
- Microservices—each daemon is independently scalable.
- Event-driven, state-machine-based operations (automata modules).
- Clear separation: networking (peerd), channel logic (channeld), routing (routed), on-chain watch (watchd), key management (signd).
- Config-driven (opts.rs modules), pluggable storage backends, CLI/RPC abstraction.

##### Essential details to capture
- Each daemon’s connectivity to:
- CLI/RPC via ZeroMQ RPC
- Other daemons via internal ESB
- External networks (Bitcoin, P2P)
- Storage backends (e.g., on-disk databases or SQL if used)
- Key signing boundary (signd) for security

##### Final pointers
- Don’t overcomplicate: start with a high-level view, then drill down into any one daemon if needed.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI / Client Layer
    subgraph "UI / Client"
        direction TB
        CLI["lnp-cli"]:::ui
        RPCClient["RPC Client Library"]:::ui
    end

    %% Service Bus Layer
    subgraph "Service Bus"
        direction TB
        RPCBus["ZeroMQ RPC Bus"]:::bus
        ESBus["Internal ESB (pub/sub)"]:::bus
    end

    %% Core Microservices
    subgraph "Core Microservices"
        direction TB
        lnpd["lnpd: channel initializer"]:::core
        peerd["peerd: peer manager"]:::core
        channeld["channeld: channel state machine"]:::core
        routed["routed: route & gossip"]:::core
        watchd["watchd: on-chain watcher"]:::core
        signd["signd: signing service"]:::core
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        Bitcoin["Bitcoin Node/Electrum"]:::external
        subgraph "Network"
            direction TB
            P2P["Lightning P2P Network"]:::external
            Tor["Tor / TCP/IP"]:::external
        end
    end

    %% Connections: UI to Bus
    CLI -->|"RPC calls"| RPCBus
    RPCClient -->|"RPC client"| RPCBus

    %% Bus to Microservices
    RPCBus <-->|RPC| lnpd
    RPCBus <-->|RPC| peerd
    RPCBus <-->|RPC| channeld
    RPCBus <-->|RPC| routed
    RPCBus <-->|RPC| watchd
    RPCBus <-->|RPC| signd

    ESBus <-->|events| lnpd
    ESBus <-->|events| peerd
    ESBus <-->|events| channeld
    ESBus <-->|events| routed
    ESBus <-->|events| watchd
    ESBus <-->|events| signd

    %% External connectivity
    watchd -->|"Monitors"| Bitcoin
    peerd -->|"Noise_XK P2P"| P2P
    peerd --> Tor
    P2P --> Tor

    %% Signing interactions
    lnpd -->|"sign requests"| signd
    channeld -->|"sign requests"| signd

    %% Click Events
    click CLI "https://github.com/lnp-wg/lnp-node/blob/master/cli/src/main.rs"
    click RPCClient "https://github.com/lnp-wg/lnp-node/blob/master/rpc/src/lib.rs"
    click RPCBus "https://github.com/lnp-wg/lnp-node/blob/master/src/bus/mod.rs"
    click ESBus "https://github.com/lnp-wg/lnp-node/blob/master/src/bus/ctl.rs"
    click lnpd "https://github.com/lnp-wg/lnp-node/blob/master/src/bin/lnpd.rs"
    click peerd "https://github.com/lnp-wg/lnp-node/blob/master/src/bin/peerd.rs"
    click channeld "https://github.com/lnp-wg/lnp-node/blob/master/src/bin/channeld.rs"
    click routed "https://github.com/lnp-wg/lnp-node/blob/master/src/bin/routed.rs"
    click watchd "https://github.com/lnp-wg/lnp-node/blob/master/src/bin/watchd.rs"
    click signd "https://github.com/lnp-wg/lnp-node/blob/master/src/bin/signd.rs"

    %% Styles
    classDef ui fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef core fill:#ABEBC6,stroke:#145A32,color:#1B2631
    classDef bus fill:#F9E79F,stroke:#9A7D0A,color:#1B2631
    classDef external fill:#F5B7B1,stroke:#7B241C,color:#1B2631
```
