Skip to content

Commit

Permalink
Keysend bLIP
Browse files Browse the repository at this point in the history
  • Loading branch information
valentinewallace committed Dec 16, 2021
1 parent 136c93c commit b974bdf
Show file tree
Hide file tree
Showing 3 changed files with 118 additions and 1 deletion.
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,3 +21,4 @@ For more detail on the process, please read [bLIP-0001](./blip-0001.md) and
|--------|---------------------------|-----------------------------|--------|
| 1 | bLIP Process | Ryan Gentry | Active |
| 2 | reserved values | Bastien Teinturier | Active |
| 3 | Keysend | Valentine Wallace | Active |
11 changes: 10 additions & 1 deletion blip-0002.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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.
107 changes: 107 additions & 0 deletions blip-0003.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
```
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
* MUST NOT set a `payment_data` field in the onion routing packet's TLV payload
* 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`.
* MUST reject the keysend if a `payment_data` field is present in the onion
routing packet's TLV payload

Note that because of the lack of a payment secret, basic MPP payments are not
supported with keysend.

# 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 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.

Additionally, as of authoring this bLIP, keysend is used in multiple lightning
ecosystem projects such as Sphinx.chat.

# 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.
* The rationale for not supporting basic MPP is (1) implementations currently do
not support it and (2) it doesn't make much sense for receivers to provide
their own `payment_secret`, which causes the payment secret to lose some of
its security properties. A future direction for keysend could be deciding that
it's acceptable to use receiver-generated payment secrets, thus making basic
MPP keysend payments possible.

# 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.
* Multi-path payments currently not supported
* 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

0 comments on commit b974bdf

Please sign in to comment.