Introduce RecipientData in ReceiveTlvs

1. New Enum for Enhanced Data Handling:
   - Introduced the `RecipientData` enum, which allows the node to include
     additional data along with the `reply_path` sent to the counterparty.
   - The node anticipates receiving this data back for further processing.

2. Variants in RecipientData:
   - The `RecipientData` enum includes two variants.
   - One of the variants, `OffersContext`, holds the `payment_id`
     of the associated Outbound BOLT12 Payment.

3. Future Usage:
   - This enum will be utilized in a subsequent commit to abandon outbound
     payments that have failed to complete for various reasons.

Author: shaavan

lightning/src/blinded_path/message.rs

@@ -13,6 +13,8 @@
 
 use bitcoin::secp256k1::{self, PublicKey, Secp256k1, SecretKey};
 
+use crate::ln::channelmanager::PaymentId;
+use crate::ln::msgs::DecodeError;
 #[allow(unused_imports)]
 use crate::prelude::*;
 
@@ -24,7 +26,7 @@ use crate::ln::onion_utils;
 use crate::onion_message::packet::ControlTlvs;
 use crate::sign::{NodeSigner, Recipient};
 use crate::crypto::streams::ChaChaPolyReadAdapter;
-use crate::util::ser::{FixedLengthReader, LengthReadableArgs, Writeable, Writer};
+use crate::util::ser::{FixedLengthReader, LengthReadableArgs, Readable, Writeable, Writer};
 
 use core::mem;
 use core::ops::Deref;
@@ -50,14 +52,6 @@ pub(crate) struct ForwardTlvs {
 	pub(crate) next_blinding_override: Option<PublicKey>,
 }
 
