# lightningdevkit/ldk-node architecture

> Architecture diagram of the GitHub repository lightningdevkit/ldk-node, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lightningdevkit/ldk-node
- Repository: https://github.com/lightningdevkit/ldk-node

## Overview

1. **Overall shape**
   - This repo is centered on a Rust library crate, `ldk-node`, that packages a self-custodial Lightning node plus an integrated on-chain wallet.
   - The public entry point is a high-level `Builder` that constructs a `Node`, which then exposes operational commands like start/stop, channel management, and payments.

2. **Core runtime boundary**
   - The Rust core is the authoritative implementation; everything else is either a storage backend, a chain/gossip data source, or a language binding layer.
   - The node runtime appears to orchestrate long-lived background work: chain sync, gossip sync, peer management, payment processing, and event emission.

3. **Chain synchronization subsystem**
   - `src/chain/` contains pluggable chain backends for `bitcoind`, `electrum`, and `esplora`.
   - This boundary abstracts how the node learns Bitcoin block and transaction data, with the README explicitly calling out Bitcoin Core RPC, Electrum servers, and Esplora servers as supported sources.

4. **Lightning gossip and graph state**
   - `src/gossip.rs`, `src/graph.rs`, `src/scoring.rs`, and `src/peer_store.rs` suggest a dedicated subsystem for channel graph knowledge, peer persistence, and routing/scoring inputs.
   - Gossip can come from the peer-to-peer Lightning network or Rapid Gossip Sync, so routing data is separate from chain data and can be swapped independently.

5. **Payments pipeline**
   - `src/payment/` is a major subsystem with distinct paths for Bolt11 invoices, Bolt12, spontaneous payments, on-chain payment handling, and unified orchestration.
   - The `asynchronous/` submodule indicates deferred or background payment flows, likely used to handle invoice lifecycle, mailbox/rate limiting, and static invoice storage.
   - This is the main data-path from API calls into Lightning or on-chain settlement.

6. **Wallet and on-chain funds management**
   - `src/wallet/`, `src/balance.rs`, and `src/tx_broadcaster.rs` indicate an integrated BDK-based wallet layer for on-chain funds.
   - On-chain address generation, persistence, and transaction broadcast are handled separately from Lightning channels, but coordinated by the node.
   - The wallet is a distinct storage and signing boundary from the Lightning state machine.

7. **Persistence layer**
   - `src/io/` provides storage backends and utilities, with `sqlite_store` as the main structured persistence option and `vss_store` as an alternate/custom backend.
   - The README also mentions file-system and custom backends, so persistence is intentionally abstracted rather than hard-wired to SQLite.
   - Stored state likely includes wallet metadata, channel state, pending payments, peer data, and entropy/material needed for recovery.

8. **Configuration, identity, and entropy**
   - `src/config.rs`, `src/entropy.rs`, `src/connection.rs`, and `src/types.rs` define node setup, identity material, connectivity, and shared types.
   - The builder can accept raw entropy or a BIP39 mnemonic, which feeds the node’s keys and recovery story.
   - This is the trust and initialization boundary: once entropy is fixed, the node identity and wallet state are derived from it.

9. **Eventing and external control**
   - `src/event.rs`, `src/message_handler.rs`, and `src/logger.rs` show the node exposing state changes and protocol events back to the caller.
   - The public API is not just request/response; the caller must consume node events and acknowledge them, which is important for diagramming control flow.
   - This makes the library feel like an embedded service with an event loop rather than a simple synchronous SDK.

10. **Liquidity and fee/risk management**
   - `src/liquidity.rs`, `src/fee_estimator.rs`, and `src/chain/*` indicate support components for deciding channel behavior and on-chain spending conditions.
   - `src/balance.rs` and `src/scoring.rs` suggest the node tracks usable funds and routing quality as part of operational decisions.

11. **FFI and multi-language distribution**
   - `src/ffi/` and `bindings/` show that the Rust core is exported through UniFFI to Swift, Kotlin/JVM/Android, and Python.
   - `bindings/ldk_node.udl`, `uniffi.toml`, and the generated platform packages mean the architecture has a strict core/binding split: Rust owns behavior, bindings provide thin language-native façades.
   - The Swift XCFramework, Kotlin Gradle projects, and Python packaging files are packaging/distribution layers, not alternate implementations.

