X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning%2Fsrc%2Futil%2Fevents.rs;h=a4a733c8e503eff05212d6570ada728a4cb95c1e;hb=f49662caa4a9cb845ae1451b0baf85b80b8dc711;hp=46ab9f74924e453b5446c27a783616cab0a0ff5d;hpb=0cdea66b0e73d45b2a137eed145a294b7d713cc4;p=rust-lightning diff --git a/lightning/src/util/events.rs b/lightning/src/util/events.rs index 46ab9f74..a4a733c8 100644 --- a/lightning/src/util/events.rs +++ b/lightning/src/util/events.rs @@ -153,10 +153,13 @@ impl_writeable_tlv_based_enum_upgradable!(ClosureReason, #[derive(Clone, Debug)] pub enum Event { /// Used to indicate that the client should generate a funding transaction with the given - /// parameters and then call ChannelManager::funding_transaction_generated. - /// Generated in ChannelManager message handling. + /// parameters and then call [`ChannelManager::funding_transaction_generated`]. + /// Generated in [`ChannelManager`] message handling. /// Note that *all inputs* in the funding transaction must spend SegWit outputs or your /// counterparty can steal your funds! + /// + /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager + /// [`ChannelManager::funding_transaction_generated`]: crate::ln::channelmanager::ChannelManager::funding_transaction_generated FundingGenerationReady { /// The random channel_id we picked which you'll need to pass into /// ChannelManager::funding_transaction_generated. @@ -180,10 +183,15 @@ pub enum Event { /// [`ChannelManager::fail_htlc_backwards`] within the HTLC's timeout, the HTLC will be /// automatically failed. /// + /// # Note + /// LDK will not stop an inbound payment from being paid multiple times, so multiple + /// `PaymentReceived` events may be generated for the same payment. + /// /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds /// [`ChannelManager::fail_htlc_backwards`]: crate::ln::channelmanager::ChannelManager::fail_htlc_backwards PaymentReceived { - /// The hash for which the preimage should be handed to the ChannelManager. + /// The hash for which the preimage should be handed to the ChannelManager. Note that LDK will + /// not stop you from registering duplicate payment hashes for inbound payments. payment_hash: PaymentHash, /// The value, in thousandths of a satoshi, that this payment is for. amt: u64, @@ -222,14 +230,20 @@ pub enum Event { /// [`Route::get_total_fees`]: crate::routing::router::Route::get_total_fees fee_paid_msat: Option, }, - /// Indicates an outbound payment we made failed. Probably some intermediary node dropped + /// Indicates an outbound HTLC we sent failed. Probably some intermediary node dropped /// something. You may wish to retry with a different route. + /// + /// Note that this does *not* indicate that all paths for an MPP payment have failed, see + /// [`Event::PaymentFailed`] and [`all_paths_failed`]. + /// + /// [`all_paths_failed`]: Self::all_paths_failed PaymentPathFailed { /// The id returned by [`ChannelManager::send_payment`] and used with - /// [`ChannelManager::retry_payment`]. + /// [`ChannelManager::retry_payment`] and [`ChannelManager::abandon_payment`]. /// /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment /// [`ChannelManager::retry_payment`]: crate::ln::channelmanager::ChannelManager::retry_payment + /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment payment_id: Option, /// The hash that was given to [`ChannelManager::send_payment`]. /// @@ -251,6 +265,20 @@ pub enum Event { /// For both single-path and multi-path payments, this is set if all paths of the payment have /// failed. This will be set to false if (1) this is an MPP payment and (2) other parts of the /// larger MPP payment were still in flight when this event was generated. + /// + /// Note that if you are retrying individual MPP parts, using this value to determine if a + /// payment has fully failed is race-y. Because multiple failures can happen prior to events + /// being processed, you may retry in response to a first failure, with a second failure + /// (with `all_paths_failed` set) still pending. Then, when the second failure is processed + /// you will see `all_paths_failed` set even though the retry of the first failure still + /// has an associated in-flight HTLC. See (1) for an example of such a failure. + /// + /// If you wish to retry individual MPP parts and learn when a payment has failed, you must + /// call [`ChannelManager::abandon_payment`] and wait for a [`Event::PaymentFailed`] event. + /// + /// (1) + /// + /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment all_paths_failed: bool, /// The payment path that failed. path: Vec, @@ -271,8 +299,31 @@ pub enum Event { #[cfg(test)] error_data: Option>, }, - /// Used to indicate that ChannelManager::process_pending_htlc_forwards should be called at a - /// time in the future. + /// Indicates an outbound payment failed. Individual [`Event::PaymentPathFailed`] events + /// provide failure information for each MPP part in the payment. + /// + /// This event is provided once there are no further pending HTLCs for the payment and the + /// payment is no longer retryable, either due to a several-block timeout or because + /// [`ChannelManager::abandon_payment`] was previously called for the corresponding payment. + /// + /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment + PaymentFailed { + /// The id returned by [`ChannelManager::send_payment`] and used with + /// [`ChannelManager::retry_payment`] and [`ChannelManager::abandon_payment`]. + /// + /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment + /// [`ChannelManager::retry_payment`]: crate::ln::channelmanager::ChannelManager::retry_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, + }, + /// Used to indicate that [`ChannelManager::process_pending_htlc_forwards`] should be called at + /// a time in the future. + /// + /// [`ChannelManager::process_pending_htlc_forwards`]: crate::ln::channelmanager::ChannelManager::process_pending_htlc_forwards PendingHTLCsForwardable { /// The minimum amount of time that should be waited prior to calling /// process_pending_htlc_forwards. To increase the effort required to correlate payments, @@ -457,6 +508,13 @@ impl Writeable for Event { (4, path, vec_type) }) }, + &Event::PaymentFailed { ref payment_id, ref payment_hash } => { + 15u8.write(writer)?; + write_tlv_fields!(writer, { + (0, payment_id, required), + (2, payment_hash, required), + }) + }, // Note that, going forward, all new events must only write data inside of // `write_tlv_fields`. Versions 0.0.101+ will ignore odd-numbered events that write // data via `write_tlv_fields`. @@ -634,6 +692,21 @@ impl MaybeReadable for Event { }; f() }, + 15u8 => { + let f = || { + let mut payment_hash = PaymentHash([0; 32]); + let mut payment_id = PaymentId([0; 32]); + read_tlv_fields!(reader, { + (0, payment_id, required), + (2, payment_hash, required), + }); + Ok(Some(Event::PaymentFailed { + payment_id, + payment_hash, + })) + }; + f() + }, // Versions prior to 0.0.100 did not ignore odd types, instead returning InvalidValue. // Version 0.0.100 failed to properly ignore odd types, possibly resulting in corrupt // reads.