BOLT Specifications

What Are the BOLT Specifications?

The BOLT specifications are a set of technical documents that define the Lightning Network protocol. BOLT stands for Basis of Lightning Technology: a reference to the lightning bolt imagery associated with the network. Each BOLT document covers a specific aspect of the protocol, from how nodes establish connections to how payments are routed across multiple hops.

Lightning Network has multiple independent implementations: LND (Lightning Labs), Core Lightning (Blockstream), Eclair (ACINQ), and LDK (Spiral). For a user running LND to send a payment to a merchant running Eclair, both implementations must speak the same protocol. The BOLTs provide that shared language. Without them, the Lightning Network would fragment into incompatible silos.

The specifications are maintained in a public GitHub repository and are authored collaboratively by developers from all major implementations. They serve as both the canonical protocol reference and the arena where protocol changes are debated and formalized.

How It Works

The BOLT specifications are organized by protocol layer. Each document defines message formats, state machines, cryptographic requirements, and expected behaviors for a specific aspect of the Lightning protocol. Implementations that conform to these specifications can interoperate regardless of their programming language or internal architecture.

BOLT 1: Base Protocol

BOLT 1 defines the foundation of Lightning peer-to-peer communication. It specifies the message framing format, the transport encryption layer (based on the Noise protocol framework), and the mandatory feature bit negotiation that occurs when two nodes connect.

Every Lightning message follows a standardized structure: a 2-byte type identifier followed by a variable-length payload. BOLT 1 also defines the init message, which nodes exchange upon connecting to advertise supported features.

// Lightning message format (BOLT 1)
+--------+----------+
| 2-byte |  payload |
|  type   | (variable|
|         |  length) |
+--------+----------+

// Example: init message (type 16)
type: 16
globalfeatures: <variable>
features: <variable>
tlv_stream: [networks, remote_addr]

BOLT 2: Peer Protocol for Channel Management

BOLT 2 specifies the messages and state transitions for the entire lifecycle of a payment channel: opening, operating, and closing. It defines how two peers negotiate channel parameters, exchange funding transactions, commit to new channel states via HTLCs, and cooperatively or unilaterally close a channel.

Key messages defined in BOLT 2 include open_channel, accept_channel, funding_created, commitment_signed, revoke_and_ack, and shutdown. The specification also defines channel reserve requirements and anchor output negotiation.

BOLT 3: Bitcoin Transaction and Script Formats

BOLT 3 defines the exact Bitcoin transaction structures that underpin Lightning channels. This includes the funding transaction, commitment transactions, HTLC-success and HTLC-timeout transactions, and the justice transactions used to punish protocol violations.

Every output script, witness structure, and transaction field is specified precisely so that all implementations construct identical transactions given the same channel state. This is critical: both channel counterparties must agree on the commitment transaction byte-for-byte to produce valid signatures.

# Commitment transaction structure (simplified, BOLT 3)
# Outputs:
#   to_local: delayed payment to channel owner
#     (revocable via revocation_key)
#   to_remote: immediate payment to counterparty
#   htlc_offered: outgoing HTLC outputs
#   htlc_received: incoming HTLC outputs
#   anchor (if negotiated): fee-bumping anchor outputs

OP_IF
    <revocationpubkey>
OP_ELSE
    <to_self_delay>
    OP_CHECKSEQUENCEVERIFY
    OP_DROP
    <local_delayedpubkey>
OP_ENDIF
OP_CHECKSIG

BOLT 4: Onion Routing Protocol

BOLT 4 specifies the onion routing protocol that provides payment privacy on Lightning. When a sender creates a payment, they construct a layered encryption packet (the "onion") where each routing node can only decrypt its own layer, revealing the next hop but nothing about the full path.

The protocol uses Sphinx-based onion encryption. Each hop peels one layer, reads its forwarding instructions, and passes the remaining onion to the next node. No intermediate node learns who the sender is, who the final recipient is, or how many hops remain. This is the same approach that makes trampoline payments possible.

BOLT 5: Recommendations for On-chain Transaction Handling

BOLT 5 provides guidance for how implementations should handle on-chain transactions when channels close unexpectedly. It covers fee estimation strategies, HTLC resolution procedures, and the logic for watchtower monitoring. When a counterparty broadcasts a revoked commitment, BOLT 5 describes how to construct and broadcast the justice transaction to claim the penalty funds.

BOLT 7: P2P Node and Channel Discovery

BOLT 7 defines the gossip protocol that allows nodes to discover each other and build a map of the network. Nodes broadcast channel_announcement messages when new channels are funded on-chain and channel_update messages to advertise routing fees and policies. node_announcement messages let nodes share their alias, color, and connection addresses.

This gossip layer is what enables pathfinding. When you send a Lightning payment, your node uses the BOLT 7 network graph to calculate a route. Nodes that want private channels can skip gossip announcements and instead use route hints in invoices to share channel information directly with the payer.

BOLT 8: Encrypted and Authenticated Transport

