XXX docs/commitmsg Add payment secret and preimage tracking in ChannelManager

This doesn't yet use such tracking anywhere.

Author: TheBlueMatt

lightning/src/ln/channelmanager.rs

@@ -352,6 +352,18 @@ struct PeerState {
 	latest_features: InitFeatures,
 }
 
+/// Stores a PaymentSecret and any other data we may need to validate an inbound payment is
+/// actually ours and not some duplicate HTLC sent to us by a node along the route.
+///
+/// For users who don't want to bother doing their own payment preimage storage, we also store that
+/// here.
+struct PendingInboundPayment {
+	payment_secret: PaymentSecret,
+	expiry_height: u32,
+	value_msat: Option<u64>,
+	payment_preimage: Option<PaymentPreimage>,
+}
+
 /// SimpleArcChannelManager is useful when you need a ChannelManager with a static lifetime, e.g.
 /// when you're using lightning-net-tokio (since tokio::spawn requires parameters with static
 /// lifetimes). Other times you can afford a reference, which is more efficient, in which case
@@ -430,6 +442,10 @@ pub struct ChannelManager<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref,
 	pub(super) channel_state: Mutex<ChannelHolder<Signer>>,
 	#[cfg(not(any(test, feature = "_test_utils")))]
 	channel_state: Mutex<ChannelHolder<Signer>>,
+
+	/// Locked *after* channel_state.
+	payment_secrets: Mutex<HashMap<PaymentHash, PendingInboundPayment>>,
+
 	our_network_key: SecretKey,
 	our_network_pubkey: PublicKey,
 
@@ -852,6 +868,8 @@ impl<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelMana
 				claimable_htlcs: HashMap::new(),
 				pending_msg_events: Vec::new(),
 			}),
+			payment_secrets: Mutex::new(HashMap::new()),
+
 			our_network_key: keys_manager.get_node_secret(),
 			our_network_pubkey: PublicKey::from_secret_key(&secp_ctx, &keys_manager.get_node_secret()),
 			secp_ctx,
@@ -3305,6 +3323,67 @@ impl<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelMana
 			self.finish_force_close_channel(failure);
 		}
 	}
+
+	/// Gets a payment secret, payment hash, and absolute CLTV expiry for use in an invoice given
+	/// to a third party wishing to pay us.
+	///
+	/// A [`PaymentReceived`] event will only be generated if the payment secret matches a payment
+	/// secret fetched via this method or [`get_payment_secret`], and which is at least the `value`
+	/// provided here, if one is provided.
+	///
+	/// invoice_expiry_delta_blocks describes the number of blocks which the invoice is valid for,
+	/// in excess of the current block height. This should match the value set in the invoice.
+	///
+	/// May panic if invoice_expiry_delta_blocks is greater than one year of blocks (52,560).
+	pub fn get_payment_secret_preimage(&self, value_msat: Option<u64>, invoice_expiry_delta_blocks: u32) -> (PaymentHash, PaymentSecret) {
+		assert!(invoice_expiry_delta_blocks <= 6*24*365); // We may overflow later if this value is too large
+
+		let payment_secret = PaymentSecret(self.keys_manager.get_secure_random_bytes());
+		let payment_preimage = PaymentPreimage(self.keys_manager.get_secure_random_bytes());
+		let payment_hash = PaymentHash(Sha256::hash(&payment_preimage.0).into_inner());
+
+		let _persistence_guard = PersistenceNotifierGuard::new(&self.total_consistency_lock, &self.persistence_notifier);
+		let mut payment_secrets = self.payment_secrets.lock().unwrap();
+		if payment_secrets.insert(payment_hash, PendingInboundPayment {
+			payment_secret, value_msat,
+			expiry_height: self.best_block.read().unwrap().height() + HTLC_FAIL_BACK_BUFFER + invoice_expiry_delta_blocks,
+			payment_preimage: Some(payment_preimage)
+		}).is_some() {
+			panic!("RNG Generated Duplicate PaymentHash");
+		}
+		(payment_hash, payment_secret)
+	}
+
+	/// Gets a payment_secret for a given payment hash, for which the payment preimage is stored
+	/// external to LDK.
+	///
+	/// A [`PaymentReceived`] event will only be generated if the payment secret matches a payment
+	/// secret fetched via this method or [`get_payment_secret_preimage`], and which is at least
+	/// the `value` provided here, if one is provided.
+	///
+	/// The payment_hash (and corresponding payment preimage) must be globally unique. This method
+	/// may return an Err if another payment with the same payment_hash is still pending.
+	///
+	/// invoice_expiry_delta_blocks describes the number of blocks which the invoice is valid for,
+	/// in excess of the current block height. This should match the value set in the invoice.
+	///
+	/// May panic if invoice_expiry_delta_blocks is greater than one year of blocks (52,560).
+	pub fn get_payment_secret(&self, payment_hash: PaymentHash, value_msat: Option<u64>, invoice_expiry_delta_blocks: u32) -> Result<PaymentSecret, APIError> {
+		let payment_secret = PaymentSecret(self.keys_manager.get_secure_random_bytes());
+
+		let _persistence_guard = PersistenceNotifierGuard::new(&self.total_consistency_lock, &self.persistence_notifier);
+		let mut payment_secrets = self.payment_secrets.lock().unwrap();
+		match payment_secrets.entry(payment_hash) {
+			hash_map::Entry::Vacant(e) => {
+				e.insert(PendingInboundPayment {
+					payment_secret, value_msat, payment_preimage: None,
+					expiry_height: self.best_block.read().unwrap().height() + HTLC_FAIL_BACK_BUFFER + invoice_expiry_delta_blocks,
+				});
+			},
+			hash_map::Entry::Occupied(_) => return Err(APIError::APIMisuseError { err: "Duplicate payment hash".to_owned() }),
+		}
+		Ok(payment_secret)
+	}
 }
 
 impl<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> MessageSendEventsProvider for ChannelManager<Signer, M, T, K, F, L>
