_ Git - rust-lightning/blob - README.md

   1 Rust-Lightning
   2 ==============
   3
   4 [![Crate](https://img.shields.io/crates/v/lightning.svg?logo=rust)](https://crates.io/crates/lightning)
   5 [![Documentation](https://img.shields.io/static/v1?logo=read-the-docs&label=docs.rs&message=lightning&color=informational)](https://docs.rs/lightning/)
   6 [![Safety Dance](https://img.shields.io/badge/unsafe-forbidden-success.svg)](https://github.com/rust-secure-code/safety-dance/)
   7 [![Security Audit](https://github.com/lightningdevkit/rust-lightning/actions/workflows/audit.yml/badge.svg)](https://github.com/lightningdevkit/rust-lightning/actions/workflows/audit.yml)
   8
   9 [LDK](https://lightningdevkit.org)/`rust-lightning` is a highly performant and flexible
  10 implementation of the Lightning Network protocol.
  11
  12 The primary crate, `lightning`, is runtime-agnostic. Data persistence, chain interactions,
  13 and networking can be provided by LDK's [sample modules](#crates), or you may provide your
  14 own custom implementations.
  15 More information is available in the [`About`](#about) section.
  16
  17 Status
  18 ------
  19 The project implements all of the [BOLT specifications](https://github.com/lightning/bolts),
  20 and has been in production use since 2021. As with any Lightning implementation, care and attention
  21 to detail is important for safe deployment.
  22
  23 Communications for `rust-lightning` and Lightning Development Kit happen through
  24 our LDK [Discord](https://discord.gg/5AcknnMfBw) channels.
  25
  26 Crates
  27 -----------
  28 1. [lightning](./lightning)
  29   The core of the LDK library, implements the Lightning protocol, channel state machine,
  30   and on-chain logic. Supports `no-std` and exposes only relatively low-level interfaces.
  31 2. [lightning-background-processor](./lightning-background-processor)
  32   Utilities to perform required background tasks for Rust Lightning.
  33 3. [lightning-block-sync](./lightning-block-sync)
  34   Utilities to fetch the chain data from a block source and feed them into Rust Lightning.
  35 4. [lightning-invoice](./lightning-invoice)
  36   Data structures to parse and serialize
  37   [BOLT #11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md)
  38   Lightning invoices.
  39 5. [lightning-net-tokio](./lightning-net-tokio)
  40   Implementation of the `rust-lightning` network stack using the
  41   [Tokio](https://github.com/tokio-rs/tokio) `async` runtime. For `rust-lightning`
  42   clients which wish to make direct connections to Lightning P2P nodes, this is
  43   a simple alternative to implementing the required network stack, especially
  44   for those already using Tokio.
  45 6. [lightning-persister](./lightning-persister)
  46   Implements utilities to manage `rust-lightning` channel data persistence and retrieval.
  47   Persisting channel data is crucial to avoiding loss of channel funds.
  48 7. [lightning-rapid-gossip-sync](./lightning-rapid-gossip-sync)
  49   Client for rapid gossip graph syncing, aimed primarily at mobile clients.
  50
  51 About
  52 -----------
  53 LDK/`rust-lightning` is a generic library that allows you to build a Lightning
  54 node without needing to worry about getting all of the Lightning state machine,
  55 routing, and on-chain punishment code (and other chain interactions) exactly
  56 correct. Note that LDK isn't, in itself, a node. For an out-of-the-box Lightning
  57 node based on LDK, see [Sensei](https://l2.technology/sensei). However, if you
  58 want to integrate Lightning with custom features such as your own chain sync,
  59 key management, data storage/backup logic, etc., LDK is likely your best option.
  60 Some `rust-lightning` utilities such as those in
  61 [`chan_utils`](./lightning/src/ln/chan_utils.rs) are also suitable for use in
  62 non-LN Bitcoin applications such as Discreet Log Contracts (DLCs) and bulletin boards.
  63
  64 A sample node which fetches blockchain data and manages on-chain funds via the
  65 Bitcoin Core RPC/REST interface is available
  66 [here](https://github.com/lightningdevkit/ldk-sample/). The individual pieces of
  67 that demo are composable, so you can pick the off-the-shelf parts you want
  68 and replace the rest.
  69
  70 In general, `rust-lightning` does not provide (but LDK has implementations of):
  71 * on-disk storage - you can store the channel state any way you want - whether
  72   Google Drive/iCloud, a local disk, any key-value store/database/a remote
  73   server, or any combination of them - we provide a clean API that provides
  74   objects which can be serialized into simple binary blobs, and stored in any
  75   way you wish.
  76 * blockchain data - we provide a simple `block_connected`/`block_disconnected`
  77   API which you provide block headers and transaction information to. We also
  78   provide an API for getting information about transactions we wish to be
  79   informed of, which is compatible with Electrum server requests/neutrino
  80   filtering/etc.
  81 * UTXO management - RL/LDK owns on-chain funds as long as they are claimable as
  82   part of a Lightning output which can be contested - once a channel is closed
  83   and all on-chain outputs are spendable only by the user, we provide users
  84   notifications that a UTXO is "theirs" again and it is up to them to spend it
  85   as they wish. Additionally, channel funding is accomplished with a generic API
  86   which notifies users of the output which needs to appear on-chain, which they
  87   can then create a transaction for. Once a transaction is created, we handle
  88   the rest. This is a large part of our API's goals - making it easier to
  89   integrate Lightning into existing on-chain wallets which have their own
  90   on-chain logic - without needing to move funds in and out of a separate
  91   Lightning wallet with on-chain transactions and a separate private key system.
  92 * networking - to enable a user to run a full Lightning node on an embedded
  93   machine, we don't specify exactly how to connect to another node at all! We
  94   provide a default implementation which uses TCP sockets, but, e.g., if you
  95   wanted to run your full Lightning node on a hardware wallet, you could, by
  96   piping the Lightning network messages over USB/serial and then sending them in
  97   a TCP socket from another machine.
  98 * private keys - again we have "default implementations", but users can choose to
  99   provide private keys to RL/LDK in any way they wish following a simple API. We
 100   even support a generic API for signing transactions, allowing users to run
 101   RL/LDK without any private keys in memory/putting private keys only on
 102   hardware wallets.
 103
 104 LDK's customizability was presented about at Advancing Bitcoin in February 2020:
 105 https://vimeo.com/showcase/8372504/video/412818125
 106
 107 Design Goal
 108 -----------
 109 The goal is to provide a fully-featured and incredibly flexible Lightning
 110 implementation, allowing users to decide how they wish to use it. With that
 111 in mind, everything should be exposed via simple, composable APIs. More
 112 information about `rust-lightning`'s flexibility is provided in the `About`
 113 section above.
 114
 115 For security reasons, do not add new dependencies. Really do not add new
 116 non-optional/non-test/non-library dependencies. Really really do not add
 117 dependencies with dependencies. Do convince Andrew to cut down dependency usage
 118 in `rust-bitcoin`.
 119
 120 Rust-Lightning vs. LDK (Lightning Development Kit)
 121 -------------
 122 `rust-lightning` refers to the core `lightning` crate within this repo, whereas
 123 LDK encompasses `rust-lightning` and all of its sample modules and crates (e.g.
 124 the `lightning-persister` crate), language bindings, sample node
 125 implementation(s), and other tools built around using `rust-lightning` for
 126 Lightning integration or building a Lightning node.
 127
 128 Tagline
 129 -------
 130
 131 *"Rust-Lightning, not Rusty's Lightning!"*
 132
 133 Contributing
 134 ------------
 135
 136 Contributors are warmly welcome, see [CONTRIBUTING.md](CONTRIBUTING.md).
 137
 138 Project Architecture
 139 ---------------------
 140
 141 For a `rust-lightning` high-level API introduction, see [ARCH.md](ARCH.md).
 142
 143 License is either Apache-2.0 or MIT, at the option of the user (ie dual-license
 144 Apache-2.0 and MIT).