X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=README.md;h=f8de40f3193af3fa2fb0be80799b320e0391ff7b;hb=refs%2Fheads%2Fupstream%2Fmain;hp=d73e71da8aaf3a10fa076ca6fc953f6949094c78;hpb=25c9a37e18b6e3e30a9ad0c8645fb8da34413199;p=rust-lightning diff --git a/README.md b/README.md index d73e71da..f8de40f3 100644 --- a/README.md +++ b/README.md @@ -4,55 +4,70 @@ Rust-Lightning [![Crate](https://img.shields.io/crates/v/lightning.svg?logo=rust)](https://crates.io/crates/lightning) [![Documentation](https://img.shields.io/static/v1?logo=read-the-docs&label=docs.rs&message=lightning&color=informational)](https://docs.rs/lightning/) [![Safety Dance](https://img.shields.io/badge/unsafe-forbidden-success.svg)](https://github.com/rust-secure-code/safety-dance/) +[![Security Audit](https://github.com/lightningdevkit/rust-lightning/actions/workflows/audit.yml/badge.svg)](https://github.com/lightningdevkit/rust-lightning/actions/workflows/audit.yml) -Rust-Lightning is a Bitcoin Lightning library written in Rust. The main crate, -`lightning`, does not handle networking, persistence, or any other I/O. Thus, -it is runtime-agnostic, but users must implement basic networking logic, chain -interactions, and disk storage. More information is available in the `About` -section. +[LDK](https://lightningdevkit.org)/`rust-lightning` is a highly performant and flexible +implementation of the Lightning Network protocol. -The `lightning-net-tokio` crate implements Lightning networking using the -[Tokio](https://github.com/tokio-rs/tokio) async runtime. - -The `lightning-persister` crate implements persistence for channel data that -is crucial to avoiding loss of channel funds. Sample modules for persistence of -other Rust-Lightning data is coming soon. +The primary crate, `lightning`, is runtime-agnostic. Data persistence, chain interactions, +and networking can be provided by LDK's [sample modules](#crates), or you may provide your +own custom implementations. +More information is available in the [`About`](#about) section. Status ------ +The project implements all of the [BOLT specifications](https://github.com/lightning/bolts), +and has been in production use since 2021. As with any Lightning implementation, care and attention +to detail is important for safe deployment. -The project implements all of the BOLT specifications in the 1.0 spec. The -implementation has pretty good test coverage that is expected to continue to -improve. It is also anticipated that as developers begin using the API, the -lessons from that will result in changes to the API, so any developer using this -API at this stage should be prepared to embrace that. The current state is -sufficient for a developer or project to experiment with it. Recent increased -contribution rate to the project is expected to lead to a high quality, stable, -production-worthy implementation in 2021. +Communications for `rust-lightning` and Lightning Development Kit happen through +our LDK [Discord](https://discord.gg/5AcknnMfBw) channels. -Communications for Rust-Lightning and Lightning Development Kit happens through -[LDK slack](http://lightningdevkit.org/). +Crates +----------- +1. [lightning](./lightning) + The core of the LDK library, implements the Lightning protocol, channel state machine, + and on-chain logic. Supports `no-std` and exposes only relatively low-level interfaces. +2. [lightning-background-processor](./lightning-background-processor) + Utilities to perform required background tasks for Rust Lightning. +3. [lightning-block-sync](./lightning-block-sync) + Utilities to fetch the chain data from a block source and feed them into Rust Lightning. +4. [lightning-invoice](./lightning-invoice) + Data structures to parse and serialize + [BOLT #11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md) + Lightning invoices. +5. [lightning-net-tokio](./lightning-net-tokio) + Implementation of the `rust-lightning` network stack using the + [Tokio](https://github.com/tokio-rs/tokio) `async` runtime. For `rust-lightning` + clients 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. +6. [lightning-persister](./lightning-persister) + Implements utilities to manage `rust-lightning` channel data persistence and retrieval. + Persisting channel data is crucial to avoiding loss of channel funds. +7. [lightning-rapid-gossip-sync](./lightning-rapid-gossip-sync) + Client for rapid gossip graph syncing, aimed primarily at mobile clients. About ----------- -LDK/Rust-Lightning is a generic library which allows you to build a lightning -node without needing to worry about getting all of the lightning state machine, +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 Rust-Lightning isn't, in itself, a node. There are various -working/in progress demos which could be used as a node today, but if you "just" -want a generic lightning node, you're almost certainly better off with -`c-lightning`/`lnd` - if, on the other hand, you want to integrate lightning -with custom features such as your own chain sync, your own key management, your -own data storage/backup logic, etc., LDK is likely your only option. Some -Rust-Lightning utilities such as those in `chan_utils` are also suitable for use -in non-LN Bitcoin applications such as DLCs and bulletin boards. - -We are currently working on a demo node which fetches blockchain data and -on-chain funds via Bitcoin Core RPC/REST. The individual pieces of that demo -are/will be 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): +correct. Note that LDK isn't, in itself, a node. For an out-of-the-box Lightning +node based on LDK, see [Sensei](https://l2.technology/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`](./lightning/src/ln/chan_utils.rs) 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](https://github.com/lightningdevkit/ldk-sample/). 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 @@ -64,52 +79,51 @@ In general, Rust-Lightning does not provide (but LDK has implementations of): 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 - a part of a lightning output which can be contested - once a channel is closed + 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 + 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 + 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 + 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 +* private keys - again we have "default implementations", but users can choose 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/7131712/video/418412286 +https://vimeo.com/showcase/8372504/video/412818125 Design Goal ----------- - -The goal is to provide a full-featured but also incredibly flexible lightning -implementation, allowing the user to decide how they wish to use it. With that +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` +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. +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. +`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. +implementation(s), and other tools built around using `rust-lightning` for +Lightning integration or building a Lightning node. Tagline ------- @@ -124,7 +138,7 @@ Contributors are warmly welcome, see [CONTRIBUTING.md](CONTRIBUTING.md). Project Architecture --------------------- -For a Rust-Lightning high-level API introduction, see [ARCH.md](ARCH.md). +For a `rust-lightning` high-level API introduction, see [ARCH.md](ARCH.md). License is either Apache-2.0 or MIT, at the option of the user (ie dual-license Apache-2.0 and MIT).