X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning%2Fsrc%2Futil%2Fevents.rs;h=7ce738898759752f11bf96779d1648bf4446dad0;hb=4992955ad395b3276f5fe509dd2331218ad4534a;hp=8b8cc1230372821aa52c0cd4e6edbdc01cb5f1bd;hpb=8088e4ba1505c026ac91f8c1489fb7d53d6b656e;p=rust-lightning diff --git a/lightning/src/util/events.rs b/lightning/src/util/events.rs index 8b8cc1230..7ce738898 100644 --- a/lightning/src/util/events.rs +++ b/lightning/src/util/events.rs @@ -15,7 +15,7 @@ //! few other things. use ln::msgs; -use ln::channelmanager::{PaymentPreimage, PaymentHash, PaymentSecret}; +use ln::{PaymentPreimage, PaymentHash, PaymentSecret}; use chain::keysinterface::SpendableOutputDescriptor; use util::ser::{Writeable, Writer, MaybeReadable, Readable}; @@ -23,7 +23,9 @@ use bitcoin::blockdata::script::Script; 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. /// @@ -61,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 @@ -88,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, @@ -129,11 +144,13 @@ 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::PaymentReceived { ref payment_hash, ref payment_secret, ref amt } => { + &Event::PaymentReceived { ref payment_hash, ref payment_preimage, ref payment_secret, ref amt, ref user_payment_id } => { 1u8.write(writer)?; payment_hash.write(writer)?; + payment_preimage.write(writer)?; payment_secret.write(writer)?; amt.write(writer)?; + user_payment_id.write(writer)?; }, &Event::PaymentSent { ref payment_preimage } => { 2u8.write(writer)?; @@ -175,8 +192,10 @@ impl MaybeReadable for Event { 0u8 => Ok(None), 1u8 => Ok(Some(Event::PaymentReceived { payment_hash: Readable::read(reader)?, + payment_preimage: Readable::read(reader)?, payment_secret: Readable::read(reader)?, amt: Readable::read(reader)?, + user_payment_id: Readable::read(reader)?, })), 2u8 => Ok(Some(Event::PaymentSent { payment_preimage: Readable::read(reader)?, @@ -359,9 +378,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) + } }