lightning-blips/blip-0001.md

bLIP: 1
Title: bLIP process
Status: Active
Author: Ryan Gentry <ryan@lightning.engineering>
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.

bLIPs will serve as the primary mechanism for proposing new features for the Lightning Network protocol, documenting their design, and avoiding collisions of 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, or in the #lightning-dev IRC channel. Additionally, the champion should check the Bitcoin Improvement Proposal (BIP) repository and the Discrete Log Contract (DLC) specification 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. 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 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).

If the bLIP needs to reserve values in shared namespaces (such as feature bits, message types or tlv fields), the author should update bLIP 0002 accordingly.

When the bLIP draft is complete, the editors will check bLIP 0002 for collisions. If there are no issues, the bLIPs editors will merge the pull request into the bLIPs repository. 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 <address@dom.ain>

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:

• 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 written by Luke Jr. which in turn was derived from Python's PEP-0001. 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.