Onion Message

What Is an Onion Message?

An onion message is a one-way encrypted message routed through the Lightning Network using the same layered encryption that protects payments. Unlike standard Lightning payments, onion messages carry data rather than value: no HTLCs are created, no channels need to exist along the path, and no funds are locked at any point.

The protocol was formally specified in BOLT #4 (Onion Routing) and merged into the Lightning specification in July 2023 via PR #759. Nodes signal support through feature bits 38/39 (option_onion_messages) in their node announcements and init messages.

Onion messages were introduced primarily to support BOLT 12 offers, which need a way for payers and merchants to exchange invoice requests and invoices without relying on external servers. Before onion messages, Lightning lacked a native mechanism for nodes to communicate anything other than payment data.

How It Works

Onion messages use the same Sphinx packet construction as Lightning payments, with several key differences that make them suitable for general-purpose messaging.

Message Structure

An onion message is sent as wire message type 513 (onion_message). Its structure includes:

• A path_key: an EC public key used for route blinding derivation at each hop
• An onion_message_packet: a Sphinx-encrypted packet containing per-hop payloads, an ephemeral public key, and an HMAC for integrity checking

type: 513 (onion_message)
data:
  [point]:    path_key              // route blinding key
  [u16]:      len                   // onion packet length
  [len*byte]: onion_message_packet  // Sphinx-encrypted payloads

Differences from Payment Onions

While onion messages reuse Lightning's onion routing cryptography, there are important structural differences:

• Payment onions use a fixed 1300-byte payload; onion messages use variable-length payloads (recommended sizes are 1366 or 32834 bytes)
• Payment onions use the payment hash as associated data in the Sphinx construction; onion messages use no associated data
• Payment onions produce error responses that propagate backward; onion messages are strictly one-way, so replies require a separate onion message sent through a blinded reply path
• Every onion message always uses route blinding, even when not strictly necessary, for consistency and privacy

Per-Hop TLV Payloads

Each hop in the onion message decrypts its own TLV (type-length-value) payload. The key TLV fields include:

onionmsg_tlv fields:
  type  2: reply_path               // blinded path for replies
  type  4: encrypted_recipient_data // encrypted routing info
  type 64: invoice_request          // BOLT 12 invoice request (final hop)
  type 66: invoice                  // BOLT 12 invoice (final hop)
  type 68: invoice_error            // BOLT 12 error (final hop)

Intermediate nodes decrypt their encrypted_recipient_data using ECDH with the blinding point. This reveals either a next_node_id or short_channel_id for forwarding. Each hop can only see the next destination: it cannot determine the sender, recipient, or total path length.

The Routing Flow

1. The sender constructs a Sphinx onion packet with per-hop encrypted payloads
2. The sender transmits the onion message (type 513) to the first hop
3. Each intermediate node peels one layer of encryption, reads its forwarding instructions, and passes the reduced packet to the next hop
4. The final recipient decrypts the innermost payload to read the message contents (such as an invoice request or invoice)
5. If the sender included a reply_path, the recipient can construct a new onion message using that blinded path to respond

Blinded Reply Paths

Since onion messages are one-way, the sender must include a blinded reply path if they expect a response. This path is a blinded path structure that routes back to the sender without revealing their identity.

The reply path contains:

• A first_node_id: the entry point of the blinded path (the only unblinded node visible to the recipient)
• A first_path_key: the initial blinding point for route derivation
• An array of blinded_path_hop entries, each containing a blinded node ID and encrypted routing data

The recipient only sees the entry node of the reply path, not the sender's actual node. Each hop in the blinded path can only decrypt its own forwarding instructions. This enables a fully private exchange where neither side learns the other's node identity.

The final hop's encrypted data can include a path_id field, allowing the sender to recognize which blinded path was used to reach them. This supports stateless path validation: the sender can publish multiple blinded paths and identify incoming replies without maintaining per-path state.

Use Cases

BOLT 12 Offer Flow

The primary use case for onion messages is the BOLT 12 offers protocol. Offers are static, reusable payment codes that replace single-use BOLT 11 invoices for many scenarios. The entire offer-to-payment flow runs over onion messages:

