X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning%2Fsrc%2Fevents%2Fmod.rs;h=418f8d5459a18e7fe3711327ba119ab87d2de5ef;hb=bb7c4d1853fe539de946cad975001593c2f845fa;hp=a5a20e7d42b3e016d5ea219f1427cd3dba0e67c2;hpb=884160c5c1d861485df9a84720663ed2b7aa952c;p=rust-lightning diff --git a/lightning/src/events/mod.rs b/lightning/src/events/mod.rs index a5a20e7d..418f8d54 100644 --- a/lightning/src/events/mod.rs +++ b/lightning/src/events/mod.rs @@ -113,7 +113,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. /// @@ -164,7 +164,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 { @@ -184,6 +187,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"), } } } @@ -197,6 +201,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`]. @@ -338,11 +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 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 @@ -351,9 +360,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 @@ -365,6 +384,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 { @@ -734,6 +755,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. @@ -750,7 +778,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. @@ -762,8 +798,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. @@ -951,7 +988,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 +1002,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 } => { @@ -1247,11 +1288,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 @@ -1260,7 +1305,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() },