Public api changes

This commit covers the initial public API changes for onion messages and
subsequent documentation updates

Author: valentinewallace

lightning/src/ln/msgs.rs

@@ -724,6 +724,17 @@ enum EncodingType {
 	Uncompressed = 0x00,
 }
 
+/// An onion message to be sent or received from a peer
+#[derive(Clone, Debug, PartialEq)]
+pub struct OnionMessage {
+	/// The blinding point used in the shared secret that is used to decrypt the onion message's
+	/// `encrypted_data` field.
+	pub blinding_point: PublicKey,
+	/// The length of the onion message routing packet.
+	pub len: u16,
+	pub(crate) onion_routing_packet: OnionPacket,
+}
+
 /// Used to put an error message in a LightningError
 #[derive(Clone, Debug)]
 pub enum ErrorAction {
@@ -909,6 +920,13 @@ pub trait RoutingMessageHandler : MessageSendEventsProvider {
 	fn handle_query_short_channel_ids(&self, their_node_id: &PublicKey, msg: QueryShortChannelIds) -> Result<(), LightningError>;
 }
 
+/// A trait to describe an object that can receive onion messages.
+pub trait OnionMessageHandler {
+	/// Handle an incoming onion_message message from the given peer.
+	fn handle_onion_message(&self, their_node_id: &PublicKey, msg: &OnionMessage);
+
+}
+
 mod fuzzy_internal_msgs {
 	use prelude::*;
 	use ln::{PaymentPreimage, PaymentSecret};

lightning/src/ln/onion_message.rs

@@ -0,0 +1,61 @@
+/// The payload of an inbound onion message.
+pub struct Payload {
+	/// Onion message senders may transmit custom TLVs for the recipient.
+	custom_tlvs: Vec<CustomTlv>,
+	// Coming soon: path_id, reply_path
+}
+
+/// 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.
+pub struct OnionMessager<Signer: Sign, K: Deref>
+where K::Target: KeysInterface<Signer = Signer>
+{
+	keys_manager: K,
+	/// When `OnionMessager` receives onion messages for which our node is the final destination, it
+	/// delegates these messages' payloads to this handler. See [`Receive`] for more information.
+	inbound_handler: Receive,
+	pending_msg_events: Vec<MessageSendEvent>,
+}
+
+/// `Receive` defines behavior for receiving the final payload of an inbound onion message. Since
+/// these [`Payload`]s contain a list of custom TLVs that are unknown to LDK, it is up to the user
+/// how to handle them.
+///
+/// Until LDK implements BOLT 12 offers in upcoming releases, it is recommended to use
+/// [`IgnoringReceiver`] unless you have a specific need to receive custom onion messages.
+pub trait Receive {
+	/// Receive an inbound onion message payload.
+	fn receive(payload: Payload);
+}
+
+/// A [`Receive`]r that simply ignores inbound onion messages.
+pub struct IgnoringReceiver {}
+impl Receive for IgnoringReceiver {
+	fn receive(payload: Payload) {}
+}
+
+impl<Signer: Sign, K: Deref> OnionMessager<Signer, K>
+	where K::Target: KeysInterface<Signer = Signer>,
+{
+	/// Constructs a new `OnionMessager` to send, forward, and receive onion messages.
+	pub fn new(keys_manager: K) -> Self {}
+
+	/// Send an empty onion message to `recipient`, routing it through `intermediate_nodes`.
+	///
+	/// LDK will not make peer connections for you, so you must be connected to the first hop of
+	/// `intermediate_nodes` for sending to work.
+	// NOTE: sending custom TLVs, reply paths, and sending to blinded routes aren't included atm
+ 	pub fn send_onion_message(&self, recipient: PublicKey, intermediate_nodes: Vec<PublicKey>) -> Result<(), APIError> {}
+}
+
+impl OnionMessageHandler for OnionMessager {
+	fn handle_onion_message(&self, peer_node_id: &PublicKey, msg: &msgs::OnionMessage) {
+	}
+}
+
+/// Useful for simplifying the parameters of [`SimpleArcChannelManager`] and
+/// [`SimpleArcPeerManager`]. See their docs for more details.
+pub type SimpleArcOnionMessager = OnionMessager<Arc<KeysManager>>;
+/// Useful for simplifying the parameters of [`SimpleRefChannelManager`] and
+/// [`SimpleRefPeerManager`]. See their docs for more details.
+pub type SimpleRefOnionMessager<'a> = OnionMessager<&'a KeysManager>;

lightning/src/ln/peer_handler.rs

@@ -197,10 +197,16 @@ impl Deref for ErroringMessageHandler {
 	fn deref(&self) -> &Self { self }
 }
 
+impl OnionMessageHandler for IgnoringMessageHandler {
+	fn handle_onion_message(&self, _their_node_id: &PublicKey, _msg: &msgs::OnionMessage) {}
+}
+
 /// Provides references to trait impls which handle different types of messages.
-pub struct MessageHandler<CM: Deref, RM: Deref> where
+pub struct MessageHandler<CM: Deref, RM: Deref, OM: Deref> where
 		CM::Target: ChannelMessageHandler,
-		RM::Target: RoutingMessageHandler {
+		RM::Target: RoutingMessageHandler,
+		OM::Target: OnionMessageHandler,
+{
 	/// A message handler which handles messages specific to channels. Usually this is just a
 	/// [`ChannelManager`] object or an [`ErroringMessageHandler`].
 	///
@@ -212,6 +218,11 @@ pub struct MessageHandler<CM: Deref, RM: Deref> where
 	///
 	/// [`NetGraphMsgHandler`]: crate::routing::network_graph::NetGraphMsgHandler
 	pub route_handler: RM,
+	/// A message handler which handles onion messages. Using this is just an [`OnionMessager`]
+	/// object or an [`IgnoringMessageHandler`].
+	///
+	/// [`OnionMessager`]: crate::ln::onion_messages::OnionMessager
+	pub onion_message_handler: OM,
 }
 
 /// Provides an object which can be used to send data to and which uniquely identifies a connection
@@ -379,7 +390,7 @@ struct PeerHolder<Descriptor: SocketDescriptor> {
 /// issues such as overly long function definitions.
 ///
 /// (C-not exported) as Arcs don't make sense in bindings
-pub type SimpleArcPeerManager<SD, M, T, F, C, L> = PeerManager<SD, Arc<SimpleArcChannelManager<M, T, F, L>>, Arc<NetGraphMsgHandler<Arc<NetworkGraph>, Arc<C>, Arc<L>>>, Arc<L>, Arc<IgnoringMessageHandler>>;
+ pub type SimpleArcPeerManager<SD, M, T, F, C, L> = PeerManager<SD, Arc<SimpleArcChannelManager<M, T, F, L>>, Arc<NetGraphMsgHandler<Arc<NetworkGraph>, Arc<C>, Arc<L>>>, Arc<L>, SimpleArcOnionMessager, Arc<IgnoringMessageHandler>>;
 
 /// SimpleRefPeerManager is a type alias for a PeerManager reference, and is the reference
 /// counterpart to the SimpleArcPeerManager type alias. Use this type by default when you don't
@@ -389,7 +400,7 @@ pub type SimpleArcPeerManager<SD, M, T, F, C, L> = PeerManager<SD, Arc<SimpleArc
 /// helps with issues such as long function definitions.
 ///
 /// (C-not exported) as Arcs don't make sense in bindings
-pub type SimpleRefPeerManager<'a, 'b, 'c, 'd, 'e, 'f, 'g, 'h, SD, M, T, F, C, L> = PeerManager<SD, SimpleRefChannelManager<'a, 'b, 'c, 'd, 'e, M, T, F, L>, &'e NetGraphMsgHandler<&'g NetworkGraph, &'h C, &'f L>, &'f L, IgnoringMessageHandler>;
+ pub type SimpleRefPeerManager<'a, 'b, 'c, 'd, 'e, 'f, 'g, 'h, SD, M, T, F, C, L> = PeerManager<SD, SimpleRefChannelManager<'a, 'b, 'c, 'd, 'e, M, T, F, L>, &'e NetGraphMsgHandler<&'g NetworkGraph, &'h C, &'f L>, SimpleRefOnionMessager<'c>, &'f L, IgnoringMessageHandler>;
 
 /// A PeerManager manages a set of peers, described by their [`SocketDescriptor`] and marshalls
 /// socket events into messages which it passes on to its [`MessageHandler`].
@@ -410,12 +421,13 @@ pub type SimpleRefPeerManager<'a, 'b, 'c, 'd, 'e, 'f, 'g, 'h, SD, M, T, F, C, L>
 /// you're using lightning-net-tokio.
 ///
 /// [`read_event`]: PeerManager::read_event
-pub struct PeerManager<Descriptor: SocketDescriptor, CM: Deref, RM: Deref, L: Deref, CMH: Deref> where
+pub struct PeerManager<Descriptor: SocketDescriptor, CM: Deref, RM: Deref, OM: Deref, L: Deref, CMH: Deref> where
 		CM::Target: ChannelMessageHandler,
 		RM::Target: RoutingMessageHandler,
+		OM::Target: OnionMessageHandler,
 		L::Target: Logger,
 		CMH::Target: CustomMessageHandler {
-	message_handler: MessageHandler<CM, RM>,
+	message_handler: MessageHandler<CM, RM, OM>,
 	peers: Mutex<PeerHolder<Descriptor>>,
 	our_node_secret: SecretKey,
 	ephemeral_key_midstate: Sha256Engine,
@@ -451,31 +463,32 @@ macro_rules! encode_msg {
 	}}
 }
 
-impl<Descriptor: SocketDescriptor, CM: Deref, L: Deref> PeerManager<Descriptor, CM, IgnoringMessageHandler, L, IgnoringMessageHandler> where
+impl<Descriptor: SocketDescriptor, CM: Deref, OM: Deref, L: Deref> PeerManager<Descriptor, CM, IgnoringMessageHandler, OM, L, IgnoringMessageHandler> where
 		CM::Target: ChannelMessageHandler,
+		OM::Target: OnionMessageHandler,
 		L::Target: Logger {
-	/// Constructs a new PeerManager with the given ChannelMessageHandler. No routing message
-	/// handler is used and network graph messages are ignored.
+	/// Constructs a new PeerManager with the given ChannelMessageHandler and OnionMessageHandler. No
+	/// routing message handler is used and network graph messages are ignored.
 	///
 	/// ephemeral_random_data is used to derive per-connection ephemeral keys and must be
 	/// cryptographically secure random bytes.
 	///
 	/// (C-not exported) as we can't export a PeerManager with a dummy route handler
-	pub fn new_channel_only(channel_message_handler: CM, our_node_secret: SecretKey, ephemeral_random_data: &[u8; 32], logger: L) -> Self {
+	pub fn new_channel_only(channel_message_handler: CM, onion_message_handler: OM, our_node_secret: SecretKey, ephemeral_random_data: &[u8; 32], logger: L) -> Self {
 		Self::new(MessageHandler {
 			chan_handler: channel_message_handler,
 			route_handler: IgnoringMessageHandler{},
 		}, our_node_secret, ephemeral_random_data, logger, IgnoringMessageHandler{})
 	}
 }
 
-impl<Descriptor: SocketDescriptor, RM: Deref, L: Deref> PeerManager<Descriptor, ErroringMessageHandler, RM, L, IgnoringMessageHandler> where
+impl<Descriptor: SocketDescriptor, RM: Deref, L: Deref> PeerManager<Descriptor, ErroringMessageHandler, RM, IgnoringMessageHandler, L, IgnoringMessageHandler> where
 		RM::Target: RoutingMessageHandler,
 		L::Target: Logger {
-	/// Constructs a new PeerManager with the given RoutingMessageHandler. No channel message
-	/// handler is used and messages related to channels will be ignored (or generate error
-	/// messages). Note that some other lightning implementations time-out connections after some
-	/// time if no channel is built with the peer.
+	/// Constructs a new PeerManager with the given RoutingMessageHandler. No channel message handler
+	/// or onion message handler is used and messages related to channels will be ignored (or generate
+	/// error messages). Note that some other lightning implementations time-out connections after
+	/// some time if no channel is built with the peer.
 	///
 	/// ephemeral_random_data is used to derive per-connection ephemeral keys and must be
 	/// cryptographically secure random bytes.

lightning/src/util/events.rs

@@ -933,6 +933,13 @@ pub enum MessageSendEvent {
 		/// The gossip_timestamp_filter which should be sent.
 		msg: msgs::GossipTimestampFilter,
 	},
+	/// Sends an onion message.
+	SendOnionMessage {
+		/// The node_id of this message recipient
+		node_id: PublicKey,
+		/// The onion message which should be sent.
+		msg: msgs::OnionMessage,
+	},
 }
 
 /// A trait indicating an object may generate message send events