Merge pull request #2269 from TheBlueMatt/2023-05-doc-events-present
[rust-lightning] / lightning / src / events / mod.rs
index 1bd1214596de769154fab9cd37e41df1b3748e7d..665fd0ed23a51ae27b7c260b33717ac9690f74db 100644 (file)
@@ -20,7 +20,7 @@ pub mod bump_transaction;
 #[cfg(anchors)]
 pub use bump_transaction::BumpTransactionEvent;
 
-use crate::chain::keysinterface::SpendableOutputDescriptor;
+use crate::sign::SpendableOutputDescriptor;
 use crate::ln::channelmanager::{InterceptId, PaymentId, RecipientOnionFields};
 use crate::ln::channel::FUNDING_CONF_DEADLINE_BLOCKS;
 use crate::ln::features::ChannelTypeFeatures;
@@ -30,7 +30,7 @@ use crate::routing::gossip::NetworkUpdate;
 use crate::util::errors::APIError;
 use crate::util::ser::{BigSize, FixedLengthReader, Writeable, Writer, MaybeReadable, Readable, RequiredWrapper, UpgradableRequired, WithoutLength};
 use crate::util::string::UntrustedString;
-use crate::routing::router::{RouteHop, RouteParameters};
+use crate::routing::router::{BlindedTail, Path, RouteHop, RouteParameters};
 
 use bitcoin::{PackedLockTime, Transaction, OutPoint};
 #[cfg(anchors)]
@@ -129,7 +129,7 @@ pub enum ClosureReason {
                /// Be careful about printing the peer_msg, a well-crafted message could exploit
                /// a security vulnerability in the terminal emulator or the logging subsystem.
                /// To be safe, use `Display` on `UntrustedString`
-               /// 
+               ///
                /// [`UntrustedString`]: crate::util::string::UntrustedString
                peer_msg: UntrustedString,
        },
