WIP: try to enforce signing vs revocation

CONTRIBUTING.md

@@ -30,9 +30,13 @@ Getting Started
 First and foremost, start small.
 
 This doesn't mean don't be ambitious with the breadth and depth of your contributions but rather
-understand the project context and culture before investing an asymmetric number of hours on
+understand the project culture before investing an asymmetric number of hours on
 development compared to your merged work.
 
+Browsing through the [meeting minutes](https://github.com/rust-bitcoin/rust-lightning/wiki/Meetings)
+is a good first step. You will learn who is working on what, how releases are drafted, what are the
+pending tasks to deliver, where you can contribute review bandwidth, etc.
+
 Even if you have an extensive open source background or sound software engineering skills, consider
 that the reviewers' comprehension of the code is as much important as technical correctness.
 
@@ -43,6 +47,8 @@ a "soft" commitment.
 If you're eager to increase the velocity of the dev process, reviewing other contributors work is
 the best you can do while waiting review on yours.
 
+Also, getting familiar with the [glossary](GLOSSARY.md) will streamline discussions with regular contributors.
+
 Contribution Workflow
 ---------------------
 

GLOSSARY.md

@@ -0,0 +1,31 @@
+# Glossary
+
+This document gathers the canonical Lightning nomenclature used by LDK contributors. Note, they may diverge from the BOLT specs or the ones used by the wider Lightning community; the test of time has revealed that it can be hard to agree on terminology. The following terms are employed with a best effort across the codebase aiming to reduce confusion.
+
+### Channel Initiator
+
+The channel initiator is the entity who is taking the decision to open a channel. Finalization relies upon the counterparty's channel acceptance policy. Within current protocol version, the initiator has the burden of paying channel onchain fees.
+
+### Holder/Counterparty
+
+Inspired by financial cryptography, a holder is an owner of a given digital value. In Lightning, the holder is the entity operating the current node, of which the interests are served by the implementation during channel operations. The counterparty is the entity participating in the channel operation as a peer, but of whom the interests are not of concern by the implementation.
+
+Used across the `Channel` data structure, part of the channel-management subsystem.
+
+### Broadcaster/Countersignatory
+
+In Lightning, states are symmetric but punishment is asymmetric, which forces channel parties to hold different commitment transactions. At transaction construction, the broadcaster designates the entity that has the unilateral capability to broadcast the transaction. The countersignatory is the entity providing signatures for the broadcastable transaction and thus verifying it encodes the off-chain states. At any point in time, there should be two "latest" commitment transactions that have been processed by each party's implementation, one where the holder is the broadcaster and the counterparty is countersignatory, and one where the holder is the countersignatory and the counterparty is the broadcaster.
+
+Used across the channel-utils library (`chan_utils.rs`).
+
+### Watchtower
+
+A watchtower is an external untrusted service that can only publish justice transactions. The security property of watchtowers is that if you subscribe to *N* of them, you will be safe if at least 1 does the right thing.
+
+A (future) deployment configuration of the monitoring (`ChainMonitor`) subsystem.
+
+### Monitor Replicas
+
+An instance of a highly available distributed channel-monitor. It must have a correctly working HSM, because they have sensitive keys that can cause loss of all funds in the channel.
+
+A deployment configuration of the monitoring (`ChainMonitor`) subsystem.

README.md

@@ -8,47 +8,108 @@ Rust-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.
+interactions, and disk storage. More information is available in the `About`
+section.
 
 The `lightning-net-tokio` crate implements Lightning networking using the
 [Tokio](https://github.com/tokio-rs/tokio) async runtime.
 
+The `lightning-persister` crate implements persistence for channel data that
+is crucial to avoiding loss of channel funds. Sample modules for persistence of
+other Rust-Lightning data is coming soon.
+
 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
+The project implements all of the BOLT specifications in the 1.0 spec. 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.
+improve. 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 2021.
 
 Communications for Rust-Lightning and Lightning Development Kit happens through
 [LDK slack](http://lightningdevkit.org/).
 
+About
+-----------
+LDK/Rust-Lightning is a generic library which allows you to build a lightning
+node without needing to worry about getting all of the lightning state machine,
+routing, and on-chain punishment code (and other chain interactions) exactly
+correct. Note that Rust-Lightning isn't, in itself, a node. There are various
+working/in progress demos which could be used as a node today, but if you "just"
+want a generic lightning node, you're almost certainly better off with
+`c-lightning`/`lnd` - if, on the other hand, you want to integrate lightning
+with custom features such as your own chain sync, your own key management, your
+own data storage/backup logic, etc., LDK is likely your only option. Some
+Rust-Lightning utilities such as those in `chan_utils` are also suitable for use
+in non-LN Bitcoin applications such as DLCs and bulletin boards.
+
+We are currently working on a demo node which fetches blockchain data and
+on-chain funds via Bitcoin Core RPC/REST. The individual pieces of that demo
+are/will be composable, so you can pick the off-the-shelf parts you want and
+replace the rest.
+
+In general, Rust-Lightning does not provide (but LDK has implementations of):
+* on-disk storage - you can store the channel state any way you want - whether
+  Google Drive/iCloud, a local disk, any key-value store/database/a remote
+  server, or any combination of them - we provide a clean API that provides
+  objects which can be serialized into simple binary blobs, and stored in any
+  way you wish.
+* blockchain data - we provide a simple `block_connected`/`block_disconnected`
+  API which you provide block headers and transaction information to. We also
+  provide an API for getting information about transactions we wish to be
+  informed of, which is compatible with Electrum server requests/neutrino
+  filtering/etc.
+* UTXO management - RL/LDK owns on-chain funds as long as they are claimable as
+  a part of a lightning output which can be contested - once a channel is closed
+  and all on-chain outputs are spendable only by the user, we provide users
+  notifications that a UTXO is "theirs" again and it is up to them to spend it
+  as they wish. Additionally, channel funding is accomplished with a generic API
+  which notifies users of the output which needs to appear on-chain, which they
+  can then create a transaction for. Once a transaction is created, we handle
+  the rest. This is a large part of our API's goals - making it easier to
+  integrate lightning into existing on-chain wallets which have their own
+  on-chain logic - without needing to move funds in and out of a separate
+  lightning wallet with on-chain transactions and a separate private key system.
+* networking - to enable a user to run a full lightning node on an embedded
+  machine, we don't specify exactly how to connect to another node at all! We
+  provide a default implementation which uses TCP sockets, but, e.g., if you
+  wanted to run your full lightning node on a hardware wallet, you could, by
+  piping the lightning network messages over USB/serial and then sending them in
+  a TCP socket from another machine.
+* private keys - again we have "default implementations", but users can chose to
+  provide private keys to RL/LDK in any way they wish following a simple API. We
+  even support a generic API for signing transactions, allowing users to run
+  RL/LDK without any private keys in memory/putting private keys only on
+  hardware wallets.
+
+LDK's customizability was presented about at Advancing Bitcoin in February 2020:
+https://vimeo.com/showcase/7131712/video/418412286
+
 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
-should be able to decide whether they wish to use their own threading/execution
-models, allowing usage inside of existing library architectures, or allow us to
-handle that for them. Same goes with network connections - if the user wishes
-to use their own networking stack, they should be able to do so! This all means
-that we should provide simple external interfaces which allow the user to drive
-all execution, while implementing sample execution drivers that create a
-full-featured lightning daemon by default.
+in mind, everything should be exposed via simple, composable APIs. More
+information about Rust-Lightning's flexibility is provided in the `About`
+section above.
 
 For security reasons, do not add new dependencies. Really do not add new
 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.
 
+Rust-Lightning vs. LDK (Lightning Development Kit)
+-------------
+Rust-Lightning refers to the core `lightning` crate within this repo, whereas
+LDK encompasses Rust-Lightning and all of its sample modules and crates (e.g.
+the `lightning-persister` crate), language bindings, sample node
+implementation(s), and other tools built around using Rust-Lightning for
+lightning integration or building a lightning node.
 
 Tagline
 -------