0ad1f4c943
When we receive an update_fulfill_htlc message, we immediately try to "claim" the HTLC against the HTLCSource. If there is one, this works great, we immediately generate a `ChannelMonitorUpdate` for the corresponding inbound HTLC and persist that before we ever get to processing our counterparty's `commitment_signed` and persisting the corresponding `ChannelMonitorUpdate`. However, if there isn't one (and this is the first successful HTLC for a payment we sent), we immediately generate a `PaymentSent` event and queue it up for the user. Then, a millisecond later, we receive the `commitment_signed` from our peer, removing the HTLC from the latest local commitment transaction as a side-effect of the `ChannelMonitorUpdate` applied. If the user has processed the `PaymentSent` event by that point, great, we're done. However, if they have not, and we crash prior to persisting the `ChannelManager`, on startup we get confused about the state of the payment. We'll force-close the channel for being stale, and see an HTLC which was removed and is no longer present in the latest commitment transaction (which we're broadcasting). Because we claim corresponding inbound HTLCs before updating a `ChannelMonitor`, we assume such HTLCs have failed - attempting to fail after having claimed should be a noop. However, in the sent-payment case we now generate a `PaymentFailed` event for the user, allowing an HTLC to complete without giving the user a preimage. Here we address this issue by storing the payment preimages for claimed outbound HTLCs in the `ChannelMonitor`, in addition to the existing inbound HTLC preimages already stored there. This allows us to fix the specific issue described by checking for a preimage and switching the type of event generated in response. In addition, it reduces the risk of future confusion by ensuring we don't fail HTLCs which were claimed but not fully committed to before a crash. It does not, however, full fix the issue here - because the preimages are removed after the HTLC has been fully removed from available commitment transactions if we are substantially delayed in persisting the `ChannelManager` from the time we receive the `update_fulfill_htlc` until after a full commitment signed dance completes we may still hit this issue. The full fix for this issue is to delay the persistence of the `ChannelMonitorUpdate` until after the `PaymentSent` event has been processed. This avoids the issue entirely, ensuring we process the event before updating the `ChannelMonitor`, the same as we ensure the upstream HTLC has been claimed before updating the `ChannelMonitor` for forwarded payments. The full solution will be implemented in a later work, however this change still makes sense at that point as well - if we were to delay the initial `commitment_signed` `ChannelMonitorUpdate` util after the `PaymentSent` event has been processed (which likely requires a database update on the users' end), we'd hold our `commitment_signed` + `revoke_and_ack` response for two DB writes (i.e. `fsync()` calls), making our commitment transaction processing a full `fsync` slower. By making this change first, we can instead delay the `ChannelMonitorUpdate` from the counterparty's final `revoke_and_ack` message until the event has been processed, giving us a full network roundtrip to do so and avoiding delaying our response as long as an `fsync` is faster than a network roundtrip. |
||
|---|---|---|
| .github/workflows | ||
| ci | ||
| fuzz | ||
| lightning | ||
| lightning-background-processor | ||
| lightning-block-sync | ||
| lightning-custom-message | ||
| lightning-invoice | ||
| lightning-net-tokio | ||
| lightning-persister | ||
| lightning-rapid-gossip-sync | ||
| lightning-transaction-sync | ||
| no-std-check | ||
| pending_changelog | ||
| .editorconfig | ||
| .gitignore | ||
| ARCH.md | ||
| Cargo.toml | ||
| CHANGELOG.md | ||
| codecov.yml | ||
| CONTRIBUTING.md | ||
| GLOSSARY.md | ||
| LICENSE-APACHE | ||
| LICENSE-MIT | ||
| LICENSE.md | ||
| README.md | ||
| rustfmt.toml | ||
| SECURITY.md | ||
Rust-Lightning
LDK/rust-lightning is a highly performant and flexible
implementation of the Lightning Network protocol.
The primary crate, lightning, is runtime-agnostic. Data persistence, chain interactions,
and networking can be provided by LDK's sample modules, or you may provide your
own custom implementations.
More information is available in the About section.
Status
The project implements all of the BOLT specifications, and has been in production use since 2021. As with any Lightning implementation, care and attention to detail is important for safe deployment.
Communications for rust-lightning and Lightning Development Kit happen through
our LDK Discord channels.
Crates
- lightning
The core of the LDK library, implements the Lightning protocol, channel state machine,
and on-chain logic. Supports
no-stdand exposes only relatively low-level interfaces. - lightning-background-processor Utilities to perform required background tasks for Rust Lightning.
- lightning-block-sync Utilities to fetch the chain data from a block source and feed them into Rust Lightning.
- lightning-invoice Data structures to parse and serialize BOLT #11 Lightning invoices.
- lightning-net-tokio
Implementation of the
rust-lightningnetwork stack using the Tokioasyncruntime. Forrust-lightningclients which wish to make direct connections to Lightning P2P nodes, this is a simple alternative to implementing the required network stack, especially for those already using Tokio. - lightning-persister
Implements utilities to manage
rust-lightningchannel data persistence and retrieval. Persisting channel data is crucial to avoiding loss of channel funds. - lightning-rapid-gossip-sync Client for rapid gossip graph syncing, aimed primarily at mobile clients.
About
LDK/rust-lightning is a generic library that allows you to build a Lightning
node without needing to worry about getting all of the Lightning state machine,
routing, and on-chain punishment code (and other chain interactions) exactly
correct. Note that LDK isn't, in itself, a node. For an out-of-the-box Lightning
node based on LDK, see Sensei. However, if you
want 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.
Some rust-lightning utilities such as those in
chan_utils are also suitable for use in
non-LN Bitcoin applications such as Discreet Log Contracts (DLCs) and bulletin boards.
A sample node which fetches blockchain data and manages on-chain funds via the Bitcoin Core RPC/REST interface is available here. The individual pieces of that demo are composable, so you can pick the off-the-shelf parts you want and replace the rest.
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 - whether Google Drive/iCloud, a local disk, any key-value store/database/a remote server, or any combination of them - we provide a clean API that provides objects which can be serialized into simple binary blobs, and stored in any way you wish.
- blockchain data - we provide a simple
block_connected/block_disconnectedAPI which you provide block headers and transaction information to. We also provide an API for getting information about transactions we wish to be informed of, which is compatible with Electrum server requests/neutrino filtering/etc. - UTXO management - RL/LDK owns on-chain funds as long as they are claimable as part of a Lightning output which can be contested - once a channel is closed and all on-chain outputs are spendable only by the user, we provide users notifications that a UTXO is "theirs" again and it is up to them to spend it as they wish. Additionally, channel funding is accomplished with a generic API which notifies users of the output which needs to appear on-chain, which they can then create a transaction for. Once a transaction is created, we handle the rest. This is a large part of our API's goals - making it easier to integrate Lightning into existing on-chain wallets which have their own on-chain logic - without needing to move funds in and out of a separate Lightning wallet with on-chain transactions and a separate private key system.
- networking - to enable a user to run a full Lightning node on an embedded machine, we don't specify exactly how to connect to another node at all! We provide a default implementation which uses TCP sockets, but, e.g., if you wanted to run your full Lightning node on a hardware wallet, you could, by piping the Lightning network messages over USB/serial and then sending them in a TCP socket from another machine.
- private keys - again we have "default implementations", but users can chose to provide private keys to RL/LDK in any way they wish following a simple API. We even support a generic API for signing transactions, allowing users to run RL/LDK without any private keys in memory/putting private keys only on hardware wallets.
LDK's customizability was presented about at Advancing Bitcoin in February 2020: https://vimeo.com/showcase/8372504/video/412818125
Design Goal
The goal is to provide a fully-featured and incredibly flexible Lightning
implementation, allowing users to decide how they wish to use it. With that
in mind, everything should be exposed via simple, composable APIs. More
information about rust-lightning's flexibility is provided in the About
section above.
For security reasons, do not add new dependencies. Really do not add new
non-optional/non-test/non-library dependencies. Really really do not add
dependencies with dependencies. Do convince Andrew to cut down dependency usage
in rust-bitcoin.
Rust-Lightning vs. LDK (Lightning Development Kit)
rust-lightning refers to the core lightning crate within this repo, whereas
LDK encompasses rust-lightning and all of its sample modules and crates (e.g.
the lightning-persister crate), language bindings, sample node
implementation(s), and other tools built around using rust-lightning for
Lightning integration or building a Lightning node.
Tagline
"Rust-Lightning, not Rusty's Lightning!"
Contributing
Contributors are warmly welcome, see CONTRIBUTING.md.
Project Architecture
For a rust-lightning high-level API introduction, see ARCH.md.
License is either Apache-2.0 or MIT, at the option of the user (ie dual-license Apache-2.0 and MIT).