-
Notifications
You must be signed in to change notification settings - Fork 491
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
c91f4aa
commit 0f086a9
Showing
1 changed file
with
102 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,102 @@ | ||
| <pre> | ||
| bLIP: 2 | ||
| Title: Keysend | ||
| Status: Active | ||
| Type: Standards Track | ||
| Author: Valentine Wallace <[email protected]> | ||
| Created: 2021-05-21 | ||
| License: BSD-2-Clause, OPL | ||
| </pre> | ||
|
|
||
| ==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 secret | ||
| * SHOULD only send payments to nodes advertising feature bit 55 in the node | ||
| context starting June 1, 2022 | ||
| Receiver: | ||
| * if completing the payment, MUST fulfill the HTLC using the TLV-provided | ||
| payment preimage | ||
| * if failing the payment, SHOULD error with `PERM|15 | ||
| incorrect_or_unknown_payment_details`. | ||
| * MUST advertise feature bit 55 in the node context only starting June 1, 2022 | ||
| 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. *However*, because of the drawbacks of keysend | ||
| and the expectation that it will eventually 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), it makes more | ||
| sense for keysend to be documented in a bLIP than included in the official BOLTs. | ||
|
|
||
| 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 feature bit is currently not supported by all implementations, but should | ||
| be supported after June 1, 2022. The purpose of this lead time is to give | ||
| implementations the chance to implement the feature without being | ||
| bLIP-incompatible in the meantime. 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 that 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. | ||
|
|
||
| ==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 as proof-of-payment. With non-keysend | ||
| payments, payers could use the payment preimage in a situation where they need | ||
| to prove that they made a payment. This does not hold for keysend payments | ||
| since the preimage was provided by the payer to begin with. | ||
| ==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 |