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