BOLT 8 specifies the transport layer encryption using the Noise_XK handshake pattern. Every Lightning peer connection is authenticated (you know who you're talking to via their node public key) and encrypted (no eavesdropper can read the messages). The protocol uses ChaCha20-Poly1305 for symmetric encryption after the handshake completes.

BOLT 9: Assigned Feature Flags

BOLT 9 maintains the registry of feature flags that nodes use to signal protocol support. Each feature has an odd/even bit convention: even bits indicate required features (if your peer doesn't support it, disconnect), while odd bits indicate optional features (nice to have, but not mandatory). This mechanism allows the protocol to evolve without breaking backward compatibility.

BOLT 11: Invoice Protocol for Lightning Payments

BOLT 11 defines the Lightning invoice format: the human-readable payment requests that encode amount, payment hash, expiry, and routing information into a bech32-encoded string. These are the invoices that begin with lnbc (mainnet) or lntb (testnet).

# BOLT 11 invoice structure
lnbc          # prefix (network)
20m           # amount (20 milli-bitcoin)
1pxxxxxxxxx   # timestamp + data fields:
              #   payment_hash
              #   description or description_hash
              #   expiry
              #   route_hints
              #   feature_bits
              # signature

BOLT 11 invoices are single-use and must be generated for each payment. This limitation led to the development of BOLT 12.

BOLT 12: Offers

BOLT 12 introduces the "offers" protocol, a significant upgrade over BOLT 11 invoices. Offers are reusable, support recurring payments, do not require a web server to generate invoices, and use onion messages to fetch invoices directly from the recipient over the Lightning Network.

While BOLT 11 invoices require out-of-band communication (scanning a QR code or clicking a link), BOLT 12 enables a fully in-protocol payment flow. A merchant publishes an offer once, and any customer can use it to request a fresh invoice at payment time.

Interoperability

The primary purpose of the BOLT specifications is interoperability. Lightning Network is not a single software project: it is a protocol implemented by independent teams writing in different languages (Go, Rust, Scala, C). The BOLTs ensure that a payment initiated by a user running LND can route through Core Lightning nodes and arrive at an Eclair-based merchant, all without any party needing to know or care what software the others run.

This interoperability extends to newer protocol layers. Layer 2 solutions like Spark that interact with Lightning benefit from the standardized message formats and payment flows defined in the BOLTs. Wallet developers building on frameworks like LDK implement the BOLT specifications to ensure their wallets work with the broader Lightning ecosystem.

The BOLT Amendment Process

BOLTs are living documents that evolve as the protocol matures. The amendment process follows a collaborative approach:

1. A developer identifies a protocol improvement and opens a pull request against the BOLTs repository
2. Implementation teams review the proposal, discussing trade-offs, edge cases, and backward compatibility
3. Multiple implementations prototype the change and test interoperability
4. Once at least two independent implementations ship the feature and confirm interoperability, the specification is updated

This approach prioritizes working code over theoretical design. No change is merged into the specification until it has been proven interoperable across implementations. The process is deliberately conservative: Lightning handles real money, and specification bugs can result in loss of funds.

Notable amendments that followed this process include anchor outputs (improving fee management for commitment transactions), keysend (spontaneous payments without invoices), and the ongoing work on PTLCs (replacing HTLCs with point-based locks for better privacy).

Use Cases

The BOLT specifications serve several audiences and purposes:

• Implementation developers use BOLTs as the authoritative reference when building or maintaining Lightning node software, ensuring their code interoperates with all other conforming implementations
• Wallet and application developers reference BOLTs to understand message formats, payment flows, and feature negotiation when integrating Lightning functionality using libraries like LDK
• Security researchers audit the BOLTs to identify potential vulnerabilities in the protocol design, such as channel probing attacks or liquidity griefing vectors
• Protocol designers proposing new features like eltoo, channel factories, or atomic multipath payments write their proposals as BOLT amendments or as complementary specifications (bLIPs)

Risks and Considerations

Specification Complexity

The BOLT specifications are dense and technical. Implementing them correctly requires deep expertise in cryptography, Bitcoin scripting, and distributed systems. Subtle misreadings can lead to consensus failures between peers, channel force-closures, or in extreme cases, loss of funds. The complexity also raises the barrier for new implementation teams, which limits the diversity of the ecosystem.

Slow Evolution

The requirement for multi-implementation consensus means the BOLT amendment process can be slow. Features that benefit the network may take years from initial proposal to specification merger. This conservative pace protects against hasty changes but can delay important improvements. To address this, the community introduced bLIPs (Bitcoin Lightning Improvement Proposals) as a lighter-weight mechanism for optional, application-level features that do not require full cross-implementation consensus.

Backward Compatibility

As the protocol evolves, maintaining backward compatibility between nodes running different specification versions becomes increasingly complex. The feature bit system (BOLT 9) helps, but mandatory features can still create network partitions if adoption is uneven. Node operators must keep their software updated to remain compatible with the broader network.

Completeness Gaps

Not every aspect of Lightning behavior is fully specified. Areas like pathfinding algorithms, fee estimation heuristics, and rebalancing strategies are left to individual implementations. While this allows innovation, it also means that node behavior can vary in ways that affect payment reliability and user experience across the network.

This content is for informational purposes only and does not constitute financial or technical advice. Always refer to the latest official BOLT specifications for implementation guidance.