diff --git a/09-features.md b/09-features.md index b508bac70..f3eca2758 100644 --- a/09-features.md +++ b/09-features.md @@ -42,6 +42,12 @@ The Context column decodes as follows: | 22/23 | `option_anchors_zero_fee_htlc_tx` | Anchor commitment type with zero fee HTLC transactions | IN | | [BOLT #3][bolt03-htlc-tx], [lightning-dev][ml-sighash-single-harmful]| | 26/27 | `option_shutdown_anysegwit` | Future segwit versions allowed in `shutdown` | IN | | [BOLT #2][bolt02-shutdown] | + +## bLIP Reserved Feature Bits +| Bits | Name | Description | Context | Dependencies | Link | +|-------|----------------------------------|-----------------------------------------------------------|----------|-------------------|---------------------------------------| +| 55 | `keysend` | Node supports receiving keysend payments | N | | [bLIP #0002][blip-0002] | + ## Requirements The origin node: @@ -89,3 +95,4 @@ This work is licensed under a [Creative Commons Attribution 4.0 International Li [bolt07-query]: 07-routing-gossip.md#query-messages [bolt04-mpp]: 04-onion-routing.md#basic-multi-part-payments [ml-sighash-single-harmful]: https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-September/002796.html +[blip-0002]: blips/blip-0002.mediawiki diff --git a/blips/blip-0001.md b/blips/blip-0001.md new file mode 100644 index 000000000..ba8def587 --- /dev/null +++ b/blips/blip-0001.md @@ -0,0 +1,302 @@ +``` +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. Optional Feature Bits are assigned +*odd* bits, while compulsory Feature Bits are assigned *even* bits. 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 `509`. + +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 folder of the lightning-rfc +repository](https://github.com/lightningnetwork/lightning-rfc) 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 lightning-rfc editors will check the requested +Feature Bit, Message Type, and/or TLV assignments for collisions. If there are no +issues, the lightning-rfc editors will merge the pull request into the [bLIPs folder +of the lightning-rfc repository](https://github.com/lightningnetwork/lightning-rfc). +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 BOLT editors are the bLIP editors, currently: + +* Bastien Teinturier (@t-bast) +* Christian Decker (@cdecker) +* Lisa Neigut (@niftynei) +* Matt Corallo (@TheBlueMatt) +* Olaoluwa Osuntokun (@roasbeef) +* 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. +* **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/blips/blip-0001/blip-0001-1.png b/blips/blip-0001/blip-0001-1.png new file mode 100644 index 000000000..b53279901 Binary files /dev/null and b/blips/blip-0001/blip-0001-1.png differ diff --git a/blips/blip-0002.md b/blips/blip-0002.md new file mode 100644 index 000000000..42c67eabe --- /dev/null +++ b/blips/blip-0002.md @@ -0,0 +1,110 @@ +``` +bLIP: 2 +Title: Keysend +Status: Active +Author: Valentine Wallace +Created: 2021-07-28 +License: BSD-2-Clause, OPL +``` + +# Abstract + +Keysend is a type of lightning payment that does not require the payee to +provide an invoice. Instead, the payer includes their payer-selected payment +preimage in the TLV onion. + +As of authoring this bLIP, keysend is already supported by lnd, C-Lightning, +Eclair, LDK, and possibly others. This bLIP serves to document what is already +well-supported in the wild, for posterity and so that new implementations don't +have to reverse-engineer keysend from existing implementations. + +# Copyright + +This bLIP is dual-licensed under the Open Publication License and BSD 2-clause +license. + +# Specification + +Sender: +* MUST include a TLV record keyed by type `5482373484` with a TLV value of a + randomly generated and cryptographically-secure 32-byte value that serves as + the HTLC payment preimage +* MUST NOT set a `payment_data` field in the onion routing packet's TLV payload +* SHOULD only send payments to nodes advertising feature bit 55 + +Receiver: +* if failing the payment due to not wanting to accept keysend payments, SHOULD + error with `PERM|15 incorrect_or_unknown_payment_details`. +* MUST advertise feature bit 55 in the node context only +* MUST reject the keysend if the preimage does not match the payment hash +* MUST reject the keysend if a `payment_data` field is present in the onion + routing packet's TLV payload + +Note that because of the lack of a payment secret, basic MPP payments are not +supported with keysend. + +# Motivation + +A convenience of layer 1 bitcoin is being able to spontaneously send to a +bitcoin address with no advance work required on the part of the payee. Keysend +brings the convenience of sponaneous payments to layer 2 (with a few caveats, +see the Drawbacks section). + +As previously mentioned, keysend also has the advantage of already being +supported by major implementations. So regardless of whether it is the best +solution to spontaneous payments, it's a good idea to have some form of +official documentation for it. + +Additionally, as of authoring this bLIP, keysend is used in multiple lightning +ecosystem projects such as Sphinx.chat. + +# Rationale + +Design decisions for keysend were largely made by the original lnd keysend +implementation (e.g. the choice of `5482373484` for the TLV type). + +* The TLV type `5482373484` was chosen at random +* The rationale behind having a feature bit is that it's nicer to opt-in to + receiving keysend payments: without a feature bit, the only way for senders to + explicitly know that receivers support keysend is by attempting a keysend + payment and seeing whether or not it fails. +* The rationale for not supporting basic MPP is (1) implementations currently do + not support it and (2) it doesn't make much sense for receivers to provide + their own `payment_secret`, which causes the payment secret to lose some of + its security properties. A future direction for keysend could be deciding that + it's acceptable to use receiver-generated payment secrets, thus making basic + MPP keysend payments possible. +* If receivers don't check that the keysend preimage doesn't match the payment + hash, then an intermediate hop forwarding non-keysend-HTLC X could discover + the final destination of X, by probing the next node on the route with a + keysend payment of identical payment hash to X and observing the processing + time discrepancies due to a hash collision with X. + +# Keysend Drawbacks + +* Inability for the payee to specify their preferred `min_final_cltv_expiry`. + This is an issue because payer and payee may have differing security + requirements, which could lead to payment failures if the payee considers the + payer's choice of `min_final_cltv_expiry` too high or too low. +* Multi-path payments currently not supported +* Loss of being able to use the preimage and invoice signature as + proof-of-payment. With regular lightning payments, payers are able to use (1) + the payment preimage and (2) the invoice signature in a situation where they + need to prove that they made a payment (the invoice signature is necessary to + prove that the payer was not an intermediary hop). This proof cannot be + provided for keysend payments because the preimage is provided by the payer to + begin with and no invoice is being paid. +* Keysend is expected to be deprecated in favor of a more well-developed + spontaneous payment solution like + [Offers](https://github.com/lightningnetwork/lightning-rfc/pull/798) or + [AMP](https://github.com/lightningnetwork/lightning-rfc/pull/658) + +# Reference Implementations + +LDK: https://github.com/rust-bitcoin/rust-lightning/pull/967 + +C-Lightning: https://github.com/ElementsProject/lightning/blob/master/plugins/keysend.c + +`lnd` original keysend PR: https://github.com/lightningnetwork/lnd/pull/3795 + +Eclair: https://github.com/ACINQ/eclair/pull/1485 \ No newline at end of file