Time out incoming HTLCs when we reach cltv_expiry (+ test)

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

diff --git a/lightning/src/util/events.rs b/lightning/src/util/events.rs
index e810368dbc3a5b0066998fef1de3d4ef1f3e894c..b3e85bad069bca8737d5dae690d7927a5f2960dd 100644 (file)
--- a/lightning/src/util/events.rs
+++ b/lightning/src/util/events.rs
@@ -57,9 +57,22 @@ pub enum Event {
        /// ChannelManager::fail_htlc_backwards to free up resources for this HTLC.
        /// The amount paid should be considered 'incorrect' when it is less than or more than twice
        /// the amount expected.
+       /// If you fail to call either ChannelManager::claim_funds of
+       /// ChannelManager::fail_htlc_backwards within the HTLC's timeout, the HTLC will be
+       /// automatically failed with PaymentFailReason::PreimageUnknown.
        PaymentReceived {
                /// The hash for which the preimage should be handed to the ChannelManager.
                payment_hash: PaymentHash,
+               /// The "payment secret". This authenticates the sender to the recipient, preventing a
+               /// number of deanonymization attacks during the routing process.
+               /// As nodes upgrade, the invoices you provide should likely migrate to setting the
+               /// var_onion_optin feature to required, at which point you should fail_backwards any HTLCs
+               /// which have a None here.
+               /// Until then, however, values of None should be ignored, and only incorrect Some values
+               /// should result in an HTLC fail_backwards.
+               /// Note that, in any case, this value must be passed as-is to any fail or claim calls as
+               /// the HTLC index includes this value.
+               payment_secret: Option<[u8; 32]>,
                /// The value, in thousandths of a satoshi, that this payment is for. Note that you must
                /// compare this to the expected value before accepting the payment (as otherwise you are
                /// providing proof-of-payment for less than the value you expected!).
@@ -99,8 +112,9 @@ pub enum Event {
                time_forwardable: Duration,
        },
        /// Used to indicate that an output was generated on-chain which you should know how to spend.
-       /// Such an output will *not* ever be spent by rust-lightning, so you need to store them
-       /// somewhere and spend them when you create on-chain spends.
+       /// Such an output will *not* ever be spent by rust-lightning, 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.
        SpendableOutputs {
                /// The outputs which you should store as spendable by you.
                outputs: Vec<SpendableOutputDescriptor>,
@@ -194,12 +208,20 @@ pub enum MessageSendEvent {
        },
        /// Used to indicate that a channel_announcement and channel_update should be broadcast to all
        /// peers (except the peer with node_id either msg.contents.node_id_1 or msg.contents.node_id_2).
+       ///
+       /// Note that after doing so, you very likely (unless you did so very recently) want to call
+       /// ChannelManager::broadcast_node_announcement to trigger a BroadcastNodeAnnouncement event.
        BroadcastChannelAnnouncement {
                /// The channel_announcement which should be sent.
                msg: msgs::ChannelAnnouncement,
                /// The followup channel_update which should be sent.
                update_msg: msgs::ChannelUpdate,
        },
+       /// Used to indicate that a node_announcement should be broadcast to all peers.
+       BroadcastNodeAnnouncement {
+               /// The node_announcement which should be sent.
+               msg: msgs::NodeAnnouncement,
+       },
        /// Used to indicate that a channel_update should be broadcast to all peers.
        BroadcastChannelUpdate {
                /// The channel_update which should be sent.