Cowrie Research

bolt-12-primary-sources-2026-05-02

3 min read

BOLT 12 primary sources — 2026-05-02

Project status in this pass

  • No separate standalone whitepaper or litepaper surfaced.
  • The clearest current source of truth is the canonical BOLT 12 spec in the lightning/bolts repository, plus the community-facing bolt12.org explainer and developer pages.
  • The materials consistently frame BOLT 12 as reusable Lightning payment-request infrastructure centered on offers, invoice requests, invoices, refunds, and privacy-preserving request delivery.

Primary-source snapshots

1) Canonical specification: 12-offer-encoding.md

  • URL: https://raw.githubusercontent.com/lightning/bolts/master/12-offer-encoding.md
  • Key excerpt:
    • The document is titled BOLT #12: Negotiation Protocol for Lightning Payments.
    • Its opening section explicitly lists “Limitations of BOLT 11,” including one-time invoices, awkward extensibility, and privacy limitations.
    • It defines the core user-pays-merchant flow as merchant publishes an offer → user sends invoice request → merchant replies with invoice → user pays.
    • It also defines a merchant-pays-user flow for refunds or ATM-style interactions.
    • The text highlights payer proofs, selective disclosure, route blinding, onion-message delivery, reusable offers, and a compact encoding designed to fit QR-code use.

2) BOLT repository root / README

  • URL: https://raw.githubusercontent.com/lightning/bolts/master/README.md
  • Key excerpt:
    • The repository presents itself as the Lightning Network’s in-progress specifications and the table of contents for the canonical specs corpus.
    • This matters because it confirms the spec repo, not a product page, is the normative source of truth for BOLT 12.

3) Community explainer site

  • URL: https://bolt12.org/
  • Key excerpt:
    • The site highlights reusable payment requests, receiver privacy, social integration, auto-withdrawals, and censorship resistance as the practical reasons BOLT 12 matters.
    • It also lists real implementations and integrations across wallets, SDKs, nodes, and services, helping show BOLT 12 is becoming ecosystem infrastructure rather than a purely theoretical draft.

4) Developer page

  • URL: https://bolt12.org/developers
  • Key excerpt:
    • The developer page says Core Lightning can use BOLT 12 with experimental offers flags enabled.
    • It says Eclair supports payoffer and tip-jar offer generation.
    • It says Lightning Dev Kit supports creating and paying offers.
    • It notes that LND does not natively support BOLT 12 yet, but LNDK can be run alongside LND to experiment with it.

Working conclusion

BOLT 12 is best cataloged as Lightning payment negotiation infrastructure: a reusable-offer and invoice-request standard that expands Lightning beyond one-shot BOLT 11 invoices into a broader messaging layer for tips, merchant checkout, refunds, social-payment identifiers, and privacy-preserving payment requests. The key evidence in this pass was the canonical spec’s explicit merchant offer → invoice request → invoice flow, the built-in refund/merchant-pays-user path, and the ecosystem site’s list of concrete wallet and node implementations.

Graph View