Merge pull request #2127 from TheBlueMatt/2023-03-payment-metadata

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

diff --git a/lightning/src/events/mod.rs b/lightning/src/events/mod.rs
index 4e7919df57b25f748a6c075573bcb86f949d7cb7..1bd1214596de769154fab9cd37e41df1b3748e7d 100644 (file)
--- a/lightning/src/events/mod.rs
+++ b/lightning/src/events/mod.rs
@@ -275,6 +275,43 @@ impl_writeable_tlv_based_enum!(InterceptNextHop,
        };
 );
 
+/// The reason the payment failed. Used in [`Event::PaymentFailed`].
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum PaymentFailureReason {
+       /// The intended recipient rejected our payment.
+       RecipientRejected,
+       /// The user chose to abandon this payment by calling [`ChannelManager::abandon_payment`].
+       ///
+       /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment
+       UserAbandoned,
+       /// We exhausted all of our retry attempts while trying to send the payment, or we
+       /// exhausted the [`Retry::Timeout`] if the user set one. If at any point a retry
+       /// attempt failed while being forwarded along the path, an [`Event::PaymentPathFailed`] will
+       /// have come before this.
+       ///
+       /// [`Retry::Timeout`]: crate::ln::channelmanager::Retry::Timeout
+       RetriesExhausted,
+       /// The payment expired while retrying, based on the provided
+       /// [`PaymentParameters::expiry_time`].
+       ///
+       /// [`PaymentParameters::expiry_time`]: crate::routing::router::PaymentParameters::expiry_time
+       PaymentExpired,
+       /// We failed to find a route while retrying the payment.
+       RouteNotFound,
+       /// This error should generally never happen. This likely means that there is a problem with
+       /// your router.
+       UnexpectedError,
+}
+
+impl_writeable_tlv_based_enum!(PaymentFailureReason,
+       (0, RecipientRejected) => {},
+       (2, UserAbandoned) => {},
+       (4, RetriesExhausted) => {},
+       (6, PaymentExpired) => {},
+       (8, RouteNotFound) => {},
+       (10, UnexpectedError) => {}, ;
+);
+
 /// An Event which you should probably take some action in response to.
 ///
 /// Note that while Writeable and Readable are implemented for Event, you probably shouldn't use
@@ -446,6 +483,9 @@ pub enum Event {
                ///
                /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
                payment_hash: PaymentHash,
+               /// The reason the payment failed. This is only `None` for events generated or serialized
+               /// by versions prior to 0.0.115.
+               reason: Option<PaymentFailureReason>,
        },
        /// Indicates that a path for an outbound payment was successful.
        ///
@@ -915,10 +955,11 @@ impl Writeable for Event {
                                        (4, *path, vec_type)
                                })
                        },
-                       &Event::PaymentFailed { ref payment_id, ref payment_hash } => {
+                       &Event::PaymentFailed { ref payment_id, ref payment_hash, ref reason } => {
                                15u8.write(writer)?;
                                write_tlv_fields!(writer, {
                                        (0, payment_id, required),
+                                       (1, reason, option),
                                        (2, payment_hash, required),
                                })
                        },
@@ -1223,13 +1264,16 @@ impl MaybeReadable for Event {
                                let f = || {
                                        let mut payment_hash = PaymentHash([0; 32]);
                                        let mut payment_id = PaymentId([0; 32]);
+                                       let mut reason = None;
                                        read_tlv_fields!(reader, {
                                                (0, payment_id, required),
+                                               (1, reason, upgradable_option),
                                                (2, payment_hash, required),
                                        });
                                        Ok(Some(Event::PaymentFailed {
                                                payment_id,
                                                payment_hash,
+                                               reason,
                                        }))
                                };
                                f()