Work around LND bug 6039

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

diff --git a/lightning/src/events/mod.rs b/lightning/src/events/mod.rs
index 01a3fef6733cfb3a7f26b0f719b5450f9d1ad468..418f8d5459a18e7fe3711327ba119ab87d2de5ef 100644 (file)
--- a/lightning/src/events/mod.rs
+++ b/lightning/src/events/mod.rs
@@ -343,11 +343,15 @@ pub enum Event {
                channel_value_satoshis: u64,
                /// The script which should be used in the transaction output.
                output_script: Script,
-               /// The `user_channel_id` value passed in to [`ChannelManager::create_channel`], or a
-               /// random value for an inbound channel. This may be zero for objects serialized with LDK
-               /// versions prior to 0.0.113.
+               /// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound
+               /// channels, or to [`ChannelManager::accept_inbound_channel`] for inbound channels if
+               /// [`UserConfig::manually_accept_inbound_channels`] config flag is set to true. Otherwise
+               /// `user_channel_id` will be randomized for an inbound channel.  This may be zero for objects
+               /// serialized with LDK versions prior to 0.0.113.
                ///
                /// [`ChannelManager::create_channel`]: crate::ln::channelmanager::ChannelManager::create_channel
+               /// [`ChannelManager::accept_inbound_channel`]: crate::ln::channelmanager::ChannelManager::accept_inbound_channel
+               /// [`UserConfig::manually_accept_inbound_channels`]: crate::util::config::UserConfig::manually_accept_inbound_channels
                user_channel_id: u128,
        },
        /// Indicates that we've been offered a payment and it needs to be claimed via calling
@@ -356,9 +360,19 @@ pub enum Event {
        /// Note that if the preimage is not known, you should call
        /// [`ChannelManager::fail_htlc_backwards`] or [`ChannelManager::fail_htlc_backwards_with_reason`]
        /// to free up resources for this HTLC and avoid network congestion.
-       /// If you fail to call either [`ChannelManager::claim_funds`], [`ChannelManager::fail_htlc_backwards`],
-       /// or [`ChannelManager::fail_htlc_backwards_with_reason`] within the HTLC's timeout, the HTLC will be
-       /// automatically failed.
+       ///
+       /// If [`Event::PaymentClaimable::onion_fields`] is `Some`, and includes custom TLVs with even type
+       /// numbers, you should use [`ChannelManager::fail_htlc_backwards_with_reason`] with
+       /// [`FailureCode::InvalidOnionPayload`] if you fail to understand and handle the contents, or
+       /// [`ChannelManager::claim_funds_with_known_custom_tlvs`] upon successful handling.
+       /// If you don't intend to check for custom TLVs, you can simply use
+       /// [`ChannelManager::claim_funds`], which will automatically fail back even custom TLVs.
+       ///
+       /// If you fail to call [`ChannelManager::claim_funds`],
+       /// [`ChannelManager::claim_funds_with_known_custom_tlvs`],
+       /// [`ChannelManager::fail_htlc_backwards`], or
+       /// [`ChannelManager::fail_htlc_backwards_with_reason`] within the HTLC's timeout, the HTLC will
+       /// be automatically failed.
        ///
        /// # Note
        /// LDK will not stop an inbound payment from being paid multiple times, so multiple
@@ -370,6 +384,8 @@ pub enum Event {
        /// This event used to be called `PaymentReceived` in LDK versions 0.0.112 and earlier.
        ///
        /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds
+       /// [`ChannelManager::claim_funds_with_known_custom_tlvs`]: crate::ln::channelmanager::ChannelManager::claim_funds_with_known_custom_tlvs
+       /// [`FailureCode::InvalidOnionPayload`]: crate::ln::channelmanager::FailureCode::InvalidOnionPayload
        /// [`ChannelManager::fail_htlc_backwards`]: crate::ln::channelmanager::ChannelManager::fail_htlc_backwards
        /// [`ChannelManager::fail_htlc_backwards_with_reason`]: crate::ln::channelmanager::ChannelManager::fail_htlc_backwards_with_reason
        PaymentClaimable {
@@ -739,6 +755,13 @@ pub enum Event {
        },
        /// Used to indicate that a previously opened channel with the given `channel_id` is in the
        /// process of closure.
+       ///
+       /// Note that this event is only triggered for accepted channels: if the
+       /// [`UserConfig::manually_accept_inbound_channels`] config flag is set to true and the channel is
+       /// rejected, no `ChannelClosed` event will be sent.
+       ///
+       /// [`ChannelManager::accept_inbound_channel`]: crate::ln::channelmanager::ChannelManager::accept_inbound_channel
+       /// [`UserConfig::manually_accept_inbound_channels`]: crate::util::config::UserConfig::manually_accept_inbound_channels
        ChannelClosed  {
                /// The `channel_id` of the channel which has been closed. Note that on-chain transactions
                /// resolving the channel are likely still awaiting confirmation.
@@ -775,8 +798,9 @@ pub enum Event {
        },
        /// Indicates a request to open a new channel by a peer.
        ///
-       /// To accept the request, call [`ChannelManager::accept_inbound_channel`]. To reject the
-       /// request, call [`ChannelManager::force_close_without_broadcasting_txn`].
+       /// To accept the request, call [`ChannelManager::accept_inbound_channel`]. To reject the request,
+       /// call [`ChannelManager::force_close_without_broadcasting_txn`]. Note that a ['ChannelClosed`]
+       /// event will _not_ be triggered if the channel is rejected.
        ///
        /// The event is only triggered when a new open channel request is received and the
        /// [`UserConfig::manually_accept_inbound_channels`] config flag is set to true.