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