BOLT-12 Offers

What Are BOLT-12 Offers?

BOLT-12 offers are a proposed upgrade to the Lightning Network's payment request system, defined in the BOLT specification process. Where traditional BOLT-11 invoices are single-use, expire quickly, and must be generated fresh for every payment, BOLT-12 introduces a persistent "offer" that acts as a reusable payment endpoint. Anyone with the offer can request a fresh invoice from the recipient at any time, without the recipient needing to be online at the moment the offer is shared.

Think of the difference like this: a BOLT-11 invoice is a one-time payment slip that expires, while a BOLT-12 offer is more like a permanent payment address. The offer itself doesn't contain a payment hash or amount: those are negotiated in real time when a sender decides to pay. This makes offers suitable for printing on a business card, embedding in a website, or encoding in a static QR code.

BOLT-12 was proposed by Rusty Russell of Blockstream and builds on the onion message system introduced alongside it. The specification aims to solve several long-standing usability and privacy problems with BOLT-11 invoices while remaining backward-compatible with the existing Lightning routing infrastructure.

How It Works

BOLT-12 introduces a multi-step protocol between sender and receiver that replaces the simple "generate invoice, share invoice, pay invoice" flow of BOLT-11. The interaction uses onion messages, which are routed through the Lightning Network like payments but carry data instead of funds.

The Offer-Invoice Flow

When a sender wants to pay a BOLT-12 offer, the following sequence occurs:

1. The recipient publishes an offer containing their node ID (or a blinded path to reach them), a description, optional amount constraints, and optional metadata such as currency or quantity limits
2. The sender decodes the offer and constructs an invoice_request onion message containing the amount they wish to pay, a payer key for identification, and any required fields
3. The sender routes this invoice_request to the recipient via the Lightning Network's onion message system, either directly or through the blinded path specified in the offer
4. The recipient validates the request, generates a fresh invoice with a unique payment hash, signs it, and sends it back to the sender via a reply onion message
5. The sender verifies the invoice signature matches the offer's node key, then pays the invoice using standard Lightning payment routing with HTLCs

Offer Encoding

BOLT-12 offers use a TLV (type-length-value) encoding scheme rather than the bech32-based format of BOLT-11. Offers are encoded with the lno prefix (lightning-node-offer), while invoices use lni and invoice requests use lnr. The TLV format is more extensible, allowing new fields to be added without breaking existing parsers.

# BOLT-12 offer (human-readable prefix: lno)
lno1qgsqvgjwmejk6gn0dskc6gr0v9eqzsyzy...

# Key fields in an offer TLV:
# - offer_id: unique identifier
# - description: what the payment is for
# - node_id: recipient's public key (or omitted if using blinded paths)
# - amount: optional fixed or minimum amount
# - paths: blinded paths to reach the recipient

Blinded Paths for Privacy

One of the most significant features of BOLT-12 is its integration with blinded paths. In BOLT-11, a recipient behind unannounced channels must include route hints that expose their channel partners and effectively reveal their node's position in the network graph. This is a fundamental privacy leak.

BOLT-12 offers can instead specify blinded paths: encrypted routing instructions where only the introduction node (the first hop in the path) is visible to the sender. The remaining hops are encrypted so that neither the sender nor intermediate nodes learn the recipient's true identity or channel structure. The recipient can rotate blinded paths regularly, and can include multiple paths for redundancy.

Payer Proofs and Refunds

Each invoice_request includes a payer_key: a cryptographic identifier chosen by the sender. This key serves as a proof-of-payment credential that the sender can later use to request refunds. The recipient can issue a refund by creating a new offer specifically for that payer_key, ensuring only the original sender can claim the returned funds.

This mechanism also enables recurring payments. A sender can include a recurrence field in their invoice_request, and the recipient can issue invoices on a schedule (daily, weekly, monthly) using the payer_key to identify the subscriber.

BOLT-12 vs. BOLT-11

The differences between BOLT-11 and BOLT-12 are significant across multiple dimensions. For a deeper look at how Lightning specifications evolve, see the Lightning Network liquidity deep dive.

Developer Experience

For developers, BOLT-12 simplifies several common workflows. With BOLT-11, accepting payments requires running a server that generates fresh invoices on demand and delivers them to payers through a separate communication channel (HTTP API, WebSocket, etc.). This means every Lightning-accepting service needs both a Lightning node and a web server.

With BOLT-12, a merchant can publish a single offer and let the Lightning protocol handle invoice generation and delivery. The offer can be encoded in a static QR code, printed on packaging, or embedded in a webpage. When a customer scans the offer, their wallet communicates directly with the merchant's node via onion messages to fetch a fresh invoice: no HTTP API required.

# BOLT-11 flow (developer must build):
# 1. Customer visits website
# 2. Backend calls LN node: createInvoice(amount)
# 3. Backend returns invoice to frontend
# 4. Customer pays invoice
# 5. Backend polls for settlement

