From b26fb851cd08882e0fec4c1f67b6ba946c3138ae Mon Sep 17 00:00:00 2001 From: Valentine Wallace Date: Thu, 23 Jun 2022 15:45:33 -0400 Subject: [PATCH] Significantly expand onion message documentation --- lightning/src/onion_message/messenger.rs | 50 +++++++++++++++++++++++- lightning/src/onion_message/mod.rs | 11 ++++++ 2 files changed, 60 insertions(+), 1 deletion(-) diff --git a/lightning/src/onion_message/messenger.rs b/lightning/src/onion_message/messenger.rs index 3b18b1186..775428720 100644 --- a/lightning/src/onion_message/messenger.rs +++ b/lightning/src/onion_message/messenger.rs @@ -28,9 +28,56 @@ use sync::{Arc, Mutex}; use 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]. +/// used to retrieve invoices and fulfill invoice requests from [offers]. Currently, only sending +/// and receiving empty onion messages is supported. +/// +/// # Example +/// +// Needs to be `ignore` until the `onion_message` module is made public, otherwise this is a test +// failure. +/// ```ignore +/// # extern crate bitcoin; +/// # use bitcoin::hashes::_export::_core::time::Duration; +/// # use bitcoin::secp256k1::{PublicKey, Secp256k1, SecretKey}; +/// # use lightning::chain::keysinterface::{InMemorySigner, KeysManager, KeysInterface}; +/// # use lightning::onion_message::{BlindedRoute, Destination, OnionMessenger}; +/// # use lightning::util::logger::{Logger, Record}; +/// # use std::sync::Arc; +/// # struct FakeLogger {}; +/// # impl Logger for FakeLogger { +/// # fn log(&self, record: &Record) { unimplemented!() } +/// # } +/// # let seed = [42u8; 32]; +/// # let time = Duration::from_secs(123456); +/// # let keys_manager = KeysManager::new(&seed, time.as_secs(), time.subsec_nanos()); +/// # let logger = Arc::new(FakeLogger {}); +/// # let node_secret = SecretKey::from_slice(&hex::decode("0101010101010101010101010101010101010101010101010101010101010101").unwrap()[..]).unwrap(); +/// # let secp_ctx = Secp256k1::new(); +/// # let hop_node_id1 = PublicKey::from_secret_key(&secp_ctx, &node_secret); +/// # let (hop_node_id2, hop_node_id3, hop_node_id4) = (hop_node_id1, hop_node_id1, +/// hop_node_id1); +/// # let destination_node_id = hop_node_id1; +/// # +/// // Create the onion messenger. This must use the same `keys_manager` as is passed to your +/// // ChannelManager. +/// let onion_messenger = OnionMessenger::new(&keys_manager, logger); +/// +/// // Send an empty onion message to a node id. +/// let intermediate_hops = [hop_node_id1, hop_node_id2]; +/// onion_messenger.send_onion_message(&intermediate_hops, Destination::Node(destination_node_id)); +/// +/// // Create a blinded route to yourself, for someone to send an onion message to. +/// # let your_node_id = hop_node_id1; +/// let hops = [hop_node_id3, hop_node_id4, your_node_id]; +/// let blinded_route = BlindedRoute::new::(&hops, &keys_manager, &secp_ctx).unwrap(); +/// +/// // Send an empty onion message to a blinded route. +/// # let intermediate_hops = [hop_node_id1, hop_node_id2]; +/// onion_messenger.send_onion_message(&intermediate_hops, Destination::BlindedRoute(blinded_route)); +/// ``` /// /// [offers]: +/// [`OnionMessenger`]: crate::onion_message::OnionMessenger pub struct OnionMessenger where K::Target: KeysInterface, L::Target: Logger, @@ -79,6 +126,7 @@ impl OnionMessenger } /// Send an empty onion message to `destination`, routing it through `intermediate_nodes`. + /// See [`OnionMessenger`] for example usage. pub fn send_onion_message(&self, intermediate_nodes: &[PublicKey], destination: Destination) -> Result<(), secp256k1::Error> { let blinding_secret_bytes = self.keys_manager.get_secure_random_bytes(); let blinding_secret = SecretKey::from_slice(&blinding_secret_bytes[..]).expect("RNG is busted"); diff --git a/lightning/src/onion_message/mod.rs b/lightning/src/onion_message/mod.rs index 9236341fa..a874fbc43 100644 --- a/lightning/src/onion_message/mod.rs +++ b/lightning/src/onion_message/mod.rs @@ -8,6 +8,17 @@ // licenses. //! Onion Messages: sending, receiving, forwarding, and ancillary utilities live here +//! +//! Onion messages are multi-purpose messages sent between peers over the lightning network. In the +//! near future, they will be used to communicate invoices for [offers], unlocking use cases such as +//! static invoices, refunds and proof of payer. Further, you will be able to accept payments +//! without revealing your node id through the use of [blinded routes]. +//! +//! LDK sends and receives onion messages via the [`OnionMessenger`]. See its documentation for more +//! information on its usage. +//! +//! [offers]: +//! [blinded routes]: crate::onion_message::BlindedRoute mod blinded_route; mod messenger; -- 2.39.5