Blog
Keysend Payments Explained - Voltage Technical Series

Keysend Payments Explained - Voltage Technical Series

Nate G
Nate G

October 19, 2021

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 generally hear about but may be unsure of what it is or what it is for. Many topics we will discuss 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 unlimited 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 can 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 the 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 can unwrap the package and discover the preimage fully. Only the final destination can 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 hidden route from the nodes moving the payment.  This data package gets incrementally unwrapped as the payment travels along hops to its 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

You will see a Payment Successful output along with the preimage if successful.

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 can 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

Before you begin to accept Keysend, one important consideration 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, peers, fee rates, and other information.

Although no one knows exactly how much of the total capacity of your node that you 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.

Conclusion

Keysend enables the payer to specify the amount to be sent. The receiver node must enable this feature manually. 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 Keysend enabled to receive ad hoc payments or donations.

Sources used as secondary research for this article:

https://github.com/lnbook/lnbook
https://docs.lightning.engineering/lightning-network-tools/lnd/receiving
https://www.youtube.com/watch?v=zaBY9_eEQWE&feature=emb_title

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


Share this post

Start Building on Bitcoin Now