X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning%2Fsrc%2Fevents%2Fmod.rs;h=a4bf1501b194376ac8ae2d1894084337d5be2fa0;hb=c08aa349f5d1e7c3935b402ee2046b077a294506;hp=2716532e099a5e318596230fdacf6a0cc88be0aa;hpb=0c52ea23dc6adfb9189f776449e78c828fa5d1f4;p=rust-lightning diff --git a/lightning/src/events/mod.rs b/lightning/src/events/mod.rs index 2716532e..a4bf1501 100644 --- a/lightning/src/events/mod.rs +++ b/lightning/src/events/mod.rs @@ -24,7 +24,7 @@ use crate::ln::channelmanager::{InterceptId, PaymentId, RecipientOnionFields}; use crate::ln::channel::FUNDING_CONF_DEADLINE_BLOCKS; use crate::ln::features::ChannelTypeFeatures; use crate::ln::msgs; -use crate::ln::{ChannelId, PaymentPreimage, PaymentHash, PaymentSecret}; +use crate::ln::types::{ChannelId, PaymentPreimage, PaymentHash, PaymentSecret}; use crate::chain::transaction; use crate::routing::gossip::NetworkUpdate; use crate::util::errors::APIError; @@ -53,8 +53,9 @@ pub enum PaymentPurpose { /// A payment for a BOLT 11 invoice. Bolt11InvoicePayment { /// The preimage to the payment_hash, if the payment hash (and secret) were fetched via - /// [`ChannelManager::create_inbound_payment`]. If provided, this can be handed directly to - /// [`ChannelManager::claim_funds`]. + /// [`ChannelManager::create_inbound_payment`]. When handling [`Event::PaymentClaimable`], + /// this can be passed directly to [`ChannelManager::claim_funds`] to claim the payment. No + /// action is needed when seen in [`Event::PaymentClaimed`]. /// /// [`ChannelManager::create_inbound_payment`]: crate::ln::channelmanager::ChannelManager::create_inbound_payment /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds @@ -75,8 +76,9 @@ pub enum PaymentPurpose { /// /// [`Offer`]: crate::offers::offer::Offer Bolt12OfferPayment { - /// The preimage to the payment hash. If provided, this can be handed directly to - /// [`ChannelManager::claim_funds`]. + /// The preimage to the payment hash. When handling [`Event::PaymentClaimable`], this can be + /// passed directly to [`ChannelManager::claim_funds`], if provided. No action is needed + /// when seen in [`Event::PaymentClaimed`]. /// /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds payment_preimage: Option, @@ -96,8 +98,9 @@ pub enum PaymentPurpose { /// /// [`Refund`]: crate::offers::refund::Refund Bolt12RefundPayment { - /// The preimage to the payment hash. If provided, this can be handed directly to - /// [`ChannelManager::claim_funds`]. + /// The preimage to the payment hash. When handling [`Event::PaymentClaimable`], this can be + /// passed directly to [`ChannelManager::claim_funds`], if provided. No action is needed + /// when seen in [`Event::PaymentClaimed`]. /// /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds payment_preimage: Option, @@ -883,9 +886,15 @@ pub enum Event { }, /// 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 + /// + /// Such an output will *never* be spent directly by LDK, and are not at risk of your /// counterparty spending them due to some kind of timeout. Thus, you need to store them /// somewhere and spend them when you create on-chain transactions. + /// + /// You may hand them to the [`OutputSweeper`] utility which will store and (re-)generate spending + /// transactions for you. + /// + /// [`OutputSweeper`]: crate::util::sweep::OutputSweeper SpendableOutputs { /// The outputs which you should store as spendable by you. outputs: Vec, @@ -1003,8 +1012,8 @@ pub enum Event { /// The features that this channel will operate with. channel_type: ChannelTypeFeatures, }, - /// Used to indicate that a previously opened channel with the given `channel_id` is in the - /// process of closure. + /// Used to indicate that a channel that got past the initial handshake with the given `channel_id` is in the + /// process of closure. This includes previously opened channels, and channels that time out from not being funded. /// /// 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 @@ -1132,6 +1141,30 @@ pub enum Event { /// /// [`ChannelHandshakeConfig::negotiate_anchors_zero_fee_htlc_tx`]: crate::util::config::ChannelHandshakeConfig::negotiate_anchors_zero_fee_htlc_tx BumpTransaction(BumpTransactionEvent), + /// We received an onion message that is intended to be forwarded to a peer + /// that is currently offline. This event will only be generated if the + /// `OnionMessenger` was initialized with + /// [`OnionMessenger::new_with_offline_peer_interception`], see its docs. + /// + /// [`OnionMessenger::new_with_offline_peer_interception`]: crate::onion_message::messenger::OnionMessenger::new_with_offline_peer_interception + OnionMessageIntercepted { + /// The node id of the offline peer. + peer_node_id: PublicKey, + /// The onion message intended to be forwarded to `peer_node_id`. + message: msgs::OnionMessage, + }, + /// Indicates that an onion message supporting peer has come online and it may + /// be time to forward any onion messages that were previously intercepted for + /// them. This event will only be generated if the `OnionMessenger` was + /// initialized with + /// [`OnionMessenger::new_with_offline_peer_interception`], see its docs. + /// + /// [`OnionMessenger::new_with_offline_peer_interception`]: crate::onion_message::messenger::OnionMessenger::new_with_offline_peer_interception + OnionMessagePeerConnected { + /// The node id of the peer we just connected to, who advertises support for + /// onion messages. + peer_node_id: PublicKey, + } } impl Writeable for Event { @@ -1395,6 +1428,19 @@ impl Writeable for Event { 35u8.write(writer)?; // Never write ConnectionNeeded events as buffered onion messages aren't serialized. }, + &Event::OnionMessageIntercepted { ref peer_node_id, ref message } => { + 37u8.write(writer)?; + write_tlv_fields!(writer, { + (0, peer_node_id, required), + (2, message, required), + }); + }, + &Event::OnionMessagePeerConnected { ref peer_node_id } => { + 39u8.write(writer)?; + write_tlv_fields!(writer, { + (0, peer_node_id, 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`. @@ -1805,6 +1851,29 @@ impl MaybeReadable for Event { }, // Note that we do not write a length-prefixed TLV for ConnectionNeeded events. 35u8 => Ok(None), + 37u8 => { + let mut f = || { + _init_and_read_len_prefixed_tlv_fields!(reader, { + (0, peer_node_id, required), + (2, message, required), + }); + Ok(Some(Event::OnionMessageIntercepted { + peer_node_id: peer_node_id.0.unwrap(), message: message.0.unwrap() + })) + }; + f() + }, + 39u8 => { + let mut f = || { + _init_and_read_len_prefixed_tlv_fields!(reader, { + (0, peer_node_id, required), + }); + Ok(Some(Event::OnionMessagePeerConnected { + peer_node_id: peer_node_id.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.