Replace PaymentSecret with RecipientOnionFields in the pub API

This moves the public payment sending API from passing an explicit
`PaymentSecret` to a new `RecipientOnionFields` struct (which
currently only contains the `PaymentSecret`). This gives us
substantial additional flexibility as we look at add both
`PaymentMetadata`, a new (well, year-or-two-old) BOLT11 invoice
extension to provide additional data sent to the recipient.

In the future, we should also add the ability to add custom TLV
entries in the `RecipientOnionFields` struct.

Author: TheBlueMatt

fuzz/src/chanmon_consistency.rs

@@ -41,7 +41,7 @@ use lightning::chain::keysinterface::{KeyMaterial, InMemorySigner, Recipient, En
 use lightning::events;
 use lightning::events::MessageSendEventsProvider;
 use lightning::ln::{PaymentHash, PaymentPreimage, PaymentSecret};
-use lightning::ln::channelmanager::{ChainParameters, ChannelDetails, ChannelManager, PaymentSendFailure, ChannelManagerReadArgs, PaymentId};
+use lightning::ln::channelmanager::{ChainParameters, ChannelDetails, ChannelManager, PaymentSendFailure, ChannelManagerReadArgs, PaymentId, RecipientOnionFields};
 use lightning::ln::channel::FEE_SPIKE_BUFFER_FEE_INCREASE_MULTIPLE;
 use lightning::ln::msgs::{self, CommitmentUpdate, ChannelMessageHandler, DecodeError, UpdateAddHTLC, Init};
 use lightning::ln::script::ShutdownScript;
@@ -361,7 +361,7 @@ fn send_payment(source: &ChanMan, dest: &ChanMan, dest_chan_id: u64, amt: u64, p
 			cltv_expiry_delta: 200,
 		}]],
 		payment_params: None,
-	}, payment_hash, &Some(payment_secret), PaymentId(payment_id)) {
+	}, payment_hash, RecipientOnionFields::secret_only(payment_secret), PaymentId(payment_id)) {
 		check_payment_err(err);
 		false
 	} else { true }
@@ -390,7 +390,7 @@ fn send_hop_payment(source: &ChanMan, middle: &ChanMan, middle_chan_id: u64, des
 			cltv_expiry_delta: 200,
 		}]],
 		payment_params: None,
-	}, payment_hash, &Some(payment_secret), PaymentId(payment_id)) {
+	}, payment_hash, RecipientOnionFields::secret_only(payment_secret), PaymentId(payment_id)) {
 		check_payment_err(err);
 		false
 	} else { true }

fuzz/src/full_stack.rs

@@ -37,7 +37,7 @@ use lightning::chain::transaction::OutPoint;
 use lightning::chain::keysinterface::{InMemorySigner, Recipient, KeyMaterial, EntropySource, NodeSigner, SignerProvider};
 use lightning::events::Event;
 use lightning::ln::{PaymentHash, PaymentPreimage, PaymentSecret};
-use lightning::ln::channelmanager::{ChainParameters, ChannelDetails, ChannelManager, PaymentId};
+use lightning::ln::channelmanager::{ChainParameters, ChannelDetails, ChannelManager, PaymentId, RecipientOnionFields};
 use lightning::ln::peer_handler::{MessageHandler,PeerManager,SocketDescriptor,IgnoringMessageHandler};
 use lightning::ln::msgs::{self, DecodeError};
 use lightning::ln::script::ShutdownScript;
