Merge pull request #3001 from optout21/splicing-feature-bit-with-any

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

diff --git a/lightning/src/events/mod.rs b/lightning/src/events/mod.rs
index 2716532e099a5e318596230fdacf6a0cc88be0aa..e72bc0228fd18fe43319744c550e295c5efa5fe7 100644 (file)
--- a/lightning/src/events/mod.rs
+++ b/lightning/src/events/mod.rs
@@ -53,8 +53,9 @@ pub enum PaymentPurpose {
        /// A payment for a BOLT 11 invoice.
        Bolt11InvoicePayment {
                /// The preimage to the payment_hash, if the payment hash (and secret) were fetched via
-               /// [`ChannelManager::create_inbound_payment`]. If provided, this can be handed directly to
-               /// [`ChannelManager::claim_funds`].
+               /// [`ChannelManager::create_inbound_payment`]. When handling [`Event::PaymentClaimable`],
+               /// this can be passed directly to [`ChannelManager::claim_funds`] to claim the payment. No
+               /// action is needed when seen in [`Event::PaymentClaimed`].
                ///
                /// [`ChannelManager::create_inbound_payment`]: crate::ln::channelmanager::ChannelManager::create_inbound_payment
                /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds
@@ -75,8 +76,9 @@ pub enum PaymentPurpose {
        ///
        /// [`Offer`]: crate::offers::offer::Offer
        Bolt12OfferPayment {
-               /// The preimage to the payment hash. If provided, this can be handed directly to
-               /// [`ChannelManager::claim_funds`].
+               /// The preimage to the payment hash. When handling [`Event::PaymentClaimable`], this can be
+               /// passed directly to [`ChannelManager::claim_funds`], if provided. No action is needed
+               /// when seen in [`Event::PaymentClaimed`].
                ///
                /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds
                payment_preimage: Option<PaymentPreimage>,
@@ -96,8 +98,9 @@ pub enum PaymentPurpose {
        ///
        /// [`Refund`]: crate::offers::refund::Refund
        Bolt12RefundPayment {
-               /// The preimage to the payment hash. If provided, this can be handed directly to
-               /// [`ChannelManager::claim_funds`].
+               /// The preimage to the payment hash. When handling [`Event::PaymentClaimable`], this can be
+               /// passed directly to [`ChannelManager::claim_funds`], if provided. No action is needed
+               /// when seen in [`Event::PaymentClaimed`].
                ///
                /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds
                payment_preimage: Option<PaymentPreimage>,
@@ -883,9 +886,15 @@ pub enum Event {
        },
        /// Used to indicate that an output which you should know how to spend was confirmed on chain
        /// and is now spendable.
-       /// Such an output will *not* ever be spent by rust-lightning, and are not at risk of your
+       ///
+       /// Such an output will *never* be spent directly by LDK, and are not at risk of your
        /// counterparty spending them due to some kind of timeout. Thus, you need to store them
        /// somewhere and spend them when you create on-chain transactions.
+       ///
+       /// You may hand them to the [`OutputSweeper`] utility which will store and (re-)generate spending
+       /// transactions for you.
+       ///
+       /// [`OutputSweeper`]: crate::util::sweep::OutputSweeper
        SpendableOutputs {
                /// The outputs which you should store as spendable by you.
                outputs: Vec<SpendableOutputDescriptor>,
@@ -1003,8 +1012,8 @@ pub enum Event {
                /// The features that this channel will operate with.
                channel_type: ChannelTypeFeatures,
        },
-       /// Used to indicate that a previously opened channel with the given `channel_id` is in the
-       /// process of closure.
+       /// Used to indicate that a channel that got past the initial handshake with the given `channel_id` is in the
+       /// process of closure. This includes previously opened channels, and channels that time out from not being funded.
        ///
        /// 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