Onion message forwarding#10089
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Summary of Changes
Hello @gijswijs, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!
This pull request introduces the foundational functionality for forwarding onion messages within the Lightning Network. It integrates a new OnionMessage wire protocol message, enables its routing through the existing Sphinx onion processing infrastructure, and provides RPC endpoints for sending and subscribing to these messages. This work lays the groundwork for future application-layer protocols like BOLT12 offers, allowing for privacy-preserving communication beyond just payments.
Highlights
- Onion Message Wire Protocol: Introduces a new
lnwire.OnionMessagetype to the wire protocol, enabling the transmission of onion-encrypted messages between Lightning Network nodes. This message type is distinct from HTLC-carrying onion packets and is designed for application-layer communication. - Sphinx Onion Processing Integration: Extends the existing Sphinx onion processing logic within
htlcswitch/hopto correctly parse and handleOnionMessagepayloads. This includes adapting the hop iterator to recognize onion messages, extracting forwarding information (such as theNextNodeIDfor node-based routing), and performing message-specific TLV validations. - New RPC Endpoints for Onion Messages: Adds
SendOnionMessageandSubscribeOnionMessagesto the LND RPC API. These new endpoints allow external applications and users to programmatically send onion messages to peers and subscribe to a stream of incoming onion messages, facilitating the development of new privacy-preserving communication features. - Dedicated Message Endpoint and Forwarding Logic: Implements a new
onion_message.OnionEndpointthat integrates with themsgmuxto process incominglnwire.OnionMessages. This endpoint is responsible for decrypting the onion blob, determining if the message is for the local node or needs forwarding, and then either dispatching it to subscribers or relaying it to the next hop in the blinded path. - Enhanced Blinded Path Handling: Introduces specific logic for blinded paths within onion messages, including the addition of
NextNodeIDtoForwardingInfo. This ensures that onion messages, which do not carry payment-related information like CLTV deltas or amounts, are correctly processed and forwarded along their intended blinded routes.
Using Gemini Code Assist
The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.
Invoking Gemini
You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.
| Feature | Command | Description |
|---|---|---|
| Code Review | /gemini review |
Performs a code review for the current pull request in its current state. |
| Pull Request Summary | /gemini summary |
Provides a summary of the current pull request in its current state. |
| Comment | @gemini-code-assist | Responds in comments when explicitly tagged, both in issue comments and review comments. |
| Help | /gemini help |
Displays a list of available commands. |
Customization
To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.
Limitations & Feedback
Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.
You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.
Footnotes
-
Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩
There was a problem hiding this comment.
Code Review
This pull request introduces onion message forwarding, a significant feature that touches multiple parts of the codebase. The changes are generally well-structured, with new functionality encapsulated in the onion_message package and corresponding updates to lnwire, htlcswitch, and the RPC layer. The inclusion of integration tests for both direct and forwarded onion messages is a great addition. I've identified a few issues that need attention: a critical bug in handling dummy hops for onion messages, a high-severity issue with TLV decoding that could lead to panics, and a medium-severity issue regarding message routing logic that could cause confusion and potential bugs. Addressing these will improve the correctness and maintainability of the new functionality.
gijswijs
force-pushed
the
onion-messaging-1
branch
5 times, most recently
from
9157266 to
83a36aa
Compare
gijswijs
force-pushed
the
onion-messaging-1
branch
from
83a36aa to
4de5d9e
Compare
gijswijs
force-pushed
the
onion-messaging-1
branch
2 times, most recently
from
953b2d8 to
3f475ce
Compare
gijswijs
force-pushed
the
onion-messaging-1
branch
from
3f475ce to
606d9e5
Compare
| // forwarding information for an onion message. It contains either | ||
| // next_node_id or short_channel_id for each non-final node. It MAY contain | ||
| // the path_id for the final node. | ||
| bytes encrypted_recipient_data = 5; |
There was a problem hiding this comment.
If this is intended for users to consume, shouldn't this be decrypted?
There was a problem hiding this comment.
I'm not sure we even need this OnionMessageUpdate to be honest.
I needed it so that I could have itests that allowed me to test e2e onion messaging: Use SendOnionMessage to kick things of at Alice's end, and use SubscribeOnionMessages at Dave's end to see if everything comes through as expected.
That being said, if somebody would like to build something on top of onion message support (like LNDK is built on top of SubscribeCustomMessages), you would need SubscribeOnionMessages and you would want this to be decrypted.
|
Since #9868 has been merged, I think this needs to be updated, wanna take a look. |
gijswijs
force-pushed
the
onion-messaging-1
branch
2 times, most recently
from
5a7e61d to
dbb64f4
Compare
yyforyongyu
force-pushed
the
0-21-0-staging
branch
2 times, most recently
from
86fd4b7 to
57eb251
Compare
gijswijs
force-pushed
the
onion-messaging-1
branch
from
dbb64f4 to
e1738ce
Compare
In this commit, we add a series of examples that show how the package can be used in the wild. They can be run as normal Example tests.
In this commit, we add a readme which serves as a general introduction to the pacakge, and also the motivation of the package. It serves as a manual for developers that may wish to interact with the package.
This commit introduces a new Mailbox interface that abstracts the message queue implementation for actors. Previously, actors used a direct channel for their mailbox, which limited flexibility and made it difficult to implement alternative mailbox strategies. The new Mailbox interface provides methods for sending, receiving, and draining messages, with full context support for cancellation. The Receive method leverages Go 1.23's iter.Seq pattern, providing a clean iterator-based API that allows natural for-range loops over messages. The ChannelMailbox implementation maintains the existing channel-based behavior while conforming to the new interface. It stores the actor's context internally, ensuring both caller and actor contexts are properly respected during send and receive operations. This simplifies context handling compared to complex context merging approaches. This abstraction enables future implementations such as priority mailboxes, persistent mailboxes, or bounded mailboxes with overflow strategies, without requiring changes to the actor implementation.
This commit adds thorough test coverage for the new Mailbox interface and ChannelMailbox implementation. The tests verify correct behavior across various scenarios including successful sends, context cancellation, mailbox closure, and concurrent operations. The test suite specifically validates that the mailbox respects both the caller's context and the actor's context during send and receive operations. This ensures that actors properly shut down when their context is cancelled, and that callers can cancel operations without affecting the actor's lifecycle. Additional tests cover edge cases such as zero-capacity mailboxes (which default to a capacity of 1), draining messages after closure, and concurrent sends from multiple goroutines. The concurrent test uses 10 senders each sending 100 messages to verify thread-safety and proper message ordering. All tests pass with the race detector enabled, confirming the implementation is free from data races.
This commit refactors the Actor implementation to use the new Mailbox interface instead of directly managing a channel. This change significantly simplifies the actor's message processing loop and improves separation of concerns. The main changes include replacing the direct channel field with a Mailbox interface, updating NewActor to create a ChannelMailbox instance, and refactoring the process method to use the iterator pattern provided by mailbox.Receive. The new implementation uses a clean for-range loop over the mailbox's message iterator, eliminating the complex select statement that previously handled both message reception and context cancellation. The Tell and Ask methods in actorRefImpl have been simplified to use the mailbox's Send method, which internally handles both the caller's context and the actor's context. This eliminates the need for complex select statements in these methods and ensures consistent context handling throughout the actor system. Message draining during shutdown is now handled through the mailbox's Drain method, providing a cleaner separation between normal message processing and cleanup operations. The actor still properly sends unprocessed messages to the Dead Letter Office and completes pending promises with appropriate errors during shutdown.
The new wire message defines the OnionMessagePayload, FinalHopPayload, ReplyPath, and related TLV encoding/decoding logic.
gijswijs
force-pushed
the
onion-messaging-1
branch
from
29dde37 to
2484abb
Compare
|
By popular demand I've rebased the PR. No fixups. Good luck with the |
🔴 PR Severity: CRITICAL
🔴 Critical (5 files)
🟠 High (3 files)
🟡 Medium (14 files)
🟢 Low (Test files, docs, generated files - excluded from classification)
AnalysisThis PR implements onion message forwarding, a significant protocol extension that touches multiple critical systems: Critical concerns:
Severity bumps applied:
Recommendation: This requires expert review from maintainers familiar with:
To override, add a |
gijswijs
force-pushed
the
onion-messaging-1
branch
2 times, most recently
from
78f0be1 to
c9c1a87
Compare
This comment was marked as duplicate.
This comment was marked as duplicate.
Much better now without the fixups :) |
Update lightning-onion to commit that includes onion-messaging support.
Adds the NewNonFinalBlindedRouteDataOnionMessage function to create blinded route data specifically for onion messages.
gijswijs
force-pushed
the
onion-messaging-1
branch
from
c9c1a87 to
ceafbc2
Compare
This comment was marked as duplicate.
This comment was marked as duplicate.
|
Just pushed a tag for the |
|
I'm running interop between CLN -> LND -> CLN to forward onion messages. Logs2026-02-04 13:43:28 2026-02-04 12:43:28.486 [DBG] PEER: Peer(02a99b66705b797f47f786c848162b1d70eef0b4cdfe8cfe73ca3011464abcb8b3): Received OnionMessage(unknown msg type=*lnwire.OnionMessage) from 02a99b66705b797f47f786c848162b1d70eef0b4cdfe8cfe73ca3011464abcb8b3@172.18.0.5:9735 I'm getting |
Initialize a sphinx router without persistent replay protection logging for onion message processing. Onion messages don't require replay protection since they don't involve payment routing.
Introduce OnionPeerActor to handle the sending of onion message to each peer. The actor is registered with the receptionist pattern to enable message routing through the actor system. Also adds onion message feature bits to the protocol, so that the actor is only spawned when the peer supports onion messages.
Add onion message forwarding capability using the OnionPeerActor for communication. Messages are routed through a receptionist pattern where each peer has a dedicated OnionPeerActor for handling message sends. The OnionEndpoint uses the sphinx router for decoding and decrypting the onion message packet and the encrypted recipient data in the payload of the onion messages.
Change SubscribeOnionMessages RPC to return OnionMessageUpdate instead of OnionMessage, including the decrypted payload to enable payload inspection in integration tests. The encrypted recipient data is still not decrypted here.
Previously, each peer created its own OnionEndpoint during Start(), requiring SphinxOnionMsg and OnionMessageServer to be passed through the peer config. This added unnecessary fields to the peer's config struct. This commit refactors onion message handling so that: - The OnionEndpoint is created once at server startup - The shared endpoint is passed to peers via config - Peers simply register the endpoint with their message router This reduces the peer config surface and properly encapsulates the OnionEndpoint's dependencies (sphinx router, resolver, message server) at the server level where they naturally belong.
This commit adds a configuration flag to disable onion messaging support. When set, lnd will: - Not advertise the onion messages feature bit (39) in init and node announcements - Skip creating the OnionEndpoint at server startup - Not register an onion message handler with peers, so incoming onion messages are not processed
Add an LRU cache to GraphNodeResolver to avoid repeated database lookups when resolving SCIDs to node public keys. The cache stores up to 1000 compressed pubkey entries, which is sufficient for typical onion message forwarding scenarios. This change also introduces a NewGraphNodeResolver constructor to properly initialize the cache, replacing direct struct literal usage.
gijswijs
force-pushed
the
onion-messaging-1
branch
from
ceafbc2 to
15b72f4
Compare
This comment was marked as duplicate.
This comment was marked as duplicate.
6 participants
With this PR we add basic forwarding functionality for onion messages. It builds on PR #9868.
It adds
OnionMessagePayloadstruct to thelnwirepackage.It also depends on the not yet merged (PR 68)[https://github.com/lightningnetwork/lightning-onion/pull/68] in the
lightning-onionpackage. For now it uses that package from a forked version.The
msgmuxendpoint for onion messages is updated to parse the onion message packet, and forward the onion based on the acquired information.The
SubscribeOnionMessagesendpoint is updated to pass along any decrypted information. This endpoint is currently solely meant for itests, although it could have practical use in the future.