Skip to content

Commit ba5fee2

Browse files
ryanthegentryryanthegentry
authored
Merge pull request #1 from lightning/updateReadme
Update README and add bLIP-0001
2 parents 017b3ab + ed194a1 commit ba5fee2

File tree

3 files changed

+325
-1
lines changed

3 files changed

+325
-1
lines changed

‎README.md‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,19 @@
1-
# blips
1+
bLIP stands for Bitcoin Lightning Improvement Proposal. A bLIP is a design document
2+
providing information to the Lightning community, or describing a new feature for
3+
the Lightning Network. The bLIP should provide a concise technical specification of
4+
the feature and a rationale for the feature. The bLIP author is responsible for
5+
building consensus within the community and documenting dissenting opinions.
6+
Importantly, if a feature is intended to become universal or near universal, it must
7+
be a [BOLT](https://github.com/lightning/bolts).
8+
9+
People wishing to submit bLIPs (Bitcoin Lightning Improvement Proposals) should
10+
first propose their idea to the [Lightning development mailing
11+
list](https://lists.linuxfoundation.org/mailman/listinfo/lightning-dev). After
12+
discussion, please open a PR. After copy-editing and acceptance, it will be
13+
published here.
14+
15+
For more detail on the process, please read <a href="blip-0001.md">bLIP-0001</a>.
16+
17+
| Number | Title | Author | Status |
18+
|--------|-------|--------|--------|
19+
|1|bLIP Process|Ryan Gentry|Active|

‎blip-0001.md‎

Lines changed: 306 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,306 @@
1+
```
2+
bLIP: 1
3+
Title: bLIP process
4+
Status: Active
5+
Author: Ryan Gentry <[email protected]>
6+
Created: 2021-05-21
7+
Post-History: 2021-06-30: https://lists.linuxfoundation.org/pipermail/lightning-dev/2021-June/003086.html
8+
[lightning-dev] bLIPs: A proposal for community-driven app layer and protocol extension standardization
9+
License: CC0
10+
```
11+
12+
# Abstract
13+
14+
bLIP stands for Bitcoin Lightning Improvement Proposal. A bLIP is a design document
15+
providing information to the Lightning community, or describing a new feature for
16+
the Lightning Network. The bLIP should provide a concise technical specification of
17+
the feature and a rationale for the feature. The bLIP author is responsible for
18+
building consensus within the community and documenting dissenting opinions.
19+
Importantly, if a feature is intended to become universal or near universal, it must
20+
be a BOLT.
21+
22+
# Copyright
23+
24+
This bLIP is licensed under the CC0 license.
25+
26+
# Rationale
27+
28+
As the Lightning community has grown, new features, standards, and protocols have
29+
been developed outside of the BOLT specification process: particularly at the
30+
application level that isn’t described within the core BOLT documents. This is great!
31+
But in the spirit of interoperability, documenting features, standards, and protocols
32+
in a single location with a standard format will make it easy on future adopters.
33+
34+
In particular, there are (at least) three scarce sets of identifiers used in Lightning
35+
Network protocol development that benefit from central organization and documentation
36+
to avoid potential clashes:
37+
38+
* **Feature Bits** are used to designate that a given node supports a given feature, and
39+
are publicly broadcasted on the Lightning Network. bLIPs may introduce new Feature Bit
40+
assignments > `100`, as those are set aside for experimental features, with the caveat
41+
that Feature Bit assignments > `1000` are discouraged from mainnet usage. Feature Bits are
42+
assigned and specified in [Bolt
43+
#9](https://github.com/lightningnetwork/lightning-rfc/blob/master/09-features.md).
44+
* **Message Types** are used to indicate how to interpret the `payload` feature of a
45+
Lightning message. Types `32768`-`65535` are set aside for experimental and
46+
application-specific messages, which are best suited to be documented in a bLIP.
47+
Message Types are assigned and specified in [Bolt
48+
#1](https://github.com/lightningnetwork/lightning-rfc/blob/master/01-messaging.md).
49+
* **Type-Length-Values (TLVs)** are used to allow for the backwards-compatible addition
50+
of new fields to existing message types (as described in in [Bolt
51+
#1](https://github.com/lightningnetwork/lightning-rfc/blob/master/01-messaging.md)).
52+
bLIPs may introduce new TLV fields to existing messages, using `type`s greater than `65536`.
53+
54+
Potentially more scarce sets of identifiers exist (e.g. [BOLT
55+
#4](https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md#failure-messages)
56+
onion failure messages, [BOLT
57+
#7](https://github.com/lightningnetwork/lightning-rfc/blob/master/07-routing-gossip.md#the-channel_update-message) `channel_update` `channel_flags` and `message_flags`, and [BOLT
58+
#11](https://github.com/lightningnetwork/lightning-rfc/blob/master/11-payment-encoding.md#tagged-fields)
59+
invoice tagged fields) in the Lightning Network protocol. If/when bLIPs are made that
60+
require these identifiers, further specification of how and where to assign and allocate
61+
them can be accomplished.
62+
63+
bLIPs will serve as the primary mechanism for proposing new features for the Lightning
64+
Network protocol, documenting their design, and avoiding collisions of these scarce
65+
identifiers (as some proposals may request one or more). Hopefully, they will provide
66+
an avenue for developers to quickly get feedback on their ideas outside of the main BOLT
67+
process. Because the bLIPs are maintained as text files in a versioned repository,
68+
their revision history is the historical record of the feature proposal.
69+
70+
It is highly recommended that a single bLIP contain a single key proposal or new idea.
71+
More focused bLIPs will tend to be more successful. If in doubt, a bLIP should be
72+
split into several well-focused ones.
73+
74+
For Lightning developers, bLIPs are a convenient way to track the progress of their
75+
implementation. Ideally, each implementation editor would list the bLIPs they have
76+
implemented. This will give end users a convenient way to know the current status of
77+
a given implementation or library.
78+
79+
# bLIP Workflow
80+
81+
The bLIP process begins with a new idea for Lightning. Each potential bLIP must have
82+
a champion -- someone who writes the bLIP using the style and format described below,
83+
shepherds the discussions in the appropriate forums, and attempts to build community
84+
consensus around the idea. The bLIP champion (a.k.a. Author) should first attempt to
85+
ascertain whether the idea is bLIP-able. The first step should be to search past
86+
discussions to see if an idea has been considered before, and if so, what issues arose
87+
in its progression. Such discussion generally happens on the [Lightning development
88+
mailing list](https://lists.linuxfoundation.org/mailman/listinfo/lightning-dev), or
89+
in the #lightning-dev IRC channel. Additionally, the champion should check the [Bitcoin
90+
Improvement Proposal (BIP) repository](https://github.com/bitcoin/bips) and the
91+
[Discrete Log Contract (DLC) specification](https://github.com/discreetlogcontracts/dlcspecs)
92+
to avoid duplication of proposals.
93+
94+
Once the champion has asked the Lightning community as to whether an idea has any
95+
chance of acceptance, a draft bLIP should be presented to the [Lightning development
96+
mailing list](https://lists.linuxfoundation.org/mailman/listinfo/lightning-dev). This
97+
gives the author a chance to flesh out the draft bLIP to make it properly formatted,
98+
of high quality, and to address additional concerns about the proposal. Following a
99+
discussion, the proposal should be submitted to the [bLIPs repository of the lightning
100+
organization](https://github.com/lightning/blips) as a pull request. This
101+
draft must be written in bLIP style as described below, and its bLIP number will be
102+
the PR number automatically assigned by Github (or, if preferred by the author, the
103+
Issue # if there was discussion in the Issues section of this repository about this bLIP).
104+
105+
When the bLIP draft is complete, the editors will check the requested Feature Bit, Message
106+
Type, and/or TLV assignments for collisions. If there are no issues, the bLIPs editors will
107+
merge the pull request into the [bLIPs repository](https://github.com/lightning/blips).
108+
The editors will not unreasonably reject a bLIP. Reasons for rejecting bLIPs include
109+
duplication of effort, disregard for formatting rules, being too unfocused or too
110+
broad, being technically unsound, not providing proper motivation or addressing
111+
backwards compatibility, or not in keeping with the Bitcoin and Lightning Network
112+
philosophy. For a bLIP to be accepted it must meet certain minimum criteria. It
113+
must be a clear and complete description of the proposed enhancement. The enhancement must
114+
represent a net improvement. The proposed implementation, if applicable, must be solid
115+
and must not complicate the protocol unduly.
116+
117+
The bLIP author may update the draft as necessary in the git repository. Updates to
118+
drafts should also be submitted by the author as pull requests.
119+
120+
## Transferring bLIP Ownership
121+
122+
It occasionally becomes necessary to transfer ownership of bLIPs to a new champion. In
123+
general, we'd like to retain the original author as a co-author of the transferred bLIP,
124+
but that's really up to the original author. A good reason to transfer ownership is
125+
because the original author no longer has the time or interest in updating it or
126+
following through with the bLIP process, or has fallen off the face of the 'net (i.e. is
127+
unreachable or not responding to email). A bad reason to transfer ownership is because
128+
you don't agree with the direction of the bLIP. We try to build consensus around a bLIP,
129+
but if that's not possible, you can always submit a competing bLIP.
130+
131+
If you are interested in assuming ownership of a bLIP, send a message asking to take over,
132+
addressed to both the original author and the bLIP editor. If the original author doesn't
133+
respond to email in a timely manner, the bLIP editor will make a unilateral decision (it's
134+
not like such decisions can't be reversed).
135+
136+
### bLIP Editors
137+
138+
The current bLIP editors are:
139+
140+
* Bastien Teinturier (@t-bast)
141+
* Christian Decker (@cdecker)
142+
* Lisa Neigut (@niftynei)
143+
* Matt Corallo (@TheBlueMatt)
144+
* Olaoluwa Osuntokun (@roasbeef)
145+
* Ryan Gentry (@ryanthegentry)
146+
* Rusty Russell (@rustyrussell)
147+
148+
### bLIP Editor Responsibilities & Workflow
149+
150+
For each new bLIP submission, the editors do the following:
151+
152+
* Read the bLIP to check if it is ready: sound and complete. The ideas must make technical
153+
sense, even if they don't seem likely to get to final status.
154+
* The title should accurately describe the content.
155+
* The bLIP draft must have been sent to the lightning-dev mailing list for discussion.
156+
* Motivation and backward compatibility (when applicable) must be addressed.
157+
* Licensing terms must be acceptable for bLIPs.
158+
159+
If the bLIP isn't ready, the editor will send it back to the author for revision, with
160+
specific instructions.
161+
162+
Once the bLIP is ready for the repository, the bLIP editor will:
163+
164+
* Assign a bLIP number (generally the PR number or, if preferred by the author, the Issue #
165+
if there was discussion in the Issues section of this repository about this bLIP)
166+
* Check the requested Feature Bit, Message Type, and/or TLV assignments for collisions.
167+
* Merge the corresponding pull request
168+
* Send a message back to the bLIP author with the next steps.
169+
170+
The bLIP editors are intended to fulfill administrative and editorial responsibilities.
171+
They do not pass judgement on bLIPs. The bLIP editors monitor bLIP changes, and update bLIP
172+
headers as appropriate.
173+
174+
## What belongs in a successful bLIP?
175+
176+
bLIPs should be written in Markdown format.
177+
178+
Each bLIP should have the following parts:
179+
180+
* **Preamble** -- Headers containing metadata about the bLIP (see below).
181+
* **Abstract** -- A short (~200 word) description of the technical issue being addressed.
182+
* **Copyright** -- The bLIP must be explicitly licensed under acceptable copyright terms (see below).
183+
* **Motivation** -- The motivation is critical for bLIPs that want to change the Lightning
184+
protocol. It should clearly explain why the existing protocol is inadequate to address
185+
the problem that the bLIP solves.
186+
* **Rationale** -- The rationale fleshes out the specification by describing what motivated
187+
the design and why particular design decisions were made. It should describe alternate
188+
designs that were considered and related work. The rationale should provide evidence of
189+
consensus within the community and discuss important objections or concerns raised
190+
during discussion.
191+
* **Specification** -- The technical specification should describe the syntax and semantics
192+
of any new feature. The specification should be detailed enough to allow competing,
193+
interoperable implementations for any of the current Lightning implementations.
194+
* **Universality** -- This section should discuss why the given feature is not intended to be
195+
universal and why it's still a good idea as a non-universal protocol. New features intended to be
196+
universally deployed should go through the BOLTs process instead.
197+
* **Backwards Compatibility** -- All bLIPs that introduce backwards incompatibilities must
198+
include a section describing these incompatibilities and their severity. The bLIP must
199+
explain how the author proposes to deal with these incompatibilities.
200+
* **Reference Implementation** -- The reference implementation must be completed before any
201+
bLIP is given status "Final", but it need not be completed before the bLIP is accepted. It
202+
is better to finish the specification and rationale first and reach consensus on it before
203+
writing code. The final implementation must include test code and documentation appropriate
204+
for the Lightning protocol.
205+
206+
### bLIP Header Preamble
207+
208+
Each bLIP must begin with an RFC 822 style header preamble. The headers must appear in the
209+
following order. Headers marked with "*" are optional and are described below. All other
210+
headers are required.
211+
212+
```
213+
bLIP: bLIP number, this is determined by the PR or Issue number
214+
Title: bLIP title
215+
Author: list of the author's or authors' name(s) and/or username(s), or name(s) and
216+
email(s). Details are below.
217+
* Discussions-To: a url pointing to the official discussions thread
218+
Status: Draft, Active, Proposed, Deferred, Rejected, Withdrawn, Final, Replaced, Obsolete
219+
Created: date created on, in ISO 8601 (yyyy-mm-dd) format
220+
* Post-History: dates of postings to lightning-dev mailing list, or link to thread in
221+
mailing list archive
222+
License: abbreviation for approved license(s)
223+
* License-Code: abbreviation for code under different approved license(s)
224+
* Requires: bLIP number(s)
225+
* Replaces: bLIP number
226+
* Superseded-By: bLIP number
227+
```
228+
229+
The Author header lists the names and email addresses of all the authors/owners of the bLIP.
230+
The format of the Author header value must be:
231+
232+
`Random J. User <[email protected]>`
233+
234+
If there are multiple authors, each should be on a separate line following RFC 2822
235+
continuation line conventions.
236+
237+
While a bLIP is in private discussions (usually during the initial Draft phase), a
238+
Discussions-To header will indicate the mailing list or URL where the bLIP is being discussed.
239+
No Discussions-To header is necessary if the bLIP is being discussed privately with the author,
240+
or on the bitcoin email mailing lists.
241+
242+
The Created header records the date that the bLIP was assigned a number, while Post-History
243+
is used to record when new versions of the bLIP are posted to bitcoin mailing lists. Dates
244+
should be in yyyy-mm-dd format, e.g. 2001-08-14. Post-History is permitted to be a link to a
245+
specific thread in a mailing list archive.
246+
247+
bLIPs may have a Requires header, indicating the bLIP numbers that this bLIP depends on.
248+
249+
bLIPs may also have a Superseded-By header indicating that a bLIP has been rendered
250+
obsolete by a later document; the value is the number of the bLIP that replaces the
251+
current document. The newer bLIP must have a Replaces header containing the number of the
252+
bLIP that it rendered obsolete.
253+
254+
### bLIP status field
255+
256+
The typical paths of the status of bLIPs are as follows:
257+
258+
![](blip-0001/blip-0001-1.png)
259+
260+
* **Draft** - The first formally tracked stage of a bLIP in development. A bLIP is merged by
261+
a bLIP Editor into the proposals folder of the lightning-rfc repository when properly formatted.
262+
* **Deferred** - The bLIP editor may also change the status to Deferred when no progress is being
263+
made on the bLIP.
264+
* **Withdrawn** - Champions of a bLIP may decide on their own to change the status between Draft,
265+
Deferred, or Withdrawn.
266+
* **Rejected** - bLIPs should be changed from Draft status to Rejected status, upon request by any
267+
person, if they have not made progress in three years. Such a bLIP may be changed to Draft
268+
status if the champion provides revisions that meaningfully address public criticism of the
269+
proposal, or to Proposed status if it meets the criteria required as described in the previous
270+
paragraph.
271+
* **Proposed** - a bLIP may only change status from Draft (or Rejected) to Proposed, when the author
272+
deems it is complete, has a working implementation (where applicable), and has community plans
273+
to progress it to the Final status.
274+
* **Final / Active** - a Proposed bLIP may progress to Final only when specific criteria reflecting
275+
real-world adoption has occurred. This is different for each bLIP depending on the nature of
276+
its proposed changes, which will be expanded on below. Evaluation of this status change should
277+
be objectively verifiable, and/or be discussed on the development mailing list. A bLIP may change
278+
status from Draft to Active when it achieves rough consensus on the mailing list. Such a proposal
279+
is said to have rough consensus if it has been open to discussion on the development mailing list
280+
for at least one month, and no person maintains any unaddressed substantiated objections to it.
281+
Addressed or obstructive objections may be ignored/overruled by general agreement that they have
282+
been sufficiently addressed, but clear reasoning must be given in such circumstances.
283+
* **Replaced or Obsolete** - when a Final bLIP is no longer relevant, its status may be changed to
284+
Replaced or Obsolete (which is equivalent to Replaced). This change must also be objectively
285+
verifiable and/or discussed.
286+
287+
### Auxiliary Files
288+
289+
bLIPs may include auxiliary files such as diagrams. Auxiliary files should be included in a
290+
subdirectory for that bLIP, or must be named bLIP-XXXX-Y.ext, where "XXXX" is the bLIP number,
291+
"Y" is a serial number (starting at 1), and "ext" is replaced by the actual file extension
292+
(e.g. "png").
293+
294+
## Licensing
295+
296+
All bLIPs must be licensed under CC-BY or CC0.
297+
298+
# History
299+
300+
This document was derived heavily from [Bitcoin's
301+
BIP-0002](https://github.com/bitcoin/bips/blob/master/bip-0002.mediawiki) written by Luke Jr.
302+
which in turn was derived from [Python's PEP-0001](https://www.python.org/dev/peps/). In many
303+
places text was simply copied and modified. Although the PEP-0001 text was written by Barry
304+
Warsaw, Jeremy Hylton, and David Goodger, they are not responsible for its use in the
305+
Bitcoin Lightning Improvement Process, and should not be bothered with technical questions
306+
specific to the Lightning Network or the bLIP. Please direct all comments to the bLIP editors.

‎blip-0001/blip-0001-1.png‎

10.1 KB
Loading

0 commit comments

Comments
 (0)