Avoid overloading introduction_node_id

[rust-lightning] / lightning / src / onion_message / messenger.rs

diff --git a/lightning/src/onion_message/messenger.rs b/lightning/src/onion_message/messenger.rs
index 1a0145441e2e45f2f8bfb17c0a8c9f54bf1b4f4c..f271e2c20cc215147e481fc724f518d7f3b2e56e 100644 (file)
--- a/lightning/src/onion_message/messenger.rs
+++ b/lightning/src/onion_message/messenger.rs
@@ -19,7 +19,6 @@ use crate::blinded_path::BlindedPath;
 use crate::blinded_path::message::{advance_path_by_one, ForwardTlvs, ReceiveTlvs};
 use crate::blinded_path::utils;
 use crate::sign::{EntropySource, KeysManager, NodeSigner, Recipient};
-use crate::events::OnionMessageProvider;
 use crate::ln::features::{InitFeatures, NodeFeatures};
 use crate::ln::msgs::{self, OnionMessageHandler};
 use crate::ln::onion_utils;
@@ -35,9 +34,21 @@ use crate::io;
 use crate::sync::{Arc, Mutex};
 use crate::prelude::*;
 
-/// A sender, receiver and forwarder of onion messages. In upcoming releases, this object will be
-/// used to retrieve invoices and fulfill invoice requests from [offers]. Currently, only sending
-/// and receiving custom onion messages is supported.
+/// A sender, receiver and forwarder of [`OnionMessage`]s.
+///
+/// # Handling Messages
+///
+/// `OnionMessenger` implements [`OnionMessageHandler`], making it responsible for either forwarding
+/// messages to peers or delegating to the appropriate handler for the message type. Currently, the
+/// available handlers are:
+/// * [`OffersMessageHandler`], for responding to [`InvoiceRequest`]s and paying [`Bolt12Invoice`]s
+/// * [`CustomOnionMessageHandler`], for handling user-defined message types
+///
+/// # Sending Messages
+///
+/// [`OnionMessage`]s are sent initially using [`OnionMessenger::send_onion_message`]. When handling
+/// a message, the matched handler may return a response message which `OnionMessenger` will send
+/// on its behalf.
 ///
 /// # Example
 ///
@@ -121,8 +132,9 @@ use crate::prelude::*;
 /// onion_messenger.send_onion_message(path, message, reply_path);
 /// ```
 ///
-/// [offers]: <https://github.com/lightning/bolts/pull/798>
-/// [`OnionMessenger`]: crate::onion_message::OnionMessenger
+/// [`OnionMessage`]: crate::ln::msgs::OnionMessage
+/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+/// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
 pub struct OnionMessenger<ES: Deref, NS: Deref, L: Deref, MR: Deref, OMH: Deref, CMH: Deref>
 where
        ES::Target: EntropySource,
@@ -256,7 +268,7 @@ pub enum PeeledOnion<CM: CustomOnionMessageContents> {
 }
 
 /// Create an onion message with contents `message` to the destination of `path`.
-/// Returns (introduction_node_id, onion_msg)
+/// Returns (first_node_id, onion_msg)
 pub fn create_onion_message<ES: Deref, NS: Deref, T: CustomOnionMessageContents>(
        entropy_source: &ES, node_signer: &NS, secp_ctx: &Secp256k1<secp256k1::All>,
        path: OnionMessagePath, message: OnionMessageContents<T>, reply_path: Option<BlindedPath>,
@@ -289,8 +301,8 @@ where
 
        let blinding_secret_bytes = entropy_source.get_secure_random_bytes();
        let blinding_secret = SecretKey::from_slice(&blinding_secret_bytes[..]).expect("RNG is busted");
-       let (introduction_node_id, blinding_point) = if intermediate_nodes.len() != 0 {
-               (intermediate_nodes[0], PublicKey::from_secret_key(&secp_ctx, &blinding_secret))
+       let (first_node_id, blinding_point) = if let Some(first_node_id) = intermediate_nodes.first() {
+               (*first_node_id, PublicKey::from_secret_key(&secp_ctx, &blinding_secret))
        } else {
                match destination {
                        Destination::Node(pk) => (pk, PublicKey::from_secret_key(&secp_ctx, &blinding_secret)),
@@ -306,7 +318,7 @@ where
        let onion_routing_packet = construct_onion_message_packet(
                packet_payloads, packet_keys, prng_seed).map_err(|()| SendError::TooBigPacket)?;
 
-       Ok((introduction_node_id, msgs::OnionMessage {
+       Ok((first_node_id, msgs::OnionMessage {
                blinding_point,
                onion_routing_packet
        }))
@@ -444,14 +456,14 @@ where
                &self, path: OnionMessagePath, message: OnionMessageContents<T>,
                reply_path: Option<BlindedPath>
        ) -> Result<(), SendError> {
-               let (introduction_node_id, onion_msg) = create_onion_message(
+               let (first_node_id, onion_msg) = create_onion_message(
                        &self.entropy_source, &self.node_signer, &self.secp_ctx,
                        path, message, reply_path
                )?;
 
                let mut pending_per_peer_msgs = self.pending_messages.lock().unwrap();
-               if outbound_buffer_full(&introduction_node_id, &pending_per_peer_msgs) { return Err(SendError::BufferFull) }
-               match pending_per_peer_msgs.entry(introduction_node_id) {
+               if outbound_buffer_full(&first_node_id, &pending_per_peer_msgs) { return Err(SendError::BufferFull) }
+               match pending_per_peer_msgs.entry(first_node_id) {
                        hash_map::Entry::Vacant(_) => Err(SendError::InvalidFirstHop),
                        hash_map::Entry::Occupied(mut e) => {
                                e.get_mut().push_back(onion_msg);
@@ -632,18 +644,7 @@ where
                features.set_onion_messages_optional();
                features
        }
-}
 
-impl<ES: Deref, NS: Deref, L: Deref, MR: Deref, OMH: Deref, CMH: Deref> OnionMessageProvider
-for OnionMessenger<ES, NS, L, MR, OMH, CMH>
-where
-       ES::Target: EntropySource,
-       NS::Target: NodeSigner,
-       L::Target: Logger,
-       MR::Target: MessageRouter,
-       OMH::Target: OffersMessageHandler,
-       CMH::Target: CustomOnionMessageHandler,
-{
        fn next_onion_message_for_peer(&self, peer_node_id: PublicKey) -> Option<msgs::OnionMessage> {
                let mut pending_msgs = self.pending_messages.lock().unwrap();
                if let Some(msgs) = pending_msgs.get_mut(&peer_node_id) {