f update docs

Author: valentinewallace

lightning/src/ln/channelmanager.rs

@@ -2591,7 +2591,8 @@ impl<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelMana
 		}
 	}
 
-	// Check that an inbound payment's `payment_data` field is sane.
+	// Check that an inbound payment's `payment_data` field is sane. See `create_inbound_payment` and
+	// `create_inbound_payment_for_hash` for details on our checks.
 	fn verify_inbound_payment_data(&self, payment_hash: PaymentHash, payment_data: msgs::FinalOnionHopData) -> Result<Option<PaymentPreimage>, ()> {
 		let (iv_bytes, encrypted_metadata_bytes) = payment_data.payment_secret.0.split_at(16);
 		let mut chacha = ChaCha20::new(&self.inbound_payments_key[..], &iv_bytes[..12]);
@@ -4610,6 +4611,17 @@ impl<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelMana
 	/// [`PaymentReceived`]: events::Event::PaymentReceived
 	/// [`PaymentReceived::payment_preimage`]: events::Event::PaymentReceived::payment_preimage
 	/// [`create_inbound_payment_for_hash`]: Self::create_inbound_payment_for_hash
+	// LDK does not store any data for pending inbound payments. Instead, in the case of
+	// `create_inbound_payment`, where LDK is supplying the payment preimage, we construct our payment
+	// secret and payment preimage to include encrypted metadata about the payment, as such:
+	//
+	// 	METADATA = payment amount (8 bytes) || expiry (8 bytes)
+	// 	IV = 16 random bytes
+	// 	payment_preimage = HMAC(ldk_pmt_hash_key, IV || METADATA)
+	// 	payment_secret = IV || CHACHA(self.inbound_payments_key, IV) xor METADATA
+	//
+	// Then on payment receipt, we verify in `verify_inbound_payment_data` that the payment preimage
+	// and payment secret match what was constructed in `create_inbound_payment`.
 	pub fn create_inbound_payment(&self, min_value_msat: Option<u64>, invoice_expiry_delta_secs: u32) -> (PaymentHash, PaymentSecret) {
 		let min_amt_msat_bytes: [u8; 8] = match min_value_msat {
 			Some(amt) => amt.to_be_bytes(),
@@ -4688,6 +4700,16 @@ impl<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelMana
 	///
 	/// [`create_inbound_payment`]: Self::create_inbound_payment
 	/// [`PaymentReceived`]: events::Event::PaymentReceived
+	// LDK does not store any data for pending inbound payments. Instead, in the case of
+	// `create_inbound_payment_for_hash`, where the user is supplying the payment preimage, we
+	// construct our payment secret to include encrypted metadata about the payment, as such:
+	//
+	// 	METADATA = top bit set for user-generated payment hash || payment amount (8 bytes) || expiry (8 bytes)
+	// 	IV = HMAC(user_pmt_hash_key, METADATA || payment_hash)[0..16]
+	// 	payment_secret = IV || CHACHA(self.inbound_payments_key, IV) xor METADATA
+	//
+	// Then on payment receipt, we verify in `verify_inbound_payment_data` that the payment preimage
+	// and payment secret match what was constructed in `create_inbound_payment`.
 	pub fn create_inbound_payment_for_hash(&self, payment_hash: PaymentHash, min_value_msat: Option<u64>, invoice_expiry_delta_secs: u32) -> Result<PaymentSecret, APIError> {
 		let mut min_amt_msat_bytes: [u8; 8] = match min_value_msat {
 			Some(amt) => amt.to_be_bytes(),