# BOLT-12 flow (protocol handles it):
# 1. Merchant publishes offer (once)
# 2. Customer wallet fetches invoice via onion message
# 3. Customer pays invoice
# 4. Node receives settlement directly

Use Cases

Static Payment Endpoints

Content creators, merchants, and open-source projects can publish a single offer that works indefinitely. Unlike BOLT-11 invoices that expire (typically within an hour), an offer remains valid until the recipient revokes it. This is analogous to a Bitcoin address but with the speed and cost advantages of Lightning payments, and without the address-reuse privacy concerns of on-chain transactions.

Recurring Payments and Subscriptions

BOLT-12's recurrence fields allow wallets to automate periodic payments. A podcast listener can subscribe to a creator by paying a BOLT-12 offer with recurrence metadata, and their wallet will automatically request and pay invoices on the specified schedule. The creator's node handles each invoice request independently, and either party can terminate the arrangement.

Point-of-Sale and Vending

Physical merchants and vending machines benefit from static QR codes that never expire. A coffee shop can print a BOLT-12 offer QR code at the counter. Each customer scans the same code, but their wallet negotiates a unique invoice with the correct amount. This eliminates the need for a screen displaying dynamic invoices and reduces the hardware requirements for Lightning-enabled point-of-sale systems.

Privacy-Preserving Donations

Organizations accepting donations can use BOLT-12 offers with blinded paths to receive funds without revealing their node's network position. This is particularly relevant for organizations operating in hostile jurisdictions or accepting politically sensitive contributions. Combined with onion routing for payment delivery, both sender and receiver can maintain strong privacy guarantees.

Implementation Status

BOLT-12 support varies across Lightning implementations:

• Core Lightning (CLN): the most mature implementation, with offer creation, payment, and fetchinvoice support available since v0.12. CLN was the first major node to ship production-ready BOLT-12 support
• LDK (Lightning Dev Kit): supports BOLT-12 offers, onion messages, and blinded paths. Wallets building on LDK (including several mobile wallets) can leverage BOLT-12 without implementing the protocol from scratch
• LND: experimental BOLT-12 support is in development. LND has historically focused on BOLT-11 and keysend payments, but work on onion message handling and offer support is progressing
• Eclair: supports BOLT-12 offers and onion messages, with ACINQ integrating the feature into their Phoenix wallet for mobile users

The uneven rollout means that interoperability between nodes can be inconsistent. A CLN node can serve offers to an LDK-based wallet, but an LND node may not yet handle incoming invoice_request messages. As adoption grows, cross-implementation compatibility is expected to improve. For context on how protocol upgrades propagate through the Lightning ecosystem, see the Taproot and Schnorr signatures deep dive, which covers a similar adoption dynamic for on-chain upgrades.

Risks and Considerations

Onion Message Reliability

BOLT-12's offer-invoice flow depends on onion messages, which are best-effort and not guaranteed to be delivered. Unlike HTLC-based payments where nodes are economically incentivized to forward (they earn routing fees), onion messages carry no fees and nodes can drop them without penalty. In a congested network, invoice_request or invoice messages could fail silently, leaving the sender with no response and no clear error.

Spam and Denial of Service

Reusable offers create a new attack surface: an attacker can send thousands of invoice_request messages to a recipient, forcing their node to generate and sign invoices that will never be paid. While each invoice is cheap to generate, the computational cost adds up at scale. Rate limiting and proof-of-work requirements for invoice requests are potential mitigations, but no standard approach has been finalized.

Adoption Fragmentation

Because BOLT-12 is not yet universally supported, wallets and services that adopt it early may find their offers unusable by a significant portion of the network. This creates a chicken-and-egg problem: widespread adoption requires broad implementation support, but implementations prioritize features that users demand. In the interim, many services will need to support both BOLT-11 and BOLT-12 payment flows, increasing complexity.

Blinded Path Tradeoffs

While blinded paths improve privacy, they add routing overhead. Each blinded path specifies a fixed route from the introduction node to the recipient, which may not be the most efficient path from the sender's perspective. If the introduction node goes offline, the entire blinded path becomes unusable. Recipients should include multiple blinded paths in their offers for redundancy, but this increases the offer's size and scanning time for QR codes.

No Offline Receiving

Despite the static nature of offers, the recipient must be online when the sender requests an invoice. The offer itself is just a pointer: the actual invoice is generated dynamically by the recipient's node. If the recipient's node is down when a customer scans the offer, the payment flow fails. This is a meaningful limitation compared to on-chain Bitcoin addresses, which can receive payments regardless of the recipient's online status. Solutions like trampoline routing and LSP-mediated invoice generation could help address this in future protocol iterations.

This glossary entry is for informational purposes only and does not constitute financial or investment advice. Always do your own research before using any protocol or technology.