mirror of
https://github.com/lightning/blips.git
synced 2024-11-19 00:50:02 +01:00
91 lines
3.7 KiB
Markdown
91 lines
3.7 KiB
Markdown
```
|
|
bLIP: 3
|
|
Title: Keysend
|
|
Status: Active
|
|
Author: Valentine Wallace <vwallace@protonmail.com>
|
|
Created: 2021-12-08
|
|
License: CC0
|
|
```
|
|
|
|
## 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.
|
|
|
|
This bLIP serves to document what is already well-supported in the wild (see
|
|
[Reference Implementations](#reference-implementations)), for posterity and so
|
|
that new implementations don't have to reverse-engineer keysend from existing
|
|
implementations.
|
|
|
|
## Copyright
|
|
|
|
This bLIP is licensed under the CC0 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 reuse a previously used preimage
|
|
* MUST NOT reuse a preimage from a previously paid invoice
|
|
* MUST set the `payment_hash` field in the `update_add_htlc` message to match
|
|
the SHA256 hash of the payment preimage
|
|
* 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`.
|
|
|
|
## 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 spontaneous payments to layer 2 (with a few caveats,
|
|
see the [Drawbacks](#keysend-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.
|
|
|
|
## 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.
|
|
|
|
## 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.
|
|
* 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>
|