@@ -4153,6 +4232,13 @@ impl Readable for HTLCForwardInfo {
 	}
 }
 
+impl_writeable!(PendingInboundPayment, 0, {
+	payment_secret,
+	expiry_height,
+	value_msat,
+	payment_preimage
+});
+
 impl<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> Writeable for ChannelManager<Signer, M, T, K, F, L>
 	where M::Target: chain::Watch<Signer>,
         T::Target: BroadcasterInterface,
@@ -4233,6 +4319,13 @@ impl<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> Writeable f
 
 		(self.last_node_announcement_serial.load(Ordering::Acquire) as u32).write(writer)?;
 
+		let payment_secrets = self.payment_secrets.lock().unwrap();
+		(payment_secrets.len() as u64).write(writer)?;
+		for (hash, pending_payment) in payment_secrets.iter() {
+			hash.write(writer)?;
+			pending_payment.write(writer)?;
+		}
+
 		Ok(())
 	}
 }
@@ -4463,6 +4556,14 @@ impl<'a, Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref>
 
 		let last_node_announcement_serial: u32 = Readable::read(reader)?;
 
+		let payment_secret_count: u64 = Readable::read(reader)?;
+		let mut payment_secrets: HashMap<PaymentHash, PendingInboundPayment> = HashMap::with_capacity(cmp::min(payment_secret_count as usize, MAX_ALLOC_SIZE/(3*32)));
+		for _ in 0..payment_secret_count {
+			if payment_secrets.insert(Readable::read(reader)?, Readable::read(reader)?).is_some() {
+				return Err(DecodeError::InvalidValue);
+			}
+		}
+
 		let mut secp_ctx = Secp256k1::new();
 		secp_ctx.seeded_randomize(&args.keys_manager.get_secure_random_bytes());
 
@@ -4481,6 +4582,8 @@ impl<'a, Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref>
 				claimable_htlcs,
 				pending_msg_events: Vec::new(),
 			}),
+			payment_secrets: Mutex::new(payment_secrets),
+
 			our_network_key: args.keys_manager.get_node_secret(),
 			our_network_pubkey: PublicKey::from_secret_key(&secp_ctx, &args.keys_manager.get_node_secret()),
 			secp_ctx,