_ Git - rust-lightning/blob - lightning/src/util/events.rs

   1 // This file is Copyright its original authors, visible in version control
   2 // history.
   3 //
   4 // This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE
   5 // or http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   6 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
   7 // You may not use this file except in accordance with one or both of these
   8 // licenses.
   9
  10 //! Events are returned from various bits in the library which indicate some action must be taken
  11 //! by the client.
  12 //!
  13 //! Because we don't have a built-in runtime, it's up to the client to call events at a time in the
  14 //! future, as well as generate and broadcast funding transactions handle payment preimages and a
  15 //! few other things.
  16
  17 use chain::keysinterface::SpendableOutputDescriptor;
  18 use ln::channelmanager::PaymentId;
  19 use ln::channel::FUNDING_CONF_DEADLINE_BLOCKS;
  20 use ln::features::ChannelTypeFeatures;
  21 use ln::msgs;
  22 use ln::msgs::DecodeError;
  23 use ln::{PaymentPreimage, PaymentHash, PaymentSecret};
  24 use routing::gossip::NetworkUpdate;
  25 use util::ser::{BigSize, FixedLengthReader, Writeable, Writer, MaybeReadable, Readable, VecReadWrapper, VecWriteWrapper};
  26 use routing::router::{RouteHop, RouteParameters};
  27
  28 use bitcoin::{PackedLockTime, Transaction};
  29 use bitcoin::blockdata::script::Script;
  30 use bitcoin::hashes::Hash;
  31 use bitcoin::hashes::sha256::Hash as Sha256;
  32 use bitcoin::secp256k1::PublicKey;
  33 use io;
  34 use prelude::*;
  35 use core::time::Duration;
  36 use core::ops::Deref;
  37 use sync::Arc;
  38
  39 /// Some information provided on receipt of payment depends on whether the payment received is a
  40 /// spontaneous payment or a "conventional" lightning payment that's paying an invoice.
  41 #[derive(Clone, Debug)]
  42 pub enum PaymentPurpose {
  43         /// Information for receiving a payment that we generated an invoice for.
  44         InvoicePayment {
  45                 /// The preimage to the payment_hash, if the payment hash (and secret) were fetched via
  46                 /// [`ChannelManager::create_inbound_payment`]. If provided, this can be handed directly to
  47                 /// [`ChannelManager::claim_funds`].
  48                 ///
  49                 /// [`ChannelManager::create_inbound_payment`]: crate::ln::channelmanager::ChannelManager::create_inbound_payment
  50                 /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds
  51                 payment_preimage: Option<PaymentPreimage>,
  52                 /// The "payment secret". This authenticates the sender to the recipient, preventing a
  53                 /// number of deanonymization attacks during the routing process.
  54                 /// It is provided here for your reference, however its accuracy is enforced directly by
  55                 /// [`ChannelManager`] using the values you previously provided to
  56                 /// [`ChannelManager::create_inbound_payment`] or
  57                 /// [`ChannelManager::create_inbound_payment_for_hash`].
  58                 ///
  59                 /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
  60                 /// [`ChannelManager::create_inbound_payment`]: crate::ln::channelmanager::ChannelManager::create_inbound_payment
  61                 /// [`ChannelManager::create_inbound_payment_for_hash`]: crate::ln::channelmanager::ChannelManager::create_inbound_payment_for_hash
  62                 payment_secret: PaymentSecret,
  63         },
  64         /// Because this is a spontaneous payment, the payer generated their own preimage rather than us
  65         /// (the payee) providing a preimage.
  66         SpontaneousPayment(PaymentPreimage),
  67 }
  68
  69 impl_writeable_tlv_based_enum!(PaymentPurpose,
  70         (0, InvoicePayment) => {
  71                 (0, payment_preimage, option),
  72                 (2, payment_secret, required),
  73         };
  74         (2, SpontaneousPayment)
  75 );
  76
  77 #[derive(Clone, Debug, PartialEq)]
  78 /// The reason the channel was closed. See individual variants more details.
  79 pub enum ClosureReason {
  80         /// Closure generated from receiving a peer error message.
  81         ///
  82         /// Our counterparty may have broadcasted their latest commitment state, and we have
  83         /// as well.
  84         CounterpartyForceClosed {
  85                 /// The error which the peer sent us.
  86                 ///
  87                 /// The string should be sanitized before it is used (e.g emitted to logs
  88                 /// or printed to stdout). Otherwise, a well crafted error message may exploit
  89                 /// a security vulnerability in the terminal emulator or the logging subsystem.
  90                 peer_msg: String,
  91         },
  92         /// Closure generated from [`ChannelManager::force_close_channel`], called by the user.
  93         ///
  94         /// [`ChannelManager::force_close_channel`]: crate::ln::channelmanager::ChannelManager::force_close_channel.
  95         HolderForceClosed,
  96         /// The channel was closed after negotiating a cooperative close and we've now broadcasted
  97         /// the cooperative close transaction. Note the shutdown may have been initiated by us.
  98         //TODO: split between CounterpartyInitiated/LocallyInitiated
  99         CooperativeClosure,
 100         /// A commitment transaction was confirmed on chain, closing the channel. Most likely this
 101         /// commitment transaction came from our counterparty, but it may also have come from
 102         /// a copy of our own `ChannelMonitor`.
 103         CommitmentTxConfirmed,
 104         /// The funding transaction failed to confirm in a timely manner on an inbound channel.
 105         FundingTimedOut,
 106         /// Closure generated from processing an event, likely a HTLC forward/relay/reception.
 107         ProcessingError {
 108                 /// A developer-readable error message which we generated.
 109                 err: String,
 110         },
 111         /// The peer disconnected prior to funding completing. In this case the spec mandates that we
 112         /// forget the channel entirely - we can attempt again if the peer reconnects.
 113         ///
 114         /// In LDK versions prior to 0.0.107 this could also occur if we were unable to connect to the
 115         /// peer because of mutual incompatibility between us and our channel counterparty.
 116         DisconnectedPeer,
 117         /// Closure generated from `ChannelManager::read` if the ChannelMonitor is newer than
 118         /// the ChannelManager deserialized.
 119         OutdatedChannelManager
 120 }
 121
 122 impl core::fmt::Display for ClosureReason {
 123         fn fmt(&self, f: &mut core::fmt::Formatter) -> Result<(), core::fmt::Error> {
 124                 f.write_str("Channel closed because ")?;
 125                 match self {
 126                         ClosureReason::CounterpartyForceClosed { peer_msg } => {
 127                                 f.write_str("counterparty force-closed with message ")?;
 128                                 f.write_str(&peer_msg)
 129                         },
 130                         ClosureReason::HolderForceClosed => f.write_str("user manually force-closed the channel"),
 131                         ClosureReason::CooperativeClosure => f.write_str("the channel was cooperatively closed"),
 132                         ClosureReason::CommitmentTxConfirmed => f.write_str("commitment or closing transaction was confirmed on chain."),
 133                         ClosureReason::FundingTimedOut => write!(f, "funding transaction failed to confirm within {} blocks", FUNDING_CONF_DEADLINE_BLOCKS),
 134                         ClosureReason::ProcessingError { err } => {
 135                                 f.write_str("of an exception: ")?;
 136                                 f.write_str(&err)
 137                         },
 138                         ClosureReason::DisconnectedPeer => f.write_str("the peer disconnected prior to the channel being funded"),
 139                         ClosureReason::OutdatedChannelManager => f.write_str("the ChannelManager read from disk was stale compared to ChannelMonitor(s)"),
 140                 }
 141         }
 142 }
 143
 144 impl_writeable_tlv_based_enum_upgradable!(ClosureReason,
 145         (0, CounterpartyForceClosed) => { (1, peer_msg, required) },
 146         (1, FundingTimedOut) => {},
 147         (2, HolderForceClosed) => {},
 148         (6, CommitmentTxConfirmed) => {},
 149         (4, CooperativeClosure) => {},
 150         (8, ProcessingError) => { (1, err, required) },
 151         (10, DisconnectedPeer) => {},
 152         (12, OutdatedChannelManager) => {},
 153 );
 154
 155 /// Intended destination of a failed HTLC as indicated in [`Event::HTLCHandlingFailed`].
 156 #[derive(Clone, Debug, PartialEq)]
 157 pub enum HTLCDestination {
 158         /// We tried forwarding to a channel but failed to do so. An example of such an instance is when
 159         /// there is insufficient capacity in our outbound channel.
 160         NextHopChannel {
 161                 /// The `node_id` of the next node. For backwards compatibility, this field is
 162                 /// marked as optional, versions prior to 0.0.110 may not always be able to provide
 163                 /// counterparty node information.
 164                 node_id: Option<PublicKey>,
 165                 /// The outgoing `channel_id` between us and the next node.
 166                 channel_id: [u8; 32],
 167         },
 168         /// Scenario where we are unsure of the next node to forward the HTLC to.
 169         UnknownNextHop {
 170                 /// Short channel id we are requesting to forward an HTLC to.
 171                 requested_forward_scid: u64,
 172         },
 173         /// Failure scenario where an HTLC may have been forwarded to be intended for us,
 174         /// but is invalid for some reason, so we reject it.
 175         ///
 176         /// Some of the reasons may include:
 177         /// * HTLC Timeouts
 178         /// * Expected MPP amount to claim does not equal HTLC total
 179         /// * Claimable amount does not match expected amount
 180         FailedPayment {
 181                 /// The payment hash of the payment we attempted to process.
 182                 payment_hash: PaymentHash
 183         },
 184 }
 185
 186 impl_writeable_tlv_based_enum_upgradable!(HTLCDestination,
 187         (0, NextHopChannel) => {
 188                 (0, node_id, required),
 189                 (2, channel_id, required),
 190         },
 191         (2, UnknownNextHop) => {
 192                 (0, requested_forward_scid, required),
 193         },
 194         (4, FailedPayment) => {
 195                 (0, payment_hash, required),
 196         }
 197 );
 198
 199 /// An Event which you should probably take some action in response to.
 200 ///
 201 /// Note that while Writeable and Readable are implemented for Event, you probably shouldn't use
 202 /// them directly as they don't round-trip exactly (for example FundingGenerationReady is never
 203 /// written as it makes no sense to respond to it after reconnecting to peers).
 204 #[derive(Clone, Debug)]
 205 pub enum Event {
 206         /// Used to indicate that the client should generate a funding transaction with the given
 207         /// parameters and then call [`ChannelManager::funding_transaction_generated`].
 208         /// Generated in [`ChannelManager`] message handling.
 209         /// Note that *all inputs* in the funding transaction must spend SegWit outputs or your
 210         /// counterparty can steal your funds!
 211         ///
 212         /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
 213         /// [`ChannelManager::funding_transaction_generated`]: crate::ln::channelmanager::ChannelManager::funding_transaction_generated
 214         FundingGenerationReady {
 215                 /// The random channel_id we picked which you'll need to pass into
 216                 /// [`ChannelManager::funding_transaction_generated`].
 217                 ///
 218                 /// [`ChannelManager::funding_transaction_generated`]: crate::ln::channelmanager::ChannelManager::funding_transaction_generated
 219                 temporary_channel_id: [u8; 32],
 220                 /// The counterparty's node_id, which you'll need to pass back into
 221                 /// [`ChannelManager::funding_transaction_generated`].
 222                 ///
 223                 /// [`ChannelManager::funding_transaction_generated`]: crate::ln::channelmanager::ChannelManager::funding_transaction_generated
 224                 counterparty_node_id: PublicKey,
 225                 /// The value, in satoshis, that the output should have.
 226                 channel_value_satoshis: u64,
 227                 /// The script which should be used in the transaction output.
 228                 output_script: Script,
 229                 /// The `user_channel_id` value passed in to [`ChannelManager::create_channel`], or 0 for
 230                 /// an inbound channel.
 231                 ///
 232                 /// [`ChannelManager::create_channel`]: crate::ln::channelmanager::ChannelManager::create_channel
 233                 user_channel_id: u64,
 234         },
 235         /// Indicates we've received (an offer of) money! Just gotta dig out that payment preimage and
 236         /// feed it to [`ChannelManager::claim_funds`] to get it....
 237         ///
 238         /// Note that if the preimage is not known, you should call
 239         /// [`ChannelManager::fail_htlc_backwards`] to free up resources for this HTLC and avoid
 240         /// network congestion.
 241         /// If you fail to call either [`ChannelManager::claim_funds`] or
 242         /// [`ChannelManager::fail_htlc_backwards`] within the HTLC's timeout, the HTLC will be
 243         /// automatically failed.
 244         ///
 245         /// # Note
 246         /// LDK will not stop an inbound payment from being paid multiple times, so multiple
 247         /// `PaymentReceived` events may be generated for the same payment.
 248         ///
 249         /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds
 250         /// [`ChannelManager::fail_htlc_backwards`]: crate::ln::channelmanager::ChannelManager::fail_htlc_backwards
 251         PaymentReceived {
 252                 /// The hash for which the preimage should be handed to the ChannelManager. Note that LDK will
 253                 /// not stop you from registering duplicate payment hashes for inbound payments.
 254                 payment_hash: PaymentHash,
 255                 /// The value, in thousandths of a satoshi, that this payment is for.
 256                 amount_msat: u64,
 257                 /// Information for claiming this received payment, based on whether the purpose of the
 258                 /// payment is to pay an invoice or to send a spontaneous payment.
 259                 purpose: PaymentPurpose,
 260         },
 261         /// Indicates a payment has been claimed and we've received money!
 262         ///
 263         /// This most likely occurs when [`ChannelManager::claim_funds`] has been called in response
 264         /// to an [`Event::PaymentReceived`]. However, if we previously crashed during a
 265         /// [`ChannelManager::claim_funds`] call you may see this event without a corresponding
 266         /// [`Event::PaymentReceived`] event.
 267         ///
 268         /// # Note
 269         /// LDK will not stop an inbound payment from being paid multiple times, so multiple
 270         /// `PaymentReceived` events may be generated for the same payment. If you then call
 271         /// [`ChannelManager::claim_funds`] twice for the same [`Event::PaymentReceived`] you may get
 272         /// multiple `PaymentClaimed` events.
 273         ///
 274         /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds
 275         PaymentClaimed {
 276                 /// The payment hash of the claimed payment. Note that LDK will not stop you from
 277                 /// registering duplicate payment hashes for inbound payments.
 278                 payment_hash: PaymentHash,
 279                 /// The value, in thousandths of a satoshi, that this payment is for.
 280                 amount_msat: u64,
 281                 /// The purpose of this claimed payment, i.e. whether the payment was for an invoice or a
 282                 /// spontaneous payment.
 283                 purpose: PaymentPurpose,
 284         },
 285         /// Indicates an outbound payment we made succeeded (i.e. it made it all the way to its target
 286         /// and we got back the payment preimage for it).
 287         ///
 288         /// Note for MPP payments: in rare cases, this event may be preceded by a `PaymentPathFailed`
 289         /// event. In this situation, you SHOULD treat this payment as having succeeded.
 290         PaymentSent {
 291                 /// The id returned by [`ChannelManager::send_payment`] and used with
 292                 /// [`ChannelManager::retry_payment`].
 293                 ///
 294                 /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
 295                 /// [`ChannelManager::retry_payment`]: crate::ln::channelmanager::ChannelManager::retry_payment
 296                 payment_id: Option<PaymentId>,
 297                 /// The preimage to the hash given to ChannelManager::send_payment.
 298                 /// Note that this serves as a payment receipt, if you wish to have such a thing, you must
 299                 /// store it somehow!
 300                 payment_preimage: PaymentPreimage,
 301                 /// The hash that was given to [`ChannelManager::send_payment`].
 302                 ///
 303                 /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
 304                 payment_hash: PaymentHash,
 305                 /// The total fee which was spent at intermediate hops in this payment, across all paths.
 306                 ///
 307                 /// Note that, like [`Route::get_total_fees`] this does *not* include any potential
 308                 /// overpayment to the recipient node.
 309                 ///
 310                 /// If the recipient or an intermediate node misbehaves and gives us free money, this may
 311                 /// overstate the amount paid, though this is unlikely.
 312                 ///
 313                 /// [`Route::get_total_fees`]: crate::routing::router::Route::get_total_fees
 314                 fee_paid_msat: Option<u64>,
 315         },
 316         /// Indicates an outbound payment failed. Individual [`Event::PaymentPathFailed`] events
 317         /// provide failure information for each MPP part in the payment.
 318         ///
 319         /// This event is provided once there are no further pending HTLCs for the payment and the
 320         /// payment is no longer retryable, either due to a several-block timeout or because
 321         /// [`ChannelManager::abandon_payment`] was previously called for the corresponding payment.
 322         ///
 323         /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment
 324         PaymentFailed {
 325                 /// The id returned by [`ChannelManager::send_payment`] and used with
 326                 /// [`ChannelManager::retry_payment`] and [`ChannelManager::abandon_payment`].
 327                 ///
 328                 /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
 329                 /// [`ChannelManager::retry_payment`]: crate::ln::channelmanager::ChannelManager::retry_payment
 330                 /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment
 331                 payment_id: PaymentId,
 332                 /// The hash that was given to [`ChannelManager::send_payment`].
 333                 ///
 334                 /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
 335                 payment_hash: PaymentHash,
 336         },
 337         /// Indicates that a path for an outbound payment was successful.
 338         ///
 339         /// Always generated after [`Event::PaymentSent`] and thus useful for scoring channels. See
 340         /// [`Event::PaymentSent`] for obtaining the payment preimage.
 341         PaymentPathSuccessful {
 342                 /// The id returned by [`ChannelManager::send_payment`] and used with
 343                 /// [`ChannelManager::retry_payment`].
 344                 ///
 345                 /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
 346                 /// [`ChannelManager::retry_payment`]: crate::ln::channelmanager::ChannelManager::retry_payment
 347                 payment_id: PaymentId,
 348                 /// The hash that was given to [`ChannelManager::send_payment`].
 349                 ///
 350                 /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
 351                 payment_hash: Option<PaymentHash>,
 352                 /// The payment path that was successful.
 353                 ///
 354                 /// May contain a closed channel if the HTLC sent along the path was fulfilled on chain.
 355                 path: Vec<RouteHop>,
 356         },
 357         /// Indicates an outbound HTLC we sent failed. Probably some intermediary node dropped
 358         /// something. You may wish to retry with a different route.
 359         ///
 360         /// Note that this does *not* indicate that all paths for an MPP payment have failed, see
 361         /// [`Event::PaymentFailed`] and [`all_paths_failed`].
 362         ///
 363         /// [`all_paths_failed`]: Self::PaymentPathFailed::all_paths_failed
 364         PaymentPathFailed {
 365                 /// The id returned by [`ChannelManager::send_payment`] and used with
 366                 /// [`ChannelManager::retry_payment`] and [`ChannelManager::abandon_payment`].
 367                 ///
 368                 /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
 369                 /// [`ChannelManager::retry_payment`]: crate::ln::channelmanager::ChannelManager::retry_payment
 370                 /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment
 371                 payment_id: Option<PaymentId>,
 372                 /// The hash that was given to [`ChannelManager::send_payment`].
 373                 ///
 374                 /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
 375                 payment_hash: PaymentHash,
 376                 /// Indicates the payment was rejected for some reason by the recipient. This implies that
 377                 /// the payment has failed, not just the route in question. If this is not set, you may
 378                 /// retry the payment via a different route.
 379                 rejected_by_dest: bool,
 380                 /// Any failure information conveyed via the Onion return packet by a node along the failed
 381                 /// payment route.
 382                 ///
 383                 /// Should be applied to the [`NetworkGraph`] so that routing decisions can take into
 384                 /// account the update.
 385                 ///
 386                 /// [`NetworkGraph`]: crate::routing::gossip::NetworkGraph
 387                 network_update: Option<NetworkUpdate>,
 388                 /// For both single-path and multi-path payments, this is set if all paths of the payment have
 389                 /// failed. This will be set to false if (1) this is an MPP payment and (2) other parts of the
 390                 /// larger MPP payment were still in flight when this event was generated.
 391                 ///
 392                 /// Note that if you are retrying individual MPP parts, using this value to determine if a
 393                 /// payment has fully failed is race-y. Because multiple failures can happen prior to events
 394                 /// being processed, you may retry in response to a first failure, with a second failure
 395                 /// (with `all_paths_failed` set) still pending. Then, when the second failure is processed
 396                 /// you will see `all_paths_failed` set even though the retry of the first failure still
 397                 /// has an associated in-flight HTLC. See (1) for an example of such a failure.
 398                 ///
 399                 /// If you wish to retry individual MPP parts and learn when a payment has failed, you must
 400                 /// call [`ChannelManager::abandon_payment`] and wait for a [`Event::PaymentFailed`] event.
 401                 ///
 402                 /// (1) <https://github.com/lightningdevkit/rust-lightning/issues/1164>
 403                 ///
 404                 /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment
 405                 all_paths_failed: bool,
 406                 /// The payment path that failed.
 407                 path: Vec<RouteHop>,
 408                 /// The channel responsible for the failed payment path.
 409                 ///
 410                 /// Note that for route hints or for the first hop in a path this may be an SCID alias and
 411                 /// may not refer to a channel in the public network graph. These aliases may also collide
 412                 /// with channels in the public network graph.
 413                 ///
 414                 /// If this is `Some`, then the corresponding channel should be avoided when the payment is
 415                 /// retried. May be `None` for older [`Event`] serializations.
 416                 short_channel_id: Option<u64>,
 417                 /// Parameters needed to compute a new [`Route`] when retrying the failed payment path.
 418                 ///
 419                 /// See [`find_route`] for details.
 420                 ///
 421                 /// [`Route`]: crate::routing::router::Route
 422                 /// [`find_route`]: crate::routing::router::find_route
 423                 retry: Option<RouteParameters>,
 424 #[cfg(test)]
 425                 error_code: Option<u16>,
 426 #[cfg(test)]
 427                 error_data: Option<Vec<u8>>,
 428         },
 429         /// Indicates that a probe payment we sent returned successful, i.e., only failed at the destination.
 430         ProbeSuccessful {
 431                 /// The id returned by [`ChannelManager::send_probe`].
 432                 ///
 433                 /// [`ChannelManager::send_probe`]: crate::ln::channelmanager::ChannelManager::send_probe
 434                 payment_id: PaymentId,
 435                 /// The hash generated by [`ChannelManager::send_probe`].
 436                 ///
 437                 /// [`ChannelManager::send_probe`]: crate::ln::channelmanager::ChannelManager::send_probe
 438                 payment_hash: PaymentHash,
 439                 /// The payment path that was successful.
 440                 path: Vec<RouteHop>,
 441         },
 442         /// Indicates that a probe payment we sent failed at an intermediary node on the path.
 443         ProbeFailed {
 444                 /// The id returned by [`ChannelManager::send_probe`].
 445                 ///
 446                 /// [`ChannelManager::send_probe`]: crate::ln::channelmanager::ChannelManager::send_probe
 447                 payment_id: PaymentId,
 448                 /// The hash generated by [`ChannelManager::send_probe`].
 449                 ///
 450                 /// [`ChannelManager::send_probe`]: crate::ln::channelmanager::ChannelManager::send_probe
 451                 payment_hash: PaymentHash,
 452                 /// The payment path that failed.
 453                 path: Vec<RouteHop>,
 454                 /// The channel responsible for the failed probe.
 455                 ///
 456                 /// Note that for route hints or for the first hop in a path this may be an SCID alias and
 457                 /// may not refer to a channel in the public network graph. These aliases may also collide
 458                 /// with channels in the public network graph.
 459                 short_channel_id: Option<u64>,
 460         },
 461         /// Used to indicate that [`ChannelManager::process_pending_htlc_forwards`] should be called at
 462         /// a time in the future.
 463         ///
 464         /// [`ChannelManager::process_pending_htlc_forwards`]: crate::ln::channelmanager::ChannelManager::process_pending_htlc_forwards
 465         PendingHTLCsForwardable {
 466                 /// The minimum amount of time that should be waited prior to calling
 467                 /// process_pending_htlc_forwards. To increase the effort required to correlate payments,
 468                 /// you should wait a random amount of time in roughly the range (now + time_forwardable,
 469                 /// now + 5*time_forwardable).
 470                 time_forwardable: Duration,
 471         },
 472         /// Used to indicate that an output which you should know how to spend was confirmed on chain
 473         /// and is now spendable.
 474         /// Such an output will *not* ever be spent by rust-lightning, and are not at risk of your
 475         /// counterparty spending them due to some kind of timeout. Thus, you need to store them
 476         /// somewhere and spend them when you create on-chain transactions.
 477         SpendableOutputs {
 478                 /// The outputs which you should store as spendable by you.
 479                 outputs: Vec<SpendableOutputDescriptor>,
 480         },
 481         /// This event is generated when a payment has been successfully forwarded through us and a
 482         /// forwarding fee earned.
 483         PaymentForwarded {
 484                 /// The incoming channel between the previous node and us. This is only `None` for events
 485                 /// generated or serialized by versions prior to 0.0.107.
 486                 prev_channel_id: Option<[u8; 32]>,
 487                 /// The outgoing channel between the next node and us. This is only `None` for events
 488                 /// generated or serialized by versions prior to 0.0.107.
 489                 next_channel_id: Option<[u8; 32]>,
 490                 /// The fee, in milli-satoshis, which was earned as a result of the payment.
 491                 ///
 492                 /// Note that if we force-closed the channel over which we forwarded an HTLC while the HTLC
 493                 /// was pending, the amount the next hop claimed will have been rounded down to the nearest
 494                 /// whole satoshi. Thus, the fee calculated here may be higher than expected as we still
 495                 /// claimed the full value in millisatoshis from the source. In this case,
 496                 /// `claim_from_onchain_tx` will be set.
 497                 ///
 498                 /// If the channel which sent us the payment has been force-closed, we will claim the funds
 499                 /// via an on-chain transaction. In that case we do not yet know the on-chain transaction
 500                 /// fees which we will spend and will instead set this to `None`. It is possible duplicate
 501                 /// `PaymentForwarded` events are generated for the same payment iff `fee_earned_msat` is
 502                 /// `None`.
 503                 fee_earned_msat: Option<u64>,
 504                 /// If this is `true`, the forwarded HTLC was claimed by our counterparty via an on-chain
 505                 /// transaction.
 506                 claim_from_onchain_tx: bool,
 507         },
 508         /// Used to indicate that a previously opened channel with the given `channel_id` is in the
 509         /// process of closure.
 510         ChannelClosed  {
 511                 /// The channel_id of the channel which has been closed. Note that on-chain transactions
 512                 /// resolving the channel are likely still awaiting confirmation.
 513                 channel_id: [u8; 32],
 514                 /// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound
 515                 /// channels, or to [`ChannelManager::accept_inbound_channel`] for inbound channels if
 516                 /// [`UserConfig::manually_accept_inbound_channels`] config flag is set to true. Otherwise
 517                 /// `user_channel_id` will be 0 for an inbound channel.
 518                 /// This will always be zero for objects serialized with LDK versions prior to 0.0.102.
 519                 ///
 520                 /// [`ChannelManager::create_channel`]: crate::ln::channelmanager::ChannelManager::create_channel
 521                 /// [`ChannelManager::accept_inbound_channel`]: crate::ln::channelmanager::ChannelManager::accept_inbound_channel
 522                 /// [`UserConfig::manually_accept_inbound_channels`]: crate::util::config::UserConfig::manually_accept_inbound_channels
 523                 user_channel_id: u64,
 524                 /// The reason the channel was closed.
 525                 reason: ClosureReason
 526         },
 527         /// Used to indicate to the user that they can abandon the funding transaction and recycle the
 528         /// inputs for another purpose.
 529         DiscardFunding {
 530                 /// The channel_id of the channel which has been closed.
 531                 channel_id: [u8; 32],
 532                 /// The full transaction received from the user
 533                 transaction: Transaction
 534         },
 535         /// Indicates a request to open a new channel by a peer.
 536         ///
 537         /// To accept the request, call [`ChannelManager::accept_inbound_channel`]. To reject the
 538         /// request, call [`ChannelManager::force_close_without_broadcasting_txn`].
 539         ///
 540         /// The event is only triggered when a new open channel request is received and the
 541         /// [`UserConfig::manually_accept_inbound_channels`] config flag is set to true.
 542         ///
 543         /// [`ChannelManager::accept_inbound_channel`]: crate::ln::channelmanager::ChannelManager::accept_inbound_channel
 544         /// [`ChannelManager::force_close_without_broadcasting_txn`]: crate::ln::channelmanager::ChannelManager::force_close_without_broadcasting_txn
 545         /// [`UserConfig::manually_accept_inbound_channels`]: crate::util::config::UserConfig::manually_accept_inbound_channels
 546         OpenChannelRequest {
 547                 /// The temporary channel ID of the channel requested to be opened.
 548                 ///
 549                 /// When responding to the request, the `temporary_channel_id` should be passed
 550                 /// back to the ChannelManager through [`ChannelManager::accept_inbound_channel`] to accept,
 551                 /// or through [`ChannelManager::force_close_without_broadcasting_txn`] to reject.
 552                 ///
 553                 /// [`ChannelManager::accept_inbound_channel`]: crate::ln::channelmanager::ChannelManager::accept_inbound_channel
 554                 /// [`ChannelManager::force_close_without_broadcasting_txn`]: crate::ln::channelmanager::ChannelManager::force_close_without_broadcasting_txn
 555                 temporary_channel_id: [u8; 32],
 556                 /// The node_id of the counterparty requesting to open the channel.
 557                 ///
 558                 /// When responding to the request, the `counterparty_node_id` should be passed
 559                 /// back to the `ChannelManager` through [`ChannelManager::accept_inbound_channel`] to
 560                 /// accept the request, or through [`ChannelManager::force_close_without_broadcasting_txn`] to reject the
 561                 /// request.
 562                 ///
 563                 /// [`ChannelManager::accept_inbound_channel`]: crate::ln::channelmanager::ChannelManager::accept_inbound_channel
 564                 /// [`ChannelManager::force_close_without_broadcasting_txn`]: crate::ln::channelmanager::ChannelManager::force_close_without_broadcasting_txn
 565                 counterparty_node_id: PublicKey,
 566                 /// The channel value of the requested channel.
 567                 funding_satoshis: u64,
 568                 /// Our starting balance in the channel if the request is accepted, in milli-satoshi.
 569                 push_msat: u64,
 570                 /// The features that this channel will operate with. If you reject the channel, a
 571                 /// well-behaved counterparty may automatically re-attempt the channel with a new set of
 572                 /// feature flags.
 573                 ///
 574                 /// Note that if [`ChannelTypeFeatures::supports_scid_privacy`] returns true on this type,
 575                 /// the resulting [`ChannelManager`] will not be readable by versions of LDK prior to
 576                 /// 0.0.106.
 577                 ///
 578                 /// Furthermore, note that if [`ChannelTypeFeatures::supports_zero_conf`] returns true on this type,
 579                 /// the resulting [`ChannelManager`] will not be readable by versions of LDK prior to
 580                 /// 0.0.107. Channels setting this type also need to get manually accepted via
 581                 /// [`crate::ln::channelmanager::ChannelManager::accept_inbound_channel_from_trusted_peer_0conf`],
 582                 /// or will be rejected otherwise.
 583                 ///
 584                 /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
 585                 channel_type: ChannelTypeFeatures,
 586         },
 587         /// Indicates that the HTLC was accepted, but could not be processed when or after attempting to
 588         /// forward it.
 589         ///
 590         /// Some scenarios where this event may be sent include:
 591         /// * Insufficient capacity in the outbound channel
 592         /// * While waiting to forward the HTLC, the channel it is meant to be forwarded through closes
 593         /// * When an unknown SCID is requested for forwarding a payment.
 594         /// * Claiming an amount for an MPP payment that exceeds the HTLC total
 595         /// * The HTLC has timed out
 596         ///
 597         /// This event, however, does not get generated if an HTLC fails to meet the forwarding
 598         /// requirements (i.e. insufficient fees paid, or a CLTV that is too soon).
 599         HTLCHandlingFailed {
 600                 /// The channel over which the HTLC was received.
 601                 prev_channel_id: [u8; 32],
 602                 /// Destination of the HTLC that failed to be processed.
 603                 failed_next_destination: HTLCDestination,
 604         },
 605 }
 606
 607 impl Writeable for Event {
 608         fn write<W: Writer>(&self, writer: &mut W) -> Result<(), io::Error> {
 609                 match self {
 610                         &Event::FundingGenerationReady { .. } => {
 611                                 0u8.write(writer)?;
 612                                 // We never write out FundingGenerationReady events as, upon disconnection, peers
 613                                 // drop any channels which have not yet exchanged funding_signed.
 614                         },
 615                         &Event::PaymentReceived { ref payment_hash, ref amount_msat, ref purpose } => {
 616                                 1u8.write(writer)?;
 617                                 let mut payment_secret = None;
 618                                 let payment_preimage;
 619                                 match &purpose {
 620                                         PaymentPurpose::InvoicePayment { payment_preimage: preimage, payment_secret: secret } => {
 621                                                 payment_secret = Some(secret);
 622                                                 payment_preimage = *preimage;
 623                                         },
 624                                         PaymentPurpose::SpontaneousPayment(preimage) => {
 625                                                 payment_preimage = Some(*preimage);
 626                                         }
 627                                 }
 628                                 write_tlv_fields!(writer, {
 629                                         (0, payment_hash, required),
 630                                         (2, payment_secret, option),
 631                                         (4, amount_msat, required),
 632                                         (6, 0u64, required), // user_payment_id required for compatibility with 0.0.103 and earlier
 633                                         (8, payment_preimage, option),
 634                                 });
 635                         },
 636                         &Event::PaymentSent { ref payment_id, ref payment_preimage, ref payment_hash, ref fee_paid_msat } => {
 637                                 2u8.write(writer)?;
 638                                 write_tlv_fields!(writer, {
 639                                         (0, payment_preimage, required),
 640                                         (1, payment_hash, required),
 641                                         (3, payment_id, option),
 642                                         (5, fee_paid_msat, option),
 643                                 });
 644                         },
 645                         &Event::PaymentPathFailed {
 646                                 ref payment_id, ref payment_hash, ref rejected_by_dest, ref network_update,
 647                                 ref all_paths_failed, ref path, ref short_channel_id, ref retry,
 648                                 #[cfg(test)]
 649                                 ref error_code,
 650                                 #[cfg(test)]
 651                                 ref error_data,
 652                         } => {
 653                                 3u8.write(writer)?;
 654                                 #[cfg(test)]
 655                                 error_code.write(writer)?;
 656                                 #[cfg(test)]
 657                                 error_data.write(writer)?;
 658                                 write_tlv_fields!(writer, {
 659                                         (0, payment_hash, required),
 660                                         (1, network_update, option),
 661                                         (2, rejected_by_dest, required),
 662                                         (3, all_paths_failed, required),
 663                                         (5, path, vec_type),
 664                                         (7, short_channel_id, option),
 665                                         (9, retry, option),
 666                                         (11, payment_id, option),
 667                                 });
 668                         },
 669                         &Event::PendingHTLCsForwardable { time_forwardable: _ } => {
 670                                 4u8.write(writer)?;
 671                                 // Note that we now ignore these on the read end as we'll re-generate them in
 672                                 // ChannelManager, we write them here only for backwards compatibility.
 673                         },
 674                         &Event::SpendableOutputs { ref outputs } => {
 675                                 5u8.write(writer)?;
 676                                 write_tlv_fields!(writer, {
 677                                         (0, VecWriteWrapper(outputs), required),
 678                                 });
 679                         },
 680                         &Event::PaymentForwarded { fee_earned_msat, prev_channel_id, claim_from_onchain_tx, next_channel_id } => {
 681                                 7u8.write(writer)?;
 682                                 write_tlv_fields!(writer, {
 683                                         (0, fee_earned_msat, option),
 684                                         (1, prev_channel_id, option),
 685                                         (2, claim_from_onchain_tx, required),
 686                                         (3, next_channel_id, option),
 687                                 });
 688                         },
 689                         &Event::ChannelClosed { ref channel_id, ref user_channel_id, ref reason } => {
 690                                 9u8.write(writer)?;
 691                                 write_tlv_fields!(writer, {
 692                                         (0, channel_id, required),
 693                                         (1, user_channel_id, required),
 694                                         (2, reason, required)
 695                                 });
 696                         },
 697                         &Event::DiscardFunding { ref channel_id, ref transaction } => {
 698                                 11u8.write(writer)?;
 699                                 write_tlv_fields!(writer, {
 700                                         (0, channel_id, required),
 701                                         (2, transaction, required)
 702                                 })
 703                         },
 704                         &Event::PaymentPathSuccessful { ref payment_id, ref payment_hash, ref path } => {
 705                                 13u8.write(writer)?;
 706                                 write_tlv_fields!(writer, {
 707                                         (0, payment_id, required),
 708                                         (2, payment_hash, option),
 709                                         (4, path, vec_type)
 710                                 })
 711                         },
 712                         &Event::PaymentFailed { ref payment_id, ref payment_hash } => {
 713                                 15u8.write(writer)?;
 714                                 write_tlv_fields!(writer, {
 715                                         (0, payment_id, required),
 716                                         (2, payment_hash, required),
 717                                 })
 718                         },
 719                         &Event::OpenChannelRequest { .. } => {
 720                                 17u8.write(writer)?;
 721                                 // We never write the OpenChannelRequest events as, upon disconnection, peers
 722                                 // drop any channels which have not yet exchanged funding_signed.
 723                         },
 724                         &Event::PaymentClaimed { ref payment_hash, ref amount_msat, ref purpose } => {
 725                                 19u8.write(writer)?;
 726                                 write_tlv_fields!(writer, {
 727                                         (0, payment_hash, required),
 728                                         (2, purpose, required),
 729                                         (4, amount_msat, required),
 730                                 });
 731                         },
 732                         &Event::ProbeSuccessful { ref payment_id, ref payment_hash, ref path } => {
 733                                 21u8.write(writer)?;
 734                                 write_tlv_fields!(writer, {
 735                                         (0, payment_id, required),
 736                                         (2, payment_hash, required),
 737                                         (4, path, vec_type)
 738                                 })
 739                         },
 740                         &Event::ProbeFailed { ref payment_id, ref payment_hash, ref path, ref short_channel_id } => {
 741                                 23u8.write(writer)?;
 742                                 write_tlv_fields!(writer, {
 743                                         (0, payment_id, required),
 744                                         (2, payment_hash, required),
 745                                         (4, path, vec_type),
 746                                         (6, short_channel_id, option),
 747                                 })
 748                         },
 749                         &Event::HTLCHandlingFailed { ref prev_channel_id, ref failed_next_destination } => {
 750                                 25u8.write(writer)?;
 751                                 write_tlv_fields!(writer, {
 752                                         (0, prev_channel_id, required),
 753                                         (2, failed_next_destination, required),
 754                                 })
 755                         },
 756                         // Note that, going forward, all new events must only write data inside of
 757                         // `write_tlv_fields`. Versions 0.0.101+ will ignore odd-numbered events that write
 758                         // data via `write_tlv_fields`.
 759                 }
 760                 Ok(())
 761         }
 762 }
 763 impl MaybeReadable for Event {
 764         fn read<R: io::Read>(reader: &mut R) -> Result<Option<Self>, msgs::DecodeError> {
 765                 match Readable::read(reader)? {
 766                         // Note that we do not write a length-prefixed TLV for FundingGenerationReady events,
 767                         // unlike all other events, thus we return immediately here.
 768                         0u8 => Ok(None),
 769                         1u8 => {
 770                                 let f = || {
 771                                         let mut payment_hash = PaymentHash([0; 32]);
 772                                         let mut payment_preimage = None;
 773                                         let mut payment_secret = None;
 774                                         let mut amount_msat = 0;
 775                                         let mut _user_payment_id = None::<u64>; // For compatibility with 0.0.103 and earlier
 776                                         read_tlv_fields!(reader, {
 777                                                 (0, payment_hash, required),
 778                                                 (2, payment_secret, option),
 779                                                 (4, amount_msat, required),
 780                                                 (6, _user_payment_id, option),
 781                                                 (8, payment_preimage, option),
 782                                         });
 783                                         let purpose = match payment_secret {
 784                                                 Some(secret) => PaymentPurpose::InvoicePayment {
 785                                                         payment_preimage,
 786                                                         payment_secret: secret
 787                                                 },
 788                                                 None if payment_preimage.is_some() => PaymentPurpose::SpontaneousPayment(payment_preimage.unwrap()),
 789                                                 None => return Err(msgs::DecodeError::InvalidValue),
 790                                         };
 791                                         Ok(Some(Event::PaymentReceived {
 792                                                 payment_hash,
 793                                                 amount_msat,
 794                                                 purpose,
 795                                         }))
 796                                 };
 797                                 f()
 798                         },
 799                         2u8 => {
 800                                 let f = || {
 801                                         let mut payment_preimage = PaymentPreimage([0; 32]);
 802                                         let mut payment_hash = None;
 803                                         let mut payment_id = None;
 804                                         let mut fee_paid_msat = None;
 805                                         read_tlv_fields!(reader, {
 806                                                 (0, payment_preimage, required),
 807                                                 (1, payment_hash, option),
 808                                                 (3, payment_id, option),
 809                                                 (5, fee_paid_msat, option),
 810                                         });
 811                                         if payment_hash.is_none() {
 812                                                 payment_hash = Some(PaymentHash(Sha256::hash(&payment_preimage.0[..]).into_inner()));
 813                                         }
 814                                         Ok(Some(Event::PaymentSent {
 815                                                 payment_id,
 816                                                 payment_preimage,
 817                                                 payment_hash: payment_hash.unwrap(),
 818                                                 fee_paid_msat,
 819                                         }))
 820                                 };
 821                                 f()
 822                         },
 823                         3u8 => {
 824                                 let f = || {
 825                                         #[cfg(test)]
 826                                         let error_code = Readable::read(reader)?;
 827                                         #[cfg(test)]
 828                                         let error_data = Readable::read(reader)?;
 829                                         let mut payment_hash = PaymentHash([0; 32]);
 830                                         let mut rejected_by_dest = false;
 831                                         let mut network_update = None;
 832                                         let mut all_paths_failed = Some(true);
 833                                         let mut path: Option<Vec<RouteHop>> = Some(vec![]);
 834                                         let mut short_channel_id = None;
 835                                         let mut retry = None;
 836                                         let mut payment_id = None;
 837                                         read_tlv_fields!(reader, {
 838                                                 (0, payment_hash, required),
 839                                                 (1, network_update, ignorable),
 840                                                 (2, rejected_by_dest, required),
 841                                                 (3, all_paths_failed, option),
 842                                                 (5, path, vec_type),
 843                                                 (7, short_channel_id, option),
 844                                                 (9, retry, option),
 845                                                 (11, payment_id, option),
 846                                         });
 847                                         Ok(Some(Event::PaymentPathFailed {
 848                                                 payment_id,
 849                                                 payment_hash,
 850                                                 rejected_by_dest,
 851                                                 network_update,
 852                                                 all_paths_failed: all_paths_failed.unwrap(),
 853                                                 path: path.unwrap(),
 854                                                 short_channel_id,
 855                                                 retry,
 856                                                 #[cfg(test)]
 857                                                 error_code,
 858                                                 #[cfg(test)]
 859                                                 error_data,
 860                                         }))
 861                                 };
 862                                 f()
 863                         },
 864                         4u8 => Ok(None),
 865                         5u8 => {
 866                                 let f = || {
 867                                         let mut outputs = VecReadWrapper(Vec::new());
 868                                         read_tlv_fields!(reader, {
 869                                                 (0, outputs, required),
 870                                         });
 871                                         Ok(Some(Event::SpendableOutputs { outputs: outputs.0 }))
 872                                 };
 873                                 f()
 874                         },
 875                         7u8 => {
 876                                 let f = || {
 877                                         let mut fee_earned_msat = None;
 878                                         let mut prev_channel_id = None;
 879                                         let mut claim_from_onchain_tx = false;
 880                                         let mut next_channel_id = None;
 881                                         read_tlv_fields!(reader, {
 882                                                 (0, fee_earned_msat, option),
 883                                                 (1, prev_channel_id, option),
 884                                                 (2, claim_from_onchain_tx, required),
 885                                                 (3, next_channel_id, option),
 886                                         });
 887                                         Ok(Some(Event::PaymentForwarded { fee_earned_msat, prev_channel_id, claim_from_onchain_tx, next_channel_id }))
 888                                 };
 889                                 f()
 890                         },
 891                         9u8 => {
 892                                 let f = || {
 893                                         let mut channel_id = [0; 32];
 894                                         let mut reason = None;
 895                                         let mut user_channel_id_opt = None;
 896                                         read_tlv_fields!(reader, {
 897                                                 (0, channel_id, required),
 898                                                 (1, user_channel_id_opt, option),
 899                                                 (2, reason, ignorable),
 900                                         });
 901                                         if reason.is_none() { return Ok(None); }
 902                                         let user_channel_id = if let Some(id) = user_channel_id_opt { id } else { 0 };
 903                                         Ok(Some(Event::ChannelClosed { channel_id, user_channel_id, reason: reason.unwrap() }))
 904                                 };
 905                                 f()
 906                         },
 907                         11u8 => {
 908                                 let f = || {
 909                                         let mut channel_id = [0; 32];
 910                                         let mut transaction = Transaction{ version: 2, lock_time: PackedLockTime::ZERO, input: Vec::new(), output: Vec::new() };
 911                                         read_tlv_fields!(reader, {
 912                                                 (0, channel_id, required),
 913                                                 (2, transaction, required),
 914                                         });
 915                                         Ok(Some(Event::DiscardFunding { channel_id, transaction } ))
 916                                 };
 917                                 f()
 918                         },
 919                         13u8 => {
 920                                 let f = || {
 921                                         let mut payment_id = PaymentId([0; 32]);
 922                                         let mut payment_hash = None;
 923                                         let mut path: Option<Vec<RouteHop>> = Some(vec![]);
 924                                         read_tlv_fields!(reader, {
 925                                                 (0, payment_id, required),
 926                                                 (2, payment_hash, option),
 927                                                 (4, path, vec_type),
 928                                         });
 929                                         Ok(Some(Event::PaymentPathSuccessful {
 930                                                 payment_id,
 931                                                 payment_hash,
 932                                                 path: path.unwrap(),
 933                                         }))
 934                                 };
 935                                 f()
 936                         },
 937                         15u8 => {
 938                                 let f = || {
 939                                         let mut payment_hash = PaymentHash([0; 32]);
 940                                         let mut payment_id = PaymentId([0; 32]);
 941                                         read_tlv_fields!(reader, {
 942                                                 (0, payment_id, required),
 943                                                 (2, payment_hash, required),
 944                                         });
 945                                         Ok(Some(Event::PaymentFailed {
 946                                                 payment_id,
 947                                                 payment_hash,
 948                                         }))
 949                                 };
 950                                 f()
 951                         },
 952                         17u8 => {
 953                                 // Value 17 is used for `Event::OpenChannelRequest`.
 954                                 Ok(None)
 955                         },
 956                         19u8 => {
 957                                 let f = || {
 958                                         let mut payment_hash = PaymentHash([0; 32]);
 959                                         let mut purpose = None;
 960                                         let mut amount_msat = 0;
 961                                         read_tlv_fields!(reader, {
 962                                                 (0, payment_hash, required),
 963                                                 (2, purpose, ignorable),
 964                                                 (4, amount_msat, required),
 965                                         });
 966                                         if purpose.is_none() { return Ok(None); }
 967                                         Ok(Some(Event::PaymentClaimed {
 968                                                 payment_hash,
 969                                                 purpose: purpose.unwrap(),
 970                                                 amount_msat,
 971                                         }))
 972                                 };
 973                                 f()
 974                         },
 975                         21u8 => {
 976                                 let f = || {
 977                                         let mut payment_id = PaymentId([0; 32]);
 978                                         let mut payment_hash = PaymentHash([0; 32]);
 979                                         let mut path: Option<Vec<RouteHop>> = Some(vec![]);
 980                                         read_tlv_fields!(reader, {
 981                                                 (0, payment_id, required),
 982                                                 (2, payment_hash, required),
 983                                                 (4, path, vec_type),
 984                                         });
 985                                         Ok(Some(Event::ProbeSuccessful {
 986                                                 payment_id,
 987                                                 payment_hash,
 988                                                 path: path.unwrap(),
 989                                         }))
 990                                 };
 991                                 f()
 992                         },
 993                         23u8 => {
 994                                 let f = || {
 995                                         let mut payment_id = PaymentId([0; 32]);
 996                                         let mut payment_hash = PaymentHash([0; 32]);
 997                                         let mut path: Option<Vec<RouteHop>> = Some(vec![]);
 998                                         let mut short_channel_id = None;
 999                                         read_tlv_fields!(reader, {
1000                                                 (0, payment_id, required),
1001                                                 (2, payment_hash, required),
1002                                                 (4, path, vec_type),
1003                                                 (6, short_channel_id, option),
1004                                         });
1005                                         Ok(Some(Event::ProbeFailed{
1006                                                 payment_id,
1007                                                 payment_hash,
1008                                                 path: path.unwrap(),
1009                                                 short_channel_id,
1010                                         }))
1011                                 };
1012                                 f()
1013                         },
1014                         // Versions prior to 0.0.100 did not ignore odd types, instead returning InvalidValue.
1015                         // Version 0.0.100 failed to properly ignore odd types, possibly resulting in corrupt
1016                         // reads.
1017                         x if x % 2 == 1 => {
1018                                 // If the event is of unknown type, assume it was written with `write_tlv_fields`,
1019                                 // which prefixes the whole thing with a length BigSize. Because the event is
1020                                 // odd-type unknown, we should treat it as `Ok(None)` even if it has some TLV
1021                                 // fields that are even. Thus, we avoid using `read_tlv_fields` and simply read
1022                                 // exactly the number of bytes specified, ignoring them entirely.
1023                                 let tlv_len: BigSize = Readable::read(reader)?;
1024                                 FixedLengthReader::new(reader, tlv_len.0)
1025                                         .eat_remaining().map_err(|_| msgs::DecodeError::ShortRead)?;
1026                                 Ok(None)
1027                         },
1028                         _ => Err(msgs::DecodeError::InvalidValue)
1029                 }
1030         }
1031 }
1032
1033 /// An event generated by ChannelManager which indicates a message should be sent to a peer (or
1034 /// broadcast to most peers).
1035 /// These events are handled by PeerManager::process_events if you are using a PeerManager.
1036 #[derive(Clone, Debug)]
1037 pub enum MessageSendEvent {
1038         /// Used to indicate that we've accepted a channel open and should send the accept_channel
1039         /// message provided to the given peer.
1040         SendAcceptChannel {
1041                 /// The node_id of the node which should receive this message
1042                 node_id: PublicKey,
1043                 /// The message which should be sent.
1044                 msg: msgs::AcceptChannel,
1045         },
1046         /// Used to indicate that we've initiated a channel open and should send the open_channel
1047         /// message provided to the given peer.
1048         SendOpenChannel {
1049                 /// The node_id of the node which should receive this message
1050                 node_id: PublicKey,
1051                 /// The message which should be sent.
1052                 msg: msgs::OpenChannel,
1053         },
1054         /// Used to indicate that a funding_created message should be sent to the peer with the given node_id.
1055         SendFundingCreated {
1056                 /// The node_id of the node which should receive this message
1057                 node_id: PublicKey,
1058                 /// The message which should be sent.
1059                 msg: msgs::FundingCreated,
1060         },
1061         /// Used to indicate that a funding_signed message should be sent to the peer with the given node_id.
1062         SendFundingSigned {
1063                 /// The node_id of the node which should receive this message
1064                 node_id: PublicKey,
1065                 /// The message which should be sent.
1066                 msg: msgs::FundingSigned,
1067         },
1068         /// Used to indicate that a channel_ready message should be sent to the peer with the given node_id.
1069         SendChannelReady {
1070                 /// The node_id of the node which should receive these message(s)
1071                 node_id: PublicKey,
1072                 /// The channel_ready message which should be sent.
1073                 msg: msgs::ChannelReady,
1074         },
1075         /// Used to indicate that an announcement_signatures message should be sent to the peer with the given node_id.
1076         SendAnnouncementSignatures {
1077                 /// The node_id of the node which should receive these message(s)
1078                 node_id: PublicKey,
1079                 /// The announcement_signatures message which should be sent.
1080                 msg: msgs::AnnouncementSignatures,
1081         },
1082         /// Used to indicate that a series of HTLC update messages, as well as a commitment_signed
1083         /// message should be sent to the peer with the given node_id.
1084         UpdateHTLCs {
1085                 /// The node_id of the node which should receive these message(s)
1086                 node_id: PublicKey,
1087                 /// The update messages which should be sent. ALL messages in the struct should be sent!
1088                 updates: msgs::CommitmentUpdate,
1089         },
1090         /// Used to indicate that a revoke_and_ack message should be sent to the peer with the given node_id.
1091         SendRevokeAndACK {
1092                 /// The node_id of the node which should receive this message
1093                 node_id: PublicKey,
1094                 /// The message which should be sent.
1095                 msg: msgs::RevokeAndACK,
1096         },
1097         /// Used to indicate that a closing_signed message should be sent to the peer with the given node_id.
1098         SendClosingSigned {
1099                 /// The node_id of the node which should receive this message
1100                 node_id: PublicKey,
1101                 /// The message which should be sent.
1102                 msg: msgs::ClosingSigned,
1103         },
1104         /// Used to indicate that a shutdown message should be sent to the peer with the given node_id.
1105         SendShutdown {
1106                 /// The node_id of the node which should receive this message
1107                 node_id: PublicKey,
1108                 /// The message which should be sent.
1109                 msg: msgs::Shutdown,
1110         },
1111         /// Used to indicate that a channel_reestablish message should be sent to the peer with the given node_id.
1112         SendChannelReestablish {
1113                 /// The node_id of the node which should receive this message
1114                 node_id: PublicKey,
1115                 /// The message which should be sent.
1116                 msg: msgs::ChannelReestablish,
1117         },
1118         /// Used to send a channel_announcement and channel_update to a specific peer, likely on
1119         /// initial connection to ensure our peers know about our channels.
1120         SendChannelAnnouncement {
1121                 /// The node_id of the node which should receive this message
1122                 node_id: PublicKey,
1123                 /// The channel_announcement which should be sent.
1124                 msg: msgs::ChannelAnnouncement,
1125                 /// The followup channel_update which should be sent.
1126                 update_msg: msgs::ChannelUpdate,
1127         },
1128         /// Used to indicate that a channel_announcement and channel_update should be broadcast to all
1129         /// peers (except the peer with node_id either msg.contents.node_id_1 or msg.contents.node_id_2).
1130         ///
1131         /// Note that after doing so, you very likely (unless you did so very recently) want to call
1132         /// ChannelManager::broadcast_node_announcement to trigger a BroadcastNodeAnnouncement event.
1133         /// This ensures that any nodes which see our channel_announcement also have a relevant
1134         /// node_announcement, including relevant feature flags which may be important for routing
1135         /// through or to us.
1136         BroadcastChannelAnnouncement {
1137                 /// The channel_announcement which should be sent.
1138                 msg: msgs::ChannelAnnouncement,
1139                 /// The followup channel_update which should be sent.
1140                 update_msg: msgs::ChannelUpdate,
1141         },
1142         /// Used to indicate that a node_announcement should be broadcast to all peers.
1143         BroadcastNodeAnnouncement {
1144                 /// The node_announcement which should be sent.
1145                 msg: msgs::NodeAnnouncement,
1146         },
1147         /// Used to indicate that a channel_update should be broadcast to all peers.
1148         BroadcastChannelUpdate {
1149                 /// The channel_update which should be sent.
1150                 msg: msgs::ChannelUpdate,
1151         },
1152         /// Used to indicate that a channel_update should be sent to a single peer.
1153         /// In contrast to [`Self::BroadcastChannelUpdate`], this is used when the channel is a
1154         /// private channel and we shouldn't be informing all of our peers of channel parameters.
1155         SendChannelUpdate {
1156                 /// The node_id of the node which should receive this message
1157                 node_id: PublicKey,
1158                 /// The channel_update which should be sent.
1159                 msg: msgs::ChannelUpdate,
1160         },
1161         /// Broadcast an error downstream to be handled
1162         HandleError {
1163                 /// The node_id of the node which should receive this message
1164                 node_id: PublicKey,
1165                 /// The action which should be taken.
1166                 action: msgs::ErrorAction
1167         },
1168         /// Query a peer for channels with funding transaction UTXOs in a block range.
1169         SendChannelRangeQuery {
1170                 /// The node_id of this message recipient
1171                 node_id: PublicKey,
1172                 /// The query_channel_range which should be sent.
1173                 msg: msgs::QueryChannelRange,
1174         },
1175         /// Request routing gossip messages from a peer for a list of channels identified by
1176         /// their short_channel_ids.
1177         SendShortIdsQuery {
1178                 /// The node_id of this message recipient
1179                 node_id: PublicKey,
1180                 /// The query_short_channel_ids which should be sent.
1181                 msg: msgs::QueryShortChannelIds,
1182         },
1183         /// Sends a reply to a channel range query. This may be one of several SendReplyChannelRange events
1184         /// emitted during processing of the query.
1185         SendReplyChannelRange {
1186                 /// The node_id of this message recipient
1187                 node_id: PublicKey,
1188                 /// The reply_channel_range which should be sent.
1189                 msg: msgs::ReplyChannelRange,
1190         },
1191         /// Sends a timestamp filter for inbound gossip. This should be sent on each new connection to
1192         /// enable receiving gossip messages from the peer.
1193         SendGossipTimestampFilter {
1194                 /// The node_id of this message recipient
1195                 node_id: PublicKey,
1196                 /// The gossip_timestamp_filter which should be sent.
1197                 msg: msgs::GossipTimestampFilter,
1198         },
1199 }
1200
1201 /// A trait indicating an object may generate message send events
1202 pub trait MessageSendEventsProvider {
1203         /// Gets the list of pending events which were generated by previous actions, clearing the list
1204         /// in the process.
1205         fn get_and_clear_pending_msg_events(&self) -> Vec<MessageSendEvent>;
1206 }
1207
1208 /// A trait indicating an object may generate onion messages to send
1209 pub trait OnionMessageProvider {
1210         /// Gets the next pending onion message for the peer with the given node id.
1211         fn next_onion_message_for_peer(&self, peer_node_id: PublicKey) -> Option<msgs::OnionMessage>;
1212 }
1213
1214 /// A trait indicating an object may generate events.
1215 ///
1216 /// Events are processed by passing an [`EventHandler`] to [`process_pending_events`].
1217 ///
1218 /// # Requirements
1219 ///
1220 /// When using this trait, [`process_pending_events`] will call [`handle_event`] for each pending
1221 /// event since the last invocation.
1222 ///
1223 /// In order to ensure no [`Event`]s are lost, implementors of this trait will persist [`Event`]s
1224 /// and replay any unhandled events on startup. An [`Event`] is considered handled when
1225 /// [`process_pending_events`] returns, thus handlers MUST fully handle [`Event`]s and persist any
1226 /// relevant changes to disk *before* returning.
1227 ///
1228 /// Further, because an application may crash between an [`Event`] being handled and the
1229 /// implementor of this trait being re-serialized, [`Event`] handling must be idempotent - in
1230 /// effect, [`Event`]s may be replayed.
1231 ///
1232 /// Note, handlers may call back into the provider and thus deadlocking must be avoided. Be sure to
1233 /// consult the provider's documentation on the implication of processing events and how a handler
1234 /// may safely use the provider (e.g., see [`ChannelManager::process_pending_events`] and
1235 /// [`ChainMonitor::process_pending_events`]).
1236 ///
1237 /// (C-not implementable) As there is likely no reason for a user to implement this trait on their
1238 /// own type(s).
1239 ///
1240 /// [`process_pending_events`]: Self::process_pending_events
1241 /// [`handle_event`]: EventHandler::handle_event
1242 /// [`ChannelManager::process_pending_events`]: crate::ln::channelmanager::ChannelManager#method.process_pending_events
1243 /// [`ChainMonitor::process_pending_events`]: crate::chain::chainmonitor::ChainMonitor#method.process_pending_events
1244 pub trait EventsProvider {
1245         /// Processes any events generated since the last call using the given event handler.
1246         ///
1247         /// See the trait-level documentation for requirements.
1248         fn process_pending_events<H: Deref>(&self, handler: H) where H::Target: EventHandler;
1249 }
1250
1251 /// A trait implemented for objects handling events from [`EventsProvider`].
1252 pub trait EventHandler {
1253         /// Handles the given [`Event`].
1254         ///
1255         /// See [`EventsProvider`] for details that must be considered when implementing this method.
1256         fn handle_event(&self, event: &Event);
1257 }
1258
1259 impl<F> EventHandler for F where F: Fn(&Event) {
1260         fn handle_event(&self, event: &Event) {
1261                 self(event)
1262         }
1263 }
1264
1265 impl<T: EventHandler> EventHandler for Arc<T> {
1266         fn handle_event(&self, event: &Event) {
1267                 self.deref().handle_event(event)
1268         }
1269 }