+`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.
+
+Status
+------
+The project implements all of the [BOLT
+specifications](https://github.com/lightning/bolts). 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.
+
+Communications for `rust-lightning` and Lightning Development Kit happen through
+our LDK [Discord](https://discord.gg/5AcknnMfBw) channels.
+
+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,
+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 [Core
+Lightning](https://github.com/ElementsProject/lightning) or
+[LND](https://github.com/lightningnetwork/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`](./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.