lnd Documentation

The chainntnfs package provides interfaces for receiving notifications triggered by specific on-chain events. It is designed to be general-purpose and can be used outside of lnd workflows.

Supported notification types include:

• New blocks connected to the current best chain.
• A specific txid reaching a defined number of confirmations.
• A target outpoint (txid:index) being spent.

The channeldb package provides the persistent storage engine for lnd. It serves as a data storage layer for the state required within the Lightning Network. It uses boltdb (an embedded pure-go key-value store based on LMDB) as its backing storage engine.

channeldb implements an object-oriented storage model where queries and mutations are performed through specific object instances rather than directly against the database. The data managed by these objects includes:

• Open channels
• Past commitment revocation states
• The channel graph (including authenticated node and channel announcements)
• Outgoing payments
• Invoices

The zpay32 package provides a scheme for encoding payment requests between two lnd nodes. It uses the zbase32 encoding scheme combined with a checksum to encode a serialized payment request.

The serialized payment request includes:

• The destination's public key
• The payment hash to use for the payment
• The value of the payment to be sent

The routing package provides core Lightning Network routing capabilities, including:

• Authentication and validation of channel announcements.
• Pruning of the channel graph.
• Path finding within the network.
• Sending outgoing payments into the network.
• Synchronizing new peers to the local channel graph state.

The Lightning Network Daemon (lnd) is a complete implementation of a Lightning Network node. It supports several pluggable back-end chain services, including:

• btcd (a full-node)
• bitcoind
• neutrino (an experimental light client)

Key capabilities include:

• Creating and closing channels.
• Managing all channel states.
• Maintaining an authenticated and validated channel graph.
• Path finding and passive payment forwarding.
• Sending onion-encrypted payments.
• Updating advertised fee schedules.
• Automatic channel management via autopilot.

LND's wallet supports Partially Signed Bitcoin Transactions (PSBT) functionality as defined in BIP174. This includes the ability to create, sign, and fund channels using PSBTs.

Important Constraint: To prevent transaction malleability, all inputs used in a funding transaction must be SegWit spends. LND will return an error if any inputs are P2PKH or normal P2SH.

The brontide package implements a secure crypto messaging protocol based on the Noise Protocol Framework. It is designed for projects requiring secure, encrypted, and authenticated communications between network-enabled programs.

Key features include:

• A raw state machine for handling handshakes and message encryption/decryption.
• Implementations of net.Conn and net.Listener interfaces, allowing the encrypted transport to be integrated seamlessly into Go codebases.
• Compliance with the secure messaging scheme described in BOLT #8 of the Lightning Network specifications.

The lnwallet package provides an abstracted wallet controller used as the core wallet within the lnd daemon. It manages critical Lightning Network operations including:

• Driving channel funding workflows.
• Providing script utilities.
• Generating witness functions for various Lightning scripts.
• Deriving revocation keys.
• Managing the commitment update state machine.

The package is designed with decoupled interfaces for signing and blockchain access, allowing for different WalletController implementations to be integrated into lnd without modifying the core codebase.

The chainio package provides blockchain data access to lnd subsystems. It uses a BlockbeatDispatcher to receive new blocks (encapsulated as Blockbeat objects) and distribute them to registered Consumer implementations.

Key components:

• Blockbeat: An interface providing information about a block.
• Consumer: An interface defining how subsystems handle a Blockbeat.
• BlockbeatDispatcher: The core service that receives blocks and distributes them to consumers.
• BeatConsumer: A struct providing a partial implementation of the Consumer interface to reduce boilerplate, including a ProcessBlock implementation and a NotifyBlockProcessed method.

Starting with v0.21.0, LND includes a safety mechanism for nodes using native-SQL backends (SQLite or PostgreSQL with --db.use-native-sql=true).

On the first startup, LND writes the active Bitcoin network (mainnet, testnet, signet, or regtest) into a chain_params row in the SQL database. On subsequent startups, LND compares the configured network against this stored value. If they do not match, LND will refuse to start to prevent silent data corruption.

Note: This guard does not affect nodes using the bbolt backend.

The EstimateRouteFee implementation is subject to ongoing evolution. Wallet developers should monitor LND releases for upcoming support in the following areas:

• Multi-Path Payment (MPP) Support: Extending estimation to scenarios where payments are split across multiple routes.
• Trampoline Routing Compatibility: Adapting estimation for implementations where intermediate nodes handle pathfinding.
• Blinded Path Integration: Ensuring correct fee estimation as blinded paths become more prevalent in the network.

The EstimateRouteFee RPC call provides fee estimates for Lightning Network payments. It operates in two distinct modes based on the input provided:

1. Graph-Based Estimation: Triggered when providing a destination public key and amount. It uses the local in-memory channel graph and mission control data (historical success rates) to calculate a route. This is fast (~100ms) but potentially less accurate for complex scenarios as it does not interact with the network.
2. Probe-Based Estimation: Triggered when providing a Payment Request/Invoice. It sends probe payments using a random payment hash to test actual network conditions (liquidity and availability). This is highly accurate but slower (1-60s) as it requires network interaction.