- Introduction =============== This is a template for documenting various concept choices. To make a new concept choice document, perform the following steps:
- Choose a concept choice number that is not yet in use.
- Make a copy of this file, and name it lightning_concept_<number>.md, where <number> is the concept choice number.
- Fill in the contents of the sections in the new document.
Each of the sections in this template describes what must be filled in in that section. In the Introduction section, a concept choice document must give a brief description of the scope of the choice, and probably some background information.
If the new concept choice document will deprecate other concept choice documents, these other concept choice documents must be listed here.
- Concepts =========== This section must contain a list of concepts, from which a choice must be made. Each item in the list must be assigned a capital latin character. Internally, the concept document can refer to the concept with the character only; external documents must refer to it with the concept choice number and the character. For instance, if concept choice #42 contains concepts A..G, then internally, these can be referred to as A, B, C and so on, but external documents must refer to them as concept choice 42A, 42B, 42C and so on.
A concept choice document may contain closely related choices that are partially or completely independent. In that case, all sensible combinations of concepts must be fully expanded into separate concepts. For instance, if two independent choices must be made, one between p and q, and one between r and s, then that must be expanded into the following list:
- A: p and r
- B: p and s
- C: q and r
- D: q and s
If such an expansion becomes inconveniently long, it may be better to split up the concept choice into separate documents.
Typically, concept descriptions need to be more than a few lines, so it may be desirable to assign a separate subsection to each concept.
-
Pro/Con analysis =================== This section must compare advantages and disadvantages of the concepts. Any dependencies between concepts inside this document and concepts outside this document should also be mentioned.
-
Evolution analysis ===================== This section must describe how difficult it is to evolve a network that uses one of the concepts towards using one of the other concepts. For instance, it would be nearly impossible to make a concept change in a large network if it required upgrading all nodes simultaneously, or if an established concept has a large network effect advantage over different concepts.
It may be useful to summarize all transitions in an NxN matrix, where N is the number of concepts.
- Concept choice ================= This section must come to a conclusion on which concept(s) should be used, and which should not be used. Some common ways of coming to a conclusion are:
- When one concept is clearly superior to all other concepts, that concept should be used. Other concepts, for which evolution towards the superior concept is easy, may also be used, especially if they are easier to implement.
- If it is easy to evolve from one concept to the other, but not in the opposite direction, it is better to use the first concept, since it keeps most options open.
- Simple concepts, which are easy to implement and easy to analyze (e.g. for security reasons or for economical reasons), are preferred over more complex concepts.
Generally speaking, the concept choice should be fairly liberal in allowing multiple concepts, especially when this is not harmful for inter-operability and does not introduce a disproportionally large amount of work for implementers.
- Document status ================== This section must include the status of the document. The status must be one of the following:
- DRAFT: Anything in the document is subject to change. There may be several different DRAFT versions of the document in circulation. All documents shall start with status DRAFT.
- FINAL: The document shall not be changed anymore, except for its document status, which may change to DEPRECATED in the future. There must be only a single version of the document with status FINAL. It is TBD how to select the version to become FINAL.
- DEPRECATED: The document has been replaced by one or more other concept choice documents. In this case, these other concept choice documents must be listed here. A concept choice can only become deprecated by concept choices that have received status FINAL.
The status of this document is: DRAFT