1. A merchant publishes an offer containing a blinded path to their node
2. The payer reads the offer and constructs an invoice_request (TLV type 64), sent as an onion message through the merchant's blinded path
3. The merchant validates the request and sends back an invoice (TLV type 66) via the payer's reply_path
4. The payer pays the invoice using a standard HTLC-based Lightning payment

This eliminates the need for external HTTP servers (as required by LNURL with BOLT 11). The entire negotiation happens within the Lightning Network itself. For a deeper look at how this changes the payment experience, see the BOLT 12 offers deep dive.

Private Communication

Beyond payment negotiation, onion messages provide a general-purpose encrypted communication channel between Lightning nodes. Potential applications include:

• Peer coordination: nodes can negotiate channel parameters, announce maintenance windows, or coordinate rebalancing without using the public gossip layer
• Service discovery: nodes can query peers for capabilities or service availability through private messages
• Future protocol extensions: any new Lightning feature that requires node-to-node communication can use onion messages as the transport, avoiding the need for separate networking infrastructure

Async Payment Coordination

Async payments (sending to offline recipients) require coordination messages between the sender, the recipient's LSP, and the recipient once they come online. Onion messages provide the private communication channel needed for this coordination without exposing payment details to the network.

Why It Matters

Onion messages transform Lightning from a pure payment network into a private communication layer. Before their introduction, Lightning nodes could only exchange structured payment data or public gossip. Any communication beyond that required external infrastructure: HTTP servers, Tor hidden services, or other out-of-band channels.

This matters for privacy. BOLT 11 invoices require the recipient to run a web server (via LNURL) to handle invoice requests dynamically, exposing an IP address or requiring Tor configuration. BOLT 12 offers with onion messages eliminate this requirement entirely: the Lightning Network itself becomes the communication medium, and blinded paths ensure neither party reveals their node identity. For more on how this improves Lightning privacy, see the blinded path privacy analysis.

For layer-2 protocols like Spark, private node communication channels are essential for coordinating off-chain state without leaking information to the broader network.

Risks and Considerations

Denial-of-Service Exposure

The central challenge with onion messages is that forwarding them costs resources (bandwidth, CPU for decryption) but provides no economic incentive. Unlike payment forwarding, which earns routing fees, relaying an onion message generates no revenue for intermediate nodes. This creates a natural vector for spam and denial-of-service attacks.

The specification addresses this by allowing nodes to rate-limit messages by simply dropping them. The proposed rate-limiting scheme (authored by Bastien Teinturier of ACINQ) suggests per-peer limits: approximately 10 messages per second from peers with an established channel, and roughly 1 message per second from peers without one.

Backpressure Mechanism

When a node rate-limits onion messages, it can send an onion_message_drop (message type 515) back to the peer that forwarded the dropped message. This backpressure signal causes the sending peer to halve its rate limit for that connection, with limits gradually doubling after 30 seconds of compliance. This adaptive mechanism prevents sudden traffic spikes from overwhelming forwarding nodes.

Channel-Only Relay

Nodes can signal feature bits 66/67 (option_onion_messages_only_channels) to indicate they only accept onion messages from peers with an established channel. This significantly reduces DoS exposure by requiring an economic commitment (channel funding) before a peer can send messages. LND, which added onion message support in v0.21, drops messages from non-channel peers by default.

No Delivery Guarantee

Onion messages offer no acknowledgment or delivery confirmation at the protocol level. If a message is dropped by a rate-limiting node or if a hop is offline, the sender has no way to know the message was lost. For BOLT 12 flows, this means the payer may need to retry invoice requests if no response arrives within a reasonable timeout.

Implementation Status

Onion message support varies across Lightning implementations:

As adoption grows, onion messages will become the standard transport for all node-to-node communication beyond payments. For background on how onion routing protects privacy in Lightning, see the onion routing privacy research.

This glossary entry is for informational purposes only and does not constitute financial or investment advice. Always do your own research before using any protocol or technology.