Bolt12

---
name: lightning-bolt12
description: |
  BOLT12 offers: reusable invoices, blinded paths, recurring payments,
  multi-asset (Taproot Assets layered). Replaces BOLT11 for many use
  cases.
  USE WHEN: implementing/integrating offers, designing recurring
  payments, evaluating BOLT11 vs BOLT12 trade-offs.
allowed-tools: Read, Grep, Glob
---

# 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

1. **Offer** (`lno1...`) — long-lived, signed by recipient. Encodes:
   - Description, amount (or "any"), expiry (or none).
   - Issuer pubkey (potentially blinded).
   - Allowed currencies / quantities.
2. **Invoice request** (`lnr1...`) — payer sends via onion message,
   asks for an invoice for this offer.
3. **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.

## Handing out an offer: BIP 353 and bLIP-42

An `lno1...` string is too long to read aloud or type. Two specs
turn it into a human-readable identity; a third identifies the
payer instead:

- **BIP 353 "DNS Payment Instructions"** — status `Complete` in the
  BIPs repo as of September 2026. Publishes a BIP 21 URI, usually
  just `bitcoin:?lno=<offer>`, in a DNSSEC-signed TXT record at
  `<user>.user._bitcoin-payment.<domain>`, displayed as
  `₿user@domain`. No HTTP endpoint in the path, unlike LNURL-pay
  / LUD-16; see the `lightning-address` skill.
- **bLIP-32 "Onion Message DNS Resolution"** — status `Active` in
  `lightning/blips` as of September 2026. Lets a client that cannot
  validate DNSSEC itself ask a node over onion messages:
  `dnssec_query` (type 65536) → `dnssec_proof` (65538), or
  `dnssec_error` (65550).
- **bLIP-42 "Bolt 12 Contacts"** (Bastien Teinturier, created
  2024-07-19) — status `Active` in `lightning/blips` as of September
  2026. Adds optional `invoice_request` TLVs that let a payment
  identify its payer: `invreq_contact_secret` (2000001729), plus
  either `invreq_payer_offer` (2000001731) or
  `invreq_payer_bip_353_name` (2000001733) with
  `invreq_payer_bip_353_signature` (2000001735) proving control of
  the offer behind that name. The recipient can then add the payer
  as a contact and pay them back with no extra round trip.

## 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_messages` feature
  bit) → can't fetch invoice request response.
- Under bLIP-42, accepting `invreq_payer_offer` /
  `invreq_payer_bip_353_name` from a payer you already hold a
  `contact_secret` for → the spec says ignore them for known
  contacts, so a leaked secret can't redirect your future payments
  to an impostor's offer.

## See also

- [bolts/SKILL.md](../bolts/SKILL.md)
- [onion/SKILL.md](../onion/SKILL.md)
- [lnurl/SKILL.md](../lnurl/SKILL.md)
- [lightning-address/SKILL.md](../lightning-address/SKILL.md)
- [../../l2/taproot-assets/SKILL.md](../../l2/taproot-assets/SKILL.md)