BLIP 0003: Keysend (lightning#5)

Keysend is a basic form of spontaneous (invoice-less) payments.
It is already supported by all major implementations, but was never
publicly specified.

README.md

@@ -21,3 +21,4 @@ For more detail on the process, please read [bLIP-0001](./blip-0001.md) and
 |--------|---------------------------|-----------------------------|--------|
 | [1](./blip-0001.md)      | bLIP Process              | Ryan Gentry                 | Active |
 | [2](./blip-0002.md)      | reserved values           | Bastien Teinturier          | Active |
+| [3](./blip-0003.md)      | Keysend                   | Valentine Wallace           | Active |

blip-0002.md

@@ -33,6 +33,7 @@ network split.
 * [TLV fields in BOLT messages](#tlv-fields-in-bolt-messages)
   * [`init`](#init)
   * [`ping`](#ping)
+  * [`update_add_htlc`](#update_add_htlc)
 
 ## Feature bits
 
@@ -44,7 +45,7 @@ bLIPs may reserve feature bits by adding them to the following table:
 
 | Bits    | Name                 | Description                                     | Context        | Dependencies                   | Link                           |
 |---------|----------------------|-------------------------------------------------|----------------|--------------------------------|--------------------------------|
-| 256/257 | `feature_name`       | Short description                               | Bolt 9 context | Dependencies on other features | Link to the corresponding bLIP |
+| 54/55   | `keysend`            | A form of spontaneous payment                   | N              | `var_onion_optin`              | [bLIP 3](./blip-0003.md)       |
 
 ## Messages
 
@@ -86,6 +87,14 @@ The following table contains extension tlv fields for the `ping` message:
 |-------|-----------------------------|--------------------------------|
 | 65536 | `tlv_field_name`            | Link to the corresponding bLIP |
 
+### `update_add_htlc`
+
+The following table contains extension tlv fields for the `update_add_htlc` message's onion payload:
+
+| Type       | Name                        | Link                           |
+|------------|-----------------------------|--------------------------------|
+| 5482373484 | `keysend_preimage`          | [bLIP 3](./blip-0003.md)       |
+
 # Copyright
 
 This bLIP is licensed under the CC0 license.

blip-0003.md

@@ -0,0 +1,91 @@
+```
+bLIP: 3
+Title: Keysend
+Status: Active
+Author: Valentine Wallace <[email protected]>
+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 sponaneous 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