AsyncPaymentsMessageHandler trait for OnionMessenger

Add a trait for handling async payments messages to OnionMessenger. This allows
users to either provide their own custom handling for async payments messages
or rely on a version provided by LDK.

Author: valentinewallace

fuzz/src/onion_message.rs

@@ -12,6 +12,7 @@ use lightning::ln::msgs::{self, DecodeError, OnionMessageHandler};
 use lightning::ln::script::ShutdownScript;
 use lightning::offers::invoice::UnsignedBolt12Invoice;
 use lightning::offers::invoice_request::UnsignedInvoiceRequest;
+use lightning::onion_message::async_payments::{AsyncPaymentsMessage, AsyncPaymentsMessageHandler};
 use lightning::onion_message::messenger::{
 	CustomOnionMessageHandler, Destination, MessageRouter, OnionMessagePath, OnionMessenger,
 	PendingOnionMessage, Responder, ResponseInstruction,
@@ -39,6 +40,7 @@ pub fn do_test<L: Logger>(data: &[u8], logger: &L) {
 		let node_id_lookup = EmptyNodeIdLookUp {};
 		let message_router = TestMessageRouter {};
 		let offers_msg_handler = TestOffersMessageHandler {};
+		let async_payments_msg_handler = TestAsyncPaymentsMessageHandler {};
 		let custom_msg_handler = TestCustomMessageHandler {};
 		let onion_messenger = OnionMessenger::new(
 			&keys_manager,
@@ -47,6 +49,7 @@ pub fn do_test<L: Logger>(data: &[u8], logger: &L) {
 			&node_id_lookup,
 			&message_router,
 			&offers_msg_handler,
+			&async_payments_msg_handler,
 			&custom_msg_handler,
 		);
 
@@ -105,6 +108,16 @@ impl OffersMessageHandler for TestOffersMessageHandler {
 	}
 }
 
+struct TestAsyncPaymentsMessageHandler {}
+
+impl AsyncPaymentsMessageHandler for TestAsyncPaymentsMessageHandler {
+	fn handle_message(
+		&self, _message: AsyncPaymentsMessage, _responder: Option<Responder>,
+	) -> ResponseInstruction<AsyncPaymentsMessage> {
+		ResponseInstruction::NoResponse
+	}
+}
+
 #[derive(Debug)]
 struct TestCustomMessage {}
 

lightning/src/ln/functional_test_utils.rs

@@ -421,6 +421,7 @@ type TestOnionMessenger<'chan_man, 'node_cfg, 'chan_mon_cfg> = OnionMessenger<
 	&'node_cfg test_utils::TestMessageRouter<'chan_mon_cfg>,
 	&'chan_man TestChannelManager<'node_cfg, 'chan_mon_cfg>,
 	IgnoringMessageHandler,
+	IgnoringMessageHandler,
 >;
 
 /// For use with [`OnionMessenger`] otherwise `test_restored_packages_retry` will fail. This is
@@ -3228,7 +3229,7 @@ pub fn create_network<'a, 'b: 'a, 'c: 'b>(node_count: usize, cfgs: &'b Vec<NodeC
 		let dedicated_entropy = DedicatedEntropy(RandomBytes::new([i as u8; 32]));
 		let onion_messenger = OnionMessenger::new(
 			dedicated_entropy, cfgs[i].keys_manager, cfgs[i].logger, &chan_mgrs[i],
-			&cfgs[i].message_router, &chan_mgrs[i], IgnoringMessageHandler {},
+			&cfgs[i].message_router, &chan_mgrs[i], IgnoringMessageHandler {}, IgnoringMessageHandler {},
 		);
 		let gossip_sync = P2PGossipSync::new(cfgs[i].network_graph.as_ref(), None, cfgs[i].logger);
 		let wallet_source = Arc::new(test_utils::TestWalletSource::new(SecretKey::from_slice(&[i as u8 + 1; 32]).unwrap()));

lightning/src/ln/peer_handler.rs

@@ -28,6 +28,7 @@ use crate::util::ser::{VecWriter, Writeable, Writer};
 use crate::ln::peer_channel_encryptor::{PeerChannelEncryptor, NextNoiseStep, MessageBuf, MSG_BUF_ALLOC_SIZE};
 use crate::ln::wire;
 use crate::ln::wire::{Encode, Type};
+use crate::onion_message::async_payments::{AsyncPaymentsMessage, AsyncPaymentsMessageHandler};
 use crate::onion_message::messenger::{CustomOnionMessageHandler, PendingOnionMessage, Responder, ResponseInstruction};
 use crate::onion_message::offers::{OffersMessage, OffersMessageHandler};
 use crate::onion_message::packet::OnionMessageContents;
@@ -148,6 +149,11 @@ impl OffersMessageHandler for IgnoringMessageHandler {
 		ResponseInstruction::NoResponse
 	}
 }
+impl AsyncPaymentsMessageHandler for IgnoringMessageHandler {
+	fn handle_message(&self, _message: AsyncPaymentsMessage, _responder: Option<Responder>) -> ResponseInstruction<AsyncPaymentsMessage> {
+		ResponseInstruction::NoResponse
+	}
+}
 impl CustomOnionMessageHandler for IgnoringMessageHandler {
 	type CustomMessage = Infallible;
 	fn handle_custom_message(&self, _message: Self::CustomMessage, _responder: Option<Responder>) -> ResponseInstruction<Self::CustomMessage> {

lightning/src/onion_message/async_payments.rs

@@ -11,13 +11,54 @@
 
 use crate::io;
 use crate::ln::msgs::DecodeError;
+use crate::onion_message::messenger::PendingOnionMessage;
+use crate::onion_message::messenger::{Responder, ResponseInstruction};
 use crate::onion_message::packet::OnionMessageContents;
 use crate::util::ser::{Readable, ReadableArgs, Writeable, Writer};
 
 // TLV record types for the `onionmsg_tlv` TLV stream as defined in BOLT 4.
 const HELD_HTLC_AVAILABLE_TLV_TYPE: u64 = 72;
 const RELEASE_HELD_HTLC_TLV_TYPE: u64 = 74;
 
+/// A handler for an [`OnionMessage`] containing an async payments message as its payload.
+///
+/// [`OnionMessage`]: crate::ln::msgs::OnionMessage
+pub trait AsyncPaymentsMessageHandler {
+	/// Handles the given message by either releasing a held HTLC, sending a payment, or replying with
+	/// an error.
+	///
+	/// The returned [`AsyncPaymentsMessage`], if any, is enqueued to be sent by [`OnionMessenger`].
+	///
+	/// [`OnionMessenger`]: crate::onion_message::messenger::OnionMessenger
+	fn handle_message(
+		&self, message: AsyncPaymentsMessage, responder: Option<Responder>,
+	) -> ResponseInstruction<AsyncPaymentsMessage>;
+
+	/// Releases any [`AsyncPaymentsMessage`]s that need to be sent.
+	///
+	/// Typically, this is used for messages initiating an async payment flow rather than in response
+	/// to another message. The latter should use the return value of [`Self::handle_message`].
+	#[cfg(not(c_bindings))]
+	fn release_pending_messages(&self) -> Vec<PendingOnionMessage<AsyncPaymentsMessage>> {
+		vec![]
+	}
+
+	/// Releases any [`AsyncPaymentsMessage`]s that need to be sent.
+	///
+	/// Typically, this is used for messages initiating a payment flow rather than in response to
+	/// another message. The latter should use the return value of [`Self::handle_message`].
+	#[cfg(c_bindings)]
+	fn release_pending_messages(
+		&self,
+	) -> Vec<(
+		AsyncPaymentsMessage,
+		crate::onion_message::messenger::Destination,
+		Option<crate::blinded_path::BlindedPath>,
+	)> {
+		vec![]
+	}
+}
+
 /// Possible async payment messages sent and received via an [`OnionMessage`].
 ///
 /// [`OnionMessage`]: crate::ln::msgs::OnionMessage

lightning/src/onion_message/functional_tests.rs

@@ -19,6 +19,7 @@ use crate::routing::test_utils::{add_channel, add_or_update_node};
 use crate::sign::{NodeSigner, Recipient};
 use crate::util::ser::{FixedLengthReader, LengthReadable, Writeable, Writer};
 use crate::util::test_utils;
+use super::async_payments::{AsyncPaymentsMessage, AsyncPaymentsMessageHandler};
 use super::messenger::{CustomOnionMessageHandler, DefaultMessageRouter, Destination, OnionMessagePath, OnionMessenger, PendingOnionMessage, Responder, ResponseInstruction, SendError, SendSuccess};
 use super::offers::{OffersMessage, OffersMessageHandler};
 use super::packet::{OnionMessageContents, Packet};
@@ -50,6 +51,7 @@ struct MessengerNode {
 			Arc<test_utils::TestKeysInterface>
 		>>,
 		Arc<TestOffersMessageHandler>,
+		Arc<TestAsyncPaymentsMessageHandler>,
 		Arc<TestCustomMessageHandler>
 	>,
 	custom_message_handler: Arc<TestCustomMessageHandler>,
@@ -79,6 +81,14 @@ impl OffersMessageHandler for TestOffersMessageHandler {
 	}
 }
 
+struct TestAsyncPaymentsMessageHandler {}
+
+impl AsyncPaymentsMessageHandler for TestAsyncPaymentsMessageHandler {
+	fn handle_message(&self, _message: AsyncPaymentsMessage, _responder: Option<Responder>) -> ResponseInstruction<AsyncPaymentsMessage> {
+		ResponseInstruction::NoResponse
+	}
+}
+
 #[derive(Clone, Debug, PartialEq)]
 enum TestCustomMessage {
 	Ping,
@@ -249,18 +259,19 @@ fn create_nodes_using_cfgs(cfgs: Vec<MessengerCfg>) -> Vec<MessengerNode> {
 			DefaultMessageRouter::new(network_graph.clone(), entropy_source.clone())
 		);
 		let offers_message_handler = Arc::new(TestOffersMessageHandler {});
+		let async_payments_message_handler = Arc::new(TestAsyncPaymentsMessageHandler {});
 		let custom_message_handler = Arc::new(TestCustomMessageHandler::new());
 		let messenger = if cfg.intercept_offline_peer_oms {
 			OnionMessenger::new_with_offline_peer_interception(
 				entropy_source.clone(), node_signer.clone(), logger.clone(),
 				node_id_lookup, message_router, offers_message_handler,
-				custom_message_handler.clone()
+				async_payments_message_handler, custom_message_handler.clone()
 			)
 		} else {
 			OnionMessenger::new(
 				entropy_source.clone(), node_signer.clone(), logger.clone(),
 				node_id_lookup, message_router, offers_message_handler,
-				custom_message_handler.clone()
+				async_payments_message_handler, custom_message_handler.clone()
 			)
 		};
 		nodes.push(MessengerNode {