Add module-level documentation for onion messages

Author: valentinewallace

lightning/src/onion_message.rs

@@ -8,6 +8,61 @@
 // 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].
+//!
+//! # Example
+//!
+//! ```
+//! # use lightning::chain::keysinterface::{KeysManager, KeysInterface};
+//! # use lightning::onion_message::{BlindedRoute, OnionMessenger};
+//! # use lightning::util::logger::{Logger, Record};
+//! # 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 = Arc::new(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 hop_node_id1 = PublicKey::from_secret_key(&secp_ctx, &node_secret);
+//! # let hop_node_id2 = hop_node_id1.clone();
+//! # let destination_node_id = hop_node_id1.clone();
+//! #
+//! // 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);
+//!
+//! // Hook up the OnionMessenger to your PeerManager, for sending and receiving messages on the
+//! // wire.
+//! # let chan_handler = IgnoringMessageHandler {};
+//! # let route_handler = IgnoringMessageHandler {};
+//! # let custom_message_handler = IgnoringMessageHandler {};
+//! # let rand_bytes = [0; 32];
+//! let message_handler = MessageHandler { chan_handler, route_handler, onion_messenger };
+//! let peer_manager = PeerManager::new(message_handler, node_secret, &rand_bytes, logger,
+//! custom_message_handler);
+//!
+//! // Send an empty onion message to a node id.
+//! let intermediate_hops = vec![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 secp_ctx = Secp256k1::new();
+//! # let your_node_id = hop_node_id1.clone();
+//! let hops = vec![hop_node_id_1, hop_node_id_2, your_node_id];
+//! let blinded_route = BlindedRoute::new(hops, keys_manager, &secp_ctx).unwrap();
+//!
+//! // Send an empty onion message to a blinded route.
+//! onion_messenger.send_onion_message(intermediate_hops, Destination::BlindedRoute(blinded_route));
+//! ```
+//!
+//! [Offers]: https://github.com/lightning/bolts/pull/798
+//! [blinded routes]: crate::onion_message::BlindedRoute
 use bitcoin::hashes::{Hash, HashEngine};
 use bitcoin::hashes::hmac::{Hmac, HmacEngine};
 use bitcoin::hashes::sha256::Hash as Sha256;