Basic structures for onion messages into LND #9868

gijswijs · 2025-05-26T14:18:23Z

This first pull request introduces the basic structures for onion messages into LND.

It adds a new message type, OnionMessage, to the lnwire package. This includes the message's definition, comprising a blinding point and an onion blob, along with the necessary serialization and deserialization logic for peer-to-peer communication.

Additionally, it exposes functionality for handling these messages via gRPC by adding two new endpoints:

• SendOnionMessage: Allows a client to send an onion message to a specific peer.
• SubscribeOnionMessages: Allows a client to subscribe to a stream of incoming onion messages. .

Scope of this PR:

Receive onion messages by registering a msgmux endpoint in brontide
'Listen in' on onion messages by dispatching the message to subscribers
Sending onion messages to a specified peer (The peer is passed through the endpoint; not derived from the onion message itself)
itest testing the above behavior

Usage of `msgmux`

msgmux provides a generic message routing system to decouple message handling from the main peer.Brontide
read loop. It's not widely used in LND as of yet, so an explanation might be in place.

A peer.Brontide instance is configured with a msgmux.Router.
Sub-systems that need to handle specific wire messages, like the onion_message.OnionEndpoint, implement the msgmux.Endpoint interface and are registered with the router.
In brontide's readHandler, when a new message is received from a peer, it is first passed to the msgRouter.RouteMsg() method.
The router checks all its registered endpoints. If an endpoint reports that it CanHandle() the message, the router forwards the message to that endpoint for processing.
If any endpoint successfully handles the message, RouteMsg returns nil. The brontide.readHandler then skips its large, legacy switch statement and proceeds to read the next message.
If no endpoint can handle the message, RouteMsg returns ErrUnableToRouteMsg, and brontide falls back to its switch statement to process the message in the traditional way.

This allows new message handling logic to be added as self-contained endpoints without modifying the peer's core read loop.

Out-of-scope (for this PR)

Onion message payload
Path finding
Blinded paths
announcing onion message support through featurebit 38/39
rate limiting/backpressure to mitigate DoS (see queue: add new BackpressureQueue[T] variant #9838)
BOLT12 offer and invoice request

coderabbitai · 2025-05-26T14:18:30Z

Important

Review skipped

Auto reviews are limited to specific labels.

🏷️ Labels to auto review (1)

llm-review

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

Review comments: Directly reply to a review comment made by CodeRabbit. Example:
- I pushed a fix in commit <commit_id>, please review it.
- Explain this complex logic.
- Open a follow-up GitHub issue for this discussion.
Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
- @coderabbitai explain this code block.
- @coderabbitai modularize this function.
PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
- @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbitai read src/utils.ts and explain its main purpose.
- @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
- @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

@coderabbitai pause to pause the reviews on a PR.
@coderabbitai resume to resume the paused reviews.
@coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
@coderabbitai full review to do a full review from scratch and review all the files again.
@coderabbitai summary to regenerate the summary of the PR.
@coderabbitai generate docstrings to generate docstrings for this PR.
@coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
@coderabbitai resolve resolve all the CodeRabbit review comments.
@coderabbitai configuration to show the current CodeRabbit configuration for the repository.
@coderabbitai help to get help.

Other keywords and placeholders

Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (`.coderabbit.yaml`)

You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
Please see the configuration documentation for more information.
If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

Visit our Documentation for detailed information on how to use CodeRabbit.
Join our Discord Community to get help, request features, and share feedback.
Follow us on X/Twitter for updates and announcements.

ziggie1984

Nice start of the onion message saga 🎉, I think the msgmux is the way to go here. I am not sure if we should use one server for all peers but if we use it we should buffer the update channel of the onionserver.

Let's now decrypt the onion message in the next PR ?

lnwire/onion_message.go

lnrpc/lightning.proto

msgmux/onion_endpoint.go

server.go

peer/brontide.go

ellemouton

removing request for review in the mean time :) feel free to re-request when ready!

mohamedawnallah

Thanks, @gijswijs, for putting this together! I've added some comments. Overall, I like the design and how it's seamlessly integrated with the LND system/subsystems. I can form a clear mental picture of the changes. Nice work!

lnwire/onion_message.go

onion_message/onion_endpoint.go

server.go

onionmessage/onion_endpoint.go

server.go

ziggie1984

I think we are close here, please also add release notes similar 🙏

ziggie1984 · 2025-09-24T08:34:40Z

lnwire/onion_message.go

