Introduction
Reading BOLT 11 invoices requires understanding a compact, bech32-encoded string that carries payment instructions on the Lightning Network. This guide decodes every component so you can create, validate, and process Lightning invoices without guesswork. Understanding this protocol prevents payment failures and ensures compatibility across wallets and nodes.
Key Takeaways
BOLT 11 is the Lightning Network invoice standard defined in Basis of Lightning Technology proposal 11. The human-readable prefix “lnbc” identifies Bitcoin Lightning invoices. Each field encodes amount, timestamp, payment hash, and routing hints in a QR-scannable format. This protocol replaced legacy Bitcoin payment requests with HTLC-backed atomic swaps.
What is BOLT 11
BOLT 11 defines the invoice protocol for Bitcoin Lightning payments, encoding all necessary data into a single URI string. The format uses bech32 encoding for error correction and QR-code optimization. Each invoice contains a payment hash that locks funds until the preimage is revealed. The specification ensures interoperability between all Lightning implementations.
Why BOLT 11 Matters
Lightning payments require precise instruction encoding because transactions are atomic and irreversible. BOLT 11 eliminates ambiguity in payment amounts, expiry times, and routing information. Without a standardized format, wallet interoperability would break at scale. The protocol’s compact design makes it suitable for mobile wallets and offline payment scenarios.
How BOLT 11 Works
The invoice string follows this structure: lnbc[amount][unit]@[timestamp]/[expiry]/[features]?[route hints]. The “lnbc” prefix identifies the currency and network. The amount field uses millisatoshi precision for microtransactions. Timestamp determines invoice creation time; expiry defines the payment window.
The data fields break down as follows:
Field Format: [field]=value
Signature Component: The final 104 characters contain the signature derived from the node’s private key. The network verifies this signature before accepting payment. This prevents invoice forgery and ensures only the intended recipient can claim funds.
Payment Hash: Generated by the receiver using HMAC-SHA256. The payer cannot determine the preimage, ensuring security. The hash commits to specific payment conditions defined in the invoice.
Used in Practice
Lightning wallets generate invoices through their backend node’s API. When scanning a QR code, the wallet parses the bech32 string and extracts routing hints. The payer validates the signature against known node public keys before initiating payment. HTLCs (Hashed Time-Locked Contracts) secure the transaction across multiple hops.
Merchants integrate BOLT 11 generation via libraries like Lightning Dev Kit. Dynamic invoices can include descriptions, fallback addresses, and custom expiry times. The Lightning Network relies on this protocol for all peer-to-peer settlements.
Risks / Limitations
BOLT 11 invoices expire after a configurable window, typically one hour. Expired invoices cannot be paid, requiring regeneration. The protocol does not support recurring payments or refund paths natively. Large invoices may exceed QR code scanner limits, requiring copy-paste or LNURL alternatives.
The signature scheme assumes honest node behavior during invoice creation. Correlated payment hashes across multiple invoices can expose receiver public keys. Privacy-conscious users should generate fresh invoices for each transaction.
BOLT 11 vs BOLT 12
BOLT 11 requires manual invoice generation for each payment, creating friction for recurring merchants. BOLT 12 introduces offer codes that function like standing orders, allowing payers to request invoices on demand. BOLT 11 remains the dominant format for point-of-sale transactions due to simplicity.
BOLT 12 adds offer encoding with blinded paths for improved privacy. The newer standard supports refunds without manual address exchange. Transitioning to BOLT 12 requires wallet updates across the Lightning ecosystem.
What to Watch
LNURL authentication and Lightning Address resolution are replacing manual invoice sharing. Watch for blockchain fee spikes affecting HTLC dust limits. Node operators must maintain updated gossip protocols for proper invoice routing.
The Taproot upgrade improves Lightning channel efficiency and reduces transaction costs. Watch Lightning Service Provider (LSP) integrations that abstract BOLT 11 complexity from end users.
FAQ
What does the “lnbc” prefix mean in BOLT 11?
The prefix “lnbc” stands for Lightning Bitcoin (mainnet). “lntbc” indicates testnet invoices. The following characters encode the amount in satoshis with optional unit suffixes like “m” for milli or “u” for micro.
Can I pay a BOLT 11 invoice twice?
No, each invoice contains a unique payment hash. Once paid, the preimage is exposed and the HTLC resolves. Any subsequent payment attempt fails because the hash has been spent.
How long is a BOLT 11 invoice valid?
The expiry field determines validity, typically set by the receiver. Standard wallets use 3600 seconds (one hour). After expiry, the invoice cannot be paid and must be regenerated.
What happens if my QR code scanner misses characters?
Bech32 encoding provides error detection. Scanners automatically reject malformed strings. If partial data is scanned, the wallet displays an error prompting re-scanning or manual entry.
Does BOLT 11 support fiat currency amounts?
Some wallets include a currency conversion field using the “c” parameter. This references exchange rate data but requires trust in the provider. The protocol itself only handles satoshi amounts.
How do I verify a BOLT 11 invoice signature?
Wallets extract the signature and public key from the invoice string. They verify the signature against the invoice data using the node’s claimed public key. Failed verification prevents payment initiation.
Can I create offline BOLT 11 invoices?
Hardware wallets can generate invoices without internet connectivity if they store the necessary private key. The signed invoice can be displayed as a QR code for scanning by any connected payer.
Leave a Reply