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: Result<PublicKey, secp256k1::Error>,
+	/// 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,12 @@ 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 : MessageSendEventsProvider {
+	/// 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,96 @@
+/// Used to construct the blinded hops portion of a blinded route. These hops cannot be identified
+/// by outside observers and thus can be used to hide the identity of the recipient.
+pub struct BlindedNode {
+	/// The blinded node id of this hop in a blinded route.
+	pub blinded_node_id: PublicKey,
+	/// The encrypted payload intended for this hop in a blinded route.
+	pub encrypted_payload: Vec<u8>,
+}
+
+/// Onion messages can be sent and received to blinded routes, which serve to hide the identity of
+/// the recipient.
+pub struct BlindedRoute {
+	/// To send to a blinded route, the sender first finds a route to the unblinded
+	/// `introduction_node_id`, which can unblind its [`encrypted_payload`] to find out the onion
+	/// message's next hop and forward it along.
+	///
+	/// [`encrypted_payload`]: BlindedNode::encrypted_payload
+	pub introduction_node_id: PublicKey,
+	/// Creators of blinded routes supply the introduction node id's `blinding_point`, which the
+	/// introduction node will use in decrypting its [`encrypted_payload`] to forward the onion
+	/// message.
+	///
+	/// [`encrypted_payload`]: BlindedNode::encrypted_payload
+	pub blinding_point: PublicKey,
+	/// The blinded hops of the blinded route.
+	pub blinded_hops: Vec<BlindedNode>,
+}
+
+impl BlindedRoute {
+	/// Create a blinded route to be forwarded along `hops`.
+	pub fn new<Signer: Sign, K: Deref>(hops: Vec<PublicKey>, keys_manager: K) -> Result<Self, secp256k1::Error>
+		where K::Target: KeysInterface<Signer = Signer> {}
+}
+
+/// The final destination of an onion message.
+pub enum Destination {
+	/// We're sending this onion message to a node.
+	Node(PublicKey),
+	/// We're sending this onion message to a blinded route.
+	BlindedRoute(BlindedRoute),
+}
+
+/// 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,
+	// Coming soon:
+	// invoice_handler: InvoiceHandler,
+	// custom_handler: CustomHandler, // handles custom onion messages
+	pending_msg_events: Vec<MessageSendEvent>,
+}
+
+// Coming soon:
+// /// `InvoiceHandler` handles incoming invoice requests, invoices, and invoice errors.
+// pub trait InvoiceHandler {
+//   /// Handles an incoming invoice request.
+//   fn handle_invoice_request(invoice_request: InvoiceRequest) -> Result<Invoice, ()>;
+//   // Handles an incoming invoice.
+//   fn handle_invoice(invoice: Invoice) -> Result<(), ()>;
+//   // Handles an incoming invoice error.
+//   fn handle_invoice_error(invoice_error: InvoiceError);
+//   // Sends a payment.
+//   fn send_payment(..);
+// }
+
+impl<Signer: Sign, K: Deref> OnionMessager<Signer, K>
+	where K::Target: KeysInterface<Signer = Signer>,
+{
+	/// Constructs a new `OnionMessager` to send, forward, and delegate received onion messages to
+	/// their respective handlers.
+	pub fn new(keys_manager: K) -> Self {}
+
+	/// Send an empty onion message to `recipient`, routing it through `intermediate_nodes`.
+	// NOTE: sending custom TLVs and reply paths aren't included atm
+	pub fn send_onion_message(&self, recipient: Destination, 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>;
+
+impl<Signer: Sign, K: Deref> MessageSendEventsProvider for OnionMessager<Signer, K>
+where K::Target: KeysInterface<Signer = Signer>
+{
+	fn get_and_clear_pending_msg_events(&self) -> Vec<MessageSendEvent> {}
+}

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. Usually 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