Beyond Payments: How Lightning's Onion Messages Enable Private Messaging and Data Delivery

The Lightning Network was designed for payments, but its onion routing infrastructure turns out to be useful for much more. With the formal adoption of onion messages in the BOLT specification (feature bits 38/39, merged via BOLTs PR #759 in August 2023), Lightning nodes can now exchange end-to-end encrypted messages routed through the network without requiring payment channels, HTLCs, or locked liquidity. This capability underpins BOLT12 offers, enables peer-to-peer messaging applications, and opens the door to decentralized notification systems built entirely on Lightning's existing topology.

How Onion Messages Work

An onion message (wire type 513) is a one-way, unreliable datagram routed through Lightning's peer-to-peer overlay network. Unlike HTLC-based payments, onion messages require no channel between hops: any two connected peers can relay a message. The protocol uses the same layered encryption as payment onions (each forwarding node peels one layer to discover the next hop) but strips away the payment-specific machinery.

Message Structure

Each onion message contains just two fields: a path_key (the route-blinding ephemeral public key) and an onion_message_packet (the encrypted onion blob containing version, ephemeral pubkey, per-hop payloads, and HMAC). The specification defines two standard packet sizes: 1,366 bytes and 32,834 bytes (~32 KB). Using fixed sizes prevents traffic analysis that could otherwise infer message types based on length.

The payload uses TLV (type-length-value) encoding. Type 2 carries an optional reply_path so the recipient can respond without knowing the sender's identity. Type 4 holds encrypted_recipient_data with routing instructions for each hop. Types 64 and above are reserved for final-hop payloads: invoice_request, invoice, and invoice_error for the BOLT12 offer flow.

One-way and unreliable: Onion messages provide no delivery confirmation and no error returns. If a message is dropped at any hop, the sender never learns about it. This is a deliberate design choice: it keeps the protocol simple, stateless for forwarding nodes, and resistant to probing attacks that exploit error paths.

Routing Without Channels

Payment routing requires channels with sufficient balance along every hop. Onion message routing only requires peer connectivity. A node can forward a message to any peer it has a TCP connection with, whether or not they share a funded channel. This dramatically expands the reachable network for messaging compared to payments, but it also introduces a free-rider problem: forwarding nodes consume bandwidth without compensation.

To mitigate abuse, many implementations restrict relay to channel peers only. The specification now includes option_onion_messages_only_channels (added via BOLTs #1343 in July 2026), letting nodes signal that they will only relay onion messages from peers with open channels. This makes the policy discoverable by senders during pathfinding.

Privacy Properties of Onion Messages

Onion messages inherit Lightning's onion routing privacy model and extend it with mandatory route blinding. Every onion message uses blinded paths, even when the sender knows the recipient's node ID directly. This provides a uniform privacy baseline across all messages.

Sender Privacy

Standard onion routing protects the sender. Each intermediate node knows only its immediate predecessor and successor in the route. The sender can also include a blinded reply path so that even the recipient never learns the sender's node public key: the reply path's introduction node is the only real identity visible to the recipient.

Receiver Privacy

Blinded paths hide the recipient's node ID and channel structure from the sender. The sender sees only the introduction node (the first unblinded node in the path), not the ultimate destination. Multiple blinded routes from the same recipient cannot be linked without additional context, preventing correlation attacks across separate interactions.

Forward Secrecy

Each onion message uses fresh ephemeral keys. Compromising a node's long-term key after a message has been forwarded does not allow retroactive decryption of previously relayed messages. This is a meaningful improvement over many messaging protocols that lack per-message key rotation.

The Primary Application: BOLT12 Offer and Invoice Exchange

The most important use of onion messages today is the BOLT12 offers protocol, formally merged into the Lightning specification via BOLTs #798 in October 2024. BOLT12 replaces the static, single-use BOLT11 invoices with reusable offers that function like permanent payment endpoints.

The Offer Flow

The interaction proceeds in four steps, all conducted within the Lightning Network itself:

1. A merchant publishes an offer: a compact, reusable payment endpoint (similar to a permanent QR code) that includes a blinded path to reach the merchant's node.
2. The payer's node decodes the offer and sends an invoice_request via onion message through the blinded path to the merchant.
3. The merchant's node validates the request, generates a BOLT12 invoice, and sends it back through the reply_path embedded in the original onion message.
4. The payer pays the invoice through blinded payment paths specified in the invoice.

This entire negotiation happens inside Lightning's peer-to-peer network. BOLT11 required an out-of-band channel (typically an HTTP server) to deliver invoices. BOLT12 eliminates that dependency, making the payment flow self-contained on the Lightning Network.

Why this matters for privacy: With BOLT11, a web server serving invoices can correlate IP addresses with payment requests. BOLT12 moves this exchange into the onion-routed network, where neither party needs to reveal their network-level identity to the other.

Messaging Applications on Lightning

Before the onion messages specification was finalized, developers built messaging systems on Lightning using an earlier technique: keysend payments with custom TLV data. These systems embed message content inside payment metadata, piggybacking on Lightning's payment infrastructure. The newer onion message protocol offers a purpose-built alternative that separates messaging from payments.

Keysend-Based Messaging: Sphinx and Juggernaut

Sphinx Chat uses LND's dest_custom_records parameter to attach end-to-end encrypted message data to keysend payments. Each message costs at least 1 satoshi plus routing fees, creating a natural spam deterrent but also a per-message cost floor.

Juggernaut, released in 2020 by John Cantrell, demonstrated peer-to-peer encrypted messaging over Lightning without servers, phone numbers, or accounts. It also relied on keysend-based message delivery.

Keysend vs. Onion Message Messaging

The keysend approach has a notable advantage: delivery confirmation via the payment preimage. If the payment succeeds, the message was delivered. Onion messages sacrifice this guarantee in exchange for zero cost, no liquidity requirements, and stronger privacy through mandatory blinding.

Potential Applications Beyond Chat

Onion messages enable use cases that go beyond person-to-person messaging:

• Decentralized notifications: a service can push status updates to a user's node without knowing their IP address or requiring a persistent connection to a centralized server
• Coordination messages for async payments: signaling between LSPs and offline recipients
• PTLC setup negotiation: exchanging adaptor signature data before committing to a payment
• Decentralized marketplace offers: publishing and responding to trade proposals without a central order book server

Onion Messages vs. Nostr for Messaging

Nostr has emerged as the leading decentralized messaging protocol in the Bitcoin ecosystem. Comparing it to Lightning onion messages reveals fundamentally different architectures optimized for different goals.

Nostr uses a client-relay model: clients publish signed events to multiple relays, which store and forward them. This architecture excels at broadcast communication, offline message storage, and social features. The tradeoff is metadata exposure: relays see sender IP addresses (unless Tor is used), and encrypted DMs using NIP-04 lack forward secrecy (NIP-44 improves on this but adoption remains partial).

Lightning onion messages provide much stronger privacy guarantees through layered encryption and mandatory route blinding, but they lack offline delivery: if the recipient's node is offline, the message is lost. They also require running (or connecting to) a Lightning node, which is a significantly higher barrier to entry than Nostr's lightweight client model.

In practice, the two protocols are complementary rather than competing. Nostr Wallet Connect (NWC) already bridges the gap by using Nostr relays to coordinate between Nostr clients and Lightning wallets, combining Nostr's accessibility with Lightning's payment capabilities.

Bandwidth Implications and Rate Limiting

The most contentious aspect of onion messages is the bandwidth free-rider problem. Forwarding nodes consume CPU cycles and network bandwidth to relay up to 32 KB messages with no economic compensation. This creates an asymmetry: senders pay nothing, but the network bears the cost.

Current Rate Limiting Approaches

Bastien Teinturier (Eclair developer) proposed a backpressure-based rate limiting scheme in 2022. The approach sets per-peer limits of 10 messages per second for channel peers and 1 message per second for non-channel peers. When limits are exceeded, the node sends an onion_message_drop (type 515) to the sender, which halves its rate limits for that peer. Limits double back if no violations occur within 30 seconds.

LND v0.21.0 (released in 2026) implemented a token-bucket rate limiter with configurable parameters: a default per-peer limit of 0.5 Mbps with 256 KiB burst, and a global limit of 5 Mbps with 1,600 KiB burst. LND also applies a channel-presence gate by default, dropping onion messages from peers without open channels as a Sybil resistance measure.

The Jamming Problem

Research by Erick Cestari (published April 2026, discussed in Bitcoin Optech Newsletter #402) identified a vulnerability: attackers can spin up malicious nodes and flood the network with spam messages, triggering rate limits on peers and causing them to drop legitimate messages. This is analogous to channel jamming in the payment layer but applied to the message layer.

Several mitigation strategies are under discussion:

• Upfront fees: nodes advertise a per-message flat fee, dropping unpaid messages
• Hop limits with proof of stake: cap the number of hops (for example, max 3) or require proof of channel balance that scales with hop count
• Bandwidth-metered payments: similar to upfront fees but settled through AMP payments
• Backpropagation-based rate limiting: the current statistical backpressure approach

No consensus has emerged on the right solution. The tension is fundamental: making relay free maximizes accessibility but invites abuse, while adding costs creates friction for legitimate use cases like BOLT12 offer exchange.

Implementation Status Across Lightning

Onion message support varies significantly across Lightning implementations, with Core Lightning leading adoption and LND playing catch-up.

Core Lightning (CLN)

CLN had experimental blinded path support as early as 2020 and has been the reference implementation for both onion messages and BOLT12. As of v24.11 (November 2024), BOLT12 offers are enabled by default with no experimental flag required.

LDK (Lightning Development Kit)

LDK added onion message sending and reply path support in 2022, with BOLT12 message handling following shortly after. LDK powers LNDK, a standalone daemon that provides BOLT12 support to LND nodes by plugging into LND's gRPC API. Strike uses LNDK in production for BOLT12 offer payments.

Eclair

Eclair added initial onion message support in 2021, with relay enabled by default in 2022. Version 0.13.0 supports full BOLT12 offers with blinded paths. In August 2026, Eclair introduced the option_onion_messages_only_channels feature bit, allowing nodes to explicitly signal their relay policy.

LND

LND does not natively support BOLT12 as of mid-2026, representing the single largest gap in the ecosystem. Version 0.21.0 added basic onion message forwarding (Stage 1 of their roadmap) with graph-based pathfinding, per-peer rate limiting, and a channel-presence gate. The full BOLT12 codec was completed for v0.22.0, but receiver, sender, multi-hop, and payment functionality remain in progress.

The LNDK workaround: Until LND ships native BOLT12, operators can run LNDK alongside LND (v0.18.0+). LNDK uses LDK's BOLT12 library to handle offer negotiation via LND's gRPC interface. A known limitation: LNDK generates a new key on restart, so offers are not persistent across restarts.

What This Means for the Lightning Ecosystem

Onion messages transform Lightning from a single-purpose payment network into a general-purpose encrypted communication layer. The BOLT12 offer flow already demonstrates the value: payments become self-contained within the Lightning Network, eliminating the need for external web servers to coordinate invoicing. As the protocol matures, applications like async payment coordination, LSP signaling, and decentralized notifications could make the message layer as important as the payment layer.

The key challenge remains bandwidth economics. Without compensation for relay, onion messages rely on the goodwill of node operators. The current rate-limiting approaches are pragmatic but imperfect: they prevent catastrophic abuse while leaving the jamming problem unsolved. The community's ability to find a sustainable incentive model will determine whether onion messages remain a niche feature for BOLT12 or grow into a broader application platform.

The Spark Perspective

While Lightning's onion message layer extends the network into messaging and data delivery, Spark takes a different approach by focusing on optimizing the payment use case itself. Spark eliminates channel management and liquidity planning entirely, providing instant finality for Bitcoin and stablecoin transfers without the operational overhead that makes Lightning node operation complex. For developers building payment applications, the Spark SDK offers a simpler integration path: no channel management, no liquidity provisioning, and no need to run relay infrastructure for message-based invoice negotiation.

The two approaches are complementary. Lightning's onion messages add coordination and communication capabilities to the network, while Spark streamlines the payment experience for end users and wallet developers. Users of General Bread, a Spark-powered wallet, can send and receive Bitcoin and USDB stablecoins instantly, without needing to understand the channel management and message relay infrastructure that Lightning's expanding application layer requires.

For a deeper look at how Lightning protects payment privacy, see our guide to onion routing and Lightning privacy. To understand the BOLT12 offer protocol that onion messages enable, read BOLT12 Offers Explained.

This article is for educational purposes only. It does not constitute financial or investment advice. Bitcoin and Layer 2 protocols involve technical and financial risk. Always do your own research and understand the tradeoffs before using any protocol.