How lightningdevkit/ldk-node works
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: runtime.rs Node · payment/mod.rs Payments · chain/mod.rs Chain Sync · builder.rs Builder
Components 34
Public API
High-level entry points used to construct and drive the node
- Builder · Configures and constructs a node instance
src/builder.rs - Config · Node configuration and runtime options
src/config.rs - Types · Common domain types shared across subsystems
src/types.rs - Entropy · Raw entropy and mnemonic-based identity material
src/entropy.rs - Connection · Connectivity and transport-related setup
src/connection.rs
Runtime Core
Long-lived Lightning node orchestration and protocol state
- Node · Main operational facade for start, stop, and commands
src/runtime.rs - Gossip · Lightning gossip ingestion and channel updates
src/gossip.rs - Payments · Unified payment entry point and flow selection
src/payment/mod.rs - Bolt11 · Lightning invoice payment path
src/payment/bolt11.rs - Bolt12 · Bolt 12 payment path
src/payment/bolt12.rs - Spontaneous · Spontaneous Lightning payment path
src/payment/spontaneous.rs - On-chain Pay · On-chain payment handling within the payment subsystem
src/payment/onchain.rs - Async Payments · Background payment coordination and stores
src/payment/asynchronous/mod.rs - Events · State changes and protocol events emitted to callers
src/event.rs - Handler · Consumes external messages and drives protocol actions
src/message_handler.rs
Data Planes
Pluggable chain, gossip, routing, and liquidity inputs
- Chain Sync · Abstracts Bitcoin chain data acquisition
src/chain/mod.rs - Bitcoind · Bitcoin Core RPC-based chain source
src/chain/bitcoind.rs - Electrum · Electrum server-based chain source
src/chain/electrum.rs - Esplora · Esplora server-based chain source
src/chain/esplora.rs - Graph · Channel graph state used for routing
src/graph.rs - Scoring · Peer and route scoring inputs
src/scoring.rs
Storage
Persistence and wallet state management
- Peer Store · Stored peer identity and connectivity state
src/peer_store.rs - Wallet · Integrated BDK-based wallet boundary
src/wallet/mod.rs - Balance · Tracks usable on-chain and channel funds
src/balance.rs - Tx Broadcaster · Broadcasts wallet and payment transactions
src/tx_broadcaster.rs - IO · Abstracts persistence backends and utilities
src/io/mod.rs - SQLite Store · Primary SQLite persistence backend
src/io/sqlite_store/mod.rs - VSS Store · Alternate/custom storage backend
src/io/vss_store.rs
Bindings & Validation
Language bindings, tests, and packaging around the Rust core
- FFI · Native boundary for generated bindings
src/ffi/mod.rs - UniFFI IDL · Interface definition for generated language bindings
bindings/ldk_node.udl - Kotlin · Kotlin/JVM and Android packaging
bindings/kotlin/ldk-node-jvm/lib/src/main/kotlin/org/lightningdevkit/ldknode/Library.kt - Swift · Swift package and XCFramework wrapper
bindings/swift/Sources/LDKNode/LDKNode.swift - Python · Python package wrapper
bindings/python/src/ldk_node/__init__.py - Integration Tests · Cross-node and end-to-end scenario coverage
tests/integration_tests_rust.rs
Connections 32
- 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