This document covers everything you need to make a node using LDK in Rust.
For an integrated example of an LDK node in Rust, see the Sample Node
- Setup covers everything you need to do to set up LDK on startup.
- Running LDK covers everything you need to do while LDK is running to keep it operational.
Note that LDK does not assume that safe shutdown is available, so there is no shutdown checklist.
1. Initialize the
What it's used for: estimating fees for on-chain transactions that LDK wants broadcasted.
- Fees must be returned in: satoshis per 1000 weight units
- Fees must be no smaller than 253 (equivalent to 1 satoshi/vbyte, rounded up)
- To reduce network traffic, you may want to cache fee results rather than retrieving fresh ones every time
2. Initialize the
What it's used for: LDK logging
Implementation notes: you'll likely want to write the logs to a file for debugging purposes.
3. Initialize the
What it's used for: broadcasting various lightning transactions
What it's used for: persisting
ChannelMonitors, which contain crucial channel data, in a timely manner
- Using LDK Sample Filesystem Persistence Module
ChannelMonitors are objects which are capable of responding to on-chain events for a given channel. Thus, you will have one
ChannelMonitorper channel. They are persisted in real-time and the
Persistmethods will block progress on sending or receiving payments until they return. You must ensure that
ChannelMonitors are durably persisted to disk before returning or you may lose funds.
- If you implement a custom persister, it's important to read the trait docs (linked in References) to make sure you satisfy the API requirements, particularly for
5. Optional: Initialize the Transaction
You must follow this step if: you are not providing full blocks to LDK, i.e. if you're using BIP 157/158 or Electrum as your chain backend
What it's used for: if you are not providing full blocks, LDK uses this object to tell you what transactions and outputs to watch for on-chain. You'll inform LDK about these transactions/outputs in Step 15.
Implementation notes: see the Blockchain Data guide for more info
6. Initialize the
What it's used for: tracking one or more
ChannelMonitors and using them to monitor the chain for lighting transactions that are relevant to our node, and broadcasting transactions if need be
Filter must be non-
None if you're using Electrum or BIP 157/158 as your chain backend
7. Initialize the
What it's used for: providing keys for signing lightning transactions
- See the Key Management guide for more info
- Note that you must write the
key_seedyou give to the
KeysManageron startup to disk, and keep using it to initialize the
KeysManagerevery time you restart. This
key_seedis used to derive your node's secret key (which corresponds to its node pubkey) and all other secret key material.
- The current time is part of the
KeysManager's parameters because it is used to derive random numbers from the seed where required, to ensure all random generation is unique across restarts.
Dependencies: random bytes
ChannelMonitors from disk#
What it's used for: if LDK is restarting and has at least 1 channel, its
ChannelMonitors will need to be (1) fed to the
ChannelManager in Step 9 and (2) synced to chain in Step 10.
Example: using LDK's sample persistence module
9. Initialize the
What it's used for: managing channel state
Implementation notes: No methods should be called on
after Step 10.
- If restarting:
ChannelManagerbytes from Step 8 and Step 17 respectively
ChannelManager to chain tip#
What it's used for: this step is only necessary if you're restarting and have open channels. This step ensures that LDK channel state is up-to-date with the bitcoin blockchain
- Full Blocks or BIP 157/158
- There are 2 main options for synchronizing to chain on startup:
- If you are connecting full blocks or using BIP 157/158, then it is recommended to use
lightning_block_syncsample module as in the example above
- Otherwise, you can use LDK's
Confirminterface as in the Electrum example above
- If you are connecting full blocks or using BIP 157/158, then it is recommended to use LDK's
- More details about LDK's interfaces to provide chain info in Step 15
- If providing providing full blocks or BIP 157/158: set of
- If using Electrum:
What it's used for:
ChainMonitor is responsible for updating the
ChannelMonitors during LDK node operation.
ChainMonitor, set of
ChannelMonitors and their funding outpoints
- Step 10 must be completed prior to this step
12. Optional: Initialize the
You must follow this step if: you need LDK to provide routes for sending payments (i.e. you are not providing your own routes)
What it's used for: generating routes to send payments over
NetGraphMsgHandler without providing an
Implementation notes: this struct is not required if you are providing your own routes.
Access, a source of chain information. Recommended to be able to verify channels before adding them to the internal network graph.
13. Initialize the
What it's used for: managing peer data and connections
Implementation notes: if you did not initialize
NetGraphMsgHandler in the previous step, you can initialize your own struct (which can be a dummy struct) that implements
KeysManager, random bytes,
What it's used for: making peer connections, facilitating peer data to and from LDK
This section assumes you've already run all the steps in Setup.
What it's used for: LDK needs to know when blocks are newly connected and disconnected and when relevant transactions are confirmed and/or reorged out.
- If you're using the
Listeninterface: blocks must be connected and disconnected in chain order
- If you're using the
Confirminterface: it's important to read the
Confirmdocs linked in References, to make sure you satisfy the interface's requirements
16. Initialize LDK
What it's used for: LDK generates events that must be handled by you, such as telling you when a payment has been successfully received or when a funding transaction is ready for broadcast.
Example: from the LDK Rust sample node, of handling these events: https://github.com/lightningdevkit/ldk-sample/blob/bc07db6ca4a3323d8718a27f85182b8157a20750/src/main.rs#L101-L240
- It's important to read the documentation for individual event handling (linked in References below) to make sure event handling requirements are satisfied
- It is recommended to read through event handling in the LDK sample node (linked in the first example) to get an idea of what integrated LDK event handling looks like
17. Initialize the
What it's used for: keeping
ChannelManager's stored state up-to-date
Implementation notes: if the
ChannelManager is not persisted properly to disk, there is risk of channels force closing the next time LDK starts up. However, in this situation, no funds other than those used to pay force-closed channel fees are at risk of being lost.
What it's used for: running tasks periodically in the background to keep LDK operational
What it's used for: if you have 1 or more public channels, you may need to announce your node and its channels occasionally. LDK will automatically announce channels when they are created, but there are no guarantees you have connected peers at that time or that your peers will propagate such announcements. The broader node-announcement message is not automatically broadcast.