---

name: lightning-bolts description: | BOLT (Basis of Lightning Technology) specification index. Wire format, channel management, onion routing, gossip, invoices, feature bits. Quick refs: BOLT-by-BOLT summary, message-type tables, feature-bit registry. USE WHEN: implementing/reading Lightning protocol, looking up message types, debugging interop between implementations. allowed-tools: Read, Grep, Glob

Lightning BOLTs

Quick refs: bolt-summary.md, feature-bits.md

The Lightning Network's specs live in github.com/lightning/bolts. There are 11 numbered BOLTs plus several "BLIPs" (BOLT improvement proposals) for in-progress extensions.

BOLT Index

BOLT	Title
1	Base Protocol — wire format, init, ping, error
2	Peer Protocol — channel open/close/update
3	Bitcoin Transaction and Script Formats — funding, commitment, HTLC, anchor
4	Onion Routing Protocol — Sphinx packet, payment forwarding
5	Recommendations for On-chain Transaction Handling
7	P2P Node and Channel Discovery — gossip
8	Encrypted and Authenticated Transport — Noise XK handshake
9	Assigned Feature Flags — feature bit registry
10	DNS Bootstrap and Assisted Node Location (deprecated)
11	Invoice Protocol — BOLT11
12	Flexible Protocol for Lightning Payments — BOLT12 offers

Concepts spread across BOLTs

• Channels (BOLT 2/3): two-party state channel with on-chain funding output spent into a sequence of off-chain commitment txs.
• HTLCs (BOLT 2/3/4): hash-time-locked contracts route payments across multiple channels atomically.
• Onion routing (BOLT 4): Sphinx-style; each hop sees only the next hop, not source / destination.
• Gossip (BOLT 7): nodes announce themselves and channels; pathfinders use this graph.
• Wire encryption (BOLT 8): Noise_XK handshake; ChaCha20-Poly1305 per-message.

Versioning

Lightning's wire protocol is append-only with feature bits:

• Init message exchanges feature bits.
• New features negotiated, not breaking changes.
• Implementations must gracefully degrade for unknown bits.

Major recent additions

Merge dates below are commits on lightning/bolts master, read at repo HEAD 1528972 (2026-08-26) in September 2026.

• Anchor outputs (BOLT-3 update, ~2020). Superseded: on 2024-05-20 BOLT 9 deleted legacy option_anchor_outputs (20/21) and renamed the zero-fee-HTLC variant at 22/23 to option_anchors.
• Dual-funded channels (BOLT 2 v2, ~2022), feature 28/29.
• option_simple_close (60/61) — simplified closing negotiation via closing_complete / closing_sig, merged 2025-02-12.
• Attribution data (36/37) — BOLT 4 per-hop attribution on update_fail_htlc / update_fulfill_htlc, merged 2025-11-14; fulfillment_payload added 2026-07-27 (#1344) and return fields capped at 32 KiB 2026-08-26 (#1349).
• Splicing (62/63) — merged into BOLT 2/9 on 2026-03-23 (#1160), so it is now spec, not a proposal.
• Zero-fee commitments (40/41) — commitment and HTLC transactions with no fee, using v3/TRUC transactions and a shared anchor; merged 2026-05-04 (#1228).
• Simple taproot channels (80/81) — merged 2026-05-04 as the extension BOLT bolt-simple-taproot.md (#995), outside the numbered BOLTs; a staging variant sits at 180/181.
• BOLT 12 payer proofs — merged 2026-07-27 (#1346), letting a payer prove after the fact that it paid a given offer.
• option_onion_messages_only_channels (66/67) — accept onion messages only from peers you have a channel with; merged 2026-07-27 (#1343).
• BOLT12 (offers, blinded paths) — shipped by CLN (v26.06, 2026-06-02 exposes offer_id on invoice notifications and a createproof RPC for BOLT 12 payer proofs). LND carries BOLT 12 code but its release notes through v0.21 announce no offers support as of September 2026.
• Async payments — an often-offline recipient publishes a BOLT 12 static invoice (an offer-derived invoice with the payment hash deliberately omitted) with an always-online LSP acting as static invoice server; the payer reaches it over onion messages, and the sender's LSP holds the HTLC until the recipient wakes. No custodian and no long-lived HTLC parked across the route. LDK is the implementation: ldk-node v0.7.0 (2025-12-03) added serving and paying static invoices, and LDK's "Async Payments: Getting Paid While Your Node Is Offline" (2026-06-26) still labels it beta — the sender-side HTLC hold is unmerged and the flow is LDK-to-LDK only. It is unrelated to trampoline routing.

Implementations and feature support

Feature	LND	CLN	LDK	Eclair
Static channels (legacy)	yes	yes	yes	no
Anchor commitment	yes	yes	yes	yes
Dual-funded	no	yes	partial	yes
MPP / AMP	yes	yes	yes	yes
Trampoline	no	no	partial	yes
BOLT12 offers	partial	yes	yes	yes
Taproot channels (80/81)	yes	no	no	yes
Splicing	no	yes	yes	yes

(Status as of September 2026. Each column was read off the project's own feature registry on master — lnwire/features.go (lnd v0.21.3-beta, 2026-09-02), common/features.c (CLN v26.06.7, 2026-08-28), lightning-types/src/features.rs (rust-lightning v0.2.6, 2026-09-09) and Features.scala (Eclair v0.14.3, 2026-09-14) — plus ldk-node v0.7.0 for what LDK ships end to end. Notes on individual rows: lnd defines no option_dual_fund (28/29) bit at all, so it has no dual funding, while LDK gates its own behind enable_dual_funded_channels; Eclair v0.14.0 removed support for non-anchor channels; trampoline is still an unmerged BOLTs proposal, PR #836 (bits 56/57), with rust-lightning defining Trampoline at those bits and handling receives (#3670, merged 2025-03-28), Eclair advertising only its own pre-spec trampoline_payment_prototype at 148/149, and neither lnd nor CLN defining any trampoline bit; lnd v0.21.0 (2026-06-05) shipped production simple taproot channels at bits 80/81 and describes splice work as groundwork only — v0.21.3-beta defines no option_splice (62/63) bit and exposes no splice RPC; CLN lists OPT_SPLICE (62) and enabled splicing by default in v26.04 (2026-04-20) but has no taproot option; rust-lightning has shipped splicing since v0.2 (2025-12-03), with SplicePrototype realigned onto bit 63 in v0.2.2 (2026-02-06) to match Eclair; LDK's only Taproot feature is bit 31 option_taproot, not simple taproot channels. Check current docs for latest.)

Test vectors

Lightning has test vector files (bolt03-tx-test-vectors.json, bolt04-onion-test-vectors.json, etc.) that all impls verify against. Used as part of CI.

Reading order

For new implementers:

1. BOLT 1 — message framing.
2. BOLT 8 — encryption.
3. BOLT 2 — channel state machine.
4. BOLT 3 — funding, commitment, HTLC scripts.
5. BOLT 4 — onion routing.
6. BOLT 7 — gossip.
7. BOLT 11 / 12 — invoices / offers.

See also

• channels/SKILL.md
• htlcs/SKILL.md
• routing/SKILL.md
• onion/SKILL.md