@@ -525,7 +525,9 @@ pub fn do_test(data: &[u8], logger: &Arc<dyn Logger>) {
 				sha.input(&payment_hash.0[..]);
 				payment_hash.0 = Sha256::from_engine(sha).into_inner();
 				payments_sent += 1;
-				match channelmanager.send_payment(&route, payment_hash, &None, PaymentId(payment_hash.0)) {
+				match channelmanager.send_payment(&route, payment_hash,
+					RecipientOnionFields::spontaneous_empty(), PaymentId(payment_hash.0))
+				{
 					Ok(_) => {},
 					Err(_) => return,
 				}
@@ -552,7 +554,9 @@ pub fn do_test(data: &[u8], logger: &Arc<dyn Logger>) {
 				let mut payment_secret = PaymentSecret([0; 32]);
 				payment_secret.0[0..8].copy_from_slice(&be64_to_array(payments_sent));
 				payments_sent += 1;
-				match channelmanager.send_payment(&route, payment_hash, &Some(payment_secret), PaymentId(payment_hash.0)) {
+				match channelmanager.send_payment(&route, payment_hash,
+					RecipientOnionFields::secret_only(payment_secret), PaymentId(payment_hash.0))
+				{
 					Ok(_) => {},
 					Err(_) => return,
 				}

lightning-invoice/src/payment.rs

@@ -16,8 +16,8 @@ use bitcoin_hashes::Hash;
 use lightning::chain;
 use lightning::chain::chaininterface::{BroadcasterInterface, FeeEstimator};
 use lightning::chain::keysinterface::{NodeSigner, SignerProvider, EntropySource};
-use lightning::ln::{PaymentHash, PaymentSecret};
-use lightning::ln::channelmanager::{ChannelManager, PaymentId, Retry, RetryableSendFailure};
+use lightning::ln::PaymentHash;
+use lightning::ln::channelmanager::{ChannelManager, PaymentId, Retry, RetryableSendFailure, RecipientOnionFields};
 use lightning::routing::router::{PaymentParameters, RouteParameters, Router};
 use lightning::util::logger::Logger;
 
@@ -146,6 +146,7 @@ fn pay_invoice_using_amount<P: Deref>(
 ) -> Result<(), PaymentError> where P::Target: Payer {
 	let payment_hash = PaymentHash((*invoice.payment_hash()).into_inner());
 	let payment_secret = Some(*invoice.payment_secret());
+	let recipient_info = RecipientOnionFields { payment_secret };
 	let mut payment_params = PaymentParameters::from_node_id(invoice.recover_payee_pub_key(),
 		invoice.min_final_cltv_expiry_delta() as u32)
 		.with_expiry_time(expiry_time_from_unix_epoch(invoice).as_secs())
@@ -158,7 +159,7 @@ fn pay_invoice_using_amount<P: Deref>(
 		final_value_msat: amount_msats,
 	};
 
-	payer.send_payment(payment_hash, &payment_secret, payment_id, route_params, retry_strategy)
+	payer.send_payment(payment_hash, recipient_info, payment_id, route_params, retry_strategy)
 }
 
 fn expiry_time_from_unix_epoch(invoice: &Invoice) -> Duration {
@@ -182,7 +183,7 @@ trait Payer {
 	///
 	/// [`Route`]: lightning::routing::router::Route
 	fn send_payment(
-		&self, payment_hash: PaymentHash, payment_secret: &Option<PaymentSecret>,
+		&self, payment_hash: PaymentHash, recipient_info: RecipientOnionFields,
 		payment_id: PaymentId, route_params: RouteParameters, retry_strategy: Retry
 	) -> Result<(), PaymentError>;
 }
@@ -199,10 +200,10 @@ where
 		L::Target: Logger,
 {
 	fn send_payment(
-		&self, payment_hash: PaymentHash, payment_secret: &Option<PaymentSecret>,
+		&self, payment_hash: PaymentHash, recipient_info: RecipientOnionFields,
 		payment_id: PaymentId, route_params: RouteParameters, retry_strategy: Retry
 	) -> Result<(), PaymentError> {
-		self.send_payment_with_retry(payment_hash, payment_secret, payment_id, route_params, retry_strategy)
+		self.send_payment_with_retry(payment_hash, recipient_info, payment_id, route_params, retry_strategy)
 			.map_err(PaymentError::Sending)
 	}
 }
@@ -212,7 +213,7 @@ mod tests {
 	use super::*;
 	use crate::{InvoiceBuilder, Currency};
 	use bitcoin_hashes::sha256::Hash as Sha256;
-	use lightning::ln::PaymentPreimage;
+	use lightning::ln::{PaymentPreimage, PaymentSecret};
 	use lightning::ln::functional_test_utils::*;
 	use secp256k1::{SecretKey, Secp256k1};
 	use std::collections::VecDeque;
@@ -249,7 +250,7 @@ mod tests {
 
 	impl Payer for TestPayer {
 		fn send_payment(
-			&self, _payment_hash: PaymentHash, _payment_secret: &Option<PaymentSecret>,
+			&self, _payment_hash: PaymentHash, _recipient_info: RecipientOnionFields,
 			_payment_id: PaymentId, route_params: RouteParameters, _retry_strategy: Retry
 		) -> Result<(), PaymentError> {
 			self.check_value_msats(Amount(route_params.final_value_msat));

lightning-invoice/src/utils.rs

@@ -667,7 +667,7 @@ mod test {
 	use lightning::chain::keysinterface::{EntropySource, PhantomKeysManager};
 	use lightning::events::{MessageSendEvent, MessageSendEventsProvider, Event};
 	use lightning::ln::{PaymentPreimage, PaymentHash};
-	use lightning::ln::channelmanager::{PhantomRouteHints, MIN_FINAL_CLTV_EXPIRY_DELTA, PaymentId};
+	use lightning::ln::channelmanager::{PhantomRouteHints, MIN_FINAL_CLTV_EXPIRY_DELTA, PaymentId, RecipientOnionFields};
 	use lightning::ln::functional_test_utils::*;
 	use lightning::ln::msgs::ChannelMessageHandler;
 	use lightning::routing::router::{PaymentParameters, RouteParameters, find_route};
@@ -725,7 +725,8 @@ mod test {
 		let payment_event = {
 			let mut payment_hash = PaymentHash([0; 32]);
 			payment_hash.0.copy_from_slice(&invoice.payment_hash().as_ref()[0..32]);
-			nodes[0].node.send_payment(&route, payment_hash, &Some(*invoice.payment_secret()), PaymentId(payment_hash.0)).unwrap();
+			nodes[0].node.send_payment(&route, payment_hash,
+				RecipientOnionFields::secret_only(*invoice.payment_secret()), PaymentId(payment_hash.0)).unwrap();
 			let mut added_monitors = nodes[0].chain_monitor.added_monitors.lock().unwrap();
 			assert_eq!(added_monitors.len(), 1);
 			added_monitors.clear();
@@ -1144,7 +1145,8 @@ mod test {
 		let (payment_event, fwd_idx) = {
 			let mut payment_hash = PaymentHash([0; 32]);
 			payment_hash.0.copy_from_slice(&invoice.payment_hash().as_ref()[0..32]);
-			nodes[0].node.send_payment(&route, payment_hash, &Some(*invoice.payment_secret()), PaymentId(payment_hash.0)).unwrap();
+			nodes[0].node.send_payment(&route, payment_hash,
+				RecipientOnionFields::secret_only(*invoice.payment_secret()), PaymentId(payment_hash.0)).unwrap();
 			let mut added_monitors = nodes[0].chain_monitor.added_monitors.lock().unwrap();
 			assert_eq!(added_monitors.len(), 1);
 			added_monitors.clear();

lightning/src/chain/chainmonitor.rs

@@ -812,7 +812,7 @@ mod tests {
 	use crate::chain::{ChannelMonitorUpdateStatus, Confirm, Watch};
 	use crate::chain::channelmonitor::LATENCY_GRACE_PERIOD_BLOCKS;
 	use crate::events::{Event, ClosureReason, MessageSendEvent, MessageSendEventsProvider};
-	use crate::ln::channelmanager::{PaymentSendFailure, PaymentId};
+	use crate::ln::channelmanager::{PaymentSendFailure, PaymentId, RecipientOnionFields};
 	use crate::ln::functional_test_utils::*;
 	use crate::ln::msgs::ChannelMessageHandler;
 	use crate::util::errors::APIError;
@@ -964,7 +964,8 @@ mod tests {
 		// If the ChannelManager tries to update the channel, however, the ChainMonitor will pass
 		// the update through to the ChannelMonitor which will refuse it (as the channel is closed).
 		chanmon_cfgs[0].persister.set_update_ret(ChannelMonitorUpdateStatus::Completed);
-		unwrap_send_err!(nodes[0].node.send_payment(&route, second_payment_hash, &Some(second_payment_secret), PaymentId(second_payment_hash.0)),
+		unwrap_send_err!(nodes[0].node.send_payment(&route, second_payment_hash, 
+				RecipientOnionFields::secret_only(second_payment_secret), PaymentId(second_payment_hash.0)),
 			true, APIError::ChannelUnavailable { ref err },
 			assert!(err.contains("ChannelMonitor storage failure")));
 		check_added_monitors!(nodes[0], 2); // After the failure we generate a close-channel monitor update

lightning/src/chain/channelmonitor.rs

@@ -4016,7 +4016,7 @@ mod tests {
 	use crate::ln::{PaymentPreimage, PaymentHash};
 	use crate::ln::chan_utils;
 	use crate::ln::chan_utils::{HTLCOutputInCommitment, ChannelPublicKeys, ChannelTransactionParameters, HolderCommitmentTransaction, CounterpartyChannelTransactionParameters};
-	use crate::ln::channelmanager::{PaymentSendFailure, PaymentId};
+	use crate::ln::channelmanager::{PaymentSendFailure, PaymentId, RecipientOnionFields};
 	use crate::ln::functional_test_utils::*;
 	use crate::ln::script::ShutdownScript;
 	use crate::util::errors::APIError;
@@ -4078,7 +4078,8 @@ mod tests {
 		// If the ChannelManager tries to update the channel, however, the ChainMonitor will pass
 		// the update through to the ChannelMonitor which will refuse it (as the channel is closed).
 		let (route, payment_hash, _, payment_secret) = get_route_and_payment_hash!(nodes[1], nodes[0], 100_000);
-		unwrap_send_err!(nodes[1].node.send_payment(&route, payment_hash, &Some(payment_secret), PaymentId(payment_hash.0)),
+		unwrap_send_err!(nodes[1].node.send_payment(&route, payment_hash,
+				RecipientOnionFields::secret_only(payment_secret), PaymentId(payment_hash.0)),
 			true, APIError::ChannelUnavailable { ref err },
 			assert!(err.contains("ChannelMonitor storage failure")));
 		check_added_monitors!(nodes[1], 2); // After the failure we generate a close-channel monitor update