Create `PaymentFailureReason` enum

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

diff --git a/lightning/src/events/mod.rs b/lightning/src/events/mod.rs
index 318cc2a6d1aabe183f44861e7bd84aea96d2355a..24252e38ebaee6103c6e359d25062f0077a8103c 100644 (file)
--- a/lightning/src/events/mod.rs
+++ b/lightning/src/events/mod.rs
@@ -272,6 +272,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
@@ -397,7 +434,7 @@ pub enum Event {
        /// Note for MPP payments: in rare cases, this event may be preceded by a `PaymentPathFailed`
        /// event. In this situation, you SHOULD treat this payment as having succeeded.
        PaymentSent {
-               /// The id returned by [`ChannelManager::send_payment`].
+               /// The `payment_id` passed to [`ChannelManager::send_payment`].
                ///
                /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
                payment_id: Option<PaymentId>,
@@ -430,11 +467,9 @@ pub enum Event {
        /// [`Retry`]: crate::ln::channelmanager::Retry
        /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment
        PaymentFailed {
-               /// The id returned by [`ChannelManager::send_payment`] and used with
-               /// [`ChannelManager::abandon_payment`].
+               /// The `payment_id` passed to [`ChannelManager::send_payment`].
                ///
                /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
-               /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment
                payment_id: PaymentId,
                /// The hash that was given to [`ChannelManager::send_payment`].
                ///
@@ -446,7 +481,7 @@ pub enum Event {
        /// Always generated after [`Event::PaymentSent`] and thus useful for scoring channels. See
        /// [`Event::PaymentSent`] for obtaining the payment preimage.
        PaymentPathSuccessful {
-               /// The id returned by [`ChannelManager::send_payment`].
+               /// The `payment_id` passed to [`ChannelManager::send_payment`].
                ///
                /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
                payment_id: PaymentId,
@@ -470,8 +505,7 @@ pub enum Event {
        ///
        /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment
        PaymentPathFailed {
-               /// The id returned by [`ChannelManager::send_payment`] and used with
-               /// [`ChannelManager::abandon_payment`].
+               /// The `payment_id` passed to [`ChannelManager::send_payment`].
                ///
                /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
                /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment