Progress pill
The Tools of the Lightning Network

Invoice, LNURL, and Keysend

Lightning Network Theory

Invoice, LNURL, and Keysend

  • The Structure of Lightning Invoices
  • The Payload of an Invoice
  • LNURL Withdrawal
  • Sending a Lightning Payment without an Invoice: Keysend
In this chapter, we will take a closer look at the operation of Lightning invoices, that is, payment requests sent by the recipient node to the sender node. The goal is to understand how to pay and receive payments on Lightning. We will also discuss 2 alternatives to classic invoices: LNURL and Keysend.

The Structure of Lightning Invoices

As explained in the chapter on HTLCs, each payment begins with the generation of an invoice by the recipient. This invoice is then transmitted to the payer (via a QR code or by copying and pasting) to initiate the payment. An invoice consists of two main parts:
  • The Human Readable Part: This section contains clearly visible metadata to enhance the user experience.
  • The Payload: this section includes information intended for machines to process the payment.
The typical structure of an invoice starts with an identifier ln for "Lightning", followed by bc for Bitcoin, then the amount of the invoice. A separator 1 distinguishes the human-readable part from the data (payload) part.
Let's take the following invoice as an example:
lnbc100u1p0x7x7dpp5l7r9y50wrzz0lwnsqgxdks50lxtwkl0mhd9lslr4rcgdtt2n6lssp5l3pkhdx0cmc9gfsqvw5xjhph84my2frzjqxqyz5vq9qsp5k4mkzv5jd8u5n89d2yc50x7ptkl0zprx0dfjh3km7g0x98g70hsqq7sqqqgqqyqqqqlgqqvnv2k5ehwnylq3rhpd9g2y0sq9ujyxsqqypjqqyqqqqqqqqqqqsqqqqq9qsq3vql5f6e45xztgj7y6xw6ghrcz3vmh8msrz8myvhsarxg42ce9yyn53lgnryx0m6qqld8fql
We can already divide it into 2 parts. First, there's the Human Readable Part:
lnbc100u
Then the part intended for the payload:

p0x7x7dpp5l7r9y50wrzz0lwnsqgxdks50lxtwkl0mhd9lslr4rcgdtt2n6lssp5l3pkhdx0cmc9gfsqvw5xjhph84my2frzjqxqyz5vq9qsp5k4mkzv5jd8u5n89d2yc50x7ptkl0zprx0dfjh3km7g0x98g70hsqq7sqqqgqqyqqqqlgqqvnv2k5ehwnylq3rhpd9g2y0sq9ujyxsqqypjqqyqqqqqqqqqqqsqqqqq9qsq3vql5f6e45xztgj7y6xw6ghrcz3vmh8msrz8myvhsarxg42ce9yyn53lgnryx0m6qqld8fql
The two parts are separated by a 1. This separator was chosen instead of a special character to allow for easy copying and pasting of the entire invoice by double-clicking.
In the first part, we can see that:
  • ln indicates that it's a Lightning transaction.
  • bc indicates that the Lightning network is on the Bitcoin blockchain (and not on the testnet or on Litecoin).
  • 100u indicates the amount of the invoice, expressed in microbitcoins (u meaning "micro"), which here equals 10,000 sats.
To designate the payment amount, it is expressed in sub-units of bitcoin. Here are the units used:
  • Millibitcoin (denoted m): Represents one-thousandth of a bitcoin.
  • Microbitcoin (denoted u): Also sometimes called "bit", represents one-millionth of a bitcoin.
  • Nanobitcoin (denoted n): Represents one-billionth of a bitcoin.
  • Picobitcoin (denoted p): Represents one-trillionth of a bitcoin.

The Payload of an Invoice

The payload of an invoice includes several pieces of information necessary for processing the payment:
  • The timestamp: The moment of the invoice's creation, expressed in Unix Timestamp (the number of seconds that have elapsed since January 1, 1970).
  • Hashing the Secret: As we saw in the section on HTLCs, the receiving node must provide the sending node with the hash of the preimage. This is used in HTLCs to secure the transaction. We referred to it as "r".
  • The Payment Secret: Another secret is generated by the recipient, but this time it is transmitted to the sending node. It is used in onion routing to prevent intermediate nodes from guessing whether the next node is the final recipient or not. This thus maintains confidentiality for the recipient with respect to the last intermediate node on the route.
  • The Recipient's Public Key: Indicates to the payer the identifier of the person to be paid.
  • The Expiration Duration: The maximum time for the invoice to be paid (1 hour by default).
  • Routing Hints: Additional information provided by the recipient to help the sender optimize the payment route.
  • The Signature: Guarantees the integrity of the invoice by authenticating all the information.
The invoices are then encoded in bech32, the same format as for Bitcoin SegWit addresses (format starting with bc1).

LNURL Withdrawal

In a traditional transaction, such as a store purchase, the invoice is generated for the total amount to be paid. Once the invoice is presented (in the form of a QR code or string of characters), the customer can scan it and finalize the transaction. The payment then follows the traditional process that we studied in the previous section. However, this process can sometimes be very cumbersome for the user experience, as it requires the receiver to send information to the sender via the invoice.
For certain situations, such as withdrawing bitcoins from an online service, the traditional process can be too cumbersome. In such cases, the LNURL withdrawal solution simplifies this process by displaying a QR code that the recipient's wallet scans to automatically create the invoice. The service then pays the invoice, and the user simply sees an instant withdrawal.
LNURL is a communication protocol that specifies a set of functionalities designed to simplify interactions between Lightning nodes and clients, as well as third-party applications. The LNURL withdrawal, as we have just seen, is thus just one example among other functionalities. This protocol is based on HTTP and enables the creation of links for various operations, such as payment requests, withdrawal requests, or other functionalities that enhance the user experience. Each LNURL is a bech32-encoded URL with the LNURL prefix, which, once scanned, triggers a series of automatic actions on the Lightning wallet. For example, the LNURL-withdraw (LUD-03) feature allows withdrawing funds from a service by scanning a QR code, without the need to manually generate an invoice. Similarly, LNURL-auth (LUD-04) enables logging into online services using a private key on one's Lightning wallet instead of a password.

Sending a Lightning Payment without an Invoice: Keysend

Another interesting case is the transfer of funds without having received an invoice beforehand, known as "Keysend". This protocol allows sending funds by adding a preimage to the encrypted payment data, which is accessible only by the recipient. This preimage enables the recipient to unlock the HTLC, thus retrieving the funds without having generated an invoice beforehand.
To simplify, in this protocol, it is the sender who generates the secret used in the HTLCs, rather than the recipient. Practically, this allows the sender to make a payment without having to interact with the recipient beforehand.
What should you take away from this chapter?
  • A Lightning Invoice is a payment request consisting of a human-readable part and a machine data part.
  • The invoice is encoded in bech32, with a 1 separator to facilitate copying and a data part containing all the information necessary to process the payment.
  • Other payment processes exist on Lightning, notably LNURL-Withdraw to facilitate withdrawals, and Keysend for direct transfers without an invoice.
In the following chapter, we will see how a node operator can manage liquidity in their channels, ensuring they are never blocked and can always send and receive payments on the Lightning Network.
Quiz
Quiz1/5
What is the role of LNURL in Lightning transactions?