Add a `PaymentClaimed` event to indicate a payment was claimed

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

diff --git a/lightning/src/util/events.rs b/lightning/src/util/events.rs
index aebdcf415c70e98b10d1b544887b7350aa7f67c2..5c00a05c370ccc477d3939209daf930ee511a4d5 100644 (file)
--- a/lightning/src/util/events.rs
+++ b/lightning/src/util/events.rs
@@ -188,8 +188,9 @@ pub enum Event {
                /// [`ChannelManager::create_channel`]: crate::ln::channelmanager::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....
+       /// Indicates we've received (an offer of) 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 should call
        /// [`ChannelManager::fail_htlc_backwards`] to free up resources for this HTLC and avoid
        /// network congestion.
@@ -213,6 +214,30 @@ pub enum Event {
                /// payment is to pay an invoice or to send a spontaneous payment.
                purpose: PaymentPurpose,
        },
+       /// Indicates a payment has been claimed and we've received money!
+       ///
+       /// This most likely occurs when [`ChannelManager::claim_funds`] has been called in response
+       /// to an [`Event::PaymentReceived`]. However, if we previously crashed during a
+       /// [`ChannelManager::claim_funds`] call you may see this event without a corresponding
+       /// [`Event::PaymentReceived`] event.
+       ///
+       /// # Note
+       /// LDK will not stop an inbound payment from being paid multiple times, so multiple
+       /// `PaymentReceived` events may be generated for the same payment. If you then call
+       /// [`ChannelManager::claim_funds`] twice for the same [`Event::PaymentReceived`] you may get
+       /// multiple `PaymentClaimed` events.
+       ///
+       /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds
+       PaymentClaimed {
+               /// The payment hash of the claimed payment. Note that LDK will not stop you from
+               /// registering duplicate payment hashes for inbound payments.
+               payment_hash: PaymentHash,
+               /// The value, in thousandths of a satoshi, that this payment is for.
+               amt: u64,
+               /// The purpose of this claimed payment, i.e. whether the payment was for an invoice or a
+               /// spontaneous payment.
+               purpose: PaymentPurpose,
+       },
        /// Indicates an outbound payment we made succeeded (i.e. it made it all the way to its target
        /// and we got back the payment preimage for it).
        ///
@@ -592,6 +617,14 @@ impl Writeable for Event {
                                // We never write the OpenChannelRequest events as, upon disconnection, peers
                                // drop any channels which have not yet exchanged funding_signed.
                        },
+                       &Event::PaymentClaimed { ref payment_hash, ref amt, ref purpose } => {
+                               19u8.write(writer)?;
+                               write_tlv_fields!(writer, {
+                                       (0, payment_hash, required),
+                                       (2, purpose, required),
+                                       (4, amt, 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`.
@@ -792,6 +825,25 @@ impl MaybeReadable for Event {
                                // Value 17 is used for `Event::OpenChannelRequest`.
                                Ok(None)
                        },
+                       19u8 => {
+                               let f = || {
+                                       let mut payment_hash = PaymentHash([0; 32]);
+                                       let mut purpose = None;
+                                       let mut amt = 0;
+                                       read_tlv_fields!(reader, {
+                                               (0, payment_hash, required),
+                                               (2, purpose, ignorable),
+                                               (4, amt, required),
+                                       });
+                                       if purpose.is_none() { return Ok(None); }
+                                       Ok(Some(Event::PaymentClaimed {
+                                               payment_hash,
+                                               purpose: purpose.unwrap(),
+                                               amt,
+                                       }))
+                               };
+                               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.