Onion message forwarding

[gijswijs]

With this PR we add basic forwarding functionality for onion messages. It builds on PR #9868.

It adds OnionMessagePayload struct to the lnwire package.
It also depends on the not yet merged (PR 68)[https://github.com/lightningnetwork/lightning-onion/pull/68] in the lightning-onion package. For now it uses that package from a forked version.

The msgmux endpoint for onion messages is updated to parse the onion message packet, and forward the onion based on the acquired information.

The SubscribeOnionMessages endpoint 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.

[gemini-code-assist]

Summary of Changes

Hello @gijswijs, I'm Gemini Code Assist¹! 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.OnionMessage type 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/hop to correctly parse and handle OnionMessage payloads. This includes adapting the hop iterator to recognize onion messages, extracting forwarding information (such as the NextNodeID for node-based routing), and performing message-specific TLV validations.
• New RPC Endpoints for Onion Messages: Adds SendOnionMessage and SubscribeOnionMessages to 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.OnionEndpoint that integrates with the msgmux to process incoming lnwire.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 NextNodeID to ForwardingInfo. 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

1. 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. ↩

[gemini-code-assist]

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.

[Abdulkbk]

Since #9868 has been merged, I think this needs to be updated, wanna take a look.

[gijswijs]

Running lnd with --protocol.no-onion-messages, I noticed we spawn OnionPeerActor if the remote peer supports onion messages regardless if we support it or not. I'm curious if there's any reason to spawn the actor if we don't support onion messages?.

@Abdulkbk Good catch! In the latest iteration, when --protocol.no-onion-messages is set, s.onionActorFactory is never initialized, it stays nil.

Then in brontide.go, the actor is only spawned when both conditions are met:

if p.remoteFeatures.HasFeature(lnwire.OnionMessagesOptional) &&
    p.cfg.SpawnOnionActor != nil {

So even if the remote peer supports onion messages, the nil check on SpawnOnionActor prevents the actor from being spawned when we've disabled onion messaging. No actors are created and no onion messages are processed or forwarded.

[gijswijs]

This is ready for a final review round.

Status:

• All CI checks pass (the only "failures" are Coveralls itest coverage decreases of -0.04% to -0.06%, which is cosmetic — unit coverage actually increased by +0.1%)
• 95 out of 97 review threads have been resolved
• The PR has been rebased and force-pushed with all feedback addressed

Unresolved threads (2) — both awaiting reviewer response only:

1. lnwire/onion_msg_payload.go (@ziggie1984) — Suggestion to add ExtraOpaqueData to the struct: The entire payload is a TLV stream with no fixed fields, so there's no concept of "trailing bytes", consistent with other pure-TLV messages like AnnouncementSignatures2. Awaiting ziggie's acknowledgement.
2. peer/brontide.go (@Roasbeef) — I've been swayed by your code-example and restructured the actor implementation. The actor is now a full end-to-end processing pipeline. So brontide sends the raw message to the actor (that is now tied to the pubkey of the originating node) and the actor takes it from there.

[Roasbeef]

LGTM ⚡️

[Abdulkbk]

I had some non-blocking in pending but I guess I'll discard since it's already merged :)