-/// Similar to [`ForwardTlvs`], but these TLVs are for the final node.
-pub(crate) struct ReceiveTlvs {
-	/// If `path_id` is `Some`, it is used to identify the blinded path that this onion message is
-	/// sending to. This is useful for receivers to check that said blinded path is being used in
-	/// the right context.
-	pub(crate) path_id: Option<[u8; 32]>,
-}
-
 impl Writeable for ForwardTlvs {
 	fn write<W: Writer>(&self, writer: &mut W) -> Result<(), io::Error> {
 		let (next_node_id, short_channel_id) = match self.next_hop {
@@ -74,16 +68,106 @@ impl Writeable for ForwardTlvs {
 	}
 }
 
+/// Similar to [`ForwardTlvs`], but these TLVs are for the final node.
+pub(crate) struct ReceiveTlvs {
+	pub tlvs: Option<RecipientData>
+}
+
+impl ReceiveTlvs {
+	pub fn new(tlvs: Option<RecipientData>) -> Self {
+		ReceiveTlvs { tlvs }
+	}
+}
+
+/// Represents additional data appended along with the sent reply path.
+///
+/// This data can be utilized by the final recipient for further processing
+/// upon receiving it back.
+#[derive(Clone, Debug)]
+pub enum RecipientData {
+	/// Represents the data specific to [`OffersMessage`]
+	///
+	/// [`OffersMessage`]: crate::onion_message::offers::OffersMessage
+	OffersContext(OffersData),
+
+	/// Represents the data appended with Custom Onion Message.
+	CustomContext(Vec<u8>),
+}
+
+/// Contains the data specific to [`OffersMessage`]
+///
+/// [`OffersMessage`]: crate::onion_message::offers::OffersMessage
+#[derive(Clone, Debug)]
+pub struct OffersData {
+	/// Payment ID of the outbound BOLT12 payment.
+	pub payment_id: Option<PaymentId>
+}
+
+impl RecipientData {
+	/// Creates a new RecipientData::OffersContext instance.
+	pub fn new_for_offers(payment_id: Option<PaymentId>) -> Self {
+		RecipientData::OffersContext(OffersData {
+			payment_id,
+		})
+	}
+
+	/// Creates a new RecipientData::CustomContext instance.
+	pub fn new_for_custom(data: Vec<u8>) -> Self {
+		RecipientData::CustomContext(data)
+	}
+}
+
+impl Writeable for RecipientData {
+	fn write<W: Writer>(&self, writer: &mut W) -> Result<(), io::Error> {
+		match self {
+			RecipientData::OffersContext(offers_data) => {
+				1u8.write(writer)?; // Identifier for OffersContext
+				offers_data.payment_id.write(writer)?; // Write the payment_id
+			}
+			RecipientData::CustomContext(data) => {
+				2u8.write(writer)?; // Identifier for CustomContext
+				data.write(writer)?; // Write the custom data
+			}
+		}
+		Ok(())
+	}
+}
+
+impl Readable for RecipientData {
+	fn read<R: io::Read>(r: &mut R) -> Result<Self, DecodeError> {
+		let type_id = u8::read(r)?;
+		match type_id {
+			1u8 => {
+				let payment_id = Option::<PaymentId>::read(r)?;
+				Ok(RecipientData::new_for_offers(payment_id))
+			}
+			2u8 => {
+				let data = Vec::<u8>::read(r)?;
+				Ok(RecipientData::new_for_custom(data))
+			}
+			_ => Err(DecodeError::InvalidValue),
+		}
+	}
+}
+
 impl Writeable for ReceiveTlvs {
 	fn write<W: Writer>(&self, writer: &mut W) -> Result<(), io::Error> {
-		// TODO: write padding
 		encode_tlv_stream!(writer, {
-			(6, self.path_id, option),
+			(6, self.tlvs, option),
 		});
 		Ok(())
 	}
 }
 
+impl Readable for ReceiveTlvs {
+	fn read<R: io::Read>(r: &mut R) -> Result<Self, DecodeError> {
+		_init_and_read_tlv_stream!(r, {
+			(6, tlvs, option),
+		});
+		Ok(ReceiveTlvs { tlvs })
+	}
+}
+
 /// Construct blinded onion message hops for the given `intermediate_nodes` and `recipient_node_id`.
 pub(super) fn blinded_hops<T: secp256k1::Signing + secp256k1::Verification>(
 	secp_ctx: &Secp256k1<T>, intermediate_nodes: &[ForwardNode], recipient_node_id: PublicKey,
@@ -99,7 +183,7 @@ pub(super) fn blinded_hops<T: secp256k1::Signing + secp256k1::Verification>(
 			None => NextMessageHop::NodeId(*pubkey),
 		})
 		.map(|next_hop| ControlTlvs::Forward(ForwardTlvs { next_hop, next_blinding_override: None }))
-		.chain(core::iter::once(ControlTlvs::Receive(ReceiveTlvs { path_id: None })));
+		.chain(core::iter::once(ControlTlvs::Receive(ReceiveTlvs::new(None))));
 
 	utils::construct_blinded_hops(secp_ctx, pks, tlvs, session_priv)
 }

lightning/src/onion_message/messenger.rs

@@ -16,7 +16,7 @@ use bitcoin::hashes::sha256::Hash as Sha256;
 use bitcoin::secp256k1::{self, PublicKey, Scalar, Secp256k1, SecretKey};
 
 use crate::blinded_path::{BlindedPath, IntroductionNode, NextMessageHop, NodeIdLookUp};
-use crate::blinded_path::message::{advance_path_by_one, ForwardNode, ForwardTlvs, ReceiveTlvs};
+use crate::blinded_path::message::{advance_path_by_one, ForwardNode, ForwardTlvs, ReceiveTlvs, RecipientData};
 use crate::blinded_path::utils;
 use crate::events::{Event, EventHandler, EventsProvider};
 use crate::sign::{EntropySource, NodeSigner, Recipient};
@@ -329,7 +329,7 @@ impl OnionMessageRecipient {
 pub struct Responder {
 	/// The path along which a response can be sent.
 	reply_path: BlindedPath,
-	path_id: Option<[u8; 32]>
+	path_id: Option<[u8; 32]>,
 }
 
 impl_writeable_tlv_based!(Responder, {
@@ -780,7 +780,7 @@ pub enum PeeledOnion<T: OnionMessageContents> {
 	/// Forwarded onion, with the next node id and a new onion
 	Forward(NextMessageHop, OnionMessage),
 	/// Received onion message, with decrypted contents, path_id, and reply path
-	Receive(ParsedOnionMessageContents<T>, Option<[u8; 32]>, Option<BlindedPath>)
+	Receive(ParsedOnionMessageContents<T>, Option<RecipientData>, Option<BlindedPath>)
 }
 
 
@@ -930,9 +930,20 @@ where
 		(control_tlvs_ss, custom_handler.deref(), logger.deref())
 	) {
 		Ok((Payload::Receive::<ParsedOnionMessageContents<<<CMH as Deref>::Target as CustomOnionMessageHandler>::CustomMessage>> {
-			message, control_tlvs: ReceiveControlTlvs::Unblinded(ReceiveTlvs { path_id }), reply_path,
+			message, control_tlvs: ReceiveControlTlvs::Unblinded(ReceiveTlvs {tlvs}), reply_path,
 		}, None)) => {
-			Ok(PeeledOnion::Receive(message, path_id, reply_path))
+			match (&message, &tlvs) {
+				(_, None) => {
+					Ok(PeeledOnion::Receive(message, None, reply_path))
+				}
+				(ParsedOnionMessageContents::Offers(_), Some(RecipientData::OffersContext(_))) => {
+					Ok(PeeledOnion::Receive(message, tlvs, reply_path))
+				}
+				(ParsedOnionMessageContents::Custom(_), Some(RecipientData::CustomContext(_))) => {
+					Ok(PeeledOnion::Receive(message, tlvs, reply_path))
+				}
+				_ => Err(())
+			}
 		},
 		Ok((Payload::Forward(ForwardControlTlvs::Unblinded(ForwardTlvs {
 			next_hop, next_blinding_override
@@ -1414,7 +1425,8 @@ where
 	fn handle_onion_message(&self, peer_node_id: &PublicKey, msg: &OnionMessage) {
 		let logger = WithContext::from(&self.logger, Some(*peer_node_id), None, None);
 		match self.peel_onion_message(msg) {
-			Ok(PeeledOnion::Receive(message, path_id, reply_path)) => {
+			Ok(PeeledOnion::Receive(message, _tlvs, reply_path)) => {
+				let path_id: Option<[u8; 32]> = None;
 				log_trace!(
 					logger,
 					"Received an onion message with path_id {:02x?} and {} reply_path: {:?}",
@@ -1701,7 +1713,7 @@ fn packet_payloads_and_keys<T: OnionMessageContents, S: secp256k1::Signing + sec
 		}, prev_control_tlvs_ss.unwrap()));
 	} else {
 		payloads.push((Payload::Receive {
-			control_tlvs: ReceiveControlTlvs::Unblinded(ReceiveTlvs { path_id: None, }),
+			control_tlvs: ReceiveControlTlvs::Unblinded(ReceiveTlvs { tlvs: None }),
 			reply_path: reply_path.take(),
 			message,
 		}, prev_control_tlvs_ss.unwrap()));

lightning/src/onion_message/packet.rs

@@ -302,19 +302,21 @@ impl Readable for ControlTlvs {
 			(1, _padding, option),
 			(2, short_channel_id, option),
 			(4, next_node_id, option),
-			(6, path_id, option),
+			(6, tlvs, option),
 			(8, next_blinding_override, option),
 		});
 		let _padding: Option<Padding> = _padding;
 
+		let receive_tlvs = tlvs.unwrap_or(ReceiveTlvs { tlvs: None });
+
 		let next_hop = match (short_channel_id, next_node_id) {
 			(Some(_), Some(_)) => return Err(DecodeError::InvalidValue),
 			(Some(scid), None) => Some(NextMessageHop::ShortChannelId(scid)),
 			(None, Some(pubkey)) => Some(NextMessageHop::NodeId(pubkey)),
 			(None, None) => None,
 		};
 
-		let valid_fwd_fmt = next_hop.is_some() && path_id.is_none();
+		let valid_fwd_fmt = next_hop.is_some();
 		let valid_recv_fmt = next_hop.is_none() && next_blinding_override.is_none();
 
 		let payload_fmt = if valid_fwd_fmt {
@@ -323,9 +325,7 @@ impl Readable for ControlTlvs {
 				next_blinding_override,
 			})
 		} else if valid_recv_fmt {
-			ControlTlvs::Receive(ReceiveTlvs {
-				path_id,
-			})
+			ControlTlvs::Receive(receive_tlvs)
 		} else {
 			return Err(DecodeError::InvalidValue)
 		};
@@ -338,7 +338,13 @@ impl Writeable for ControlTlvs {
 	fn write<W: Writer>(&self, w: &mut W) -> Result<(), io::Error> {
 		match self {
 			Self::Forward(tlvs) => tlvs.write(w),
-			Self::Receive(tlvs) => tlvs.write(w),
+			Self::Receive(tlvs) => {
+				let tlvs = Some(tlvs);
+				encode_tlv_stream!(w, {
+					(6, tlvs, option)
+				});
+				Ok(())
+			}
 		}
 	}
 }

lightning/src/util/ser.rs

@@ -103,6 +103,7 @@ impl Writer for LengthCalculatingWriter {
 	}
 }
 
+
 /// Essentially [`std::io::Take`] but a bit simpler and with a method to walk the underlying stream
 /// forward to ensure we always consume exactly the fixed length specified.
 ///

lightning/src/util/ser_macros.rs

@@ -557,6 +557,7 @@ macro_rules! _decode_tlv_stream_range {
 			// Finally, read the length and value itself:
 			let length: ser::BigSize = $crate::util::ser::Readable::read(&mut stream_ref)?;
 			let mut s = ser::FixedLengthReader::new(&mut stream_ref, length.0);
+
 			match typ.0 {
 				$(_t if $crate::_decode_tlv_stream_match_check!(_t, $type, $fieldty) => {
 					$crate::_decode_tlv!($stream, s, $field, $fieldty);