+type OnionMessage struct {
+	// BlindingPoint is the route blinding ephemeral pubkey to be used for
+	// the onion message.
+	BlindingPoint *btcec.PublicKey


Nit: +1 for renaming to path_key, maybe also do this for our whole codebase where we currently use blindingPoint quite often ?

lnwire/onion_message.go

lnrpc/lightning.proto

ziggie1984 · 2025-09-24T08:55:16Z

onionmessage/log.go

+)
+
+// Subsystem defines the logging code for this subsystem.
+const Subsystem = "OMSG"


What does the G stand for here ?

onion -> o
message -> msg
onion + message -> omsg

onion_message/onion_endpoint.go

ziggie1984 · 2025-09-24T08:58:47Z

itest/lnd_onion_message_test.go

+	require.NoError(ht.T, err)
+	randomPub := randomPriv.PubKey()
+	msgBlindingPoint := randomPub.SerializeCompressed()
+	msgOnion := []byte{1, 2, 3}


shouldn't this fail because of the following (I know it is not a spec. MUST but why don't we follow it?):

SHOULD set onion_message_packet len to 1366 or 32834.

Yes, we will follow it.
There's an ongoing debate on how to handle onion_message_packet sizes in the lightning-onion package, but whatever solution we end up with, in one of the PRs in this saga the size will be clamped to those two values.

Micro-nit: add a comment that this is only for testing purposes and the onionMsg is supposed to be either 1300 or 32... big

ziggie1984 · 2025-09-24T11:20:08Z

server.go

+// SendOnionMessage sends a custom message to the peer with the specified
+// pubkey.
+// TODO(gijs): change this message to include path finding.
+func (s *server) SendOnionMessage(peerPub [33]byte,


you mean having a separate sub-rpc-server for onion-messages ?

lightninglabs-deploy · 2025-10-02T15:12:21Z

@gijswijs, remember to re-request review from reviewers when ready

Roasbeef · 2025-10-03T01:05:34Z

lnwire/onion_message.go

+	// manner as onions used to route HTLCs, with the exception that it uses
+	// blinded routes by default.
+	OnionBlob []byte
+}


No need for an ExtraData field here?

not sure if we need it on this level tho, why would I use a blinded route and add more information basically unblinded, I think the bulk of extra data will be in onionmsg_tlv where we defintily need the ExtraData, but I mean there is no cost of provisioning it here as well.

Roasbeef · 2025-10-03T01:06:56Z

lnrpc/lightning.proto

+    /* lncli: `subscribeonion`
+    SubscribeOnionMessages subscribes to a stream of incoming onion messages.
+    */
+    rpc SubscribeOnionMessages (SubscribeOnionMessagesRequest)


Is this intended to be just for forwarded onion messages, or the ones received?

For the ones received.

itest/lnd_onion_message_test.go

Roasbeef · 2025-10-03T01:09:34Z

peer/brontide.go


+	// OnionMessageServer is an instance of a message server that dispatches
+	// onion messages to subscribers.
+	OnionMessageServer *subscribe.Server


Just to verify my understanding: this is just hooked up into direct point-to-point messaging for now, to make a simple demo via the RPC server?

Yeah, and to be able to see what messages are received in itests.

peer/brontide.go

Roasbeef · 2025-10-03T01:13:22Z

server.go

 	return peer.SendMessageLazy(true, msg)
 }

+// SendOnionMessage sends a custom message to the peer with the specified


IIUC, you'll do this in a follow up PR, but I think the actor package can fit rather nicely here.

We have two actor types: the processor, and the endpoint.

The processor handles the crypto logic to figure out who to send the message to next.

A message endpoint becomes an actor, identifiable by the public key of the node.

When we read an onion message off the wire, we send it to the processor actor, who the sends it to the relevant processor actor.

I have a PR that abstracts out the mailbox for actors, so it can be anything that implements the queue abstraction.

I know that PR. And I thought of using it. But I also wanted to keep the number of moving parts as low as possible. This PR saga will pull in the (yet unmerged) BackPressureQueue in and I thought it was wise not to pull in another unmerged PR.

gijswijs · 2025-10-07T13:25:55Z

Ok, this PR is ready for the next round of reviews.
This is what I did so far:

Naming Improvements:
- The package onion_message was renamed to onionmessage.
- In the wire and RPC message definitions (lnwire and lnrpc), a key field was renamed from BlindingPoint to PathKey to align with spec. Comments and related documentation were also updated to reflect this change.
Context Propagation:
- The SendOnionMessage RPC handler and its underlying methods now accept a context.Context. This allows the operation to be cancelled, for instance if the request times out or the client disconnects. For good measure I made a similar change to the SendCustomMessage RPC handler.
Logging:
- Logging was improved to use a structured format (slog).

