Keysend Payments Explained - Voltage Technical Series

The Voltage Technical Series is a weekly education article focusing on topics and concepts involving the Bitcoin Lightning Network.

Keysend Payments Explained - Voltage Technical Series

Howdy, everyone! This is the first Technical Series article and I am ridiculously excited to dive into some topics that many node runners and Lightning users in general hear about but may be unsure of what it actually is or what it is for. A lot of topics that we will be discussing in this series are not necessarily required to run a good routing node, or even use Lightning, but for those who want to dive deeper I think you will find a lot of value. This week we will be talking about Keysend.

First, a bit of background. The Lightning Network payment mechanism has historically revolved around what is called BOLT 11, which describes in detail the technical nature of the lightning invoice. A BOLT 11 invoice is generated by a user of the Lightning Network who wants to receive a payment.

For example, if I mowed Bob's lawn and want payment from Bob on the Lightning Network, I would need to generate an invoice and give Bob that invoice either through text string or QR code. But...what if Bob could pay me using lightning without me having to generate an invoice? By providing him with just my Lightning node's public key, Bob can pay me an unlimited amount of times with no invoices required.

What else can Keysend enable?

Most Lightning Network implementations have a form of Keysend, including LND, and C-Lightning.  With Keysend, Lightning users are able to more easily accept donations, report earnings, and build Lightning-only APIs. Further innovations around chat (ex. Sphinx Chat) or streaming payments (Podcasting 2.0, Breez) could also be accomplished by sending extra information with the onion packet that envelopes the payment information.  

What does a Keysend payment look like?

The payment data that is sent into the network carries required information.  This information includes an encoded amount of sats to send, a message, and a preimage. After the payment reaches the destination and the receiving node accepts the payment, the preimage is revealed and payment is confirmed. A keysend payment is end-to-end encrypted which means none of the nodes moving the payment are able to fully unwrap the package and discover the preimage. Only the final destination is able to do that.

How is the Data Sent?

In a regular invoice based Lightning payment, the receiver picks a preimage and then applies a cryptographic hash to it and then gives the invoice to the payer. The preimage acts as proof the payment was completed once paid due to the invoice being signed by the recipient. For a Keysend payment, the payer picks the preimage instead and then uses onion wrapping to seal the data as it routes to the recipient.

The onion wrapped data is transmitted along a route that is hidden from the nodes moving the payment.  This data package gets incrementally unwrapped as the payment travels along hops to it's final destination.

How do I receive a Keysend payment?

If you are using Voltage, be sure to toggle Keysend to on in your Dashboard Settings:

If you are using a local LND, be sure to set the following under Application Options in your .conf file:

accept-keysend=1

By doing this you are signaling that you are willing to accept Keysend payments.

How do I send a Keysend Payment?

To send through Thunderhub click the Send option:

Make sure to Toggle "Is Keysend" to Yes.

Next, paste in the Public Key of the node you want to pay. You do not need to include the full URI string (Do not include an @ or anything after an @).

Press Decode.

Enter the amount you wish to send in sats and click send. Congrats you just did a Keysend payment!

If you are using LNCLI, use the following command to send a keysend payment:

lncli sendpayment --dest=<pubkey of destionation> --amt=<amount in satoshis> --keysend

If successful, you will see a Payment Successful output along with the preimage.

For C-Lightning, you use the keysend RPC command in place of the pay RPC command along with the destination pubkey and amount. For more information on using Keysend with C-Lightning, you can check out the official doc here.

Keysend Shortcomings

No Proof of Payment

The preimage is sent with the payment but only the receiver is able to read it. The receiver can then use the onion wrapped preimage to settle the payment. Due to the payer picking the preimage, the payer can't prove that they paid anything even after the payment is complete since no new information was gained.

No Hop Hints

By using Keysend your payment may utilize a less efficient route due to not knowing the channels of who you are paying.  You still have the power to refuse payments.

Adds Complexity

There is no enforced consensus on Lightning. As each implementation grows and develops their own unique features, the complexity of the network will increase. The more complex the lightning network becomes in this regard, the harder it is to have a standard across all implementations.

Privacy

One important consideration before you begin to accept Keysend is whether or not you want the world to know all of your public channels and capacity. Your pubkey says a lot about you and your node including total capacity, your peers, fee rates, and other information.

Although no one knows exactly how much of the total capacity of your node that you personally own, you may be in a position where you do not want this information out in the open and tied directly to you. It is important to note that a regular BOLT 11 invoice can also be decoded to expose your pubkey as well.

Conclusion

Keysend enables the payer to specify the amount to be sent. The receiver node must enable this feature manually. This is because the receiver may not want to deal with the risk of spam or lack of proof of receipt. A node that serves a merchant function arguably does not have a good reason to enable Keysend. However, an educator or developer may want to have Keysend enabled to receive ad hoc payments or donations.

Sources used as secondary research for this article:

GitHub - lnbook/lnbook: Mastering the Lightning Network (LN)
Mastering the Lightning Network (LN). Contribute to lnbook/lnbook development by creating an account on GitHub.
Receiving Payments - Builder’s Guide

If you have any questions or comments either email us at support@voltage.cloud, use our live on-site chat, or join us in Telegram. ⚡️

----