claude-dev-suite BOLT12 Offers
BOLT12 is a flexible payment protocol that addresses BOLT11's limitations:
- BOLT11 invoices are single-use and expire.
- BOLT11 reveals destination pubkey.
- BOLT11 has no built-in support for recurring payments or refunds.
BOLT12 offers a static, reusable identifier (the "offer") that lets payers fetch a fresh invoice each payment via Lightning's onion message system.
Three message types
- Offer (
lno1...) — long-lived, signed by recipient. Encodes:- Description, amount (or "any"), expiry (or none).
- Issuer pubkey (potentially blinded).
- Allowed currencies / quantities.
- Invoice request (
lnr1...) — payer sends via onion message, asks for an invoice for this offer. - Invoice (
lni1...) — receiver responds with one-time invoice. Standard payment proceeds.
Bech32 encoding
All three types use the BOLT11-style bech32 encoding with lno1,
lnr1, lni1 prefixes (no chain prefix; chain encoded in TLV).
TLV-only
Unlike BOLT11's tag/data tuples, BOLT12 uses pure TLV everywhere. Future-proof; new fields don't break old parsers.
Blinded paths
Offers can include blinded paths — partial routes that hide the recipient's node id. The offer is signed by an "introduction node" + blinded route data; recipient is anonymous to the payer.
Recurring payments
Offers can specify recurrence:
quantity_min: 1, quantity_max: 100
recurrence: monthly for 12 months
Same offer used for subscription: payer fetches a fresh invoice each month.
Multi-asset (Taproot Assets layered)
BOLT12 + Taproot Assets together enable invoices priced in non-BTC assets routed over LN. Recipient gets BTC amounts; payer pays in asset terms; intermediate hops handle conversion.
Use cases vs BOLT11
| Use case | BOLT11 | BOLT12 |
|---|---|---|
| One-time payment with known amount | yes | yes |
| Static "donate to me" QR code | hacky (LNURL-pay) | native |
| Recurring subscription | manual | native |
| Refund flow | no | yes |
| Hidden destination | no | yes (blinded paths) |
| Multi-asset | no (need TAP/RGB) | yes |
Implementation status (late 2025)
| Implementation | Send | Receive | Recurring |
|---|---|---|---|
| CLN | yes | yes | yes |
| LDK | yes | yes | partial |
| LND | partial | partial | no |
| Eclair | yes | yes | partial |
| phoenixd | yes (receive especially) | yes | partial |
Common bugs
- Treating
lno1...as a single-use invoice → it's not, can be reused. - Failing to fetch invoice via onion message → expecting BOLT11 flow.
- Caching invoice from offer → invoices are one-shot; fetch fresh each payment.
- Missing onion-message support (
option_onion_messagesfeature bit) → can't fetch invoice request response.