Add note in `OnionMessageIntercepted` to handle the connected event
What the developer wrote
Authored by Matt Corallo
Add note in `OnionMessageIntercepted` to handle the connected event
Users implementing the "onion message mailbox" feature and handling
`OnionMessageIntercepted` events need to also handle
`Event::OnionMessagePeerConnected` events.
Here we update the event docs for both to add additional references
and be more explicit about what implementors need to do.
What changed, and why it matters
This commit only updates documentation comments for two existing events in the Lightning Dev Kit Rust library. It adds guidance telling developers that if they store an intercepted onion message when a peer is offline, they should also handle the peer-connected event to forward the stored message. There are no code changes, no behavior changes, and no security fix or vulnerability.
No security action needed. Treat as a normal documentation improvement.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The diff is a pure documentation edit in lightning/src/events/mod.rs. It adds a cross-reference note in the Event::OnionMessageIntercepted rustdoc telling implementors to handle Event::OnionMessagePeerConnected once the peer reconnects, and rewords the OnionMessagePeerConnected docs to reference Event::OnionMessageIntercepted and OnionMessenger::forward_onion_message. No logic, API, or state-handling code is modified.
Changed components
lightning/src/events/mod.rs documentationInspect captured patch +9 / −4
diff --git a/lightning/src/events/mod.rs b/lightning/src/events/mod.rs
index d8a1a18..14c3c63 100644
--- a/lightning/src/events/mod.rs
+++ b/lightning/src/events/mod.rs
@@ -1687,6 +1687,9 @@ pub enum Event {
/// The offline peer should be awoken if possible on receipt of this event, such as via the LSPS5
/// protocol.
///
+ /// Once they connect, you should handle the generated [`Event::OnionMessagePeerConnected`] and
+ /// provide the stored message.
+ ///
/// # Failure Behavior and Persistence
/// This event will eventually be replayed after failures-to-handle (i.e., the event handler
/// returning `Err(ReplayEvent ())`), but won't be persisted across restarts.
@@ -1698,16 +1701,18 @@ pub enum Event {
/// The onion message intended to be forwarded to `peer_node_id`.
message: msgs::OnionMessage,
},
- /// Indicates that an onion message supporting peer has come online and it may
- /// be time to forward any onion messages that were previously intercepted for
- /// them. This event will only be generated if the `OnionMessenger` was
- /// initialized with
+ /// Indicates that an onion message supporting peer has come online and any messages previously
+ /// stored for them (from [`Event::OnionMessageIntercepted`]s) should be forwarded to them by
+ /// calling [`OnionMessenger::forward_onion_message`].
+ ///
+ /// This event will only be generated if the `OnionMessenger` was initialized with
/// [`OnionMessenger::new_with_offline_peer_interception`], see its docs.
///
/// # Failure Behavior and Persistence
/// This event will eventually be replayed after failures-to-handle (i.e., the event handler
/// returning `Err(ReplayEvent ())`), but won't be persisted across restarts.
///
+ /// [`OnionMessenger::forward_onion_message`]: crate::onion_message::messenger::OnionMessenger::forward_onion_message
/// [`OnionMessenger::new_with_offline_peer_interception`]: crate::onion_message::messenger::OnionMessenger::new_with_offline_peer_interception
OnionMessagePeerConnected {
/// The node id of the peer we just connected to, who advertises support for
Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.