@@ -377,7 +377,7 @@ pub enum Event {
                /// This field will always be filled in when the event was generated by LDK versions
                /// 0.0.113 and above.
                ///
-               /// [phantom nodes]: crate::chain::keysinterface::PhantomKeysManager
+               /// [phantom nodes]: crate::sign::PhantomKeysManager
                receiver_node_id: Option<PublicKey>,
                /// The hash for which the preimage should be handed to the ChannelManager. Note that LDK will
                /// not stop you from registering duplicate payment hashes for inbound payments.
@@ -425,7 +425,7 @@ pub enum Event {
                /// This field will always be filled in when the event was generated by LDK versions
                /// 0.0.113 and above.
                ///
-               /// [phantom nodes]: crate::chain::keysinterface::PhantomKeysManager
+               /// [phantom nodes]: crate::sign::PhantomKeysManager
                receiver_node_id: Option<PublicKey>,
                /// The payment hash of the claimed payment. Note that LDK will not stop you from
                /// registering duplicate payment hashes for inbound payments.
@@ -498,12 +498,14 @@ pub enum Event {
                payment_id: PaymentId,
                /// The hash that was given to [`ChannelManager::send_payment`].
                ///
+               /// This will be `Some` for all payments which completed on LDK 0.0.104 or later.
+               ///
                /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
                payment_hash: Option<PaymentHash>,
                /// The payment path that was successful.
                ///
                /// May contain a closed channel if the HTLC sent along the path was fulfilled on chain.
-               path: Vec<RouteHop>,
+               path: Path,
        },
        /// Indicates an outbound HTLC we sent failed, likely due to an intermediary node being unable to
        /// handle the HTLC.
@@ -518,6 +520,8 @@ pub enum Event {
        PaymentPathFailed {
                /// The `payment_id` passed to [`ChannelManager::send_payment`].
                ///
+               /// This will be `Some` for all payment paths which failed on LDK 0.0.103 or later.
+               ///
                /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
                /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment
                payment_id: Option<PaymentId>,
@@ -535,7 +539,7 @@ pub enum Event {
                /// [`NetworkGraph`]: crate::routing::gossip::NetworkGraph
                failure: PathFailure,
                /// The payment path that failed.
-               path: Vec<RouteHop>,
+               path: Path,
                /// The channel responsible for the failed payment path.
                ///
                /// Note that for route hints or for the first hop in a path this may be an SCID alias and
@@ -561,7 +565,7 @@ pub enum Event {
                /// [`ChannelManager::send_probe`]: crate::ln::channelmanager::ChannelManager::send_probe
                payment_hash: PaymentHash,
                /// The payment path that was successful.
-               path: Vec<RouteHop>,
+               path: Path,
        },
        /// Indicates that a probe payment we sent failed at an intermediary node on the path.
        ProbeFailed {
@@ -574,7 +578,7 @@ pub enum Event {
                /// [`ChannelManager::send_probe`]: crate::ln::channelmanager::ChannelManager::send_probe
                payment_hash: PaymentHash,
                /// The payment path that failed.
-               path: Vec<RouteHop>,
+               path: Path,
                /// The channel responsible for the failed probe.
                ///
                /// Note that for route hints or for the first hop in a path this may be an SCID alias and
@@ -884,7 +888,8 @@ impl Writeable for Event {
                                        (1, None::<NetworkUpdate>, option), // network_update in LDK versions prior to 0.0.114
                                        (2, payment_failed_permanently, required),
                                        (3, false, required), // all_paths_failed in LDK versions prior to 0.0.114
-                                       (5, *path, vec_type),
+                                       (4, path.blinded_tail, option),
+                                       (5, path.hops, vec_type),
                                        (7, short_channel_id, option),
                                        (9, None::<RouteParameters>, option), // retry in LDK versions prior to 0.0.115
                                        (11, payment_id, option),
@@ -952,7 +957,8 @@ impl Writeable for Event {
                                write_tlv_fields!(writer, {
                                        (0, payment_id, required),
                                        (2, payment_hash, option),
-                                       (4, *path, vec_type)
+                                       (4, path.hops, vec_type),
+                                       (6, path.blinded_tail, option),
                                })
                        },
                        &Event::PaymentFailed { ref payment_id, ref payment_hash, ref reason } => {
@@ -982,7 +988,8 @@ impl Writeable for Event {
                                write_tlv_fields!(writer, {
                                        (0, payment_id, required),
                                        (2, payment_hash, required),
-                                       (4, *path, vec_type)
+                                       (4, path.hops, vec_type),
+                                       (6, path.blinded_tail, option),
                                })
                        },
                        &Event::ProbeFailed { ref payment_id, ref payment_hash, ref path, ref short_channel_id } => {
@@ -990,8 +997,9 @@ impl Writeable for Event {
                                write_tlv_fields!(writer, {
                                        (0, payment_id, required),
                                        (2, payment_hash, required),
-                                       (4, *path, vec_type),
+                                       (4, path.hops, vec_type),
                                        (6, short_channel_id, option),
+                                       (8, path.blinded_tail, option),
                                })
                        },
                        &Event::HTLCHandlingFailed { ref prev_channel_id, ref failed_next_destination } => {
@@ -1122,6 +1130,7 @@ impl MaybeReadable for Event {
                                        let mut payment_hash = PaymentHash([0; 32]);
                                        let mut payment_failed_permanently = false;
                                        let mut network_update = None;
+                                       let mut blinded_tail: Option<BlindedTail> = None;
                                        let mut path: Option<Vec<RouteHop>> = Some(vec![]);
                                        let mut short_channel_id = None;
                                        let mut payment_id = None;
@@ -1130,6 +1139,7 @@ impl MaybeReadable for Event {
                                                (0, payment_hash, required),
                                                (1, network_update, upgradable_option),
                                                (2, payment_failed_permanently, required),
+                                               (4, blinded_tail, option),
                                                (5, path, vec_type),
                                                (7, short_channel_id, option),
                                                (11, payment_id, option),
@@ -1141,7 +1151,7 @@ impl MaybeReadable for Event {
                                                payment_hash,
                                                payment_failed_permanently,
                                                failure,
-                                               path: path.unwrap(),
+                                               path: Path { hops: path.unwrap(), blinded_tail },
                                                short_channel_id,
                                                #[cfg(test)]
                                                error_code,
@@ -1244,18 +1254,16 @@ impl MaybeReadable for Event {
                        },
                        13u8 => {
                                let f = || {
-                                       let mut payment_id = PaymentId([0; 32]);
-                                       let mut payment_hash = None;
-                                       let mut path: Option<Vec<RouteHop>> = Some(vec![]);
-                                       read_tlv_fields!(reader, {
+                                       _init_and_read_tlv_fields!(reader, {
                                                (0, payment_id, required),
                                                (2, payment_hash, option),
                                                (4, path, vec_type),
+                                               (6, blinded_tail, option),
                                        });
                                        Ok(Some(Event::PaymentPathSuccessful {
-                                               payment_id,
+                                               payment_id: payment_id.0.unwrap(),
                                                payment_hash,
-                                               path: path.unwrap(),
+                                               path: Path { hops: path.unwrap(), blinded_tail },
                                        }))
                                };
                                f()
@@ -1305,38 +1313,33 @@ impl MaybeReadable for Event {
                        },
                        21u8 => {
                                let f = || {
-                                       let mut payment_id = PaymentId([0; 32]);
-                                       let mut payment_hash = PaymentHash([0; 32]);
-                                       let mut path: Option<Vec<RouteHop>> = Some(vec![]);
-                                       read_tlv_fields!(reader, {
+                                       _init_and_read_tlv_fields!(reader, {
                                                (0, payment_id, required),
                                                (2, payment_hash, required),
                                                (4, path, vec_type),
+                                               (6, blinded_tail, option),
                                        });
                                        Ok(Some(Event::ProbeSuccessful {
-                                               payment_id,
-                                               payment_hash,
-                                               path: path.unwrap(),
+                                               payment_id: payment_id.0.unwrap(),
+                                               payment_hash: payment_hash.0.unwrap(),
+                                               path: Path { hops: path.unwrap(), blinded_tail },
                                        }))
                                };
                                f()
                        },
                        23u8 => {
                                let f = || {
-                                       let mut payment_id = PaymentId([0; 32]);
-                                       let mut payment_hash = PaymentHash([0; 32]);
-                                       let mut path: Option<Vec<RouteHop>> = Some(vec![]);
-                                       let mut short_channel_id = None;
-                                       read_tlv_fields!(reader, {
+                                       _init_and_read_tlv_fields!(reader, {
                                                (0, payment_id, required),
                                                (2, payment_hash, required),
                                                (4, path, vec_type),
                                                (6, short_channel_id, option),
+                                               (8, blinded_tail, option),
                                        });
                                        Ok(Some(Event::ProbeFailed {
-                                               payment_id,
-                                               payment_hash,
-                                               path: path.unwrap(),
+                                               payment_id: payment_id.0.unwrap(),
+                                               payment_hash: payment_hash.0.unwrap(),
+                                               path: Path { hops: path.unwrap(), blinded_tail },
                                                short_channel_id,
                                        }))
                                };