mirror of
https://github.com/lightning/blips.git
synced 2024-11-19 00:50:02 +01:00
BLIP 0003: Keysend (#5)
Keysend is a basic form of spontaneous (invoice-less) payments. It is already supported by all major implementations, but was never publicly specified.
This commit is contained in:
parent
e169d45327
commit
44434a9738
@ -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 |
|
||||
|
11
blip-0002.md
11
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.
|
||||
|
91
blip-0003.md
Normal file
91
blip-0003.md
Normal file
@ -0,0 +1,91 @@
|
||||
```
|
||||
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 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
|
Loading…
Reference in New Issue
Block a user