diff --git a/README.md b/README.md index 4d046bc..e5c84f9 100644 --- a/README.md +++ b/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 | diff --git a/blip-0002.md b/blip-0002.md index d06ee26..7817702 100644 --- a/blip-0002.md +++ b/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. diff --git a/blip-0003.md b/blip-0003.md new file mode 100644 index 0000000..9de65ea --- /dev/null +++ b/blip-0003.md @@ -0,0 +1,91 @@ +``` +bLIP: 3 +Title: Keysend +Status: Active +Author: Valentine Wallace +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