Add payment secret and preimage tracking in ChannelManager

This adds support for tracking payment secrets and (optionally)
payment preimages in ChannelManager. This potentially makes client
implementations much simper as they don't have to have external
payment preimage tracking.

This doesn't yet use such tracking anywhere.

Author: TheBlueMatt

lightning/src/ln/channelmanager.rs

@@ -353,6 +353,23 @@ 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 {
+	/// The payment secret which the sender must use for us to accept this payment
+	payment_secret: PaymentSecret,
+	/// Height at which this HTLC expires - block height above this value will result in this
+	/// payment being removed. Note that we'll reject any payments within HTLC_FAIL_BACK_BUFFER of
+	/// the height at which they are received.
+	expiry_height: u32,
+	// Other required attributes of the payment, optionally enforced:
+	payment_preimage: Option<PaymentPreimage>,
+	min_value_msat: Option<u64>,
+}
+
 /// 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
@@ -431,6 +448,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>>,
+
+	/// Pending inbound payments by. Locked *after* channel_state.
+	pending_inbound_payments: Mutex<HashMap<PaymentHash, PendingInboundPayment>>,
+
 	our_network_key: SecretKey,
 	our_network_pubkey: PublicKey,
 
@@ -853,6 +874,8 @@ impl<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelMana
 				claimable_htlcs: HashMap::new(),
 				pending_msg_events: Vec::new(),
 			}),
+			pending_inbound_payments: 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,
@@ -3321,6 +3344,85 @@ impl<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelMana
 			self.finish_force_close_channel(failure);
 		}
 	}
+
+	/// Gets a payment secret and payment hash 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.
+	///
+	/// `min_value_msat` should be set if the invoice being generated contains a value. Any payment
+	/// received for the returned PaymentHash will be required to be at least `min_value_msat`
+	/// before a [`PaymentReceived`] event will be generated, ensuring that we do not provide the
+	/// server "proof-of-payment" unless they have paid the required amount.
+	///
+	/// `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).
+	///
+	/// [`get_payment_secret`]: Self::get_payment_secret
+	/// [`PaymentReceived`]: events::Event::PaymentReceived
+	pub fn get_payment_secret_preimage(&self, min_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.pending_inbound_payments.lock().unwrap();
+		if payment_secrets.insert(payment_hash, PendingInboundPayment {
+			payment_secret, min_value_msat,
+			expiry_height: self.best_block.read().unwrap().height() + 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.
+	///
+	/// `min_value_msat` should be set if the invoice being generated contains a value. Any payment
+	/// received for the returned PaymentHash will be required to be at least `min_value_msat`
+	/// before a [`PaymentReceived`] event will be generated, ensuring that we do not provide the
+	/// server "proof-of-payment" unless they have paid the required amount.
+	///
+	/// `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).
+	///
+	/// [`get_payment_secret_preimage`]: Self::get_payment_secret_preimage
+	/// [`PaymentReceived`]: events::Event::PaymentReceived
+	pub fn get_payment_secret(&self, payment_hash: PaymentHash, min_value_msat: Option<u64>, invoice_expiry_delta_blocks: u32) -> Result<PaymentSecret, APIError> {
+		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 _persistence_guard = PersistenceNotifierGuard::new(&self.total_consistency_lock, &self.persistence_notifier);
+		let mut payment_secrets = self.pending_inbound_payments.lock().unwrap();
+		match payment_secrets.entry(payment_hash) {
+			hash_map::Entry::Vacant(e) => {
+				e.insert(PendingInboundPayment {
+					payment_secret, min_value_msat, payment_preimage: None,
+					expiry_height: self.best_block.read().unwrap().height() + 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>
@@ -4116,6 +4218,13 @@ impl Readable for HTLCForwardInfo {
 	}
 }
 
+impl_writeable!(PendingInboundPayment, 0, {
+	payment_secret,
+	expiry_height,
+	payment_preimage,
+	min_value_msat
+});
+
 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,
@@ -4196,6 +4305,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 pending_inbound_payments = self.pending_inbound_payments.lock().unwrap();
+		(pending_inbound_payments.len() as u64).write(writer)?;
+		for (hash, pending_payment) in pending_inbound_payments.iter() {
+			hash.write(writer)?;
+			pending_payment.write(writer)?;
+		}
+
 		Ok(())
 	}
 }
@@ -4426,6 +4542,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 pending_inbound_payment_count: u64 = Readable::read(reader)?;
+		let mut pending_inbound_payments: HashMap<PaymentHash, PendingInboundPayment> = HashMap::with_capacity(cmp::min(pending_inbound_payment_count as usize, MAX_ALLOC_SIZE/(3*32)));
+		for _ in 0..pending_inbound_payment_count {
+			if pending_inbound_payments.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());
 
@@ -4444,6 +4568,8 @@ impl<'a, Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref>
 				claimable_htlcs,
 				pending_msg_events: Vec::new(),
 			}),
+			pending_inbound_payments: Mutex::new(pending_inbound_payments),
+
 			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,