X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning%2Fsrc%2Futil%2Fevents.rs;h=4d68d01f6ed9301661145b222cf5b0aea2dba870;hb=30b9d9fbeaa62537beb8d3ea0b2866703d0d7c92;hp=475533c902a372fdb0bea1b86cb0e754dc90fbe4;hpb=ccf92157620da45032d75f06b5972eaf142c1ce3;p=rust-lightning diff --git a/lightning/src/util/events.rs b/lightning/src/util/events.rs index 475533c9..4d68d01f 100644 --- a/lightning/src/util/events.rs +++ b/lightning/src/util/events.rs @@ -565,11 +565,9 @@ 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`] and used with - /// [`ChannelManager::retry_payment`]. + /// The id returned by [`ChannelManager::send_payment`]. /// /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment - /// [`ChannelManager::retry_payment`]: crate::ln::channelmanager::ChannelManager::retry_payment payment_id: Option, /// The preimage to the hash given to ChannelManager::send_payment. /// Note that this serves as a payment receipt, if you wish to have such a thing, you must @@ -594,16 +592,16 @@ pub enum Event { /// 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 due to [`ChannelManager::abandon_payment`] having been - /// called for the corresponding payment. + /// payment is no longer retryable, due either to the [`Retry`] provided or + /// [`ChannelManager::abandon_payment`] having been called for the corresponding payment. /// + /// [`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::retry_payment`] and [`ChannelManager::abandon_payment`]. + /// [`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`]. @@ -616,11 +614,9 @@ 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`] and used with - /// [`ChannelManager::retry_payment`]. + /// The id returned by [`ChannelManager::send_payment`]. /// /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment - /// [`ChannelManager::retry_payment`]: crate::ln::channelmanager::ChannelManager::retry_payment payment_id: PaymentId, /// The hash that was given to [`ChannelManager::send_payment`]. /// @@ -631,24 +627,22 @@ pub enum Event { /// May contain a closed channel if the HTLC sent along the path was fulfilled on chain. path: Vec, }, - /// Indicates an outbound HTLC we sent failed. Probably some intermediary node dropped - /// something. You may wish to retry with a different route. - /// - /// If you have given up retrying this payment and wish to fail it, you MUST call - /// [`ChannelManager::abandon_payment`] at least once for a given [`PaymentId`] or memory - /// related to payment tracking will leak. + /// Indicates an outbound HTLC we sent failed, likely due to an intermediary node being unable to + /// handle the HTLC. /// /// Note that this does *not* indicate that all paths for an MPP payment have failed, see /// [`Event::PaymentFailed`] and [`all_paths_failed`]. /// + /// See [`ChannelManager::abandon_payment`] for giving up on this payment before its retries have + /// been exhausted. + /// /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment /// [`all_paths_failed`]: Self::PaymentPathFailed::all_paths_failed PaymentPathFailed { /// The id returned by [`ChannelManager::send_payment`] and used with - /// [`ChannelManager::retry_payment`] and [`ChannelManager::abandon_payment`]. + /// [`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`]. @@ -656,8 +650,8 @@ pub enum Event { /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment payment_hash: PaymentHash, /// Indicates the payment was rejected for some reason by the recipient. This implies that - /// the payment has failed, not just the route in question. If this is not set, you may - /// retry the payment via a different route. + /// the payment has failed, not just the route in question. If this is not set, the payment may + /// be retried via a different route. payment_failed_permanently: bool, /// Any failure information conveyed via the Onion return packet by a node along the failed /// payment route. @@ -670,20 +664,6 @@ 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, @@ -696,12 +676,9 @@ pub enum Event { /// If this is `Some`, then the corresponding channel should be avoided when the payment is /// retried. May be `None` for older [`Event`] serializations. short_channel_id: Option, - /// Parameters needed to compute a new [`Route`] when retrying the failed payment path. - /// - /// See [`find_route`] for details. + /// Parameters used by LDK to compute a new [`Route`] when retrying the failed payment path. /// /// [`Route`]: crate::routing::router::Route - /// [`find_route`]: crate::routing::router::find_route retry: Option, #[cfg(test)] error_code: Option, @@ -1612,13 +1589,18 @@ pub enum MessageSendEvent { /// The channel_announcement which should be sent. msg: msgs::ChannelAnnouncement, /// The followup channel_update which should be sent. - update_msg: msgs::ChannelUpdate, + update_msg: Option, }, /// Used to indicate that a channel_update should be broadcast to all peers. BroadcastChannelUpdate { /// The channel_update which should be sent. msg: msgs::ChannelUpdate, }, + /// Used to indicate that a node_announcement should be broadcast to all peers. + BroadcastNodeAnnouncement { + /// The node_announcement which should be sent. + msg: msgs::NodeAnnouncement, + }, /// Used to indicate that a channel_update should be sent to a single peer. /// In contrast to [`Self::BroadcastChannelUpdate`], this is used when the channel is a /// private channel and we shouldn't be informing all of our peers of channel parameters.