BOLT 12 - Natively Enhancing Lightning’s User Experience

BOLT 12 - Natively Enhancing Lightning’s User Experience


June 23, 2023


If you use the Lightning Network regularly, or if you read our article about LNURL, you might be familiar with the user experience limitations that the Lightning Network faces. In case you don’t know, here’s a quick recap.

The current standard for requesting payments over Lightning is BOLT 11. Every payment requires an invoice, and every invoice, in its turn, is bound to a payment pre-image. It’s unsafe to pay the same invoice more than once because this can result in funds being stolen. Also, invoices can only be used to request payments, not to send them.

This makes the Lightning Network limited in terms of possible use cases when compared to traditional payment networks. If a streamer has to stop what it’s doing to generate a new invoice every time someone wants to tip him, he’ll probably not end up using lighting. Or, if people want to insert fiat currency and receive bitcoin over lightning in an ATM, they would have to not only insert the money but also pull up their phones to create an invoice for the ATM to scan it. Or even worse, they would have to type the invoice by hand.


These examples reveal Lightning's constraints, and they are just a drop in the ocean of use cases where Lightning can’t compete. To outperform other payment networks, it must cater to a broader range of use cases.

The Proposed Solution

BOLT 12 is an attempt led by Blockstream’s CLN developer Rusty Russell to solve these limitations. The goal is to enable lightning clients to generate static QR codes that can be used for payments and also to send money, like in the ATM example above. Russel was also the author of the BOLT 11 spec, so if there’s one person that is aware of its limitations, it’s him.

It’s a simple idea: Enable Lighting Nodes to create a static QR code that has the information needed for a wallet to be able to communicate with it, so they can coordinate further actions. If you how LNURL works this already sounds familiar. The major difference from LNULR is that BOLT 12 aims to do this communication and coordination natively on the network.

Because BOLT 12 only needs to embed information about a lightning node, and not information about the payment, like BOLT 11, the end result is a much simpler QR code. There’s room to add additional data, such as blinded paths, for instance. This is one of the misunderstandings about it. It’s not that blinded paths require BOLT 12, it’s that it makes it much simpler to use it.

Rusty aims to enable this communication and coordination of lightning nodes using Onion Messages, a mechanism very similar to the Onion Routing protocol, used to send payments across the network, but without the payment part. This is will enable Offers to work natively in the network, without the need for external servers, as is the case for LNURL. Today, Onion Messages are still under development, which is one reason why BOLT 12 is still not ratified.

With BOLT 12, the user will scan an “offer” instead of an invoice. Offers serve as a preliminary step to the invoice_request message, where readers can request one or multiple invoices based on the offer. There are two uses for invoice requests. The first is a response to an offer, containing the id of the offer’s owner and relevant offer details, received via an Onion message. If the request is valid, the response is to send an invoice using the reply path specified in the onion message. The other use case involves publishing an 'invoice_request' directly, using a QR code, for instance. This request contains the id of the node that will pay the invoice, essentially forming an offer to send money.

Offers and invoice requests are encoded in the Type-Length-Value (TLV) format, described in BOLT 1, the default encoding protocol for messages on the Lightning Network. This protocol facilitates network upgrades by providing a flexible and extensible way to structure and exchange data. It allows new features to be added without disrupting existing implementations, ensuring compatibility and reducing the risks and complexities associated with network upgrades. This means that BOLT 12 does not require an entire network upgrade. It’s an opt-in feature.

Another interesting feature is that unlike regular proof of payments on Lightning, which can only ensure that the invoice was paid, BOLT 12 also enables the payer to prove that they were the ones who made the payment. Additionally, if a dispute needs to be resolved, the payer can reveal only a part of the invoice to solve the issue, preserving some of their privacy.

Payment Flows

Let's explore the two possible payment flows using Offers: one where a user pays a merchant, and another where a user receives money from a merchant. To simplify, whenever "user" or "merchant" is mentioned, assume it refers to their respective Lightning nodes. We'll start with the former:

The user scans the merchant’s Offer and extracts the information on the QR code to request an invoice through an invoice_request message. Once the merchant receives this message, they respond with the invoice. The user then proceeds with the payment as in a standard transaction. From here, the payment process continues as usual.

Now let’s see what happens when the merchant pays the user:

The merchant creates a QR code representing an invoice request, complete with offer fields expressing the intent to pay. The user scans this code, generates an invoice based on the invoice_request, and forwards it to the merchant. Once the merchant receives the invoice, it pays it, and the payment carries on as normal.


In conclusion, the Lightning Network faces certain user experience limitations due to its reliance on the BOLT 11 standard for requesting payments. BOLT 12, led by Blockstream’s CLN developer Rusty Russell, is a solution aimed at overcoming these constraints by enabling Lightning nodes to generate static QR codes for both receiving and sending payments. By implementing Onion Messages and introducing the concept of offers, BOLT 12 simplifies the payment process while preserving privacy and enhancing user experience. While still in development, BOLT 12 holds the potential to significantly expand the use cases of the Lightning Network, allowing it to better compete with traditional payment networks and further revolutionize the world of digital transactions.

Explore our Lightning FAQ which is growing weekly with new content helping builders grok and understand the foundational components of Lightning.

You can start building on Lightning today, hop on our Dashboard and spin up your own node below!

Share this post

Start Building on Bitcoin Now