X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning%2Fsrc%2Futil%2Fevents.rs;h=0fc7c6b3a3d166096019407784b929588ddbddd8;hb=e3968e09939b0b48ec7b4b614a75018c0d3114b0;hp=43a2dc3bd6f881ab4ec69241f30f5a2b37651a8e;hpb=ad5f72894c9fa501e3d71fee7f12f8cfdc9dd55e;p=rust-lightning diff --git a/lightning/src/util/events.rs b/lightning/src/util/events.rs index 43a2dc3b..0fc7c6b3 100644 --- a/lightning/src/util/events.rs +++ b/lightning/src/util/events.rs @@ -1,3 +1,12 @@ +// This file is Copyright its original authors, visible in version control +// history. +// +// This file is licensed under the Apache License, Version 2.0 or the MIT license +// , at your option. +// You may not use this file except in accordance with one or both of these +// licenses. + //! Events are returned from various bits in the library which indicate some action must be taken //! by the client. //! @@ -6,22 +15,24 @@ //! few other things. use ln::msgs; -use ln::channelmanager::{PaymentPreimage, PaymentHash, PaymentSecret}; -use chain::transaction::OutPoint; +use ln::{PaymentPreimage, PaymentHash, PaymentSecret}; use chain::keysinterface::SpendableOutputDescriptor; -use util::ser::{Writeable, Writer, MaybeReadable, Readable}; +use util::ser::{Writeable, Writer, MaybeReadable, Readable, VecReadWrapper, VecWriteWrapper}; use bitcoin::blockdata::script::Script; -use secp256k1::key::PublicKey; +use bitcoin::secp256k1::key::PublicKey; -use std::time::Duration; +use prelude::*; +use core::time::Duration; +use core::ops::Deref; /// 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 /// them directly as they don't round-trip exactly (for example FundingGenerationReady is never /// written as it makes no sense to respond to it after reconnecting to peers). +#[derive(Clone, Debug)] pub enum Event { /// Used to indicate that the client should generate a funding transaction with the given /// parameters and then call ChannelManager::funding_transaction_generated. @@ -39,16 +50,6 @@ pub enum Event { /// The value passed in to ChannelManager::create_channel user_channel_id: u64, }, - /// Used to indicate that the client may now broadcast the funding transaction it created for a - /// channel. Broadcasting such a transaction prior to this event may lead to our counterparty - /// trivially stealing all funds in the funding transaction! - FundingBroadcastSafe { - /// The output, which was passed to ChannelManager::funding_transaction_generated, which is - /// now safe to broadcast. - funding_txo: OutPoint, - /// The value passed in to ChannelManager::create_channel - user_channel_id: u64, - }, /// Indicates we've received money! Just gotta dig out that payment preimage and feed it to /// ChannelManager::claim_funds to get it.... /// Note that if the preimage is not known or the amount paid is incorrect, you should call @@ -62,25 +63,40 @@ pub enum Event { PaymentReceived { /// The hash for which the preimage should be handed to the ChannelManager. payment_hash: PaymentHash, + /// 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`]: crate::ln::channelmanager::ChannelManager::create_inbound_payment + /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds + payment_preimage: Option, /// The "payment secret". This authenticates the sender to the recipient, preventing a /// number of deanonymization attacks during the routing process. - /// As nodes upgrade, the invoices you provide should likely migrate to setting the - /// payment_secret feature to required, at which point you should fail_backwards any HTLCs - /// which have a None here. - /// Until then, however, values of None should be ignored, and only incorrect Some values - /// should result in an HTLC fail_backwards. - /// Note that, in any case, this value must be passed as-is to any fail or claim calls as - /// the HTLC index includes this value. - payment_secret: Option, + /// It is provided here for your reference, however its accuracy is enforced directly by + /// [`ChannelManager`] using the values you previously provided to + /// [`ChannelManager::create_inbound_payment`] or + /// [`ChannelManager::create_inbound_payment_for_hash`]. + /// + /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager + /// [`ChannelManager::create_inbound_payment`]: crate::ln::channelmanager::ChannelManager::create_inbound_payment + /// [`ChannelManager::create_inbound_payment_for_hash`]: crate::ln::channelmanager::ChannelManager::create_inbound_payment_for_hash + payment_secret: PaymentSecret, /// The value, in thousandths of a satoshi, that this payment is for. Note that you must /// compare this to the expected value before accepting the payment (as otherwise you are /// providing proof-of-payment for less than the value you expected!). amt: u64, + /// This is the `user_payment_id` which was provided to + /// [`ChannelManager::create_inbound_payment_for_hash`] or + /// [`ChannelManager::create_inbound_payment`]. It has no meaning inside of LDK and is + /// simply copied here. It may be used to correlate PaymentReceived events with invoice + /// metadata stored elsewhere. + /// + /// [`ChannelManager::create_inbound_payment`]: crate::ln::channelmanager::ChannelManager::create_inbound_payment + /// [`ChannelManager::create_inbound_payment_for_hash`]: crate::ln::channelmanager::ChannelManager::create_inbound_payment_for_hash + user_payment_id: u64, }, /// Indicates an outbound payment we made succeeded (ie it made it all the way to its target /// and we got back the payment preimage for it). - /// Note that duplicative PaymentSent Events may be generated - it is your responsibility to - /// deduplicate them by payment_preimage (which MUST be unique)! PaymentSent { /// The preimage to the hash given to ChannelManager::send_payment. /// Note that this serves as a payment receipt, if you wish to have such a thing, you must @@ -89,8 +105,6 @@ pub enum Event { }, /// Indicates an outbound payment we made failed. Probably some intermediary node dropped /// something. You may wish to retry with a different route. - /// Note that duplicative PaymentFailed Events may be generated - it is your responsibility to - /// deduplicate them by payment_hash (which MUST be unique)! PaymentFailed { /// The hash which was given to ChannelManager::send_payment. payment_hash: PaymentHash, @@ -112,7 +126,8 @@ pub enum Event { /// now + 5*time_forwardable). time_forwardable: Duration, }, - /// Used to indicate that an output was generated on-chain which you should know how to spend. + /// 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 /// 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. @@ -130,20 +145,21 @@ 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::FundingBroadcastSafe { ref funding_txo, ref user_channel_id } => { + &Event::PaymentReceived { ref payment_hash, ref payment_preimage, ref payment_secret, ref amt, ref user_payment_id } => { 1u8.write(writer)?; - funding_txo.write(writer)?; - user_channel_id.write(writer)?; - }, - &Event::PaymentReceived { ref payment_hash, ref payment_secret, ref amt } => { - 2u8.write(writer)?; - payment_hash.write(writer)?; - payment_secret.write(writer)?; - amt.write(writer)?; + write_tlv_fields!(writer, { + (0, payment_hash, required), + (2, payment_secret, required), + (4, amt, required), + (6, user_payment_id, required), + (8, payment_preimage, option), + }); }, &Event::PaymentSent { ref payment_preimage } => { - 3u8.write(writer)?; - payment_preimage.write(writer)?; + 2u8.write(writer)?; + write_tlv_fields!(writer, { + (0, payment_preimage, required), + }); }, &Event::PaymentFailed { ref payment_hash, ref rejected_by_dest, #[cfg(test)] @@ -151,25 +167,27 @@ impl Writeable for Event { #[cfg(test)] ref error_data, } => { - 4u8.write(writer)?; - payment_hash.write(writer)?; - rejected_by_dest.write(writer)?; + 3u8.write(writer)?; #[cfg(test)] error_code.write(writer)?; #[cfg(test)] error_data.write(writer)?; + write_tlv_fields!(writer, { + (0, payment_hash, required), + (2, rejected_by_dest, required), + }); }, &Event::PendingHTLCsForwardable { time_forwardable: _ } => { - 5u8.write(writer)?; + 4u8.write(writer)?; + write_tlv_fields!(writer, {}); // We don't write the time_fordwardable out at all, as we presume when the user // deserializes us at least that much time has elapsed. }, &Event::SpendableOutputs { ref outputs } => { - 6u8.write(writer)?; - (outputs.len() as u64).write(writer)?; - for output in outputs.iter() { - output.write(writer)?; - } + 5u8.write(writer)?; + write_tlv_fields!(writer, { + (0, VecWriteWrapper(outputs), required), + }); }, } Ok(()) @@ -179,36 +197,83 @@ impl MaybeReadable for Event { fn read(reader: &mut R) -> Result, msgs::DecodeError> { match Readable::read(reader)? { 0u8 => Ok(None), - 1u8 => Ok(Some(Event::FundingBroadcastSafe { - funding_txo: Readable::read(reader)?, - user_channel_id: Readable::read(reader)?, - })), - 2u8 => Ok(Some(Event::PaymentReceived { - payment_hash: Readable::read(reader)?, - payment_secret: Readable::read(reader)?, - amt: Readable::read(reader)?, - })), - 3u8 => Ok(Some(Event::PaymentSent { - payment_preimage: Readable::read(reader)?, - })), - 4u8 => Ok(Some(Event::PaymentFailed { - payment_hash: Readable::read(reader)?, - rejected_by_dest: Readable::read(reader)?, + 1u8 => { + let f = || { + let mut payment_hash = PaymentHash([0; 32]); + let mut payment_preimage = None; + let mut payment_secret = PaymentSecret([0; 32]); + let mut amt = 0; + let mut user_payment_id = 0; + read_tlv_fields!(reader, { + (0, payment_hash, required), + (2, payment_secret, required), + (4, amt, required), + (6, user_payment_id, required), + (8, payment_preimage, option), + }); + Ok(Some(Event::PaymentReceived { + payment_hash, + payment_preimage, + payment_secret, + amt, + user_payment_id, + })) + }; + f() + }, + 2u8 => { + let f = || { + let mut payment_preimage = PaymentPreimage([0; 32]); + read_tlv_fields!(reader, { + (0, payment_preimage, required), + }); + Ok(Some(Event::PaymentSent { + payment_preimage, + })) + }; + f() + }, + 3u8 => { + let f = || { #[cfg(test)] - error_code: Readable::read(reader)?, + let error_code = Readable::read(reader)?; #[cfg(test)] - error_data: Readable::read(reader)?, - })), - 5u8 => Ok(Some(Event::PendingHTLCsForwardable { - time_forwardable: Duration::from_secs(0) - })), - 6u8 => { - let outputs_len: u64 = Readable::read(reader)?; - let mut outputs = Vec::new(); - for _ in 0..outputs_len { - outputs.push(Readable::read(reader)?); - } - Ok(Some(Event::SpendableOutputs { outputs })) + let error_data = Readable::read(reader)?; + let mut payment_hash = PaymentHash([0; 32]); + let mut rejected_by_dest = false; + read_tlv_fields!(reader, { + (0, payment_hash, required), + (2, rejected_by_dest, required), + }); + Ok(Some(Event::PaymentFailed { + payment_hash, + rejected_by_dest, + #[cfg(test)] + error_code, + #[cfg(test)] + error_data, + })) + }; + f() + }, + 4u8 => { + let f = || { + read_tlv_fields!(reader, {}); + Ok(Some(Event::PendingHTLCsForwardable { + time_forwardable: Duration::from_secs(0) + })) + }; + f() + }, + 5u8 => { + let f = || { + let mut outputs = VecReadWrapper(Vec::new()); + read_tlv_fields!(reader, { + (0, outputs, required), + }); + Ok(Some(Event::SpendableOutputs { outputs: outputs.0 })) + }; + f() }, _ => Err(msgs::DecodeError::InvalidValue) } @@ -218,7 +283,7 @@ impl MaybeReadable for Event { /// An event generated by ChannelManager which indicates a message should be sent to a peer (or /// broadcast to most peers). /// These events are handled by PeerManager::process_events if you are using a PeerManager. -#[derive(Clone)] +#[derive(Clone, Debug)] 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. @@ -324,6 +389,15 @@ pub enum MessageSendEvent { /// The channel_update which should be sent. msg: msgs::ChannelUpdate, }, + /// Used to indicate that a channel_update should be sent to a single peer. + /// In contrast to [`Self::BroadcastChannelUpdate`], this is used when the channel is a + /// private channel and we shouldn't be informing all of our peers of channel parameters. + SendChannelUpdate { + /// The node_id of the node which should receive this message + node_id: PublicKey, + /// The channel_update which should be sent. + msg: msgs::ChannelUpdate, + }, /// Broadcast an error downstream to be handled HandleError { /// The node_id of the node which should receive this message @@ -332,10 +406,33 @@ pub enum MessageSendEvent { action: msgs::ErrorAction }, /// When a payment fails we may receive updates back from the hop where it failed. In such - /// cases this event is generated so that we can inform the router of this information. + /// cases this event is generated so that we can inform the network graph of this information. PaymentFailureNetworkUpdate { - /// The channel/node update which should be sent to router + /// The channel/node update which should be sent to NetGraphMsgHandler update: msgs::HTLCFailChannelUpdate, + }, + /// Query a peer for channels with funding transaction UTXOs in a block range. + SendChannelRangeQuery { + /// The node_id of this message recipient + node_id: PublicKey, + /// The query_channel_range which should be sent. + msg: msgs::QueryChannelRange, + }, + /// Request routing gossip messages from a peer for a list of channels identified by + /// their short_channel_ids. + SendShortIdsQuery { + /// The node_id of this message recipient + node_id: PublicKey, + /// The query_short_channel_ids which should be sent. + msg: msgs::QueryShortChannelIds, + }, + /// Sends a reply to a channel range query. This may be one of several SendReplyChannelRange events + /// emitted during processing of the query. + SendReplyChannelRange { + /// The node_id of this message recipient + node_id: PublicKey, + /// The reply_channel_range which should be sent. + msg: msgs::ReplyChannelRange, } } @@ -346,9 +443,49 @@ pub trait MessageSendEventsProvider { fn get_and_clear_pending_msg_events(&self) -> Vec; } -/// A trait indicating an object may generate events +/// A trait indicating an object may generate events. +/// +/// Events are processed by passing an [`EventHandler`] to [`process_pending_events`]. +/// +/// # Requirements +/// +/// See [`process_pending_events`] for requirements around event processing. +/// +/// When using this trait, [`process_pending_events`] will call [`handle_event`] for each pending +/// event since the last invocation. The handler must either act upon the event immediately +/// or preserve it for later handling. +/// +/// Note, handlers may call back into the provider and thus deadlocking must be avoided. Be sure to +/// consult the provider's documentation on the implication of processing events and how a handler +/// may safely use the provider (e.g., see [`ChannelManager::process_pending_events`] and +/// [`ChainMonitor::process_pending_events`]). +/// +/// (C-not implementable) As there is likely no reason for a user to implement this trait on their +/// own type(s). +/// +/// [`process_pending_events`]: Self::process_pending_events +/// [`handle_event`]: EventHandler::handle_event +/// [`ChannelManager::process_pending_events`]: crate::ln::channelmanager::ChannelManager#method.process_pending_events +/// [`ChainMonitor::process_pending_events`]: crate::chain::chainmonitor::ChainMonitor#method.process_pending_events pub trait EventsProvider { - /// Gets the list of pending events which were generated by previous actions, clearing the list - /// in the process. - fn get_and_clear_pending_events(&self) -> Vec; + /// Processes any events generated since the last call using the given event handler. + /// + /// Subsequent calls must only process new events. However, handlers must be capable of handling + /// duplicate events across process restarts. This may occur if the provider was recovered from + /// an old state (i.e., it hadn't been successfully persisted after processing pending events). + fn process_pending_events(&self, handler: H) where H::Target: EventHandler; +} + +/// A trait implemented for objects handling events from [`EventsProvider`]. +pub trait EventHandler { + /// Handles the given [`Event`]. + /// + /// See [`EventsProvider`] for details that must be considered when implementing this method. + fn handle_event(&self, event: Event); +} + +impl EventHandler for F where F: Fn(Event) { + fn handle_event(&self, event: Event) { + self(event) + } }