12. **Testing architecture and external dependencies**
   - `tests/` is heavily integration-oriented and spans multiple Lightning peers: CLN, LND, Eclair, plus Rust-based scenarios and VSS variants.
   - Docker compose files and test helpers indicate the repo validates interoperability against live node implementations and local Bitcoin infrastructure.
   - `scripts/download_bitcoind_electrs.sh` and benchmark/audit workflows reinforce that the system depends on external Bitcoin/LN services during verification.

13. **Public surface vs internal subsystems**
   - For an architecture diagram, the main user-facing boundary is `Builder -> Node -> commands/events`.
   - Behind that boundary are four major internal planes: chain sync, Lightning/gossip/routing, payments, and wallet/persistence.
   - The bindings, tests, and CI are surrounding support systems that package, validate, and publish the same core node for multiple environments.

Main entry points: [`src/runtime.rs`](https://github.com/lightningdevkit/ldk-node/blob/main/src/runtime.rs) (Node), [`src/payment/mod.rs`](https://github.com/lightningdevkit/ldk-node/blob/main/src/payment/mod.rs) (Payments), [`src/chain/mod.rs`](https://github.com/lightningdevkit/ldk-node/blob/main/src/chain/mod.rs) (Chain Sync), [`src/builder.rs`](https://github.com/lightningdevkit/ldk-node/blob/main/src/builder.rs) (Builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public_api["Public API"]
  node_builder["Builder<br/>public API<br/>[builder.rs]"]
  node_config["Config<br/>setup<br/>[config.rs]"]
  node_types["Types<br/>[types.rs]"]
  node_entropy["Entropy<br/>identity seed<br/>[entropy.rs]"]
  node_connection["Connection<br/>network settings<br/>[connection.rs]"]
end

subgraph group_runtime_core["Runtime Core"]
  node_node_runtime["Node<br/>runtime<br/>[runtime.rs]"]
  node_gossip["Gossip<br/>network sync<br/>[gossip.rs]"]
  node_payment_mod["Payments<br/>payment orchestration<br/>[mod.rs]"]
  node_bolt11["Bolt11<br/>invoice flow<br/>[bolt11.rs]"]
  node_bolt12["Bolt12<br/>offer flow<br/>[bolt12.rs]"]
  node_spontaneous["Spontaneous<br/>keysend flow<br/>[spontaneous.rs]"]
  node_onchain_pay["On-chain Pay<br/>on-chain flow<br/>[onchain.rs]"]
  node_async_pay["Async Payments<br/>deferred flows<br/>[mod.rs]"]
  node_event["Events<br/>event stream<br/>[event.rs]"]
  node_message_handler["Handler<br/>control loop<br/>[message_handler.rs]"]
end

subgraph group_data_planes["Data Planes"]
  node_chain_mod{{"Chain Sync<br/>chain boundary<br/>[mod.rs]"}}
  node_bitcoind["Bitcoind<br/>chain backend<br/>[bitcoind.rs]"]
  node_electrum["Electrum<br/>chain backend<br/>[electrum.rs]"]
  node_esplora["Esplora<br/>chain backend<br/>[esplora.rs]"]
  node_graph(("Graph<br/>routing state<br/>[graph.rs]"))
  node_scoring(("Scoring<br/>routing heuristic<br/>[scoring.rs]"))
end

subgraph group_storage["Storage"]
  node_peer_store[("Peer Store<br/>peer persistence<br/>[peer_store.rs]")]
  node_wallet["Wallet<br/>[mod.rs]"]
  node_balance(("Balance<br/>funds view<br/>[balance.rs]"))
  node_tx_broadcaster["Tx Broadcaster<br/>broadcast adapter<br/>[tx_broadcaster.rs]"]
  node_io[("IO<br/>storage boundary<br/>[mod.rs]")]
  node_sqlite_store[("SQLite Store<br/>structured store<br/>[mod.rs]")]
  node_vss_store[("VSS Store<br/>alternate store<br/>[vss_store.rs]")]
end

subgraph group_distribution["Bindings & Validation"]
  node_ffi_mod["FFI<br/>[mod.rs]"]
  node_uniffi_udl["UniFFI IDL<br/>binding definition<br/>[ldk_node.udl]"]
  node_kotlin["Kotlin<br/>binding package<br/>[Library.kt]"]
  node_swift["Swift<br/>binding package<br/>[LDKNode.swift]"]
  node_python["Python<br/>binding package<br/>[__init__.py]"]
  node_tests["Integration Tests<br/>interop validation"]
end

node_builder -->|"constructs"| node_node_runtime
node_builder -->|"uses"| node_config
node_builder -->|"seeds"| node_entropy
node_builder -->|"sets"| node_connection
node_node_runtime -->|"syncs"| node_chain_mod
node_chain_mod -->|"backend"| node_bitcoind
node_chain_mod -->|"backend"| node_electrum
node_chain_mod -->|"backend"| node_esplora
node_node_runtime -->|"drives"| node_gossip
node_gossip -->|"updates"| node_graph
node_gossip -->|"persists"| node_peer_store
node_graph -->|"feeds"| node_scoring
node_node_runtime -->|"executes"| node_payment_mod
node_payment_mod -->|"selects"| node_bolt11
node_payment_mod -->|"selects"| node_bolt12
node_payment_mod -->|"selects"| node_spontaneous
node_payment_mod -->|"selects"| node_onchain_pay
node_payment_mod -->|"coordinates"| node_async_pay
node_node_runtime -->|"controls"| node_wallet
node_wallet -->|"tracks"| node_balance
node_wallet -->|"broadcasts"| node_tx_broadcaster
node_node_runtime -->|"persists"| node_io
node_io -->|"implements"| node_sqlite_store
node_io -->|"implements"| node_vss_store
node_node_runtime -->|"emits"| node_event
node_message_handler -->|"drives"| node_node_runtime
node_ffi_mod -->|"generated from"| node_uniffi_udl
node_uniffi_udl -->|"generates"| node_kotlin
node_uniffi_udl -->|"generates"| node_swift
node_uniffi_udl -->|"generates"| node_python
node_tests -->|"validates"| node_node_runtime
node_tests -->|"uses"| node_chain_mod

click node_builder "https://github.com/lightningdevkit/ldk-node/blob/main/src/builder.rs"
click node_node_runtime "https://github.com/lightningdevkit/ldk-node/blob/main/src/runtime.rs"
click node_config "https://github.com/lightningdevkit/ldk-node/blob/main/src/config.rs"
click node_types "https://github.com/lightningdevkit/ldk-node/blob/main/src/types.rs"
click node_entropy "https://github.com/lightningdevkit/ldk-node/blob/main/src/entropy.rs"
click node_connection "https://github.com/lightningdevkit/ldk-node/blob/main/src/connection.rs"
click node_chain_mod "https://github.com/lightningdevkit/ldk-node/blob/main/src/chain/mod.rs"
click node_bitcoind "https://github.com/lightningdevkit/ldk-node/blob/main/src/chain/bitcoind.rs"
click node_electrum "https://github.com/lightningdevkit/ldk-node/blob/main/src/chain/electrum.rs"
click node_esplora "https://github.com/lightningdevkit/ldk-node/blob/main/src/chain/esplora.rs"
click node_gossip "https://github.com/lightningdevkit/ldk-node/blob/main/src/gossip.rs"
click node_graph "https://github.com/lightningdevkit/ldk-node/blob/main/src/graph.rs"
click node_scoring "https://github.com/lightningdevkit/ldk-node/blob/main/src/scoring.rs"
click node_peer_store "https://github.com/lightningdevkit/ldk-node/blob/main/src/peer_store.rs"
click node_payment_mod "https://github.com/lightningdevkit/ldk-node/blob/main/src/payment/mod.rs"
click node_bolt11 "https://github.com/lightningdevkit/ldk-node/blob/main/src/payment/bolt11.rs"
click node_bolt12 "https://github.com/lightningdevkit/ldk-node/blob/main/src/payment/bolt12.rs"
click node_spontaneous "https://github.com/lightningdevkit/ldk-node/blob/main/src/payment/spontaneous.rs"
click node_onchain_pay "https://github.com/lightningdevkit/ldk-node/blob/main/src/payment/onchain.rs"
click node_async_pay "https://github.com/lightningdevkit/ldk-node/blob/main/src/payment/asynchronous/mod.rs"
click node_wallet "https://github.com/lightningdevkit/ldk-node/blob/main/src/wallet/mod.rs"
click node_balance "https://github.com/lightningdevkit/ldk-node/blob/main/src/balance.rs"
click node_tx_broadcaster "https://github.com/lightningdevkit/ldk-node/blob/main/src/tx_broadcaster.rs"
click node_io "https://github.com/lightningdevkit/ldk-node/blob/main/src/io/mod.rs"
click node_sqlite_store "https://github.com/lightningdevkit/ldk-node/blob/main/src/io/sqlite_store/mod.rs"
click node_vss_store "https://github.com/lightningdevkit/ldk-node/blob/main/src/io/vss_store.rs"
click node_event "https://github.com/lightningdevkit/ldk-node/blob/main/src/event.rs"
click node_message_handler "https://github.com/lightningdevkit/ldk-node/blob/main/src/message_handler.rs"
click node_ffi_mod "https://github.com/lightningdevkit/ldk-node/blob/main/src/ffi/mod.rs"
click node_uniffi_udl "https://github.com/lightningdevkit/ldk-node/blob/main/bindings/ldk_node.udl"
click node_kotlin "https://github.com/lightningdevkit/ldk-node/blob/main/bindings/kotlin/ldk-node-jvm/lib/src/main/kotlin/org/lightningdevkit/ldknode/Library.kt"
click node_swift "https://github.com/lightningdevkit/ldk-node/blob/main/bindings/swift/Sources/LDKNode/LDKNode.swift"
click node_python "https://github.com/lightningdevkit/ldk-node/blob/main/bindings/python/src/ldk_node/__init__.py"
click node_tests "https://github.com/lightningdevkit/ldk-node/blob/main/tests/integration_tests_rust.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_builder,node_config,node_types,node_entropy,node_connection toneBlue
class node_node_runtime,node_gossip,node_payment_mod,node_bolt11,node_bolt12,node_spontaneous,node_onchain_pay,node_async_pay,node_event,node_message_handler toneAmber
class node_chain_mod,node_bitcoind,node_electrum,node_esplora,node_graph,node_scoring toneMint
class node_peer_store,node_wallet,node_balance,node_tx_broadcaster,node_io,node_sqlite_store,node_vss_store toneRose
class node_ffi_mod,node_uniffi_udl,node_kotlin,node_swift,node_python,node_tests toneIndigo
```

## Components

### Public API

High-level entry points used to construct and drive the node

- [Builder](https://github.com/lightningdevkit/ldk-node/blob/main/src/builder.rs): public API · Configures and constructs a node instance · `src/builder.rs`
- [Config](https://github.com/lightningdevkit/ldk-node/blob/main/src/config.rs): setup · Node configuration and runtime options · `src/config.rs`
- [Types](https://github.com/lightningdevkit/ldk-node/blob/main/src/types.rs): shared types · Common domain types shared across subsystems · `src/types.rs`
- [Entropy](https://github.com/lightningdevkit/ldk-node/blob/main/src/entropy.rs): identity seed · Raw entropy and mnemonic-based identity material · `src/entropy.rs`
- [Connection](https://github.com/lightningdevkit/ldk-node/blob/main/src/connection.rs): network settings · Connectivity and transport-related setup · `src/connection.rs`

### Runtime Core

Long-lived Lightning node orchestration and protocol state

- [Node](https://github.com/lightningdevkit/ldk-node/blob/main/src/runtime.rs): runtime · Main operational facade for start, stop, and commands · `src/runtime.rs`
- [Gossip](https://github.com/lightningdevkit/ldk-node/blob/main/src/gossip.rs): network sync · Lightning gossip ingestion and channel updates · `src/gossip.rs`
- [Payments](https://github.com/lightningdevkit/ldk-node/blob/main/src/payment/mod.rs): payment orchestration · Unified payment entry point and flow selection · `src/payment/mod.rs`
- [Bolt11](https://github.com/lightningdevkit/ldk-node/blob/main/src/payment/bolt11.rs): invoice flow · Lightning invoice payment path · `src/payment/bolt11.rs`
- [Bolt12](https://github.com/lightningdevkit/ldk-node/blob/main/src/payment/bolt12.rs): offer flow · Bolt 12 payment path · `src/payment/bolt12.rs`
- [Spontaneous](https://github.com/lightningdevkit/ldk-node/blob/main/src/payment/spontaneous.rs): keysend flow · Spontaneous Lightning payment path · `src/payment/spontaneous.rs`
- [On-chain Pay](https://github.com/lightningdevkit/ldk-node/blob/main/src/payment/onchain.rs): on-chain flow · On-chain payment handling within the payment subsystem · `src/payment/onchain.rs`
- [Async Payments](https://github.com/lightningdevkit/ldk-node/blob/main/src/payment/asynchronous/mod.rs): deferred flows · Background payment coordination and stores · `src/payment/asynchronous/mod.rs`
- [Events](https://github.com/lightningdevkit/ldk-node/blob/main/src/event.rs): event stream · State changes and protocol events emitted to callers · `src/event.rs`
- [Handler](https://github.com/lightningdevkit/ldk-node/blob/main/src/message_handler.rs): control loop · Consumes external messages and drives protocol actions · `src/message_handler.rs`

### Data Planes

Pluggable chain, gossip, routing, and liquidity inputs

- [Chain Sync](https://github.com/lightningdevkit/ldk-node/blob/main/src/chain/mod.rs): chain boundary · Abstracts Bitcoin chain data acquisition · `src/chain/mod.rs`
- [Bitcoind](https://github.com/lightningdevkit/ldk-node/blob/main/src/chain/bitcoind.rs): chain backend · Bitcoin Core RPC-based chain source · `src/chain/bitcoind.rs`
- [Electrum](https://github.com/lightningdevkit/ldk-node/blob/main/src/chain/electrum.rs): chain backend · Electrum server-based chain source · `src/chain/electrum.rs`
- [Esplora](https://github.com/lightningdevkit/ldk-node/blob/main/src/chain/esplora.rs): chain backend · Esplora server-based chain source · `src/chain/esplora.rs`
- [Graph](https://github.com/lightningdevkit/ldk-node/blob/main/src/graph.rs): routing state · Channel graph state used for routing · `src/graph.rs`
- [Scoring](https://github.com/lightningdevkit/ldk-node/blob/main/src/scoring.rs): routing heuristic · Peer and route scoring inputs · `src/scoring.rs`

### Storage

Persistence and wallet state management

- [Peer Store](https://github.com/lightningdevkit/ldk-node/blob/main/src/peer_store.rs): peer persistence · Stored peer identity and connectivity state · `src/peer_store.rs`
- [Wallet](https://github.com/lightningdevkit/ldk-node/blob/main/src/wallet/mod.rs): on-chain wallet · Integrated BDK-based wallet boundary · `src/wallet/mod.rs`
- [Balance](https://github.com/lightningdevkit/ldk-node/blob/main/src/balance.rs): funds view · Tracks usable on-chain and channel funds · `src/balance.rs`
- [Tx Broadcaster](https://github.com/lightningdevkit/ldk-node/blob/main/src/tx_broadcaster.rs): broadcast adapter · Broadcasts wallet and payment transactions · `src/tx_broadcaster.rs`
- [IO](https://github.com/lightningdevkit/ldk-node/blob/main/src/io/mod.rs): storage boundary · Abstracts persistence backends and utilities · `src/io/mod.rs`
- [SQLite Store](https://github.com/lightningdevkit/ldk-node/blob/main/src/io/sqlite_store/mod.rs): structured store · Primary SQLite persistence backend · `src/io/sqlite_store/mod.rs`
- [VSS Store](https://github.com/lightningdevkit/ldk-node/blob/main/src/io/vss_store.rs): alternate store · Alternate/custom storage backend · `src/io/vss_store.rs`

### Bindings & Validation

Language bindings, tests, and packaging around the Rust core

- [FFI](https://github.com/lightningdevkit/ldk-node/blob/main/src/ffi/mod.rs): ffi bridge · Native boundary for generated bindings · `src/ffi/mod.rs`
- [UniFFI IDL](https://github.com/lightningdevkit/ldk-node/blob/main/bindings/ldk_node.udl): binding definition · Interface definition for generated language bindings · `bindings/ldk_node.udl`
- [Kotlin](https://github.com/lightningdevkit/ldk-node/blob/main/bindings/kotlin/ldk-node-jvm/lib/src/main/kotlin/org/lightningdevkit/ldknode/Library.kt): binding package · Kotlin/JVM and Android packaging · `bindings/kotlin/ldk-node-jvm/lib/src/main/kotlin/org/lightningdevkit/ldknode/Library.kt`
- [Swift](https://github.com/lightningdevkit/ldk-node/blob/main/bindings/swift/Sources/LDKNode/LDKNode.swift): binding package · Swift package and XCFramework wrapper · `bindings/swift/Sources/LDKNode/LDKNode.swift`
- [Python](https://github.com/lightningdevkit/ldk-node/blob/main/bindings/python/src/ldk_node/__init__.py): binding package · Python package wrapper · `bindings/python/src/ldk_node/__init__.py`
- [Integration Tests](https://github.com/lightningdevkit/ldk-node/blob/main/tests/integration_tests_rust.rs): interop validation · Cross-node and end-to-end scenario coverage · `tests/integration_tests_rust.rs`

## Connections

- Builder → Node: constructs · Builder creates the operational node runtime
- Builder → Config: uses · Builder applies configuration and startup options
- Builder → Entropy: seeds · Entropy or mnemonic material initializes identity
- Builder → Connection: sets · Builder configures connectivity inputs
- Node → Chain Sync: syncs · Node coordinates chain synchronization
- Chain Sync → Bitcoind: backend · Bitcoin Core RPC backend option
- Chain Sync → Electrum: backend · Electrum backend option
- Chain Sync → Esplora: backend · Esplora backend option
- Node → Gossip: drives · Node manages gossip and network state
- Gossip → Graph: updates · Gossip feeds routing graph state
- Gossip → Peer Store: persists · Peer knowledge is stored for reuse
- Graph → Scoring: feeds · Graph state informs routing quality scoring
- Node → Payments: executes · Node routes payment commands into payment flows
- Payments → Bolt11: selects · Invoice-based payment path
- Payments → Bolt12: selects · Bolt 12 payment path
- Payments → Spontaneous: selects · Spontaneous payment path
- Payments → On-chain Pay: selects · On-chain payment path
- Payments → Async Payments: coordinates · Deferred background payment handling
- Node → Wallet: controls · Node integrates the on-chain wallet
- Wallet → Balance: tracks · Wallet state contributes to usable balance views
- Wallet → Tx Broadcaster: broadcasts · Wallet-backed transactions are broadcast externally
- Node → IO: persists · Node stores durable state through IO abstraction
- IO → SQLite Store: implements · Primary persistence backend
- IO → VSS Store: implements · Alternate persistence backend
- Node → Events: emits · Node publishes events to callers
- Handler → Node: drives · External messages are handled against node state
- FFI → UniFFI IDL: generated from · FFI layer is defined by UniFFI IDL
- UniFFI IDL → Kotlin: generates · Kotlin bindings are generated from the IDL
- UniFFI IDL → Swift: generates · Swift bindings are generated from the IDL
- UniFFI IDL → Python: generates · Python bindings are generated from the IDL
- Integration Tests → Node: validates · Integration tests exercise the Rust node core
- Integration Tests → Chain Sync: uses · Tests rely on real chain backends and infrastructure
