mirror of
https://github.com/lightning/blips.git
synced 2024-11-19 00:50:02 +01:00
Update README and add bLIP-0001
This commit is contained in:
ryanthegentry
parent
017b3ab3f0
commit
ed194a1f0d
20
README.md
20
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 <a href="blip-0001.md">bLIP-0001</a>.
|
||||||
|
|
||||||
|
| Number | Title | Author | Status |
|
||||||
|
|--------|-------|--------|--------|
|
||||||
|
|1|bLIP Process|Ryan Gentry|Active|
|
||||||
|
|||||||
306
blip-0001.md
Normal file
306
blip-0001.md
Normal file
@ -0,0 +1,306 @@
|
|||||||
|
```
|
||||||
|
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.
|
||||||
|
|
||||||
|
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 <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](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.
|
||||||
BIN
blip-0001/blip-0001-1.png
Normal file
BIN
blip-0001/blip-0001-1.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 10 KiB |
Loading…
Reference in New Issue
Block a user