mirrors/lightning-blips
1
0
Fork 0
mirror of https://github.com/lightning/blips.git synced 2024-11-19 00:50:02 +01:00
Code Issues Projects Releases Wiki Activity

Clean up markdown (#9)

Browse Source 
Apply common markdown linting rules.
This commit is contained in:
Bastien Teinturier 2022-01-05 17:02:37 +01:00 committed by GitHub
parent 44434a9738
commit 6e5493832e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 160 additions and 161 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
README.md
View File

@ -1,24 +1,24 @@
# Bitcoin Lightning Improvement Proposal
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
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
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](./blip-0001.md) and
[bLIP-0002](./blip-0002.md).
| Number | Title | Author | Status |
|--------|---------------------------|-----------------------------|--------|
| Number | Title | Author | Status |
|--------------------------|---------------------------|-----------------------------|--------|
| [1](./blip-0001.md) | bLIP Process | Ryan Gentry | Active |
| [2](./blip-0002.md) | reserved values | Bastien Teinturier | Active |
| [2](./blip-0002.md) | Reserved Values | Bastien Teinturier | Active |
| [3](./blip-0003.md) | Keysend | Valentine Wallace | Active |

250
blip-0001.md
View File

@ -9,102 +9,102 @@ Post-History: 2021-06-30: https://lists.linuxfoundation.org/pipermail/lightning-
License: CC0
```
# Abstract
## 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
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
## Copyright
This bLIP is licensed under the CC0 license.
# Rationale
## 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.
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,
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
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
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
## 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
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)
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
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
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).
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](./blip-0002.md) 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](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
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
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
### 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,
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
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
@ -123,26 +123,26 @@ The current bLIP editors are:
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
* 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
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 #
* 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
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?
@ -154,33 +154,33 @@ 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
* **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
* **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,
* **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
* **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
* **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
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.
```
@ -200,81 +200,81 @@ License: abbreviation for approved license(s)
* Superseded-By: bLIP number
```
The Author header lists the names and email addresses of all the authors/owners of the bLIP.
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
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,
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
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
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)
![blip status workflow](blip-0001/blip-0001-1.png)
* **Draft** - The first formally tracked stage of a bLIP in development. A bLIP is merged by
* **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
* **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,
* **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
* **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
* **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
* **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
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
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
## 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
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.

20
blip-0002.md
View File

@ -7,7 +7,7 @@ Created: 2021-11-05
License: CC0
```
# Abstract
## Abstract
bLIPs may need to define messages and fields that need to be correctly parsed and interpreted
throughout the network to ensure interoperability and guarantee backwards-compatibility.
@ -24,9 +24,9 @@ bLIP authors must edit the tables below to reserve values in these various names
there will be no conflict between unrelated bLIPs, which would otherwise potentially lead to a
network split.
# Reserved values
## Reserved values
## Table of Contents
### Table of Contents
* [Feature bits](#feature-bits)
* [Messages](#messages)
@ -35,7 +35,7 @@ network split.
* [`ping`](#ping)
* [`update_add_htlc`](#update_add_htlc)
## Feature bits
### Feature bits
Feature bits are specified in [Bolt 9](https://github.com/lightning/bolts/blob/master/09-features.md).
They let nodes publicly advertise that they support or require a given feature.
@ -47,7 +47,7 @@ bLIPs may reserve feature bits by adding them to the following table:
|---------|----------------------|-------------------------------------------------|----------------|--------------------------------|--------------------------------|
| 54/55 | `keysend` | A form of spontaneous payment | N | `var_onion_optin` | [bLIP 3](./blip-0003.md) |
## Messages
### Messages
The BOLTs define a standard [message format](https://github.com/lightning/bolts/blob/master/01-messaging.md#lightning-message-format)
that every lightning implementation understands.
@ -59,7 +59,7 @@ bLIPs may create new messages and reserve their type in the following table:
|-------|-----------------------------|--------------------------------|
| 32768 | `message_name` | Link to the corresponding bLIP |
## TLV fields in BOLT messages
### TLV fields in BOLT messages
Every BOLT message contains a trailing `extension` field, which is a tlv stream with tlv fields
specific to that BOLT message.
@ -71,7 +71,7 @@ bLIPs must carefully decide whether these new tlv fields should be even or odd,
When adding new tlv fields to existing BOLT messages, bLIPS must use types greater than `65536`
and fill the table corresponding to the message they're modifying.
### `init`
#### `init`
The following table contains extension tlv fields for the `init` message:
@ -79,7 +79,7 @@ The following table contains extension tlv fields for the `init` message:
|-------|-----------------------------|--------------------------------|
| 65536 | `tlv_field_name` | Link to the corresponding bLIP |
### `ping`
#### `ping`
The following table contains extension tlv fields for the `ping` message:
@ -87,7 +87,7 @@ The following table contains extension tlv fields for the `ping` message:
|-------|-----------------------------|--------------------------------|
| 65536 | `tlv_field_name` | Link to the corresponding bLIP |
### `update_add_htlc`
#### `update_add_htlc`
The following table contains extension tlv fields for the `update_add_htlc` message's onion payload:
@ -95,6 +95,6 @@ The following table contains extension tlv fields for the `update_add_htlc` mess
|------------|-----------------------------|--------------------------------|
| 5482373484 | `keysend_preimage` | [bLIP 3](./blip-0003.md) |
# Copyright
## Copyright
This bLIP is licensed under the CC0 license.

29
blip-0003.md
View File

@ -7,7 +7,7 @@ Created: 2021-12-08
License: CC0
```
# Abstract
## 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
@ -18,13 +18,14 @@ This bLIP serves to document what is already well-supported in the wild (see
that new implementations don't have to reverse-engineer keysend from existing
implementations.
# Copyright
## Copyright
This bLIP is licensed under the CC0 license.
# Specification
## 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
@ -35,11 +36,12 @@ Sender:
* SHOULD only send payments to nodes advertising the `keysend` feature bit
Receiver:
* if failing the payment due to not wanting to accept keysend payments or if
the preimage does not match the payment hash, SHOULD error with
`PERM|15 incorrect_or_unknown_payment_details`.
`PERM|15 incorrect_or_unknown_payment_details`.
# Motivation
## 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
@ -51,7 +53,7 @@ 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.
# Rationale
## Rationale
Design decisions for keysend were largely made by the original lnd keysend
implementation (e.g. the choice of `5482373484` for the TLV type).
@ -62,7 +64,7 @@ implementation (e.g. the choice of `5482373484` for the TLV type).
explicitly know that receivers support keysend is by attempting a keysend
payment and seeing whether or not it fails.
# Keysend Drawbacks
## 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
@ -80,12 +82,9 @@ implementation (e.g. the choice of `5482373484` for the TLV type).
[Offers](https://github.com/lightningnetwork/lightning-rfc/pull/798) or
[AMP](https://github.com/lightningnetwork/lightning-rfc/pull/658)
# Reference Implementations
## 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
* 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>