diff --git a/README.md b/README.md index 10325d0..6e64b8a 100644 --- a/README.md +++ b/README.md @@ -1 +1,19 @@ -# blips +bLIP stands for Bitcoin Lightning Improvement Proposal. A bLIP is a design document +providing information to the Lightning community, or describing a new feature for +the Lightning Network. The bLIP should provide a concise technical specification of +the feature and a rationale for the feature. The bLIP author is responsible for +building consensus within the community and documenting dissenting opinions. +Importantly, if a feature is intended to become universal or near universal, it must +be a [BOLT](https://github.com/lightning/bolts). + +People wishing to submit bLIPs (Bitcoin Lightning Improvement Proposals) should +first propose their idea to the [Lightning development mailing +list](https://lists.linuxfoundation.org/mailman/listinfo/lightning-dev). After +discussion, please open a PR. After copy-editing and acceptance, it will be +published here. + +For more detail on the process, please read bLIP-0001. + +| Number | Title | Author | Status | +|--------|-------|--------|--------| +|1|bLIP Process|Ryan Gentry|Active| diff --git a/blip-0001.md b/blip-0001.md new file mode 100644 index 0000000..2703c87 --- /dev/null +++ b/blip-0001.md @@ -0,0 +1,306 @@ +``` +bLIP: 1 +Title: bLIP process +Status: Active +Author: Ryan Gentry +Created: 2021-05-21 +Post-History: 2021-06-30: https://lists.linuxfoundation.org/pipermail/lightning-dev/2021-June/003086.html + [lightning-dev] bLIPs: A proposal for community-driven app layer and protocol extension standardization +License: CC0 +``` + +# Abstract + +bLIP stands for Bitcoin Lightning Improvement Proposal. A bLIP is a design document +providing information to the Lightning community, or describing a new feature for +the Lightning Network. The bLIP should provide a concise technical specification of +the feature and a rationale for the feature. The bLIP author is responsible for +building consensus within the community and documenting dissenting opinions. +Importantly, if a feature is intended to become universal or near universal, it must +be a BOLT. + +# Copyright + +This bLIP is licensed under the CC0 license. + +# Rationale + +As the Lightning community has grown, new features, standards, and protocols have +been developed outside of the BOLT specification process: particularly at the +application level that isn’t described within the core BOLT documents. This is great! +But in the spirit of interoperability, documenting features, standards, and protocols +in a single location with a standard format will make it easy on future adopters. + +In particular, there are (at least) three scarce sets of identifiers used in Lightning +Network protocol development that benefit from central organization and documentation +to avoid potential clashes: + +* **Feature Bits** are used to designate that a given node supports a given feature, and +are publicly broadcasted on the Lightning Network. bLIPs may introduce new Feature Bit +assignments > `100`, as those are set aside for experimental features, with the caveat +that Feature Bit assignments > `1000` are discouraged from mainnet usage. Feature Bits are +assigned and specified in [Bolt + #9](https://github.com/lightningnetwork/lightning-rfc/blob/master/09-features.md). +* **Message Types** are used to indicate how to interpret the `payload` feature of a +Lightning message. Types `32768`-`65535` are set aside for experimental and +application-specific messages, which are best suited to be documented in a bLIP. +Message Types are assigned and specified in [Bolt + #1](https://github.com/lightningnetwork/lightning-rfc/blob/master/01-messaging.md). +* **Type-Length-Values (TLVs)** are used to allow for the backwards-compatible addition +of new fields to existing message types (as described in in [Bolt + #1](https://github.com/lightningnetwork/lightning-rfc/blob/master/01-messaging.md)). +bLIPs may introduce new TLV fields to existing messages, using `type`s greater than `65536`. + +Potentially more scarce sets of identifiers exist (e.g. [BOLT + #4](https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md#failure-messages) +onion failure messages, [BOLT + #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 + #11](https://github.com/lightningnetwork/lightning-rfc/blob/master/11-payment-encoding.md#tagged-fields) +invoice tagged fields) in the Lightning Network protocol. If/when bLIPs are made that +require these identifiers, further specification of how and where to assign and allocate +them can be accomplished. + +bLIPs will serve as the primary mechanism for proposing new features for the Lightning +Network protocol, documenting their design, and avoiding collisions of these scarce +identifiers (as some proposals may request one or more). Hopefully, they will provide +an avenue for developers to quickly get feedback on their ideas outside of the main BOLT +process. Because the bLIPs are maintained as text files in a versioned repository, +their revision history is the historical record of the feature proposal. + +It is highly recommended that a single bLIP contain a single key proposal or new idea. +More focused bLIPs will tend to be more successful. If in doubt, a bLIP should be +split into several well-focused ones. + +For Lightning developers, bLIPs are a convenient way to track the progress of their +implementation. Ideally, each implementation editor would list the bLIPs they have +implemented. This will give end users a convenient way to know the current status of +a given implementation or library. + +# bLIP Workflow + +The bLIP process begins with a new idea for Lightning. Each potential bLIP must have +a champion -- someone who writes the bLIP using the style and format described below, +shepherds the discussions in the appropriate forums, and attempts to build community +consensus around the idea. The bLIP champion (a.k.a. Author) should first attempt to +ascertain whether the idea is bLIP-able. The first step should be to search past +discussions to see if an idea has been considered before, and if so, what issues arose +in its progression. Such discussion generally happens on the [Lightning development +mailing list](https://lists.linuxfoundation.org/mailman/listinfo/lightning-dev), or +in the #lightning-dev IRC channel. Additionally, the champion should check the [Bitcoin +Improvement Proposal (BIP) repository](https://github.com/bitcoin/bips) and the +[Discrete Log Contract (DLC) specification](https://github.com/discreetlogcontracts/dlcspecs) +to avoid duplication of proposals. + +Once the champion has asked the Lightning community as to whether an idea has any +chance of acceptance, a draft bLIP should be presented to the [Lightning development +mailing list](https://lists.linuxfoundation.org/mailman/listinfo/lightning-dev). This +gives the author a chance to flesh out the draft bLIP to make it properly formatted, +of high quality, and to address additional concerns about the proposal. Following a +discussion, the proposal should be submitted to the [bLIPs repository of the lightning +organization](https://github.com/lightning/blips) as a pull request. This +draft must be written in bLIP style as described below, and its bLIP number will be +the PR number automatically assigned by Github (or, if preferred by the author, the +Issue # if there was discussion in the Issues section of this repository about this bLIP). + +When the bLIP draft is complete, the editors will check the requested Feature Bit, Message +Type, and/or TLV assignments for collisions. If there are no issues, the bLIPs editors will +merge the pull request into the [bLIPs repository](https://github.com/lightning/blips). +The editors will not unreasonably reject a bLIP. Reasons for rejecting bLIPs include +duplication of effort, disregard for formatting rules, being too unfocused or too +broad, being technically unsound, not providing proper motivation or addressing +backwards compatibility, or not in keeping with the Bitcoin and Lightning Network +philosophy. For a bLIP to be accepted it must meet certain minimum criteria. It +must be a clear and complete description of the proposed enhancement. The enhancement must +represent a net improvement. The proposed implementation, if applicable, must be solid +and must not complicate the protocol unduly. + +The bLIP author may update the draft as necessary in the git repository. Updates to +drafts should also be submitted by the author as pull requests. + +## Transferring bLIP Ownership + +It occasionally becomes necessary to transfer ownership of bLIPs to a new champion. In +general, we'd like to retain the original author as a co-author of the transferred bLIP, +but that's really up to the original author. A good reason to transfer ownership is +because the original author no longer has the time or interest in updating it or +following through with the bLIP process, or has fallen off the face of the 'net (i.e. is +unreachable or not responding to email). A bad reason to transfer ownership is because +you don't agree with the direction of the bLIP. We try to build consensus around a bLIP, +but if that's not possible, you can always submit a competing bLIP. + +If you are interested in assuming ownership of a bLIP, send a message asking to take over, +addressed to both the original author and the bLIP editor. If the original author doesn't +respond to email in a timely manner, the bLIP editor will make a unilateral decision (it's +not like such decisions can't be reversed). + +### bLIP Editors + +The current bLIP editors are: + +* Bastien Teinturier (@t-bast) +* Christian Decker (@cdecker) +* Lisa Neigut (@niftynei) +* Matt Corallo (@TheBlueMatt) +* Olaoluwa Osuntokun (@roasbeef) +* Ryan Gentry (@ryanthegentry) +* Rusty Russell (@rustyrussell) + +### bLIP Editor Responsibilities & Workflow + +For each new bLIP submission, the editors do the following: + +* Read the bLIP to check if it is ready: sound and complete. The ideas must make technical +sense, even if they don't seem likely to get to final status. +* The title should accurately describe the content. +* The bLIP draft must have been sent to the lightning-dev mailing list for discussion. +* Motivation and backward compatibility (when applicable) must be addressed. +* Licensing terms must be acceptable for bLIPs. + +If the bLIP isn't ready, the editor will send it back to the author for revision, with +specific instructions. + +Once the bLIP is ready for the repository, the bLIP editor will: + +* Assign a bLIP number (generally the PR number or, if preferred by the author, the Issue # +if there was discussion in the Issues section of this repository about this bLIP) +* Check the requested Feature Bit, Message Type, and/or TLV assignments for collisions. +* Merge the corresponding pull request +* Send a message back to the bLIP author with the next steps. + +The bLIP editors are intended to fulfill administrative and editorial responsibilities. +They do not pass judgement on bLIPs. The bLIP editors monitor bLIP changes, and update bLIP +headers as appropriate. + +## What belongs in a successful bLIP? + +bLIPs should be written in Markdown format. + +Each bLIP should have the following parts: + +* **Preamble** -- Headers containing metadata about the bLIP (see below). +* **Abstract** -- A short (~200 word) description of the technical issue being addressed. +* **Copyright** -- The bLIP must be explicitly licensed under acceptable copyright terms (see below). +* **Motivation** -- The motivation is critical for bLIPs that want to change the Lightning +protocol. It should clearly explain why the existing protocol is inadequate to address +the problem that the bLIP solves. +* **Rationale** -- The rationale fleshes out the specification by describing what motivated +the design and why particular design decisions were made. It should describe alternate +designs that were considered and related work. The rationale should provide evidence of +consensus within the community and discuss important objections or concerns raised +during discussion. +* **Specification** -- The technical specification should describe the syntax and semantics +of any new feature. The specification should be detailed enough to allow competing, +interoperable implementations for any of the current Lightning implementations. +* **Universality** -- This section should discuss why the given feature is not intended to be +universal and why it's still a good idea as a non-universal protocol. New features intended to be +universally deployed should go through the BOLTs process instead. +* **Backwards Compatibility** -- All bLIPs that introduce backwards incompatibilities must +include a section describing these incompatibilities and their severity. The bLIP must +explain how the author proposes to deal with these incompatibilities. +* **Reference Implementation** -- The reference implementation must be completed before any +bLIP is given status "Final", but it need not be completed before the bLIP is accepted. It +is better to finish the specification and rationale first and reach consensus on it before +writing code. The final implementation must include test code and documentation appropriate +for the Lightning protocol. + +### bLIP Header Preamble + +Each bLIP must begin with an RFC 822 style header preamble. The headers must appear in the +following order. Headers marked with "*" are optional and are described below. All other +headers are required. + +``` +bLIP: bLIP number, this is determined by the PR or Issue number +Title: bLIP title +Author: list of the author's or authors' name(s) and/or username(s), or name(s) and +email(s). Details are below. +* Discussions-To: a url pointing to the official discussions thread +Status: Draft, Active, Proposed, Deferred, Rejected, Withdrawn, Final, Replaced, Obsolete +Created: date created on, in ISO 8601 (yyyy-mm-dd) format +* Post-History: dates of postings to lightning-dev mailing list, or link to thread in + mailing list archive +License: abbreviation for approved license(s) +* License-Code: abbreviation for code under different approved license(s) +* Requires: bLIP number(s) +* Replaces: bLIP number +* Superseded-By: bLIP number +``` + +The Author header lists the names and email addresses of all the authors/owners of the bLIP. +The format of the Author header value must be: + +`Random J. User ` + +If there are multiple authors, each should be on a separate line following RFC 2822 +continuation line conventions. + +While a bLIP is in private discussions (usually during the initial Draft phase), a +Discussions-To header will indicate the mailing list or URL where the bLIP is being discussed. +No Discussions-To header is necessary if the bLIP is being discussed privately with the author, +or on the bitcoin email mailing lists. + +The Created header records the date that the bLIP was assigned a number, while Post-History +is used to record when new versions of the bLIP are posted to bitcoin mailing lists. Dates +should be in yyyy-mm-dd format, e.g. 2001-08-14. Post-History is permitted to be a link to a +specific thread in a mailing list archive. + +bLIPs may have a Requires header, indicating the bLIP numbers that this bLIP depends on. + +bLIPs may also have a Superseded-By header indicating that a bLIP has been rendered +obsolete by a later document; the value is the number of the bLIP that replaces the +current document. The newer bLIP must have a Replaces header containing the number of the +bLIP that it rendered obsolete. + +### bLIP status field + +The typical paths of the status of bLIPs are as follows: + +![](blip-0001/blip-0001-1.png) + +* **Draft** - The first formally tracked stage of a bLIP in development. A bLIP is merged by +a bLIP Editor into the proposals folder of the lightning-rfc repository when properly formatted. +* **Deferred** - The bLIP editor may also change the status to Deferred when no progress is being +made on the bLIP. +* **Withdrawn** - Champions of a bLIP may decide on their own to change the status between Draft, +Deferred, or Withdrawn. +* **Rejected** - bLIPs should be changed from Draft status to Rejected status, upon request by any +person, if they have not made progress in three years. Such a bLIP may be changed to Draft +status if the champion provides revisions that meaningfully address public criticism of the +proposal, or to Proposed status if it meets the criteria required as described in the previous +paragraph. +* **Proposed** - a bLIP may only change status from Draft (or Rejected) to Proposed, when the author +deems it is complete, has a working implementation (where applicable), and has community plans +to progress it to the Final status. +* **Final / Active** - a Proposed bLIP may progress to Final only when specific criteria reflecting +real-world adoption has occurred. This is different for each bLIP depending on the nature of +its proposed changes, which will be expanded on below. Evaluation of this status change should +be objectively verifiable, and/or be discussed on the development mailing list. A bLIP may change +status from Draft to Active when it achieves rough consensus on the mailing list. Such a proposal +is said to have rough consensus if it has been open to discussion on the development mailing list +for at least one month, and no person maintains any unaddressed substantiated objections to it. +Addressed or obstructive objections may be ignored/overruled by general agreement that they have +been sufficiently addressed, but clear reasoning must be given in such circumstances. +* **Replaced or Obsolete** - when a Final bLIP is no longer relevant, its status may be changed to +Replaced or Obsolete (which is equivalent to Replaced). This change must also be objectively +verifiable and/or discussed. + +### Auxiliary Files + +bLIPs may include auxiliary files such as diagrams. Auxiliary files should be included in a +subdirectory for that bLIP, or must be named bLIP-XXXX-Y.ext, where "XXXX" is the bLIP number, +"Y" is a serial number (starting at 1), and "ext" is replaced by the actual file extension +(e.g. "png"). + +## Licensing + +All bLIPs must be licensed under CC-BY or CC0. + +# History + +This document was derived heavily from [Bitcoin's + BIP-0002](https://github.com/bitcoin/bips/blob/master/bip-0002.mediawiki) written by Luke Jr. +which in turn was derived from [Python's PEP-0001](https://www.python.org/dev/peps/). In many +places text was simply copied and modified. Although the PEP-0001 text was written by Barry +Warsaw, Jeremy Hylton, and David Goodger, they are not responsible for its use in the +Bitcoin Lightning Improvement Process, and should not be bothered with technical questions +specific to the Lightning Network or the bLIP. Please direct all comments to the bLIP editors. diff --git a/blip-0001/blip-0001-1.png b/blip-0001/blip-0001-1.png new file mode 100644 index 0000000..b532799 Binary files /dev/null and b/blip-0001/blip-0001-1.png differ