Update PaymentPurpose's payment_preimage docs

[rust-lightning] / lightning / src / events / mod.rs

diff --git a/lightning/src/events/mod.rs b/lightning/src/events/mod.rs
index 94df71b69eaab51e2f074a6b81d30902a0b002f4..d34db885f7c4e0d24ad52281f143f5fb08c385ad 100644 (file)
--- a/lightning/src/events/mod.rs
+++ b/lightning/src/events/mod.rs
@@ -53,8 +53,9 @@ pub enum PaymentPurpose {
        /// A payment for a BOLT 11 invoice.
        Bolt11InvoicePayment {
                /// The preimage to the payment_hash, if the payment hash (and secret) were fetched via
-               /// [`ChannelManager::create_inbound_payment`]. If provided, this can be handed directly to
-               /// [`ChannelManager::claim_funds`].
+               /// [`ChannelManager::create_inbound_payment`]. When handling [`Event::PaymentClaimable`],
+               /// this can be passed directly to [`ChannelManager::claim_funds`] to claim the payment. No
+               /// action is needed when seen in [`Event::PaymentClaimed`].
                ///
                /// [`ChannelManager::create_inbound_payment`]: crate::ln::channelmanager::ChannelManager::create_inbound_payment
                /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds
@@ -75,8 +76,9 @@ pub enum PaymentPurpose {
        ///
        /// [`Offer`]: crate::offers::offer::Offer
        Bolt12OfferPayment {
-               /// The preimage to the payment hash. If provided, this can be handed directly to
-               /// [`ChannelManager::claim_funds`].
+               /// The preimage to the payment hash. When handling [`Event::PaymentClaimable`], this can be
+               /// passed directly to [`ChannelManager::claim_funds`], if provided. No action is needed
+               /// when seen in [`Event::PaymentClaimed`].
                ///
                /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds
                payment_preimage: Option<PaymentPreimage>,
@@ -96,8 +98,9 @@ pub enum PaymentPurpose {
        ///
        /// [`Refund`]: crate::offers::refund::Refund
        Bolt12RefundPayment {
-               /// The preimage to the payment hash. If provided, this can be handed directly to
-               /// [`ChannelManager::claim_funds`].
+               /// The preimage to the payment hash. When handling [`Event::PaymentClaimable`], this can be
+               /// passed directly to [`ChannelManager::claim_funds`], if provided. No action is needed
+               /// when seen in [`Event::PaymentClaimed`].
                ///
                /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds
                payment_preimage: Option<PaymentPreimage>,
@@ -135,6 +138,34 @@ impl PaymentPurpose {
                        PaymentPurpose::SpontaneousPayment(..) => true,
                }
        }
+
+       pub(crate) fn from_parts(
+               payment_preimage: Option<PaymentPreimage>, payment_secret: PaymentSecret,
+               payment_context: Option<PaymentContext>,
+       ) -> Self {
+               match payment_context {
+                       Some(PaymentContext::Unknown(_)) | None => {
+                               PaymentPurpose::Bolt11InvoicePayment {
+                                       payment_preimage,
+                                       payment_secret,
+                               }
+                       },
+                       Some(PaymentContext::Bolt12Offer(context)) => {
+                               PaymentPurpose::Bolt12OfferPayment {
+                                       payment_preimage,
+                                       payment_secret,
+                                       payment_context: context,
+                               }
+                       },
+                       Some(PaymentContext::Bolt12Refund(context)) => {
+                               PaymentPurpose::Bolt12RefundPayment {
+                                       payment_preimage,
+                                       payment_secret,
+                                       payment_context: context,
+                               }
+                       },
+               }
+       }
 }
 
 impl_writeable_tlv_based_enum!(PaymentPurpose,
@@ -1408,28 +1439,7 @@ impl MaybeReadable for Event {
                                                (11, payment_context, option),
                                        });
                                        let purpose = match payment_secret {
-                                               Some(secret) => match payment_context {
-                                                       Some(PaymentContext::Unknown(_)) | None => {
-                                                               PaymentPurpose::Bolt11InvoicePayment {
-                                                                       payment_preimage,
-                                                                       payment_secret: secret,
-                                                               }
-                                                       },
-                                                       Some(PaymentContext::Bolt12Offer(context)) => {
-                                                               PaymentPurpose::Bolt12OfferPayment {
-                                                                       payment_preimage,
-                                                                       payment_secret: secret,
-                                                                       payment_context: context,
-                                                               }
-                                                       },
-                                                       Some(PaymentContext::Bolt12Refund(context)) => {
-                                                               PaymentPurpose::Bolt12RefundPayment {
-                                                                       payment_preimage,
-                                                                       payment_secret: secret,
-                                                                       payment_context: context,
-                                                               }
-                                                       },
-                                               },
+                                               Some(secret) => PaymentPurpose::from_parts(payment_preimage, secret, payment_context),
                                                None if payment_preimage.is_some() => PaymentPurpose::SpontaneousPayment(payment_preimage.unwrap()),
                                                None => return Err(msgs::DecodeError::InvalidValue),
                                        };