Support spontaneous payments in InvoicePayer

InvoicePayer handles retries not only when handling PaymentPathFailed
events but also for some types of PaymentSendFailure on the initial
send. Expand InvoicePayer's interface with a pay_pubkey function for
spontaneous (keysend) payments. Add a send_spontaneous_payment function
to the Payer trait to support this and implement it for ChannelManager.

Author: jkczyz

lightning-invoice/src/payment.rs

@@ -27,7 +27,7 @@
 //! # extern crate lightning_invoice;
 //! # extern crate secp256k1;
 //! #
-//! # use lightning::ln::{PaymentHash, PaymentSecret};
+//! # use lightning::ln::{PaymentHash, PaymentPreimage, PaymentSecret};
 //! # use lightning::ln::channelmanager::{ChannelDetails, PaymentId, PaymentSendFailure};
 //! # use lightning::ln::msgs::LightningError;
 //! # use lightning::routing;
@@ -53,6 +53,9 @@
 //! #     fn send_payment(
 //! #         &self, route: &Route, payment_hash: PaymentHash, payment_secret: &Option<PaymentSecret>
 //! #     ) -> Result<PaymentId, PaymentSendFailure> { unimplemented!() }
+//! #     fn send_spontaneous_payment(
+//! #         &self, route: &Route, payment_preimage: PaymentPreimage
+//! #     ) -> Result<PaymentId, PaymentSendFailure> { unimplemented!() }
 //! #     fn retry_payment(
 //! #         &self, route: &Route, payment_id: PaymentId
 //! #     ) -> Result<(), PaymentSendFailure> { unimplemented!() }
@@ -110,11 +113,12 @@
 //! as updates to the network graph or changes to channel scores should be applied prior to
 //! retries, typically by way of composing [`EventHandler`]s accordingly.
 
-use crate::Invoice;
+use crate::{DEFAULT_MIN_FINAL_CLTV_EXPIRY, Invoice};
 
 use bitcoin_hashes::Hash;
+use bitcoin_hashes::sha256::Hash as Sha256;
 
-use lightning::ln::{PaymentHash, PaymentSecret};
+use lightning::ln::{PaymentHash, PaymentPreimage, PaymentSecret};
 use lightning::ln::channelmanager::{ChannelDetails, PaymentId, PaymentSendFailure};
 use lightning::ln::msgs::LightningError;
 use lightning::routing;
@@ -161,6 +165,11 @@ pub trait Payer {
 		&self, route: &Route, payment_hash: PaymentHash, payment_secret: &Option<PaymentSecret>
 	) -> Result<PaymentId, PaymentSendFailure>;
 
+	/// Sends a spontaneous payment over the Lightning Network using the given [`Route`].
+	fn send_spontaneous_payment(
+		&self, route: &Route, payment_preimage: PaymentPreimage
+	) -> Result<PaymentId, PaymentSendFailure>;
+
 	/// Retries a failed payment path for the [`PaymentId`] using the given [`Route`].
 	fn retry_payment(&self, route: &Route, payment_id: PaymentId) -> Result<(), PaymentSendFailure>;
 }
@@ -282,15 +291,54 @@ where
 			final_cltv_expiry_delta: invoice.min_final_cltv_expiry() as u32,
 		};
 
-		self.pay_internal(&mut entry, &params, payment_hash, &payment_secret)
+		let send_payment = |route: &Route| {
+			self.payer.send_payment(route, payment_hash, &payment_secret)
+		};
+		self.pay_internal(&mut entry, &params, send_payment)
+			.map_err(|e| { entry.remove(); e })
+	}
+
+	/// Pays `pubkey` an amount using the hash of the given preimage, caching it for later use in
+	/// case a retry is needed.
+	///
+	/// You should ensure that `payment_preimage` is unique and that its `payment_hash` has never
+	/// been paid before. Because [`InvoicePayer`] is stateless no effort is made to do so for you.
+	pub fn pay_pubkey(
+		&self, pubkey: PublicKey, payment_preimage: PaymentPreimage, amount_msats: u64
+	) -> Result<PaymentId, PaymentError> {
+		let payment_hash = PaymentHash(Sha256::hash(&payment_preimage.0).into_inner());
+		let mut payment_cache = self.payment_cache.lock().unwrap();
+		let mut entry = match payment_cache.entry(payment_hash) {
+			hash_map::Entry::Occupied(_) => return Err(PaymentError::Invoice("payment pending")),
+			hash_map::Entry::Vacant(entry) => {
+				// TODO: Replace with hash_map::Entry::insert once no longer experimental
+				entry.insert(0);
+				match payment_cache.entry(payment_hash) {
+					hash_map::Entry::Occupied(entry) => entry,
+					hash_map::Entry::Vacant(_) => unreachable!(),
+				}
+			},
+		};
+
+		let payee = Payee::for_keysend(pubkey);
+		let params = RouteParameters {
+			payee,
+			final_value_msat: amount_msats,
+			final_cltv_expiry_delta: DEFAULT_MIN_FINAL_CLTV_EXPIRY as u32,
+		};
+
+		let send_payment = |route: &Route| {
+			self.payer.send_spontaneous_payment(route, payment_preimage)
+		};
+		self.pay_internal(&mut entry, &params, send_payment)
 			.map_err(|e| { entry.remove(); e })
 	}
 
