X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning%2Fsrc%2Fevents%2Fmod.rs;h=b482996b916d077b16da87696230abcac8f4e1bc;hb=1ceb41e08b2d76b23d2505a10a88db8d840895ca;hp=a96d36b645312e6efe854a8ddb4f272db3b94532;hpb=783e8188a7bd6470d5926bf5d1bae1350996801a;p=rust-lightning diff --git a/lightning/src/events/mod.rs b/lightning/src/events/mod.rs index a96d36b6..b482996b 100644 --- a/lightning/src/events/mod.rs +++ b/lightning/src/events/mod.rs @@ -32,7 +32,9 @@ use crate::util::ser::{BigSize, FixedLengthReader, Writeable, Writer, MaybeReada use crate::util::string::UntrustedString; use crate::routing::router::{RouteHop, RouteParameters}; -use bitcoin::{PackedLockTime, Transaction}; +use bitcoin::{PackedLockTime, Transaction, OutPoint}; +#[cfg(anchors)] +use bitcoin::{Txid, TxIn, TxOut, Witness}; use bitcoin::blockdata::script::Script; use bitcoin::hashes::Hash; use bitcoin::hashes::sha256::Hash as Sha256; @@ -319,7 +321,9 @@ pub enum Event { /// /// # Note /// LDK will not stop an inbound payment from being paid multiple times, so multiple - /// `PaymentClaimable` events may be generated for the same payment. + /// `PaymentClaimable` events may be generated for the same payment. In such a case it is + /// polite (and required in the lightning specification) to fail the payment the second time + /// and give the sender their money back rather than accepting double payment. /// /// # Note /// This event used to be called `PaymentReceived` in LDK versions 0.0.112 and earlier. @@ -347,6 +351,14 @@ pub enum Event { via_channel_id: Option<[u8; 32]>, /// The `user_channel_id` indicating over which channel we received the payment. via_user_channel_id: Option, + /// The block height at which this payment will be failed back and will no longer be + /// eligible for claiming. + /// + /// Prior to this height, a call to [`ChannelManager::claim_funds`] is guaranteed to + /// succeed, however you should wait for [`Event::PaymentClaimed`] to be sure. + /// + /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds + claim_deadline: Option, }, /// Indicates a payment has been claimed and we've received money! /// @@ -385,7 +397,7 @@ 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`]. + /// The `payment_id` passed to [`ChannelManager::send_payment`]. /// /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment payment_id: Option, @@ -418,11 +430,9 @@ pub enum Event { /// [`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::abandon_payment`]. + /// The `payment_id` passed to [`ChannelManager::send_payment`]. /// /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment - /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment payment_id: PaymentId, /// The hash that was given to [`ChannelManager::send_payment`]. /// @@ -434,7 +444,7 @@ 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`]. + /// The `payment_id` passed to [`ChannelManager::send_payment`]. /// /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment payment_id: PaymentId, @@ -458,8 +468,7 @@ pub enum Event { /// /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment PaymentPathFailed { - /// The id returned by [`ChannelManager::send_payment`] and used with - /// [`ChannelManager::abandon_payment`]. + /// The `payment_id` passed to [`ChannelManager::send_payment`]. /// /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment @@ -608,12 +617,39 @@ pub enum Event { /// The caveat described above the `fee_earned_msat` field applies here as well. outbound_amount_forwarded_msat: Option, }, + /// Used to indicate that a channel with the given `channel_id` is being opened and pending + /// confirmation on-chain. + /// + /// This event is emitted when the funding transaction has been signed and is broadcast to the + /// network. For 0conf channels it will be immediately followed by the corresponding + /// [`Event::ChannelReady`] event. + ChannelPending { + /// The `channel_id` of the channel that is pending confirmation. + channel_id: [u8; 32], + /// 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. + /// + /// [`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, + /// The `temporary_channel_id` this channel used to be known by during channel establishment. + /// + /// Will be `None` for channels created prior to LDK version 0.0.115. + former_temporary_channel_id: Option<[u8; 32]>, + /// The `node_id` of the channel counterparty. + counterparty_node_id: PublicKey, + /// The outpoint of the channel's funding transaction. + funding_txo: OutPoint, + }, /// Used to indicate that a channel with the given `channel_id` is ready to /// be used. This event is emitted either when the funding transaction has been confirmed /// on-chain, or, in case of a 0conf channel, when both parties have confirmed the channel /// establishment. ChannelReady { - /// The channel_id of the channel that is ready. + /// The `channel_id` of the channel that is ready. channel_id: [u8; 32], /// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound /// channels, or to [`ChannelManager::accept_inbound_channel`] for inbound channels if @@ -624,7 +660,7 @@ pub enum Event { /// [`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, - /// The node_id of the channel counterparty. + /// The `node_id` of the channel counterparty. counterparty_node_id: PublicKey, /// The features that this channel will operate with. channel_type: ChannelTypeFeatures, @@ -632,7 +668,7 @@ pub enum Event { /// Used to indicate that a previously opened channel with the given `channel_id` is in the /// process of closure. ChannelClosed { - /// The channel_id of the channel which has been closed. Note that on-chain transactions + /// The `channel_id` of the channel which has been closed. Note that on-chain transactions /// resolving the channel are likely still awaiting confirmation. channel_id: [u8; 32], /// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound @@ -744,7 +780,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::PaymentClaimable { 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, ref claim_deadline } => { 1u8.write(writer)?; let mut payment_secret = None; let payment_preimage; @@ -765,6 +801,7 @@ impl Writeable for Event { (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 + (7, claim_deadline, option), (8, payment_preimage, option), }); }, @@ -931,6 +968,16 @@ impl Writeable for Event { (6, channel_type, required), }); }, + &Event::ChannelPending { ref channel_id, ref user_channel_id, ref former_temporary_channel_id, ref counterparty_node_id, ref funding_txo } => { + 31u8.write(writer)?; + write_tlv_fields!(writer, { + (0, channel_id, required), + (2, user_channel_id, required), + (4, former_temporary_channel_id, required), + (6, counterparty_node_id, required), + (8, funding_txo, required), + }); + }, // Note that, going forward, all new events must only write data inside of // `write_tlv_fields`. Versions 0.0.101+ will ignore odd-numbered events that write // data via `write_tlv_fields`. @@ -953,6 +1000,7 @@ impl MaybeReadable for Event { 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 claim_deadline = None; let mut via_user_channel_id = None; read_tlv_fields!(reader, { (0, payment_hash, required), @@ -962,6 +1010,7 @@ impl MaybeReadable for Event { (4, amount_msat, required), (5, via_user_channel_id, option), (6, _user_payment_id, option), + (7, claim_deadline, option), (8, payment_preimage, option), }); let purpose = match payment_secret { @@ -979,6 +1028,7 @@ impl MaybeReadable for Event { purpose, via_channel_id, via_user_channel_id, + claim_deadline, })) }; f() @@ -1271,6 +1321,31 @@ impl MaybeReadable for Event { }; f() }, + 31u8 => { + let f = || { + let mut channel_id = [0; 32]; + let mut user_channel_id: u128 = 0; + let mut former_temporary_channel_id = None; + let mut counterparty_node_id = RequiredWrapper(None); + let mut funding_txo = RequiredWrapper(None); + read_tlv_fields!(reader, { + (0, channel_id, required), + (2, user_channel_id, required), + (4, former_temporary_channel_id, required), + (6, counterparty_node_id, required), + (8, funding_txo, required), + }); + + Ok(Some(Event::ChannelPending { + channel_id, + user_channel_id, + former_temporary_channel_id, + counterparty_node_id: counterparty_node_id.0.unwrap(), + funding_txo: funding_txo.0.unwrap() + })) + }; + f() + }, // Versions prior to 0.0.100 did not ignore odd types, instead returning InvalidValue. // Version 0.0.100 failed to properly ignore odd types, possibly resulting in corrupt // reads.