X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning%2Fsrc%2Futil%2Fevents.rs;h=f7ec29e79e1898bc12e79594a43bc206f55f2791;hb=0aaba2ce45a5f295aa76ff4afeaf96fa5f52bb5a;hp=9818bfc4c8da0eb8fc746a8133d08df84aaaa5d8;hpb=d3f1e25f65bd67305a6e3fd3e824cc750dec1ad9;p=rust-lightning diff --git a/lightning/src/util/events.rs b/lightning/src/util/events.rs index 9818bfc4..f7ec29e7 100644 --- a/lightning/src/util/events.rs +++ b/lightning/src/util/events.rs @@ -17,7 +17,7 @@ use crate::chain::keysinterface::SpendableOutputDescriptor; #[cfg(anchors)] use crate::ln::chan_utils::HTLCOutputInCommitment; -use crate::ln::channelmanager::PaymentId; +use crate::ln::channelmanager::{InterceptId, PaymentId}; use crate::ln::channel::FUNDING_CONF_DEADLINE_BLOCKS; use crate::ln::features::ChannelTypeFeatures; use crate::ln::msgs; @@ -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. /// @@ -288,6 +297,22 @@ pub enum BumpTransactionEvent { }, } +/// Will be used in [`Event::HTLCIntercepted`] to identify the next hop in the HTLC's path. +/// Currently only used in serialization for the sake of maintaining compatibility. More variants +/// will be added for general-purpose HTLC forward intercepts as well as trampoline forward +/// intercepts in upcoming work. +enum InterceptNextHop { + FakeScid { + requested_next_hop_scid: u64, + }, +} + +impl_writeable_tlv_based_enum!(InterceptNextHop, + (0, FakeScid) => { + (0, requested_next_hop_scid, required), + }; +); + /// 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 @@ -318,14 +343,15 @@ pub enum Event { channel_value_satoshis: u64, /// The script which should be used in the transaction output. output_script: Script, - /// The `user_channel_id` value passed in to [`ChannelManager::create_channel`], or 0 for - /// an inbound channel. + /// The `user_channel_id` value passed in to [`ChannelManager::create_channel`], or a + /// random value for an inbound channel. This may be zero for objects serialized with LDK + /// versions prior to 0.0.113. /// /// [`ChannelManager::create_channel`]: crate::ln::channelmanager::ChannelManager::create_channel - user_channel_id: u64, + 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 @@ -336,11 +362,21 @@ 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 { + 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 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. payment_hash: PaymentHash, @@ -349,28 +385,39 @@ pub enum Event { /// Information for claiming this received payment, based on whether the purpose of the /// payment is to pay an invoice or to send a spontaneous payment. purpose: PaymentPurpose, + /// The `channel_id` indicating over which channel we received the payment. + via_channel_id: Option<[u8; 32]>, + /// The `user_channel_id` indicating over which channel we received the payment. + via_user_channel_id: Option, }, /// 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 nodes]. + /// This field will always be filled in when the event was generated by LDK versions + /// 0.0.113 and above. + /// + /// [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, }, @@ -566,6 +613,38 @@ pub enum Event { /// now + 5*time_forwardable). time_forwardable: Duration, }, + /// 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, 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, + /// How many msats were received on the inbound edge of this HTLC. + inbound_amount_msat: u64, + /// How many msats the payer intended to route to the next node. Depending on the reason you are + /// intercepting this payment, you might take a fee by forwarding less than this amount. + /// + /// Note that LDK will NOT check that expected fees were factored into this value. You MUST + /// check that whatever fee you want has been included here or subtract it as required. Further, + /// LDK will not stop you from forwarding more than you received. + expected_outbound_amount_msat: u64, + }, /// Used to indicate that an output which you should know how to spend was confirmed on chain /// and is now spendable. /// Such an output will *not* ever be spent by rust-lightning, and are not at risk of your @@ -612,12 +691,12 @@ pub enum Event { /// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound /// channels, or to [`ChannelManager::accept_inbound_channel`] for inbound channels if /// [`UserConfig::manually_accept_inbound_channels`] config flag is set to true. Otherwise - /// `user_channel_id` will be 0 for an inbound channel. + /// `user_channel_id` will be randomized for an inbound channel. /// /// [`ChannelManager::create_channel`]: crate::ln::channelmanager::ChannelManager::create_channel /// [`ChannelManager::accept_inbound_channel`]: crate::ln::channelmanager::ChannelManager::accept_inbound_channel /// [`UserConfig::manually_accept_inbound_channels`]: crate::util::config::UserConfig::manually_accept_inbound_channels - user_channel_id: u64, + user_channel_id: u128, /// The node_id of the channel counterparty. counterparty_node_id: PublicKey, /// The features that this channel will operate with. @@ -632,13 +711,14 @@ pub enum Event { /// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound /// channels, or to [`ChannelManager::accept_inbound_channel`] for inbound channels if /// [`UserConfig::manually_accept_inbound_channels`] config flag is set to true. Otherwise - /// `user_channel_id` will be 0 for an inbound channel. - /// This will always be zero for objects serialized with LDK versions prior to 0.0.102. + /// `user_channel_id` will be randomized for inbound channels. + /// This may be zero for inbound channels serialized prior to 0.0.113 and will always be + /// zero for objects serialized with LDK versions prior to 0.0.102. /// /// [`ChannelManager::create_channel`]: crate::ln::channelmanager::ChannelManager::create_channel /// [`ChannelManager::accept_inbound_channel`]: crate::ln::channelmanager::ChannelManager::accept_inbound_channel /// [`UserConfig::manually_accept_inbound_channels`]: crate::util::config::UserConfig::manually_accept_inbound_channels - user_channel_id: u64, + user_channel_id: u128, /// The reason the channel was closed. reason: ClosureReason }, @@ -737,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 } => { + &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; @@ -752,8 +832,11 @@ impl Writeable for Event { } write_tlv_fields!(writer, { (0, payment_hash, required), + (1, receiver_node_id, option), (2, payment_secret, option), + (3, via_channel_id, option), (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 (8, payment_preimage, option), }); @@ -802,6 +885,17 @@ impl Writeable for Event { (0, WithoutLength(outputs), required), }); }, + &Event::HTLCIntercepted { requested_next_hop_scid, payment_hash, inbound_amount_msat, expected_outbound_amount_msat, intercept_id } => { + 6u8.write(writer)?; + let intercept_scid = InterceptNextHop::FakeScid { requested_next_hop_scid }; + write_tlv_fields!(writer, { + (0, intercept_id, required), + (2, intercept_scid, required), + (4, payment_hash, required), + (6, inbound_amount_msat, required), + (8, expected_outbound_amount_msat, required), + }); + } &Event::PaymentForwarded { fee_earned_msat, prev_channel_id, claim_from_onchain_tx, next_channel_id } => { 7u8.write(writer)?; write_tlv_fields!(writer, { @@ -813,10 +907,16 @@ impl Writeable for Event { }, &Event::ChannelClosed { ref channel_id, ref user_channel_id, ref reason } => { 9u8.write(writer)?; + // `user_channel_id` used to be a single u64 value. In order to remain backwards + // compatible with versions prior to 0.0.113, the u128 is serialized as two + // separate u64 values. + let user_channel_id_low = *user_channel_id as u64; + let user_channel_id_high = (*user_channel_id >> 64) as u64; write_tlv_fields!(writer, { (0, channel_id, required), - (1, user_channel_id, required), - (2, reason, required) + (1, user_channel_id_low, required), + (2, reason, required), + (3, user_channel_id_high, required), }); }, &Event::DiscardFunding { ref channel_id, ref transaction } => { @@ -846,10 +946,11 @@ impl Writeable for Event { // We never write the OpenChannelRequest events as, upon disconnection, peers // drop any channels which have not yet exchanged funding_signed. }, - &Event::PaymentClaimed { ref payment_hash, ref amount_msat, ref purpose } => { + &Event::PaymentClaimed { ref payment_hash, ref amount_msat, ref purpose, ref receiver_node_id } => { 19u8.write(writer)?; write_tlv_fields!(writer, { (0, payment_hash, required), + (1, receiver_node_id, option), (2, purpose, required), (4, amount_msat, required), }); @@ -915,11 +1016,17 @@ impl MaybeReadable for Event { let mut payment_preimage = None; let mut payment_secret = None; let mut amount_msat = 0; + 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 via_user_channel_id = None; read_tlv_fields!(reader, { (0, payment_hash, required), + (1, receiver_node_id, option), (2, payment_secret, option), + (3, via_channel_id, option), (4, amount_msat, required), + (5, via_user_channel_id, option), (6, _user_payment_id, option), (8, payment_preimage, option), }); @@ -931,10 +1038,13 @@ 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, purpose, + via_channel_id, + via_user_channel_id, })) }; f() @@ -1015,6 +1125,30 @@ impl MaybeReadable for Event { }; f() }, + 6u8 => { + let mut payment_hash = PaymentHash([0; 32]); + let mut intercept_id = InterceptId([0; 32]); + let mut requested_next_hop_scid = InterceptNextHop::FakeScid { requested_next_hop_scid: 0 }; + let mut inbound_amount_msat = 0; + let mut expected_outbound_amount_msat = 0; + read_tlv_fields!(reader, { + (0, intercept_id, required), + (2, requested_next_hop_scid, required), + (4, payment_hash, required), + (6, inbound_amount_msat, required), + (8, expected_outbound_amount_msat, required), + }); + let next_scid = match requested_next_hop_scid { + InterceptNextHop::FakeScid { requested_next_hop_scid: scid } => scid + }; + Ok(Some(Event::HTLCIntercepted { + payment_hash, + requested_next_hop_scid: next_scid, + inbound_amount_msat, + expected_outbound_amount_msat, + intercept_id, + })) + }, 7u8 => { let f = || { let mut fee_earned_msat = None; @@ -1035,14 +1169,22 @@ impl MaybeReadable for Event { let f = || { let mut channel_id = [0; 32]; let mut reason = None; - let mut user_channel_id_opt = None; + let mut user_channel_id_low_opt: Option = None; + let mut user_channel_id_high_opt: Option = None; read_tlv_fields!(reader, { (0, channel_id, required), - (1, user_channel_id_opt, option), + (1, user_channel_id_low_opt, option), (2, reason, ignorable), + (3, user_channel_id_high_opt, option), }); if reason.is_none() { return Ok(None); } - let user_channel_id = if let Some(id) = user_channel_id_opt { id } else { 0 }; + + // `user_channel_id` used to be a single u64 value. In order to remain + // backwards compatible with versions prior to 0.0.113, the u128 is serialized + // as two separate u64 values. + let user_channel_id = (user_channel_id_low_opt.unwrap_or(0) as u128) + + ((user_channel_id_high_opt.unwrap_or(0) as u128) << 64); + Ok(Some(Event::ChannelClosed { channel_id, user_channel_id, reason: reason.unwrap() })) }; f() @@ -1101,13 +1243,16 @@ impl MaybeReadable for Event { let mut payment_hash = PaymentHash([0; 32]); let mut purpose = None; let mut amount_msat = 0; + let mut receiver_node_id = None; read_tlv_fields!(reader, { (0, payment_hash, required), + (1, receiver_node_id, option), (2, purpose, ignorable), (4, amount_msat, required), }); if purpose.is_none() { return Ok(None); } Ok(Some(Event::PaymentClaimed { + receiver_node_id, payment_hash, purpose: purpose.unwrap(), amount_msat, @@ -1180,7 +1325,7 @@ impl MaybeReadable for Event { 29u8 => { let f = || { let mut channel_id = [0; 32]; - let mut user_channel_id: u64 = 0; + let mut user_channel_id: u128 = 0; let mut counterparty_node_id = OptionDeserWrapper(None); let mut channel_type = OptionDeserWrapper(None); read_tlv_fields!(reader, {