|
| 1 | +``` |
| 2 | +bLIP: 3 |
| 3 | +Title: Keysend |
| 4 | +Status: Active |
| 5 | +Author: Valentine Wallace <[email protected]> |
| 6 | +Created: 2021-12-08 |
| 7 | +License: CC0 |
| 8 | +``` |
| 9 | + |
| 10 | +# Abstract |
| 11 | + |
| 12 | +Keysend is a type of lightning payment that does not require the payee to |
| 13 | +provide an invoice. Instead, the payer includes their payer-selected payment |
| 14 | +preimage in the TLV onion. |
| 15 | + |
| 16 | +This bLIP serves to document what is already well-supported in the wild (see |
| 17 | +[Reference Implementations](#reference-implementations)), for posterity and so |
| 18 | +that new implementations don't have to reverse-engineer keysend from existing |
| 19 | +implementations. |
| 20 | + |
| 21 | +# Copyright |
| 22 | + |
| 23 | +This bLIP is licensed under the CC0 license. |
| 24 | + |
| 25 | +# Specification |
| 26 | + |
| 27 | +Sender: |
| 28 | +* MUST include a TLV record keyed by type `5482373484` with a TLV value of a |
| 29 | + randomly generated and cryptographically-secure 32-byte value that serves as |
| 30 | + the HTLC payment preimage |
| 31 | +* MUST NOT reuse a previously used preimage |
| 32 | +* MUST NOT reuse a preimage from a previously paid invoice |
| 33 | +* MUST set the `payment_hash` field in the `update_add_htlc` message to match |
| 34 | + the SHA256 hash of the payment preimage |
| 35 | +* MUST NOT set a `payment_data` field in the onion routing packet's TLV payload |
| 36 | +* SHOULD only send payments to nodes advertising the `keysend` feature bit |
| 37 | + |
| 38 | +Receiver: |
| 39 | +* if failing the payment due to not wanting to accept keysend payments or if |
| 40 | + the preimage does not match the payment hash, SHOULD error with |
| 41 | + `PERM|15 incorrect_or_unknown_payment_details`. |
| 42 | +* MUST reject the keysend if a `payment_data` field is present in the onion |
| 43 | + routing packet's TLV payload |
| 44 | + |
| 45 | +Note that because of the lack of a payment secret, basic MPP payments are not |
| 46 | +supported with keysend. |
| 47 | + |
| 48 | +# Motivation |
| 49 | + |
| 50 | +A convenience of layer 1 bitcoin is being able to spontaneously send to a |
| 51 | +bitcoin address with no advance work required on the part of the payee. Keysend |
| 52 | +brings the convenience of sponaneous payments to layer 2 (with a few caveats, |
| 53 | +see the Drawbacks section). |
| 54 | + |
| 55 | +As previously mentioned, keysend also has the advantage of already being |
| 56 | +supported by major implementations. So regardless of whether it is the best |
| 57 | +solution to spontaneous payments, it's a good idea to have some form of |
| 58 | +official documentation for it. |
| 59 | + |
| 60 | +Additionally, as of authoring this bLIP, keysend is used in multiple lightning |
| 61 | +ecosystem projects such as Sphinx.chat. |
| 62 | + |
| 63 | +# Rationale |
| 64 | + |
| 65 | +Design decisions for keysend were largely made by the original lnd keysend |
| 66 | +implementation (e.g. the choice of `5482373484` for the TLV type). |
| 67 | + |
| 68 | +* The TLV type `5482373484` was chosen at random |
| 69 | +* The rationale behind having a feature bit is that it's nicer to opt-in to |
| 70 | + receiving keysend payments: without a feature bit, the only way for senders to |
| 71 | + explicitly know that receivers support keysend is by attempting a keysend |
| 72 | + payment and seeing whether or not it fails. |
| 73 | +* The rationale for not supporting basic MPP is (1) implementations currently do |
| 74 | + not support it and (2) it doesn't make much sense for receivers to provide |
| 75 | + their own `payment_secret`, which causes the payment secret to lose some of |
| 76 | + its security properties. A future direction for keysend could be deciding that |
| 77 | + it's acceptable to use receiver-generated payment secrets, thus making basic |
| 78 | + MPP keysend payments possible. |
| 79 | + |
| 80 | +# Keysend Drawbacks |
| 81 | + |
| 82 | +* Inability for the payee to specify their preferred `min_final_cltv_expiry`. |
| 83 | + This is an issue because payer and payee may have differing security |
| 84 | + requirements, which could lead to payment failures if the payee considers the |
| 85 | + payer's choice of `min_final_cltv_expiry` too high or too low. |
| 86 | +* Multi-path payments currently not supported |
| 87 | +* Loss of being able to use the preimage and invoice signature as |
| 88 | + proof-of-payment. With regular lightning payments, payers are able to use (1) |
| 89 | + the payment preimage and (2) the invoice signature in a situation where they |
| 90 | + need to prove that they made a payment (the invoice signature is necessary to |
| 91 | + prove that the payer was not an intermediary hop). This proof cannot be |
| 92 | + provided for keysend payments because the preimage is provided by the payer to |
| 93 | + begin with and no invoice is being paid. |
| 94 | +* Keysend is expected to be deprecated in favor of a more well-developed |
| 95 | + spontaneous payment solution like |
| 96 | + [Offers](https://github.com/lightningnetwork/lightning-rfc/pull/798) or |
| 97 | + [AMP](https://github.com/lightningnetwork/lightning-rfc/pull/658) |
| 98 | + |
| 99 | +# Reference Implementations |
| 100 | + |
| 101 | +LDK: https://github.com/rust-bitcoin/rust-lightning/pull/967 |
| 102 | + |
| 103 | +C-Lightning: https://github.com/ElementsProject/lightning/blob/master/plugins/keysend.c |
| 104 | + |
| 105 | +lnd original keysend PR: https://github.com/lightningnetwork/lnd/pull/3795 |
| 106 | + |
| 107 | +Eclair: https://github.com/ACINQ/eclair/pull/1485 |
0 commit comments