lnd — Lightning Network Daemon

Generated package documentation • ~1,800 Go source files • 180+ packages
Go Lightning Bitcoin

What is lnd?

lnd (Lightning Network Daemon) is the reference implementation of a full Lightning Network node, written in Go by Lightning Labs. It manages Bitcoin channels, routes payments over the Lightning Network using source-based onion routing, and exposes a gRPC + REST API consumed by wallets and applications.

This documentation mirrors the lnd source tree. Each package is documented in a .md file at the corresponding path. Use the sidebar or the folder tree below to navigate. Top-level files (server.go, rpcserver.go, config.go) are the main entry points; from there the major subsystems radiate outward.

Key Types & Interfaces

Daemon Core

server.go
server.Server
Root daemon struct. Owns all subsystem handles: peer manager, funding manager, HTLC switch, channel router, invoice registry, and the chain watcher.
rpcserver.go
rpcserver.rpcServer
Implements the LightningServer gRPC interface. Bridges external API calls into internal subsystems. Handles auth via macaroons.
config.go
Config
Top-level daemon configuration: chain backend, network, paths, fees, routing policy, RPC listeners, TLS settings, and all subserver configs.
accessman.go
AccessMan
Manages per-peer access slots and rate limiting. Controls which peers may open new channels or send messages.

Channel & Wallet

lnwallet/
LightningWallet
On-chain wallet and channel factory. Manages UTXOs, coin selection, PSBT flows, and creates/restores channel state.
lnwallet/btcwallet/
BtcWallet
Implements WalletController + BlockChainIO using the btcwallet library. Primary on-chain backend for mainnet/testnet.
lnwallet/rpcwallet/
RPCKeyRing
Remote signer pattern. All signing operations delegated to a remote gRPC endpoint; local wallet is watch-only.
lnwallet/chanfunding/
Assembler / Intent
Abstractions for channel funding flows: WalletAssembler (normal), CannedAssembler (pre-signed), PsbtAssembler (PSBT external signing).
lnwallet/chancloser/
ChanCloser
Cooperative close state machine. Negotiates fee and script with the remote peer through closeIdle → closingNegotiated → closeComplete states.

HTLC Switch & Routing

htlcswitch/
Switch
Central HTLC packet switch. Forwards, settles, and fails HTLCs between channel links. Maintains circuit map and forwarding log.
htlcswitch/
ChannelLink
Per-channel HTLC processor. Manages commitment updates, bandwidth estimation, and re-transmission after reconnect.
routing/
ChannelRouter
Source-based pathfinder. Maintains in-memory graph, runs Dijkstra/probability-weighted pathfinding, drives payment lifecycle and mission control.
routing/blindedpath/
BuildBlindedPaymentPaths
Constructs BOLT-12 blinded routes for privacy-preserving payments. Selects candidate paths, pads hops, and encrypts relay info.
routing/route/
Route / Hop
Wire-level representation of a payment route. Route encodes the ordered hop sequence; Hop carries per-hop HTLC parameters and TLV payload.
routing/chainview/
FilteredChainView
Interface for watching the chain for channel spend/close events. Backends: btcd, bitcoind, neutrino.

Graph & Channel Database

graph/db/
ChannelGraph / GraphCache
Persistent channel graph store (BoltDB/SQL). GraphCache provides an in-memory O(1) neighbor lookup layer used during pathfinding.
graph/db/models/
Node / ChannelEdgeInfo / ChannelEdgePolicy
Domain model types. Node holds public key + gossip fields; ChannelEdgeInfo is the undirected channel record; ChannelEdgePolicy is the directional routing policy.
channeldb/
DB (channeldb)
BoltDB-backed store for local channel state, payments, invoices, forwarding log, and mission control. 35 numbered schema migrations.
payments/db/
PaymentControl
Tracks in-flight and completed payments, HTLC attempts, and settlement status. Backed by either KV store or SQL.

Chain & Notifications

chainntnfs/
TxNotifier
Central engine for confirmation and spend notifications. Shared by all chain backends. Handles reorg detection and mempool tracking.
chainntnfs/bitcoindnotify/
BitcoindNotifier
ChainNotifier backed by bitcoind via ZMQ block/tx streams and RPC. Used in production environments.
chainio/
Blockbeat / Consumer
Fan-out mechanism delivering new block events to all registered subsystems in priority order before moving to the next block.

Watchtower

watchtower/blob/
JusticeKit
Encrypted breach remedy transaction. Stores the data a tower needs to broadcast justice transactions, keyed by BreachHint/BreachKey.
watchtower/lookout/
Lookout
Breach detection engine running on the tower side. Scans each new block for matching breach hints and queues justice transactions.
watchtower/wtclient/
Manager
Client-side watchtower manager. Maintains tower sessions, encrypts and uploads channel state backups, and handles session negotiation.

