X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning%2Fsrc%2Fevents%2Fmod.rs;h=63762dc55d4a95b82e95c8660ae652809641a9c1;hb=e1a6bc3cadb8c89ba38afb5846fb80f349d99449;hp=2d576d33a0581404baf686b64587e65a6d0b3ab6;hpb=9873c7dad851a0ffa16f38a4788115cb5e0f5907;p=rust-lightning diff --git a/lightning/src/events/mod.rs b/lightning/src/events/mod.rs index 2d576d33..63762dc5 100644 --- 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 @@ -321,7 +358,9 @@ pub enum Event { /// /// # Note /// LDK will not stop an inbound payment from being paid multiple times, so multiple - /// `PaymentClaimable` events may be generated for the same payment. + /// `PaymentClaimable` events may be generated for the same payment. In such a case it is + /// polite (and required in the lightning specification) to fail the payment the second time + /// and give the sender their money back rather than accepting double payment. /// /// # Note /// This event used to be called `PaymentReceived` in LDK versions 0.0.112 and earlier. @@ -349,6 +388,14 @@ pub enum Event { via_channel_id: Option<[u8; 32]>, /// The `user_channel_id` indicating over which channel we received the payment. via_user_channel_id: Option, + /// The block height at which this payment will be failed back and will no longer be + /// eligible for claiming. + /// + /// Prior to this height, a call to [`ChannelManager::claim_funds`] is guaranteed to + /// succeed, however you should wait for [`Event::PaymentClaimed`] to be sure. + /// + /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds + claim_deadline: Option, }, /// Indicates a payment has been claimed and we've received money! /// @@ -387,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, @@ -420,23 +467,24 @@ 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`]. /// /// [`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, }, /// Indicates that a path for an outbound payment was successful. /// /// 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, @@ -460,8 +508,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 @@ -773,7 +820,7 @@ impl Writeable for Event { // We never write out FundingGenerationReady events as, upon disconnection, peers // drop any channels which have not yet exchanged funding_signed. }, - &Event::PaymentClaimable { ref payment_hash, ref amount_msat, ref purpose, ref receiver_node_id, ref via_channel_id, ref via_user_channel_id } => { + &Event::PaymentClaimable { ref payment_hash, ref amount_msat, ref purpose, ref receiver_node_id, ref via_channel_id, ref via_user_channel_id, ref claim_deadline } => { 1u8.write(writer)?; let mut payment_secret = None; let payment_preimage; @@ -794,6 +841,7 @@ impl Writeable for Event { (4, amount_msat, required), (5, via_user_channel_id, option), (6, 0u64, required), // user_payment_id required for compatibility with 0.0.103 and earlier + (7, claim_deadline, option), (8, payment_preimage, option), }); }, @@ -895,10 +943,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), }) }, @@ -992,6 +1041,7 @@ impl MaybeReadable for Event { let mut receiver_node_id = None; let mut _user_payment_id = None::; // For compatibility with 0.0.103 and earlier let mut via_channel_id = None; + let mut claim_deadline = None; let mut via_user_channel_id = None; read_tlv_fields!(reader, { (0, payment_hash, required), @@ -1001,6 +1051,7 @@ impl MaybeReadable for Event { (4, amount_msat, required), (5, via_user_channel_id, option), (6, _user_payment_id, option), + (7, claim_deadline, option), (8, payment_preimage, option), }); let purpose = match payment_secret { @@ -1018,6 +1069,7 @@ impl MaybeReadable for Event { purpose, via_channel_id, via_user_channel_id, + claim_deadline, })) }; f() @@ -1197,13 +1249,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()