The following will be addressed in later PRs:

Handling of ExtraData specifically for onion messages (see: Basic structures for onion messages into LND #9868 (comment))

Open questions:

Should we implement the actor package? (see: Basic structures for onion messages into LND #9868 (comment))
Should we rename BlindingPoint to PathKey in all other places as well? This is a substantial renaming and should be done in a separate PR.

ziggie1984 · 2025-10-08T09:34:39Z

can you rebase on 21-staging

gijswijs · 2025-10-08T09:50:13Z

can you rebase on 21-staging

✔️

ziggie1984

LGTM

ziggie1984 · 2025-10-08T11:28:37Z

lnwire/onion_message.go

+	// manner as onions used to route HTLCs, with the exception that it uses
+	// blinded routes by default.
+	OnionBlob []byte
+}


not sure if we need it on this level tho, why would I use a blinded route and add more information basically unblinded, I think the bulk of extra data will be in onionmsg_tlv where we defintily need the ExtraData, but I mean there is no cost of provisioning it here as well.

ziggie1984 · 2025-10-08T11:33:44Z

itest/lnd_onion_message_test.go

+	require.NoError(ht.T, err)
+	randomPub := randomPriv.PubKey()
+	msgBlindingPoint := randomPub.SerializeCompressed()
+	msgOnion := []byte{1, 2, 3}


Micro-nit: add a comment that this is only for testing purposes and the onionMsg is supposed to be either 1300 or 32... big

ziggie1984 · 2025-10-08T11:37:52Z

onionmessage/onion_endpoint.go

+	}
+
+	peer := msg.PeerPub.SerializeCompressed()
+	log.DebugS(ctx, "OnionEndpoint received OnionMessage",


maybe it makes sense to add the peer to the ctx so that it is printed below as well?

Not sure if I follow. We get the peer from which we receive the message from the 'msg' itself. Do you mean the peer that is parsing the message, so the node itself?

The log message now shows this:

2025-10-09 11:00:14.625 [DBG] OMSG onion_endpoint.go:71: OnionEndpoint received OnionMessage peer=02765192bdda4b72ac78a87661656102ce891ffd9961570850164d258e7ed2c88f path_key=02e97c12b29f onion_blob=010203 "blob length"=3

I was thinking of something like this:

ctx = btclog.WithCtx(ctx, slog.String("peer", hex.EncodeToString(peer)), lnutils.LogPubKey("path_key", onionMsg.PathKey), ) log.DebugS(ctx, "OnionEndpoint received OnionMessage", btclog.HexN("onion_blob", onionMsg.OnionBlob, 10), slog.Int("blob_length", len(onionMsg.OnionBlob)))

then below in

log.ErrorS(ctx, "Failed to send onion message update", err)

you will have all the information when using this ctx again.

ellemouton

lgtm 🙏

lnutils/log.go

lnwire/test_message.go

Abdulkbk

LGTM!, very easy to follow. Left some nits

lnrpc/lightning.proto

onionmessage/onion_endpoint.go

rpcserver.go

lnwire/message.go

This message type is a message that carries an onion-encrypted payload used for BOLT12 messages.

This commit creates the necessary endpoints for onion messages. Specifically, it adds the following: - `SendOnionMessage` endpoint to send onion messages. - `SubscribeOnionMessages` endpoint to subscribe to incoming onion messages. It uses the `msgmux` package to handle the onion messages.

The only way to unblock SendCustomMessage is if the peer activates, disconnects or the server shuts down. This means that if the context is cancelled, we will still wait until one of those other events happen. With this commit we thread the context through to SendCustomMessage, so that if the context is cancelled, we can return early. This improves the cancellation semantics.

gijswijs requested review from ellemouton and ziggie1984 and removed request for ziggie1984 May 26, 2025 14:18

saubyk assigned gijswijs May 27, 2025

ziggie1984 reviewed Jun 7, 2025

View reviewed changes

gijswijs force-pushed the onion-messaging branch 2 times, most recently from 5762808 to 9f23971 Compare June 10, 2025 15:49

saubyk added this to the v0.20.0 milestone Jun 11, 2025

saubyk added the onion routing label Jun 11, 2025

saubyk added this to lnd v0.20 Jun 11, 2025

saubyk moved this to In progress in lnd v0.20 Jun 11, 2025

ellemouton reviewed Jul 8, 2025

View reviewed changes

gijswijs force-pushed the onion-messaging branch from 9f23971 to e5726a7 Compare July 9, 2025 13:36

ZZiigguurraatt mentioned this pull request Jul 15, 2025

Onion messaging + bolt 12 offers #9369

Closed

5 tasks

gijswijs force-pushed the onion-messaging branch from e5726a7 to fefe590 Compare July 17, 2025 19:02

gijswijs mentioned this pull request Jul 17, 2025

Onion message forwarding #10089

Open

mohamedawnallah reviewed Aug 4, 2025

View reviewed changes

gijswijs force-pushed the onion-messaging branch 2 times, most recently from 9549248 to d872936 Compare September 1, 2025 11:37

gijswijs changed the title ~~PoC Onion messaging using msgmux~~ Onion messaging using msgmux Sep 9, 2025

gijswijs marked this pull request as ready for review September 9, 2025 15:27

gijswijs changed the title ~~Onion messaging using msgmux~~ Basic structures for onion messages into LND Sep 15, 2025

gijswijs mentioned this pull request Sep 15, 2025

[epic]: Implement Onion Messaging (BOLT4) and Support Downstream BOLT12 Features #10220

Open

gijswijs force-pushed the onion-messaging branch from d872936 to 99a62aa Compare September 16, 2025 09:40

saubyk requested review from ellemouton and ziggie1984 September 16, 2025 16:43

gijswijs modified the milestones: v0.20.0, v0.21.0 Sep 17, 2025

ziggie1984 reviewed Sep 24, 2025

View reviewed changes

Roasbeef reviewed Oct 3, 2025

View reviewed changes

gijswijs force-pushed the onion-messaging branch from 9857299 to c72c704 Compare October 7, 2025 12:41

gijswijs force-pushed the onion-messaging branch 2 times, most recently from fa0822b to 3a18daf Compare October 7, 2025 14:03

gijswijs requested review from ellemouton and ziggie1984 October 7, 2025 14:55

ziggie1984 changed the base branch from master to 0-21-0-staging October 7, 2025 19:59

gijswijs force-pushed the onion-messaging branch 2 times, most recently from 4c133b9 to a988f91 Compare October 8, 2025 09:49

ziggie1984 approved these changes Oct 8, 2025

View reviewed changes

ziggie1984 reviewed Oct 8, 2025

View reviewed changes

gijswijs force-pushed the onion-messaging branch from a988f91 to bbe7671 Compare October 9, 2025 09:50

ellemouton approved these changes Oct 9, 2025

View reviewed changes

lnutils/log.go Outdated Show resolved Hide resolved

lnwire/test_message.go Show resolved Hide resolved

Abdulkbk approved these changes Oct 9, 2025

View reviewed changes

lnrpc/lightning.proto Outdated Show resolved Hide resolved

onionmessage/onion_endpoint.go Outdated Show resolved Hide resolved

rpcserver.go Outdated Show resolved Hide resolved

lnwire/message.go Show resolved Hide resolved

gijswijs mentioned this pull request Oct 10, 2025

btclog: handle nil slices in HexN gracefully btcsuite/btclog#25

Open

gijswijs force-pushed the onion-messaging branch from bbe7671 to 72ecd16 Compare October 10, 2025 13:24

yyforyongyu force-pushed the 0-21-0-staging branch from 496c5e3 to 8eb29f1 Compare October 13, 2025 16:39

gijswijs added 5 commits October 14, 2025 16:00

lnwire: add onion message type

e62d08d

This message type is a message that carries an onion-encrypted payload used for BOLT12 messages.

lnrpc: SendOnionMessage rpc endpoint

9724de8

docs: update release notes for 0.21.0

0cbf2ad

gijswijs force-pushed the onion-messaging branch from 72ecd16 to 0cbf2ad Compare October 14, 2025 14:00

gijswijs merged commit 1ccb526 into lightningnetwork:0-21-0-staging Oct 14, 2025
39 checks passed

github-project-automation bot moved this from In review to Done in v0.21 Oct 14, 2025

Basic structures for onion messages into LND #9868

Basic structures for onion messages into LND #9868

Uh oh!

Conversation

gijswijs commented May 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Scope of this PR:

Usage of msgmux

Out-of-scope (for this PR)

Uh oh!

coderabbitai bot commented May 26, 2025

Review skipped

Chat

Support

CodeRabbit Commands (Invoked using PR comments)

Other keywords and placeholders

CodeRabbit Configuration File (.coderabbit.yaml)

Documentation and Community

Uh oh!

ziggie1984 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ellemouton left a comment

Choose a reason for hiding this comment

Uh oh!

mohamedawnallah left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ziggie1984 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lightninglabs-deploy commented Oct 2, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gijswijs commented May 26, 2025 •

edited

Loading

Usage of `msgmux`

CodeRabbit Configuration File (`.coderabbit.yaml`)