Add a GLOSSARY.md

Closes #766

Contributions by Devrandom <[email protected]>

Author: Antoine Riard

GLOSSARY.md

@@ -0,0 +1,27 @@
+# Glossary
+
+This document gathers the canonical nomenclature of the Lightning concepts used by the 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 terms employed. The following terms are employed with a best effort across the codebase aiming to reduce both code reviewers and library users confusion.
+
+### Holder/Counterparty
+
+Inspired by financial cryptography, the holder is the entity beneficiary of a right. In LDK context, it designates the entity who is served by the implementation in its 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. Those roles are fixed for the lifetime of a channel and doesn't change in fonction of the state (message, blocks, ...) processed.
+
+Used across the channel-management subsystem (`Channel`).
+
+### Broadcaster/Countersignatory
+
+In Lightning, states are symmetrics but punishment is asymmetric, which forces channel parties to hold different commitment transactions. At transaction construction, the broadcaster designates the entity which has the unilateral capability to broadcast the tranaction. The countersignatory designates the entity providing signatures for the broadcastable transaction and thus verifying its encodes the off-chain states. Those roles are dynamic for the lifetime of a channel and change during the phases of a channel update.
+
+Used across the channel-utils library (`chan_utils.rs`).
+
+### Watchtower
+
+An external untrusted service, which can only publish justice transactions. The security property of a watchtower is that if you subscribe to n of them, you will be safe if at least 1 does the right thing.
+
+Used across the monitoring (`ChannelMonitor`) and onchain (`OnchainTxHandler`) subsystems.
+
+### Monitor Replicata
+
+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.
+
+Used across the monitoring (`ChannelMonitor`) and onchain (`OnchainTxHandler`) subsystems.