Repository files navigation

LDK/rust-lightning is a highly performant and flexibleimplementation of the Lightning Network protocol.

The primary crate,lightning, is runtime-agnostic. Data persistence, chain interactions,and networking can be provided by LDK'ssample modules, or you may provide yourown custom implementations.More information is available in theAbout section.

The project implements all of theBOLT specifications,and has been in production use since 2021. As with any Lightning implementation, care and attentionto detail is important for safe deployment.

Communications forrust-lightning and Lightning Development Kit happen throughour LDKDiscord channels.

1. lightningThe core of the LDK library, implements the Lightning protocol, channel state machine,and on-chain logic. Supportsno_std and exposes only relatively low-level interfaces.
2. lightning-background-processorUtilities to perform required background tasks for Rust Lightning.
3. lightning-block-syncUtilities to fetch the chain data from a block source and feed them into Rust Lightning.
4. lightning-invoiceData structures to parse and serializeBOLT #11Lightning invoices.
5. lightning-net-tokioImplementation of therust-lightning network stack using theTokioasync runtime. Forrust-lightningclients which wish to make direct connections to Lightning P2P nodes, this isa simple alternative to implementing the required network stack, especiallyfor those already using Tokio.
6. lightning-persisterImplements utilities to managerust-lightning channel data persistence and retrieval.Persisting channel data is crucial to avoiding loss of channel funds.
7. lightning-rapid-gossip-syncClient for rapid gossip graph syncing, aimed primarily at mobile clients.

LDK/rust-lightning is a generic library that allows you to build a Lightningnode without needing to worry about getting all of the Lightning state machine,routing, and on-chain punishment code (and other chain interactions) exactlycorrect. Note that LDK isn't, in itself, a node. For an out-of-the-box Lightningnode based on LDK, seeLDK-sample. However, if youwant to integrate Lightning with custom features such as your own chain sync,key management, data storage/backup logic, etc., LDK is likely your best option.Somerust-lightning utilities such as those inchan_utils are also suitable for use innon-LN Bitcoin applications such as Discreet Log Contracts (DLCs) and bulletin boards.

Also check outLDK-node libraryif you want to easily integrate lightning in your application without taking care ofall the boiler plate code.

In general,rust-lightning does not provide (but LDK has implementations of):

• on-disk storage - you can store the channel state any way you want - whetherGoogle Drive/iCloud, a local disk, any key-value store/database/a remoteserver, or any combination of them - we provide a clean API that providesobjects which can be serialized into simple binary blobs, and stored in anyway you wish.
• blockchain data - we provide a simpleblock_connected/block_disconnectedAPI which you provide block headers and transaction information to. We alsoprovide an API for getting information about transactions we wish to beinformed of, which is compatible with Electrum server requests/neutrinofiltering/etc.
• UTXO management - RL/LDK owns on-chain funds as long as they are claimable aspart of a Lightning output which can be contested - once a channel is closedand all on-chain outputs are spendable only by the user, we provide usersnotifications that a UTXO is "theirs" again and it is up to them to spend itas they wish. Additionally, channel funding is accomplished with a generic APIwhich notifies users of the output which needs to appear on-chain, which theycan then create a transaction for. Once a transaction is created, we handlethe rest. This is a large part of our API's goals - making it easier tointegrate Lightning into existing on-chain wallets which have their ownon-chain logic - without needing to move funds in and out of a separateLightning wallet with on-chain transactions and a separate private key system.
• networking - to enable a user to run a full Lightning node on an embeddedmachine, we don't specify exactly how to connect to another node at all! Weprovide a default implementation which uses TCP sockets, but, e.g., if youwanted to run your full Lightning node on a hardware wallet, you could, bypiping the Lightning network messages over USB/serial and then sending them ina TCP socket from another machine.
• private keys - again we have "default implementations", but users can choose toprovide private keys to RL/LDK in any way they wish following a simple API. Weeven support a generic API for signing transactions, allowing users to runRL/LDK without any private keys in memory/putting private keys only onhardware wallets.

LDK's customizability was presented about at Advancing Bitcoin in February 2020:https://vimeo.com/showcase/8372504/video/412818125

The goal is to provide a fully-featured and incredibly flexible Lightningimplementation, allowing users to decide how they wish to use it. With thatin mind, everything should be exposed via simple, composable APIs. Moreinformation aboutrust-lightning's flexibility is provided in theAboutsection above.

For security reasons, do not add new dependencies. Really do not add newnon-optional/non-test/non-library dependencies. Really really do not adddependencies with dependencies. Do convince Andrew to cut down dependency usageinrust-bitcoin.

rust-lightning refers to the corelightning crate within this repo, whereasLDK encompassesrust-lightning and all of its sample modules and crates (e.g.thelightning-persister crate), language bindings, sample nodeimplementation(s), and other tools built around usingrust-lightning forLightning integration or building a Lightning node.

"Rust-Lightning, not Rusty's Lightning!"

Contributors are warmly welcome, seeCONTRIBUTING.md.

For arust-lightning high-level API introduction, seeARCH.md.

License is either Apache-2.0 or MIT, at the option of the user (ie dual-licenseApache-2.0 and MIT).