X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning%2Fsrc%2Futil%2Fevents.rs;h=f7ec29e79e1898bc12e79594a43bc206f55f2791;hb=0aaba2ce45a5f295aa76ff4afeaf96fa5f52bb5a;hp=04a3b1004bd342f1d438b37c1f1035a7b1f3d346;hpb=5efc1976cdd551fa8378108570aa2e40281bd5fb;p=rust-lightning diff --git a/lightning/src/util/events.rs b/lightning/src/util/events.rs index 04a3b100..f7ec29e7 100644 --- a/lightning/src/util/events.rs +++ b/lightning/src/util/events.rs @@ -182,6 +182,12 @@ pub enum HTLCDestination { /// Short channel id we are requesting to forward an HTLC to. requested_forward_scid: u64, }, + /// We couldn't forward to the outgoing scid. An example would be attempting to send a duplicate + /// intercept HTLC. + InvalidForward { + /// Short channel id we are requesting to forward an HTLC to. + requested_forward_scid: u64 + }, /// Failure scenario where an HTLC may have been forwarded to be intended for us, /// but is invalid for some reason, so we reject it. /// @@ -200,12 +206,15 @@ impl_writeable_tlv_based_enum_upgradable!(HTLCDestination, (0, node_id, required), (2, channel_id, required), }, + (1, InvalidForward) => { + (0, requested_forward_scid, required), + }, (2, UnknownNextHop) => { (0, requested_forward_scid, required), }, (4, FailedPayment) => { (0, payment_hash, required), - } + }, ); #[cfg(anchors)] @@ -240,7 +249,7 @@ pub enum BumpTransactionEvent { /// with additional inputs to meet the target feerate. Failure to meet the target feerate /// decreases the confirmation odds of the transaction package (which includes the commitment /// and child anchor transactions), possibly resulting in a loss of funds. Once the transaction - /// is constructed, it must be fully signed for and broadcasted by the consumer of the event + /// is constructed, it must be fully signed for and broadcast by the consumer of the event /// along with the `commitment_tx` enclosed. Note that the `commitment_tx` must always be /// broadcast first, as the child anchor transaction depends on it. /// @@ -341,8 +350,8 @@ pub enum Event { /// [`ChannelManager::create_channel`]: crate::ln::channelmanager::ChannelManager::create_channel user_channel_id: u128, }, - /// Indicates we've received (an offer of) money! Just gotta dig out that payment preimage and - /// feed it to [`ChannelManager::claim_funds`] to get it.... + /// Indicates that we've been offered a payment and it needs to be claimed via calling + /// [`ChannelManager::claim_funds`] with the preimage given in [`PaymentPurpose`]. /// /// Note that if the preimage is not known, you should call /// [`ChannelManager::fail_htlc_backwards`] to free up resources for this HTLC and avoid @@ -353,17 +362,20 @@ pub enum Event { /// /// # Note /// LDK will not stop an inbound payment from being paid multiple times, so multiple - /// `PaymentReceived` events may be generated for the same payment. + /// `PaymentClaimable` events may be generated for the same payment. + /// + /// # Note + /// This event used to be called `PaymentReceived` in LDK versions 0.0.112 and earlier. /// /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds /// [`ChannelManager::fail_htlc_backwards`]: crate::ln::channelmanager::ChannelManager::fail_htlc_backwards - PaymentReceived { - /// The node that received the payment. - /// This is useful to identify payments which were received via [phantom node payments]. + PaymentClaimable { + /// The node that will receive the payment after it has been claimed. + /// This is useful to identify payments received via [phantom nodes]. /// This field will always be filled in when the event was generated by LDK versions /// 0.0.113 and above. /// - /// [phantom node payments]: crate::chain::keysinterface::PhantomKeysManager + /// [phantom nodes]: crate::chain::keysinterface::PhantomKeysManager receiver_node_id: Option, /// 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. @@ -381,31 +393,31 @@ pub enum Event { /// Indicates a payment has been claimed and we've received money! /// /// This most likely occurs when [`ChannelManager::claim_funds`] has been called in response - /// to an [`Event::PaymentReceived`]. However, if we previously crashed during a + /// to an [`Event::PaymentClaimable`]. However, if we previously crashed during a /// [`ChannelManager::claim_funds`] call you may see this event without a corresponding - /// [`Event::PaymentReceived`] event. + /// [`Event::PaymentClaimable`] event. /// /// # Note /// LDK will not stop an inbound payment from being paid multiple times, so multiple - /// `PaymentReceived` events may be generated for the same payment. If you then call - /// [`ChannelManager::claim_funds`] twice for the same [`Event::PaymentReceived`] you may get + /// `PaymentClaimable` events may be generated for the same payment. If you then call + /// [`ChannelManager::claim_funds`] twice for the same [`Event::PaymentClaimable`] you may get /// multiple `PaymentClaimed` events. /// /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds PaymentClaimed { /// The node that received the payment. - /// This is useful to identify payments which were received via [phantom node payments]. + /// This is useful to identify payments which were received via [phantom nodes]. /// This field will always be filled in when the event was generated by LDK versions /// 0.0.113 and above. /// - /// [phantom node payments]: crate::chain::keysinterface::PhantomKeysManager + /// [phantom nodes]: crate::chain::keysinterface::PhantomKeysManager receiver_node_id: Option, /// The payment hash of the claimed payment. 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. amount_msat: u64, - /// The purpose of this claimed payment, i.e. whether the payment was for an invoice or a + /// The purpose of the claimed payment, i.e. whether the payment was for an invoice or a /// spontaneous payment. purpose: PaymentPurpose, }, @@ -601,11 +613,25 @@ pub enum Event { /// now + 5*time_forwardable). time_forwardable: Duration, }, - /// Used to indicate that we've intercepted an HTLC forward. + /// Used to indicate that we've intercepted an HTLC forward. This event will only be generated if + /// you've encoded an intercept scid in the receiver's invoice route hints using + /// [`ChannelManager::get_intercept_scid`] and have set [`UserConfig::accept_intercept_htlcs`]. + /// + /// [`ChannelManager::forward_intercepted_htlc`] or + /// [`ChannelManager::fail_intercepted_htlc`] MUST be called in response to this event. See + /// their docs for more information. + /// + /// [`ChannelManager::get_intercept_scid`]: crate::ln::channelmanager::ChannelManager::get_intercept_scid + /// [`UserConfig::accept_intercept_htlcs`]: crate::util::config::UserConfig::accept_intercept_htlcs + /// [`ChannelManager::forward_intercepted_htlc`]: crate::ln::channelmanager::ChannelManager::forward_intercepted_htlc + /// [`ChannelManager::fail_intercepted_htlc`]: crate::ln::channelmanager::ChannelManager::fail_intercepted_htlc HTLCIntercepted { /// An id to help LDK identify which HTLC is being forwarded or failed. intercept_id: InterceptId, - /// The fake scid that was programmed as the next hop's scid. + /// The fake scid that was programmed as the next hop's scid, generated using + /// [`ChannelManager::get_intercept_scid`]. + /// + /// [`ChannelManager::get_intercept_scid`]: crate::ln::channelmanager::ChannelManager::get_intercept_scid requested_next_hop_scid: u64, /// The payment hash used for this HTLC. payment_hash: PaymentHash, @@ -791,7 +817,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::PaymentReceived { 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 } => { 1u8.write(writer)?; let mut payment_secret = None; let payment_preimage; @@ -1012,7 +1038,7 @@ impl MaybeReadable for Event { None if payment_preimage.is_some() => PaymentPurpose::SpontaneousPayment(payment_preimage.unwrap()), None => return Err(msgs::DecodeError::InvalidValue), }; - Ok(Some(Event::PaymentReceived { + Ok(Some(Event::PaymentClaimable { receiver_node_id, payment_hash, amount_msat,