+/// Information which is provided, encrypted, to the payment recipient when sending HTLCs.
+///
+/// This should generally be constructed with data communicated to us from the recipient (via a
+/// BOLT11 or BOLT12 invoice).
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct RecipientOnionFields {
+ /// The [`PaymentSecret`] is an arbitrary 32 bytes provided by the recipient for us to repeat
+ /// in the onion. It is unrelated to `payment_hash` (or [`PaymentPreimage`]) and exists to
+ /// authenticate the sender to the recipient and prevent payment-probing (deanonymization)
+ /// attacks.
+ ///
+ /// If you do not have one, the [`Route`] you pay over must not contain multiple paths as
+ /// multi-path payments require a recipient-provided secret.
+ ///
+ /// Some implementations may reject spontaneous payments with payment secrets, so you may only
+ /// want to provide a secret for a spontaneous payment if MPP is needed and you know your
+ /// recipient will not reject it.
+ pub payment_secret: Option<PaymentSecret>,
+ /// The payment metadata serves a similar purpose as [`Self::payment_secret`] but is of
+ /// arbitrary length. This gives recipients substantially more flexibility to receive
+ /// additional data.
+ ///
+ /// In LDK, while the [`Self::payment_secret`] is fixed based on an internal authentication
+ /// scheme to authenticate received payments against expected payments and invoices, this field
+ /// is not used in LDK for received payments, and can be used to store arbitrary data in
+ /// invoices which will be received with the payment.
+ ///
+ /// Note that this field was added to the lightning specification more recently than
+ /// [`Self::payment_secret`] and while nearly all lightning senders support secrets, metadata
+ /// may not be supported as universally.
+ pub payment_metadata: Option<Vec<u8>>,
+}
+
+impl_writeable_tlv_based!(RecipientOnionFields, {
+ (0, payment_secret, option),
+ (2, payment_metadata, option),
+});
+
+impl RecipientOnionFields {
+ /// Creates a [`RecipientOnionFields`] from only a [`PaymentSecret`]. This is the most common
+ /// set of onion fields for today's BOLT11 invoices - most nodes require a [`PaymentSecret`]
+ /// but do not require or provide any further data.
+ pub fn secret_only(payment_secret: PaymentSecret) -> Self {
+ Self { payment_secret: Some(payment_secret), payment_metadata: None }
+ }
+
+ /// Creates a new [`RecipientOnionFields`] with no fields. This generally does not create
+ /// payable HTLCs except for single-path spontaneous payments, i.e. this should generally
+ /// only be used for calls to [`ChannelManager::send_spontaneous_payment`]. If you are sending
+ /// a spontaneous MPP this will not work as all MPP require payment secrets; you may
+ /// instead want to use [`RecipientOnionFields::secret_only`].
+ ///
+ /// [`ChannelManager::send_spontaneous_payment`]: super::channelmanager::ChannelManager::send_spontaneous_payment
+ /// [`RecipientOnionFields::secret_only`]: RecipientOnionFields::secret_only
+ pub fn spontaneous_empty() -> Self {
+ Self { payment_secret: None, payment_metadata: None }
+ }
+
+ /// When we have received some HTLC(s) towards an MPP payment, as we receive further HTLC(s) we
+ /// have to make sure that some fields match exactly across the parts. For those that aren't
+ /// required to match, if they don't match we should remove them so as to not expose data
+ /// that's dependent on the HTLC receive order to users.
+ ///
+ /// Here we implement this, first checking compatibility then mutating two objects and then
+ /// dropping any remaining non-matching fields from both.
+ pub(super) fn check_merge(&mut self, further_htlc_fields: &mut Self) -> Result<(), ()> {
+ if self.payment_secret != further_htlc_fields.payment_secret { return Err(()); }
+ if self.payment_metadata != further_htlc_fields.payment_metadata { return Err(()); }
+ // For custom TLVs we should just drop non-matching ones, but not reject the payment.
+ Ok(())
+ }
+}
+