-	fn pay_internal(
-		&self, entry: &mut PaymentEntry, params: &RouteParameters, payment_hash: PaymentHash,
-		payment_secret: &Option<PaymentSecret>,
+	fn pay_internal<F: FnOnce(&Route) -> Result<PaymentId, PaymentSendFailure> + Copy>(
+		&self, entry: &mut PaymentEntry, params: &RouteParameters, send_payment: F,
 	) -> Result<PaymentId, PaymentError> {
 		if has_expired(params) {
+			let payment_hash = entry.key();
 			log_trace!(self.logger, "Invoice expired prior to send for payment {}", log_bytes!(payment_hash.0));
 			return Err(PaymentError::Invoice("Invoice expired prior to send"));
 		}
@@ -304,7 +352,7 @@ where
 			&self.scorer.lock(),
 		).map_err(|e| PaymentError::Routing(e))?;
 
-		match self.payer.send_payment(&route, payment_hash, payment_secret) {
+		match send_payment(&route) {
 			Ok(payment_id) => Ok(payment_id),
 			Err(e) => match e {
 				PaymentSendFailure::ParameterError(_) => Err(e),
@@ -315,7 +363,7 @@ where
 						Err(e)
 					} else {
 						*retry_count += 1;
-						Ok(self.pay_internal(entry, params, payment_hash, payment_secret)?)
+						Ok(self.pay_internal(entry, params, send_payment)?)
 					}
 				},
 				PaymentSendFailure::PartialFailure { failed_paths_retry, payment_id, .. } => {
@@ -530,6 +578,10 @@ mod tests {
 			.unwrap()
 	}
 
+	fn pubkey() -> PublicKey {
+		PublicKey::from_slice(&hex::decode("02eec7245d6b7d2ccb30380bfbe2a3648cd7a942653f5aa340edcea1f283686619").unwrap()[..]).unwrap()
+	}
+
 	#[test]
 	fn pays_invoice_on_first_attempt() {
 		let event_handled = core::cell::RefCell::new(false);
@@ -985,6 +1037,55 @@ mod tests {
 		}
 	}
 
+	#[test]
+	fn pays_pubkey_with_amount() {
+		let event_handled = core::cell::RefCell::new(false);
+		let event_handler = |_: &_| { *event_handled.borrow_mut() = true; };
+
+		let pubkey = pubkey();
+		let payment_preimage = PaymentPreimage([1; 32]);
+		let payment_hash = PaymentHash(Sha256::hash(&payment_preimage.0).into_inner());
+		let final_value_msat = 100;
+
+		let payer = TestPayer::new()
+			.expect_send(Amount::Spontaneous(final_value_msat))
+			.expect_send(Amount::ForInvoiceOrRetry(final_value_msat));
+		let router = TestRouter {};
+		let scorer = RefCell::new(TestScorer::new());
+		let logger = TestLogger::new();
+		let invoice_payer =
+			InvoicePayer::new(&payer, router, &scorer, &logger, event_handler, RetryAttempts(2));
+
+		let payment_id =
+			Some(invoice_payer.pay_pubkey(pubkey, payment_preimage, final_value_msat).unwrap());
+		assert_eq!(*payer.attempts.borrow(), 1);
+
+		let retry = RouteParameters {
+			payee: Payee::for_keysend(pubkey),
+			final_value_msat,
+			final_cltv_expiry_delta: DEFAULT_MIN_FINAL_CLTV_EXPIRY as u32,
+		};
+		let event = Event::PaymentPathFailed {
+			payment_id,
+			payment_hash,
+			network_update: None,
+			rejected_by_dest: false,
+			all_paths_failed: false,
+			path: vec![],
+			short_channel_id: None,
+			retry: Some(retry),
+		};
+		invoice_payer.handle_event(&event);
+		assert_eq!(*event_handled.borrow(), false);
+		assert_eq!(*payer.attempts.borrow(), 2);
+
+		invoice_payer.handle_event(&Event::PaymentSent {
+			payment_id, payment_preimage, payment_hash, fee_paid_msat: None
+		});
+		assert_eq!(*event_handled.borrow(), true);
+		assert_eq!(*payer.attempts.borrow(), 2);
+	}
+
 	#[test]
 	fn scores_failed_channel() {
 		let event_handled = core::cell::RefCell::new(false);
@@ -1132,11 +1233,17 @@ mod tests {
 	}
 
 	struct TestPayer {
-		expectations: core::cell::RefCell<VecDeque<u64>>,
+		expectations: core::cell::RefCell<VecDeque<Amount>>,
 		attempts: core::cell::RefCell<usize>,
 		failing_on_attempt: Option<usize>,
 	}
 
+	#[derive(Clone, Debug, PartialEq, Eq)]
+	enum Amount {
+		ForInvoiceOrRetry(u64),
+		Spontaneous(u64),
+	}
+
 	impl TestPayer {
 		fn new() -> Self {
 			Self {
@@ -1147,6 +1254,11 @@ mod tests {
 		}
 
 		fn expect_value_msat(self, value_msat: u64) -> Self {
+			self.expectations.borrow_mut().push_back(Amount::ForInvoiceOrRetry(value_msat));
+			self
+		}
+
+		fn expect_send(self, value_msat: Amount) -> Self {
 			self.expectations.borrow_mut().push_back(value_msat);
 			self
 		}
@@ -1169,10 +1281,9 @@ mod tests {
 			}
 		}
 
-		fn check_value_msats(&self, route: &Route) {
+		fn check_value_msats(&self, actual_value_msats: Amount) {
 			let expected_value_msats = self.expectations.borrow_mut().pop_front();
 			if let Some(expected_value_msats) = expected_value_msats {
-				let actual_value_msats = route.get_total_amount();
 				assert_eq!(actual_value_msats, expected_value_msats);
 			}
 		}
@@ -1207,7 +1318,20 @@ mod tests {
 			_payment_secret: &Option<PaymentSecret>
 		) -> Result<PaymentId, PaymentSendFailure> {
 			if self.check_attempts() {
-				self.check_value_msats(route);
+				self.check_value_msats(Amount::ForInvoiceOrRetry(route.get_total_amount()));
+				Ok(PaymentId([1; 32]))
+			} else {
+				Err(PaymentSendFailure::ParameterError(APIError::MonitorUpdateFailed))
+			}
+		}
+
+		fn send_spontaneous_payment(
+			&self,
+			route: &Route,
+			_payment_preimage: PaymentPreimage,
+		) -> Result<PaymentId, PaymentSendFailure> {
+			if self.check_attempts() {
+				self.check_value_msats(Amount::Spontaneous(route.get_total_amount()));
 				Ok(PaymentId([1; 32]))
 			} else {
 				Err(PaymentSendFailure::ParameterError(APIError::MonitorUpdateFailed))
@@ -1218,7 +1342,7 @@ mod tests {
 			&self, route: &Route, _payment_id: PaymentId
 		) -> Result<(), PaymentSendFailure> {
 			if self.check_attempts() {
-				self.check_value_msats(route);
+				self.check_value_msats(Amount::ForInvoiceOrRetry(route.get_total_amount()));
 				Ok(())
 			} else {
 				Err(PaymentSendFailure::ParameterError(APIError::MonitorUpdateFailed))

lightning-invoice/src/utils.rs

@@ -8,7 +8,7 @@ use bitcoin_hashes::Hash;
 use lightning::chain;
 use lightning::chain::chaininterface::{BroadcasterInterface, FeeEstimator};
 use lightning::chain::keysinterface::{Sign, KeysInterface};
-use lightning::ln::{PaymentHash, PaymentSecret};
+use lightning::ln::{PaymentHash, PaymentPreimage, PaymentSecret};
 use lightning::ln::channelmanager::{ChannelDetails, ChannelManager, PaymentId, PaymentSendFailure, MIN_FINAL_CLTV_EXPIRY};
 use lightning::ln::msgs::LightningError;
 use lightning::routing;
@@ -141,6 +141,13 @@ where
 		self.send_payment(route, payment_hash, payment_secret)
 	}
 
+	fn send_spontaneous_payment(
+		&self, route: &Route, payment_preimage: PaymentPreimage,
+	) -> Result<PaymentId, PaymentSendFailure> {
+		self.send_spontaneous_payment(route, Some(payment_preimage))
+			.map(|(_, payment_id)| payment_id)
+	}
+
 	fn retry_payment(
 		&self, route: &Route, payment_id: PaymentId
 	) -> Result<(), PaymentSendFailure> {