BOLT 11

Anna is buying an ebook. Instead of bank details, the shop displays a Lightning invoice, which her wallet reads. She need not understand the long string: before confirming, she checks the amount, purpose and fee. Some invoices leave the amount open, for example for a voluntary contribution. The payer then enters it; an omitted amount does not mean a zero payment. For the curious, the prefix lnbc identifies the main network; lntb identifies testnet, lntbs signet and lnbcrt regtest, which are testing environments. The encoded amount is in BTC with an optional m, u, n or p multiplier, not directly in satoshi. With p it must end in 0 to represent whole millisatoshi: 1000 msat = 1 sat. [1]

The description connects the technical request to a human purpose, such as Anna’s book. An invoice contains either the text itself in field d or its digital fingerprint in field h. That fingerprint is calculated with SHA256; the wallet must check that a separately supplied description produces the same result. This short checking value calculated from the text is called a hash. The fingerprint alone does not tell you what was ordered. A valid signature binds the description to the recipient’s key, but does not promise that the seller will deliver the book. Application developers have another responsibility: a description is untrusted text to display safely as data, never to execute as code. [1]

Anna leaves her order open and returns later. Her wallet may report that the invoice has expired; she should then request a new one. Expiry is calculated from the creation timestamp and duration x. If x is absent, the default is 3600 seconds, or an hour. Expiry does not reverse a completed payment. Field c, technically min_final_cltv_expiry_delta, serves a different purpose: it sets a time margin for the final conditional payment, an HTLC, on the route. An HTLC makes settlement conditional on providing the right secret in time. This margin is measured in blocks, not invoice-validity seconds; without c, the payer uses at least 18 blocks. These two time settings must not be confused. [1]

A Lightning payment travels through payment channels. Within a channel, two parties keep updating how funds are divided without recording every ordinary payment on the main Bitcoin blockchain. Success requires a usable route and enough funds on the appropriate sides of its channels: liquidity. Field r can supply routing hints for the final stretch. These help find the recipient, but are not a live report of available capacity. They can also reveal public node keys, channel identifiers and fee parameters, so do not treat the full invoice as private. Optional field f may offer a regular Bitcoin address as a fallback. Paying it uses the main chain, has its own fees and requires confirmations. It is not simply another button for the same delivery method. [1] [2] [5]

A scanned QR code or a received invoice is not a receipt. After sending, check the wallet’s outcome: pending differs from complete. Successful settlement is also evidenced by the correct preimage, a secret value whose hash must match the payment hash in the invoice. Keep the invoice and that value as payment evidence, not as a guarantee that goods were delivered. If the app disconnects or loses the response, first check the original payment’s status. Immediately requesting a new invoice or using the fallback address can mean paying again. Some wallets recognize repeated attempts, but the format itself provides no universal protection across applications and payment methods. [2] [4]

The long string uses Bech32 encoding. Its checksum helps detect transcription mistakes; it is not encryption and does not hide the contents. The ECDSA digital signature on secp256k1 has a different job: it verifies that the payment details correspond to the recipient’s key and have not subsequently changed. It does not verify the legal identity or honesty of the person behind that key. Unlike Bitcoin Bech32 addresses, BOLT 11 may exceed 90 characters. Uppercase works well for QR codes, but a valid string must not mix upper and lower case. People generally scan or copy the invoice while their wallet performs these checks. [1]

The payment hash is the digital fingerprint of a secret payment preimage, calculated with SHA256 and stored in field p. On successful settlement the payer learns the preimage and can check that its fingerprint matches. Field s instead contains payment_secret. The payer already reads this value from the invoice and passes it to the recipient in the final part of the routed payment; it helps protect the recipient against probing by forwarding nodes. Secret is neither the preimage nor the wallet seed. Reading it from a QR code is therefore neither proof of payment nor a way to restore the wallet. Current BOLT 11 requires both p and s. Similar names conceal distinct jobs: identifying a payment, supplying a required value and evidencing settlement. [1] [2]

Wallets also need to know whether they support the requested payment. Field 9 carries feature flags. An unknown even bit denotes a mandatory feature and requires refusing the payment; an unknown odd bit is optional and can be ignored. Known dependencies between features must also be satisfied. Basic MPP, for example, splits one payment into parts that are combined at the recipient. It can be used only when the invoice offers basic_mpp. Splitting does not create several independent invoices or a reason to pay each part again. For a beginner, the practical lesson is simple: do not work around an unsupported-feature message by manually editing the invoice; resolve wallet compatibility first. [1] [3]