gRPC Subservers (lnrpc/)

lnrpc/routerrpc/
RouterServer
Payment routing RPC: SendPaymentV2, BuildRoute, QueryRoutes, HTLC interceptor, mission control reset.
lnrpc/walletrpc/
WalletKitServer
On-chain wallet RPC: UTXOs, PSBT flows, address management, coin selection, bump fee, import accounts/public keys.
lnrpc/invoicesrpc/
InvoicesServer
Invoice management RPC: AddHoldInvoice, SettleInvoice, CancelInvoice, SubscribeSingleInvoice.
lnrpc/signrpc/
SignerServer
Signing RPC: SignMessage, VerifyMessage, ComputeInputScript, MuSig2 multi-round signing flows.
lnrpc/chainrpc/
ChainNotifierServer
Chain event streaming RPC: RegisterConfirmationsNtfn, RegisterSpendNtfn, RegisterBlockEpochNtfn.
lnrpc/autopilotrpc/
AutopilotServer
Autopilot channel management RPC: Status, ModifyStatus, QueryScores, SetScores.

Storage Backends

kvdb/etcd/
etcd backend
walletdb-compatible backend using etcd with STM (Software Transactional Memory) for serializable isolation.
kvdb/postgres/
Postgres backend
walletdb-compatible Postgres driver. Used in clustered deployments.
kvdb/sqlite/
SQLite backend
walletdb-compatible SQLite driver for single-node deployments.
sqldb/sqlc/
SQLC queries
Auto-generated type-safe Go query code from SQL schemas. Used by payment, invoice, and graph SQL stores.

Core Subsystems

Package Description
server.goRoot daemon. Starts/stops all subsystems, manages peer connections, owns the funding and contract court managers.
rpcserver.goLightningServer gRPC implementation. Entry point for all external API calls.
channeldb/BoltDB/SQL store for local channel state, payments, invoices, and forwarding log. 35 schema migrations.
htlcswitch/HTLC packet switch and per-channel link processors. Circuit map, forwarding log, interceptors.
routing/Channel router, pathfinder, mission control, payment lifecycle state machine, blinded path builder.
lnwallet/On-chain wallet, channel factory, PSBT support, coin selection, cooperative close state machine.
lnrpc/All gRPC subservers: router, wallet, invoices, signer, chain, autopilot, peers, watchtower client, dev.
graph/Channel graph DB + in-memory GraphCache. Stores node/edge gossip data used by the router.
chainntnfs/TxNotifier + ChainNotifier implementations (bitcoind, btcd, neutrino). Confirmation and spend subscriptions.
contractcourt/Unilateral close arbitrator. Watches chain for breaches and force closes; drives justice/second-level tx.
watchtower/Watchtower server + client. Breach detection, justice kit encryption, session management, wire protocol.
funding/Channel funding manager. Drives the channel opening state machine, handles pending/open channel lifecycle.
invoices/Invoice registry. Manages AMP/MPP invoice state, HTLC settlement, hold invoice callbacks.
discovery/Gossip subsystem. Authenticates and propagates channel announcements and node updates.
sweep/UTXO sweeper. Batches time-sensitive outputs (HTLC timeout/success, commit outputs) and fee-bumps via CPFP/RBF.
peer/Per-peer Brontide connection handler. Encodes/decodes wire messages, manages channel link lifecycle.
payments/Payment DB (KV + SQL). MPPayment, HTLCAttempt records, PaymentControl interface.
kvdb/walletdb-compatible KV store drivers: BoltDB, etcd, Postgres, SQLite.
sqldb/SQL database layer. SQLC-generated queries, migrations, connection pool.
lnwire/Lightning wire protocol message types. All BOLT message structs and their serialization.
macaroons/Macaroon-based auth. Service, baking constraints, validation middleware.
brontide/Noise_XX encrypted transport. Handshake and framing for peer-to-peer connections.
tlv/Type-Length-Value encoding primitives used throughout LN protocol messages and database records.
chainio/Blockbeat fan-out. Delivers new block events to all consumers in priority order.
cmd/lncli/lncli binary. Parses flags, connects to lnd gRPC, and dispatches subcommands.
lntest/Integration test harness: HarnessNode, HarnessRPC, miner, mock implementations, polling helpers.
itest/Integration test case suites: wallet, channels, payments, bump fee, custom features, and more.
internal/musig2v040/Vendored MuSig2 v0.4.0 for legacy channel interoperability.

Folder Structure