MSTR Cat

Blockchain/Level V · Layers/5.1 Lightning/Lesson 3

Invoices: BOLT11 and BOLT12

From single-use strings to reusable offers, and the web servers that bridged the gap

MaterialsA Lightning wallet capable of decoding invoicesA public BOLT11 decoder tool accessible via browserA sample BOLT11 invoice and a BOLT12 offer string

Wonder

  1. Why does a payment request that expires in an hour force merchants into constant regeneration?
  2. How can a static QR code remain valid for years while still producing unique, secure invoices per transaction?
  3. What specific data fields allow a wallet to verify that an invoice has not been tampered with before sending funds?

Explore

  1. A BOLT11 invoice is a bech32 string beginning with ‘lnbc’ that encapsulates all necessary payment parameters. It encodes an optional amount (in bitcoin, with a multiplier letter, down to fractions of a satoshi), a specific payment hash derived from a secret preimage, and an expiry timestamp defaulting to one hour. The payee node’s public key identifies the destination, while optional route hints guide the payer if direct channels are unavailable. The entire string is signed by the payee, ensuring integrity.
  2. This architecture makes BOLT11 invoices strictly single-use. Once a sender pays the associated payment hash, the invoice is settled and cannot be redeemed again. Paying it twice is unsafe: after the first payment the preimage is known to every node on that route, so any of those nodes that also sits on the second payment’s route could take it. This constraint necessitates dynamic QR codes for retail, where merchants must generate a new string for every customer, complicating point-of-sale hardware.
  3. Community developers addressed this friction through LNURL and Lightning Addresses, which rely on external web servers. A user scans a static URI pointing to a server endpoint; the wallet fetches a fresh BOLT11 invoice from that server before initiating payment. This decouples the public address from the specific transaction data, allowing a single link to serve unlimited payments while maintaining the security of unique, single-use invoices behind the scenes.
  4. BOLT12 ‘offers,’ designed by Rusty Russell and added to the specification in 2024, internalize this flow. These reusable payment codes begin with ‘lno’ and function as static identifiers for a payee node. When scanned, the payer’s wallet sends an onion message directly over the Lightning Network to fetch a fresh invoice from the offer creator. This eliminates the dependency on external web servers, integrating request generation into the core protocol.
  5. BOLT12 offers support features absent in BOLT11, including flows in which the merchant pays the user, such as refunds or withdrawals (recurring payments were drafted but removed from the merged specification). Offers can also use blinded paths to hide the receiving node within the channel graph, instead of publishing its public key. This design reduces privacy leakage compared to standard invoices that expose routing hints or fallback addresses directly.
  6. Spontaneous payments bypass invoices entirely using keysend or AMP (Atomic Multi-Path) protocols, where senders push funds to a known node key without prior request. For hands-on verification, paste any Lightning invoice into a public BOLT11 decoder. Identify the human-readable prefix, the amount, the payment hash, the expiry time, and the payee signature. Compare this with an ‘lno’ string, which carries no payment hash, only what the payer needs to request an invoice: the node ID or blinded paths to it.

Key facts

  • BOLT11 invoices are single-use bech32 strings beginning with ‘lnbc’, encoding amount, hash, and signature.
  • LNURL and Lightning Addresses use web servers to fetch fresh BOLT11 invoices from static links.
  • BOLT12 offers begin with ‘lno’ and generate unique invoices via onion messages over the Lightning Network.
  • BOLT12 offers are reusable and support merchant-to-user payments such as refunds, which BOLT11 does not.
  • The default expiry time for a BOLT11 invoice is one hour (3600 seconds).
  • Keysend allows spontaneous payment to a node public key without an invoice.

Exercise nine, six, three, one

9CollectList 9 distinct payment request formats or identifiers used in digital finance, from legacy bank transfer codes to modern crypto standards. Note whether each is single-use or reusable.
6ClusterGroup the 9 into 6 categories based on how they handle uniqueness: static-reusable, dynamic-single-use, server-mediated-fresh-fetch, protocol-native-fresh-fetch, key-based-spontaneous, or other.
3DistillReduce the 6 groups to 3 fundamental trade-offs between user convenience (static codes) and cryptographic security (unique hashes).
1CrystallizeWrite 1 sentence explaining why BOLT12 offers eliminate the need for external web servers in reusable payment flows.

Fact check

Dates, figures and claims checked against the published sources listed below.

Open in the interactive academy →

PT ES ZH JA KO RU DE FR MS