X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning%2Fsrc%2Fevents%2Fmod.rs;h=28313046433151bdb566beb5a2974bdd1d469908;hb=8866ed35330bae1af2237c1951d9c4025938aa65;hp=f4c4af7e90ff02bf5cf59c22994a7728ded4fcf5;hpb=773e8ad583def9aa060f708334c942b5b2fd24aa;p=rust-lightning diff --git a/lightning/src/events/mod.rs b/lightning/src/events/mod.rs index f4c4af7e..28313046 100644 --- a/lightning/src/events/mod.rs +++ b/lightning/src/events/mod.rs @@ -14,10 +14,8 @@ //! future, as well as generate and broadcast funding transactions handle payment preimages and a //! few other things. -#[cfg(anchors)] pub mod bump_transaction; -#[cfg(anchors)] pub use bump_transaction::BumpTransactionEvent; use crate::sign::SpendableOutputDescriptor; @@ -81,6 +79,37 @@ impl_writeable_tlv_based_enum!(PaymentPurpose, (2, SpontaneousPayment) ); +/// Information about an HTLC that is part of a payment that can be claimed. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct ClaimedHTLC { + /// The `channel_id` of the channel over which the HTLC was received. + pub channel_id: [u8; 32], + /// The `user_channel_id` of the channel over which the HTLC was received. This is the 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 randomized for an inbound channel. + /// + /// This field will be zero for a payment that was serialized prior to LDK version 0.0.117. (This + /// should only happen in the case that a payment was claimable prior to LDK version 0.0.117, but + /// was not actually claimed until after upgrading.) + /// + /// [`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 + pub user_channel_id: u128, + /// The block height at which this HTLC expires. + pub cltv_expiry: u32, + /// The amount (in msats) of this part of an MPP. + pub value_msat: u64, +} +impl_writeable_tlv_based!(ClaimedHTLC, { + (0, channel_id, required), + (2, user_channel_id, required), + (4, cltv_expiry, required), + (6, value_msat, required), +}); + /// When the payment path failure took place and extra details about it. [`PathFailure::OnPath`] may /// contain a [`NetworkUpdate`] that needs to be applied to the [`NetworkGraph`]. /// @@ -115,7 +144,7 @@ impl_writeable_tlv_based_enum_upgradable!(PathFailure, ); #[derive(Clone, Debug, PartialEq, Eq)] -/// The reason the channel was closed. See individual variants more details. +/// The reason the channel was closed. See individual variants for more details. pub enum ClosureReason { /// Closure generated from receiving a peer error message. /// @@ -166,7 +195,10 @@ pub enum ClosureReason { /// /// [`ChannelMonitor`]: crate::chain::channelmonitor::ChannelMonitor /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager - OutdatedChannelManager + OutdatedChannelManager, + /// The counterparty requested a cooperative close of a channel that had not been funded yet. + /// The channel has been immediately closed. + CounterpartyCoopClosedUnfundedChannel, } impl core::fmt::Display for ClosureReason { @@ -186,6 +218,7 @@ impl core::fmt::Display for ClosureReason { }, ClosureReason::DisconnectedPeer => f.write_str("the peer disconnected prior to the channel being funded"), ClosureReason::OutdatedChannelManager => f.write_str("the ChannelManager read from disk was stale compared to ChannelMonitor(s)"), + ClosureReason::CounterpartyCoopClosedUnfundedChannel => f.write_str("the peer requested the unfunded channel be closed"), } } } @@ -199,6 +232,7 @@ impl_writeable_tlv_based_enum_upgradable!(ClosureReason, (8, ProcessingError) => { (1, err, required) }, (10, DisconnectedPeer) => {}, (12, OutdatedChannelManager) => {}, + (13, CounterpartyCoopClosedUnfundedChannel) => {}, ); /// Intended destination of a failed HTLC as indicated in [`Event::HTLCHandlingFailed`]. @@ -340,11 +374,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 a - /// random value for an inbound channel. This may be zero for objects serialized with LDK - /// versions prior to 0.0.113. + /// 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 randomized 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 + /// [`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: u128, }, /// Indicates that we've been offered a payment and it needs to be claimed via calling @@ -353,9 +391,19 @@ pub enum Event { /// Note that if the preimage is not known, you should call /// [`ChannelManager::fail_htlc_backwards`] or [`ChannelManager::fail_htlc_backwards_with_reason`] /// to free up resources for this HTLC and avoid network congestion. - /// If you fail to call either [`ChannelManager::claim_funds`], [`ChannelManager::fail_htlc_backwards`], - /// or [`ChannelManager::fail_htlc_backwards_with_reason`] within the HTLC's timeout, the HTLC will be - /// automatically failed. + /// + /// If [`Event::PaymentClaimable::onion_fields`] is `Some`, and includes custom TLVs with even type + /// numbers, you should use [`ChannelManager::fail_htlc_backwards_with_reason`] with + /// [`FailureCode::InvalidOnionPayload`] if you fail to understand and handle the contents, or + /// [`ChannelManager::claim_funds_with_known_custom_tlvs`] upon successful handling. + /// If you don't intend to check for custom TLVs, you can simply use + /// [`ChannelManager::claim_funds`], which will automatically fail back even custom TLVs. + /// + /// If you fail to call [`ChannelManager::claim_funds`], + /// [`ChannelManager::claim_funds_with_known_custom_tlvs`], + /// [`ChannelManager::fail_htlc_backwards`], or + /// [`ChannelManager::fail_htlc_backwards_with_reason`] 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 @@ -367,6 +415,8 @@ pub enum Event { /// 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::claim_funds_with_known_custom_tlvs`]: crate::ln::channelmanager::ChannelManager::claim_funds_with_known_custom_tlvs + /// [`FailureCode::InvalidOnionPayload`]: crate::ln::channelmanager::FailureCode::InvalidOnionPayload /// [`ChannelManager::fail_htlc_backwards`]: crate::ln::channelmanager::ChannelManager::fail_htlc_backwards /// [`ChannelManager::fail_htlc_backwards_with_reason`]: crate::ln::channelmanager::ChannelManager::fail_htlc_backwards_with_reason PaymentClaimable { @@ -451,6 +501,12 @@ pub enum Event { /// The purpose of the claimed payment, i.e. whether the payment was for an invoice or a /// spontaneous payment. purpose: PaymentPurpose, + /// The HTLCs that comprise the claimed payment. This will be empty for events serialized prior + /// to LDK version 0.0.117. + htlcs: Vec, + /// The sender-intended sum total of all the MPP parts. This will be `None` for events + /// serialized prior to LDK version 0.0.117. + sender_intended_total_msat: Option, }, /// Indicates an outbound payment we made succeeded (i.e. it made it all the way to its target /// and we got back the payment preimage for it). @@ -488,6 +544,11 @@ pub enum Event { /// payment is no longer retryable, due either to the [`Retry`] provided or /// [`ChannelManager::abandon_payment`] having been called for the corresponding payment. /// + /// In exceedingly rare cases, it is possible that an [`Event::PaymentFailed`] is generated for + /// a payment after an [`Event::PaymentSent`] event for this same payment has already been + /// received and processed. In this case, the [`Event::PaymentFailed`] event MUST be ignored, + /// and the payment MUST be treated as having succeeded. + /// /// [`Retry`]: crate::ln::channelmanager::Retry /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment PaymentFailed { @@ -654,6 +715,10 @@ pub enum Event { SpendableOutputs { /// The outputs which you should store as spendable by you. outputs: Vec, + /// The `channel_id` indicating which channel the spendable outputs belong to. + /// + /// This will always be `Some` for events generated by LDK versions 0.0.117 and above. + channel_id: Option<[u8; 32]>, }, /// This event is generated when a payment has been successfully forwarded through us and a /// forwarding fee earned. @@ -736,6 +801,13 @@ pub enum Event { }, /// Used to indicate that a previously opened channel with the given `channel_id` is in the /// process of closure. + /// + /// Note that this event is only triggered for accepted channels: if the + /// [`UserConfig::manually_accept_inbound_channels`] config flag is set to true and the channel is + /// rejected, no `ChannelClosed` event will be sent. + /// + /// [`ChannelManager::accept_inbound_channel`]: crate::ln::channelmanager::ChannelManager::accept_inbound_channel + /// [`UserConfig::manually_accept_inbound_channels`]: crate::util::config::UserConfig::manually_accept_inbound_channels ChannelClosed { /// The `channel_id` of the channel which has been closed. Note that on-chain transactions /// resolving the channel are likely still awaiting confirmation. @@ -752,7 +824,15 @@ pub enum Event { /// [`UserConfig::manually_accept_inbound_channels`]: crate::util::config::UserConfig::manually_accept_inbound_channels user_channel_id: u128, /// The reason the channel was closed. - reason: ClosureReason + reason: ClosureReason, + /// Counterparty in the closed channel. + /// + /// This field will be `None` for objects serialized prior to LDK 0.0.117. + counterparty_node_id: Option, + /// Channel capacity of the closing channel (sats). + /// + /// This field will be `None` for objects serialized prior to LDK 0.0.117. + channel_capacity_sats: Option, }, /// Used to indicate to the user that they can abandon the funding transaction and recycle the /// inputs for another purpose. @@ -764,8 +844,9 @@ pub enum Event { }, /// Indicates a request to open a new channel by a peer. /// - /// To accept the request, call [`ChannelManager::accept_inbound_channel`]. To reject the - /// request, call [`ChannelManager::force_close_without_broadcasting_txn`]. + /// To accept the request, call [`ChannelManager::accept_inbound_channel`]. To reject the request, + /// call [`ChannelManager::force_close_without_broadcasting_txn`]. Note that a ['ChannelClosed`] + /// event will _not_ be triggered if the channel is rejected. /// /// The event is only triggered when a new open channel request is received and the /// [`UserConfig::manually_accept_inbound_channels`] config flag is set to true. @@ -832,12 +913,14 @@ pub enum Event { /// Destination of the HTLC that failed to be processed. failed_next_destination: HTLCDestination, }, - #[cfg(anchors)] /// Indicates that a transaction originating from LDK needs to have its fee bumped. This event /// requires confirmed external funds to be readily available to spend. /// - /// LDK does not currently generate this event. It is limited to the scope of channels with - /// anchor outputs, which will be introduced in a future release. + /// LDK does not currently generate this event unless the + /// [`ChannelHandshakeConfig::negotiate_anchors_zero_fee_htlc_tx`] config flag is set to true. + /// It is limited to the scope of channels with anchor outputs. + /// + /// [`ChannelHandshakeConfig::negotiate_anchors_zero_fee_htlc_tx`]: crate::util::config::ChannelHandshakeConfig::negotiate_anchors_zero_fee_htlc_tx BumpTransaction(BumpTransactionEvent), } @@ -909,7 +992,7 @@ impl Writeable for Event { (2, payment_failed_permanently, required), (3, false, required), // all_paths_failed in LDK versions prior to 0.0.114 (4, path.blinded_tail, option), - (5, path.hops, vec_type), + (5, path.hops, required_vec), (7, short_channel_id, option), (9, None::, option), // retry in LDK versions prior to 0.0.115 (11, payment_id, option), @@ -921,10 +1004,11 @@ impl Writeable for Event { // Note that we now ignore these on the read end as we'll re-generate them in // ChannelManager, we write them here only for backwards compatibility. }, - &Event::SpendableOutputs { ref outputs } => { + &Event::SpendableOutputs { ref outputs, channel_id } => { 5u8.write(writer)?; write_tlv_fields!(writer, { (0, WithoutLength(outputs), required), + (1, channel_id, option), }); }, &Event::HTLCIntercepted { requested_next_hop_scid, payment_hash, inbound_amount_msat, expected_outbound_amount_msat, intercept_id } => { @@ -951,7 +1035,9 @@ impl Writeable for Event { (5, outbound_amount_forwarded_msat, option), }); }, - &Event::ChannelClosed { ref channel_id, ref user_channel_id, ref reason } => { + &Event::ChannelClosed { ref channel_id, ref user_channel_id, ref reason, + ref counterparty_node_id, ref channel_capacity_sats + } => { 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 @@ -963,6 +1049,8 @@ impl Writeable for Event { (1, user_channel_id_low, required), (2, reason, required), (3, user_channel_id_high, required), + (5, counterparty_node_id, option), + (7, channel_capacity_sats, option), }); }, &Event::DiscardFunding { ref channel_id, ref transaction } => { @@ -977,7 +1065,7 @@ impl Writeable for Event { write_tlv_fields!(writer, { (0, payment_id, required), (2, payment_hash, option), - (4, path.hops, vec_type), + (4, path.hops, required_vec), (6, path.blinded_tail, option), }) }, @@ -994,13 +1082,15 @@ 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, ref receiver_node_id } => { + &Event::PaymentClaimed { ref payment_hash, ref amount_msat, ref purpose, ref receiver_node_id, ref htlcs, ref sender_intended_total_msat } => { 19u8.write(writer)?; write_tlv_fields!(writer, { (0, payment_hash, required), (1, receiver_node_id, option), (2, purpose, required), (4, amount_msat, required), + (5, *htlcs, optional_vec), + (7, sender_intended_total_msat, option), }); }, &Event::ProbeSuccessful { ref payment_id, ref payment_hash, ref path } => { @@ -1008,7 +1098,7 @@ impl Writeable for Event { write_tlv_fields!(writer, { (0, payment_id, required), (2, payment_hash, required), - (4, path.hops, vec_type), + (4, path.hops, required_vec), (6, path.blinded_tail, option), }) }, @@ -1017,7 +1107,7 @@ impl Writeable for Event { write_tlv_fields!(writer, { (0, payment_id, required), (2, payment_hash, required), - (4, path.hops, vec_type), + (4, path.hops, required_vec), (6, short_channel_id, option), (8, path.blinded_tail, option), }) @@ -1029,7 +1119,6 @@ impl Writeable for Event { (2, failed_next_destination, required), }) }, - #[cfg(anchors)] &Event::BumpTransaction(ref event)=> { 27u8.write(writer)?; match event { @@ -1163,7 +1252,9 @@ impl MaybeReadable for Event { (1, network_update, upgradable_option), (2, payment_failed_permanently, required), (4, blinded_tail, option), - (5, path, vec_type), + // Added as a part of LDK 0.0.101 and always filled in since. + // Defaults to an empty Vec, though likely should have been `Option`al. + (5, path, optional_vec), (7, short_channel_id, option), (11, payment_id, option), (13, failure_opt, upgradable_option), @@ -1188,10 +1279,12 @@ impl MaybeReadable for Event { 5u8 => { let f = || { let mut outputs = WithoutLength(Vec::new()); + let mut channel_id: Option<[u8; 32]> = None; read_tlv_fields!(reader, { (0, outputs, required), + (1, channel_id, option), }); - Ok(Some(Event::SpendableOutputs { outputs: outputs.0 })) + Ok(Some(Event::SpendableOutputs { outputs: outputs.0, channel_id })) }; f() }, @@ -1246,11 +1339,15 @@ impl MaybeReadable for Event { let mut reason = UpgradableRequired(None); let mut user_channel_id_low_opt: Option = None; let mut user_channel_id_high_opt: Option = None; + let mut counterparty_node_id = None; + let mut channel_capacity_sats = None; read_tlv_fields!(reader, { (0, channel_id, required), (1, user_channel_id_low_opt, option), (2, reason, upgradable_required), (3, user_channel_id_high_opt, option), + (5, counterparty_node_id, option), + (7, channel_capacity_sats, option), }); // `user_channel_id` used to be a single u64 value. In order to remain @@ -1259,7 +1356,8 @@ impl MaybeReadable for Event { 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: _init_tlv_based_struct_field!(reason, upgradable_required) })) + Ok(Some(Event::ChannelClosed { channel_id, user_channel_id, reason: _init_tlv_based_struct_field!(reason, upgradable_required), + counterparty_node_id, channel_capacity_sats })) }; f() }, @@ -1280,13 +1378,13 @@ impl MaybeReadable for Event { _init_and_read_tlv_fields!(reader, { (0, payment_id, required), (2, payment_hash, option), - (4, path, vec_type), + (4, path, required_vec), (6, blinded_tail, option), }); Ok(Some(Event::PaymentPathSuccessful { payment_id: payment_id.0.unwrap(), payment_hash, - path: Path { hops: path.unwrap(), blinded_tail }, + path: Path { hops: path, blinded_tail }, })) }; f() @@ -1319,17 +1417,23 @@ impl MaybeReadable for Event { let mut purpose = UpgradableRequired(None); let mut amount_msat = 0; let mut receiver_node_id = None; + let mut htlcs: Option> = Some(vec![]); + let mut sender_intended_total_msat: Option = None; read_tlv_fields!(reader, { (0, payment_hash, required), (1, receiver_node_id, option), (2, purpose, upgradable_required), (4, amount_msat, required), + (5, htlcs, optional_vec), + (7, sender_intended_total_msat, option), }); Ok(Some(Event::PaymentClaimed { receiver_node_id, payment_hash, purpose: _init_tlv_based_struct_field!(purpose, upgradable_required), amount_msat, + htlcs: htlcs.unwrap_or(vec![]), + sender_intended_total_msat, })) }; f() @@ -1339,13 +1443,13 @@ impl MaybeReadable for Event { _init_and_read_tlv_fields!(reader, { (0, payment_id, required), (2, payment_hash, required), - (4, path, vec_type), + (4, path, required_vec), (6, blinded_tail, option), }); Ok(Some(Event::ProbeSuccessful { payment_id: payment_id.0.unwrap(), payment_hash: payment_hash.0.unwrap(), - path: Path { hops: path.unwrap(), blinded_tail }, + path: Path { hops: path, blinded_tail }, })) }; f() @@ -1355,14 +1459,14 @@ impl MaybeReadable for Event { _init_and_read_tlv_fields!(reader, { (0, payment_id, required), (2, payment_hash, required), - (4, path, vec_type), + (4, path, required_vec), (6, short_channel_id, option), (8, blinded_tail, option), }); Ok(Some(Event::ProbeFailed { payment_id: payment_id.0.unwrap(), payment_hash: payment_hash.0.unwrap(), - path: Path { hops: path.unwrap(), blinded_tail }, + path: Path { hops: path, blinded_tail }, short_channel_id, })) }; @@ -1454,6 +1558,7 @@ impl MaybeReadable for Event { /// broadcast to most peers). /// These events are handled by PeerManager::process_events if you are using a PeerManager. #[derive(Clone, Debug)] +#[cfg_attr(test, derive(PartialEq))] pub enum MessageSendEvent { /// Used to indicate that we've accepted a channel open and should send the accept_channel /// message provided to the given peer.