Reword first paragraph and add tagline

[rust-lightning] / README.md

diff --git a/README.md b/README.md
index b8807aad57873e45920b41d5b401226789c95791..4d0da8dd5372e82abf1e61efc7cbb0f1fd1ddb92 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,9 +1,20 @@
+Rust-Lightning
+==============
+
+[![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, not Rusty's Lightning!
-=====
+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 is a full Lightning using the
+[Tokio](https://github.com/tokio-rs/tokio) async runtime.
 
-Documentation can be found at [docs.rs](https://docs.rs/lightning/)
+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
@@ -16,6 +27,12 @@ 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
 in mind, everything should be exposed via simple, composable APIs. The user
@@ -32,8 +49,21 @@ non-optional/non-test/non-library dependencies. Really really do not add
 dependencies with dependencies. Do convince Andrew to cut down dependency usage
 in rust-bitcoin.
 
-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.
 
-License is Apache-2.0.
+Tagline
+-------
+
+*"Rust-Lightning, not Rusty's Lightning!"*
+
+Contributing
+------------
+
+Contributors are warmly welcome, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+Project Architecture
+---------------------
+
+For a Rust-Lightning high-level API introduction, see [ARCH.md](ARCH.md).
+
+License is either Apache-2.0 or MIT, at the option of the user (ie dual-license
+Apache-2.0 and MIT).