Merge pull request #225 from TheBlueMatt/2018-10-214-redo
[rust-lightning] / src / util / events.rs
index 22721729be1d8ab29ec5504c04142bd3e422ee57..3a077a4b5ba9caad01086b23bad35a404217a57f 100644 (file)
@@ -14,6 +14,7 @@
 
 use ln::msgs;
 use chain::transaction::OutPoint;
+use chain::keysinterface::SpendableOutputDescriptor;
 
 use bitcoin::blockdata::script::Script;
 
@@ -50,8 +51,11 @@ pub enum Event {
        },
        /// 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, you must call ChannelManager::fail_htlc_backwards
-       /// to free up resources for this HTLC.
+       /// Note that if the preimage is not known or the amount paid is incorrect, you must call
+       /// ChannelManager::fail_htlc_backwards with PaymentFailReason::PreimageUnknown or
+       /// PaymentFailReason::AmountMismatch, respectively, to free up resources for this HTLC.
+       /// The amount paid should be considered 'incorrect' when it is less than or more than twice
+       /// the amount expected.
        PaymentReceived {
                /// The hash for which the preimage should be handed to the ChannelManager.
                payment_hash: [u8; 32],
@@ -60,6 +64,8 @@ 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
@@ -68,9 +74,15 @@ 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: [u8; 32],
+               /// Indicates the payment was rejected for some reason by the recipient. This implies that
+               /// the payment has failed, not just the route in question. If this is not set, you may
+               /// retry the payment via a different route.
+               rejected_by_dest: bool,
        },
        /// Used to indicate that ChannelManager::process_pending_htlc_forwards should be called at a
        /// time in the future.
@@ -78,6 +90,13 @@ pub enum Event {
                /// The earliest time at which process_pending_htlc_forwards should be called.
                time_forwardable: Instant,
        },
+       /// Used to indicate that an output was generated on-chain which you should know how to spend.
+       /// Such an output will *not* ever be spent by rust-lightning, so you need to store them
+       /// somewhere and spend them when you create on-chain spends.
+       SpendableOutputs {
+               /// The outputs which you should store as spendable by you.
+               outputs: Vec<SpendableOutputDescriptor>,
+       },
 
        // Events indicating the network loop should send a message to a peer:
        // TODO: Move these into a separate struct and make a top-level enum
@@ -121,6 +140,15 @@ pub enum Event {
                /// The update messages which should be sent. ALL messages in the struct should be sent!
                updates: msgs::CommitmentUpdate,
        },
+       /// Used to indicate that a revoke_and_ack message should be sent to the peer with the given node_id.
+       ///
+       /// This event is handled by PeerManager::process_events if you are using a PeerManager.
+       SendRevokeAndACK {
+               /// The node_id of the node which should receive this message
+               node_id: PublicKey,
+               /// The message which should be sent.
+               msg: msgs::RevokeAndACK,
+       },
        /// Used to indicate that a shutdown message should be sent to the peer with the given node_id.
        ///
        /// This event is handled by PeerManager::process_events if you are using a PeerManager.
@@ -157,6 +185,14 @@ pub enum Event {
                node_id: PublicKey,
                /// The action which should be taken.
                action: Option<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.
+       ///
+       /// This event is handled by PeerManager::process_events if you are using a PeerManager.
+       PaymentFailureNetworkUpdate {
+               /// The channel/node update which should be sent to router
+               update: msgs::HTLCFailChannelUpdate,
        }
 }