Delay DelayedPaymentOutput spendable events until the CSV delay

[rust-lightning] / lightning / src / util / events.rs

diff --git a/lightning/src/util/events.rs b/lightning/src/util/events.rs
index ac0fc3c89dcc484a9cd37a71745f41225598940d..b3c77c9ae36b561d93c81e438538a2dd684e8e8c 100644 (file)
--- 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.
 ///
@@ -95,8 +97,6 @@ pub enum Event {
        },
        /// 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
@@ -105,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,
@@ -128,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.
@@ -380,9 +379,46 @@ pub trait MessageSendEventsProvider {
        fn get_and_clear_pending_msg_events(&self) -> Vec<MessageSendEvent>;
 }
 
-/// 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`]).
+///
+/// [`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<Event>;
+       /// 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<H: Deref>(&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<F> EventHandler for F where F: Fn(Event) {
+       fn handle_event(&self, event: Event) {
+               self(event)
+       }
 }