Add FailureCode enum

This enum is used to specify which error code and data to send
to peers when failing back an HTLC.

Author: alecchendev

lightning/src/ln/channelmanager.rs

@@ -289,6 +289,30 @@ struct ReceiveError {
 	msg: &'static str,
 }
 
+/// This enum is used to specify which error data to send to peers when failing back an HTLC
+/// using [`ChannelManager::fail_htlc_backwards_with_reason`].
+///
+/// For more info on failure codes, see <https://github.com/lightning/bolts/blob/master/04-onion-routing.md#failure-messages>.
+#[derive(Clone, Copy)]
+pub enum FailureCode {
+	/// We had a temporary error processing the payment. Useful if no other error codes fit 
+	/// and you want to indicate that the payer may want to retry.
+	TemporaryNodeFailure             = 0x2000 | 2,
+	/// We have a required feature which was not in this onion. For example, you may require
+	/// some additional metadata that was not provided with this payment.
+	RequiredNodeFeatureMissing       = 0x4000 | 0x2000 | 3,
+	/// The CLTV expiry is too close to the current block height for safe handling by us. This
+	/// should only be used when failing back as a forwarding node.
+	ExpiryTooSoon                    = 0x1000 | 14,
+	/// You may wish to use this when a `payment_hash` is unknown, the `payment_secret` is
+	/// required and not present, the `payment_secret` doesn't match the `payment_hash`, the
+	/// received amount is incorrect, the CLTV expiry of the HTLC is too close to the current
+	/// block height for safe handling, or `payment_metadata` isn't present when it should be.
+	/// Using this failure code in [`ChannelManager::fail_htlc_backwards_with_reason`] is
+	/// equivalent to calling [`ChannelManager::fail_htlc_backwards`].
+	IncorrectOrUnknownPaymentDetails = 0x4000 | 15,
+}
+
 type ShutdownResult = (Option<(OutPoint, ChannelMonitorUpdate)>, Vec<(HTLCSource, PaymentHash, PublicKey, [u8; 32])>);
 
 /// Error type returned across the peer_state mutex boundary. When an Err is generated for a
@@ -3472,16 +3496,45 @@ where
 	/// [`events::Event::PaymentClaimed`] events even for payments you intend to fail, especially on
 	/// startup during which time claims that were in-progress at shutdown may be replayed.
 	pub fn fail_htlc_backwards(&self, payment_hash: &PaymentHash) {
+		self.fail_htlc_backwards_with_reason(payment_hash, &FailureCode::IncorrectOrUnknownPaymentDetails);
+	}
+
+	/// This is a variant of [`ChannelManager::fail_htlc_backwards`] that allows you to specify the
+	/// reason for the failure.
+	///
+	/// See [`FailureCode`] for valid failure codes.
+	pub fn fail_htlc_backwards_with_reason(&self, payment_hash: &PaymentHash, failure_code: &FailureCode) {
 		let _persistence_guard = PersistenceNotifierGuard::notify_on_drop(&self.total_consistency_lock, &self.persistence_notifier);
 
 		let removed_source = self.claimable_payments.lock().unwrap().claimable_htlcs.remove(payment_hash);
 		if let Some((_, mut sources)) = removed_source {
 			for htlc in sources.drain(..) {
-				let mut htlc_msat_height_data = htlc.value.to_be_bytes().to_vec();
-				htlc_msat_height_data.extend_from_slice(&self.best_block.read().unwrap().height().to_be_bytes());
-				let source = HTLCSource::PreviousHopData(htlc.prev_hop);
-				let reason = HTLCFailReason::reason(0x4000 | 15, htlc_msat_height_data);
+				let source = HTLCSource::PreviousHopData(htlc.prev_hop.clone());
 				let receiver = HTLCDestination::FailedPayment { payment_hash: *payment_hash };
+
+				let reason = match failure_code {
+					FailureCode::TemporaryNodeFailure => HTLCFailReason::from_failure_code(*failure_code as u16),
+					FailureCode::RequiredNodeFeatureMissing => HTLCFailReason::from_failure_code(*failure_code as u16),
+					FailureCode::ExpiryTooSoon => {
+						let short_channel_id = htlc.prev_hop.short_channel_id;
+						let (counterparty_node_id, chan_id) = self.short_to_chan_info.read().unwrap().get(&short_channel_id).cloned().unwrap();
+						let per_peer_state = self.per_peer_state.read().unwrap();
+						let peer_state = per_peer_state.get(&counterparty_node_id).unwrap().lock().unwrap();
+						let chan = peer_state.channel_by_id.get(&chan_id).unwrap();
+						let channel_update = self.get_channel_update_for_onion(short_channel_id, chan).unwrap();
+						let mut channel_update_data = Vec::new();
+						(channel_update.serialized_length() as u16 + 2).write(&mut channel_update_data).expect("Writes cannot fail");
+						msgs::ChannelUpdate::TYPE.write(&mut channel_update_data).expect("Writes cannot fail");
+						channel_update.write(&mut channel_update_data).expect("Writes cannot fail");
+						HTLCFailReason::reason(*failure_code as u16, channel_update_data)
+					},
+					FailureCode::IncorrectOrUnknownPaymentDetails => {
+						let mut htlc_msat_height_data = htlc.value.to_be_bytes().to_vec();
+						htlc_msat_height_data.extend_from_slice(&self.best_block.read().unwrap().height().to_be_bytes());
+						HTLCFailReason::reason(*failure_code as u16, htlc_msat_height_data)
+					}
+				};
+
 				self.fail_htlc_backwards_internal(&source, &payment_hash, &reason, receiver);
 			}
 		}