Skip to content

Commit 313b89d

Browse files
Fill in top-level docs for onion message offline peer interception.
1 parent 81d992f commit 313b89d

File tree

2 files changed

+31
-0
lines changed

2 files changed

+31
-0
lines changed

lightning/src/events/mod.rs

+11
Original file line numberDiff line numberDiff line change
@@ -1041,14 +1041,25 @@ pub enum Event {
10411041
///
10421042
/// [`ChannelHandshakeConfig::negotiate_anchors_zero_fee_htlc_tx`]: crate::util::config::ChannelHandshakeConfig::negotiate_anchors_zero_fee_htlc_tx
10431043
BumpTransaction(BumpTransactionEvent),
1044+
/// We received an onion message that is intended to be forwarded to a peer
1045+
/// that is currently offline. This event will only be generated if the
1046+
/// `OnionMessenger` was initialized with
1047+
/// [`OnionMessenger::new_with_offline_peer_interception`], see its docs.
10441048
///
1049+
/// [`OnionMessenger::new_with_offline_peer_interception`]: crate::onion_message::messenger::OnionMessenger::new_with_offline_peer_interception
10451050
OnionMessageForOfflinePeer {
10461051
/// The node id of the offline peer.
10471052
peer_node_id: PublicKey,
10481053
/// The onion message intended to be forwarded to `peer_node_id`.
10491054
message: msgs::OnionMessage,
10501055
},
1056+
/// Indicates that an onion message supporting peer has come online and it may
1057+
/// be time to forward any onion messages that were previously intercepted for
1058+
/// them. This event will only be generated if the `OnionMessenger` was
1059+
/// initialized with
1060+
/// [`OnionMessenger::new_with_offline_peer_interception`], see its docs.
10511061
///
1062+
/// [`OnionMessenger::new_with_offline_peer_interception`]: crate::onion_message::messenger::OnionMessenger::new_with_offline_peer_interception
10521063
OnionMessagePeerConnected {
10531064
/// The node id of the peer we just connected to, who advertises support for
10541065
/// onion messages.

lightning/src/onion_message/messenger.rs

+20
Original file line numberDiff line numberDiff line change
@@ -805,7 +805,27 @@ where
805805
)
806806
}
807807

808+
/// Similar to [`Self::new`], but rather than dropping onion messages that are
809+
/// intended to be forwarded to offline peers, we will intercept them for
810+
/// later forwarding.
808811
///
812+
/// Interception flow:
813+
/// 1. If an onion message for an offline peer is received, `OnionMessenger` will
814+
/// generate an [`Event::OnionMessageForOfflinePeer`]. Event handlers can
815+
/// then choose to persist this onion message for later forwarding, or drop
816+
/// it.
817+
/// 2. When the offline peer later comes back online, `OnionMessenger` will
818+
/// generate an [`Event::OnionMessagePeerConnected`]. Event handlers will
819+
/// then fetch all previously intercepted onion messages for this peer.
820+
/// 3. Once the stored onion messages are fetched, they can finally be
821+
/// forwarded to the now-online peer via [`Self::forward_onion_message`].
822+
///
823+
/// # Note
824+
///
825+
/// LDK will not rate limit how many [`Event::OnionMessageForOfflinePeer`]s
826+
/// are generated, so it is the caller's responsibility to limit how many
827+
/// onion messages are persisted and only persist onion messages for relevant
828+
/// peers.
809829
pub fn new_with_offline_peer_interception(
810830
entropy_source: ES, node_signer: NS, logger: L, node_id_lookup: NL,
811831
message_router: MR, offers_handler: OMH, custom_handler: CMH

0 commit comments

Comments
 (0)