-Rust-Lightning, not Rusty's Lightning!
+Rust-Lightning
+==============
-Currently somewhere near 5% towards usable, published to see if there is any
-real interest from folks in either contributing to or using a lightning rust
-library.
+[![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/)
+
+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.
+
+The `lightning-net-tokio` crate implements Lightning networking using the
+[Tokio](https://github.com/tokio-rs/tokio) async runtime.
+
+Status
+------
+
+The project implements all of the BOLT specifications in the 1.0 spec except
+for [channel queries](https://github.com/lightningnetwork/lightning-rfc/blob/master/07-routing-gossip.md#query-messages). The
+implementation has pretty good test coverage that is expected to continue to
+improve. There are a number of internal refactorings being done now that will
+make the code base more welcoming to new contributors. 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 2020.
+
+Communications for Rust-Lightning and Lightning Development Kit happens through
+[LDK slack](http://lightningdevkit.org/).
+
+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
dependencies with dependencies. Do convince Andrew to cut down dependency usage
in rust-bitcoin.
-Assorted random TODOs:
-
- * Create a general timer interface - this should be passed around in reference
- form to most objects to allow them to register functions which are called on
- a timer. By default we should provide an implementation of this which uses
- some newfangled rusty promise-y library, but should generally ensure a
- client can simply integrate this into whatever existing timer interface
- they use.
-
- * Networking...having a simple bytes-in-bytes-out interface which does message
- handling and calls our encryption layer is probably the right approach. We
- should then also probably use the same promise-y library we use for timers
- to do socket selection and reading/writing.
-
- * Figure out how to expose when-to-connect and who-to-connect-to.
-
- * Implement when-to-connect and who-to-connect-to based on route/node rumoring
- and channelmanager state.
-
- * Some kind of serialization format for on-disk storage of things like
- channels, channelmonitors, routing db, etc.
-
- * BOLT 10/network bootstrapping implementation.
- * Some kind of DoS thing including ban tracking and putting that info in
- HandleError (and also rename HandleError) to be propagated up...and then
- handled.
+Tagline
+-------
- * All the random TODOs and unimplemented!()s across the codebase.
+*"Rust-Lightning, not Rusty's Lightning!"*
- * BOLT 11 (invoice/address creation/generation) implementation
+Contributing
+------------
- * Type-ify our somewhat random usage of Uint256/[u8; 32]. Use Sha256dHash
- where appropriate, create our own types for everything else.
+Contributors are warmly welcome, see [CONTRIBUTING.md](CONTRIBUTING.md).
- * Some kind of logging subsystem/API.
+Project Architecture
+---------------------
-Notes on coding style:
- * Use tabs. If you want to align lines, use spaces. Any desired alignment
- should display fine at any tab-length display setting.
+For a Rust-Lightning high-level API introduction, see [ARCH.md](ARCH.md).
-License is Apache-2.0.
+License is either Apache-2.0 or MIT, at the option of the user (ie dual-license
+Apache-2.0 and MIT).