Skip to content

Latest commit

 

History

History
90 lines (70 loc) · 3.69 KB

blip-0003.md

File metadata and controls

90 lines (70 loc) · 3.69 KB
Raw
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), 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 spontaneous 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.

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 or AMP

Reference Implementations