Yield BumpHTLCResolution events

Author: wpaulino

lightning/src/chain/channelmonitor.rs

@@ -53,7 +53,7 @@ use crate::util::ser::{Readable, ReadableArgs, MaybeReadable, Writer, Writeable,
 use crate::util::byte_utils;
 use crate::util::events::Event;
 #[cfg(anchors)]
-use crate::util::events::{AnchorDescriptor, BumpTransactionEvent};
+use crate::util::events::{AnchorDescriptor, HTLCDescriptor, BumpTransactionEvent};
 
 use crate::prelude::*;
 use core::{cmp, mem};
@@ -2378,7 +2378,28 @@ impl<Signer: Sign> ChannelMonitorImpl<Signer> {
 						pending_htlcs,
 					}));
 				},
-				_ => {},
+				ClaimEvent::BumpHTLC {
+					target_feerate_sat_per_1000_weight, tx_template, htlcs,
+				} => {
+					let mut htlc_descriptors = Vec::with_capacity(htlcs.len());
+					for htlc in htlcs {
+						htlc_descriptors.push(HTLCDescriptor {
+							channel_keys_id: self.channel_keys_id,
+							channel_value_satoshis: self.channel_value_satoshis,
+							per_commitment_number: htlc.per_commitment_number,
+							htlc: htlc.htlc,
+							preimage: htlc.preimage,
+							counterparty_base_htlc_key: htlc.counterparty_base_htlc_key,
+							counterparty_base_revocation_key: htlc.counterparty_base_revocation_key,
+							counterparty_sig: htlc.counterparty_sig,
+						});
+					}
+					ret.push(Event::BumpTransaction(BumpTransactionEvent::HTLCResolution {
+						target_feerate_sat_per_1000_weight,
+						tx_template,
+						htlc_descriptors,
+					}));
+				}
 			}
 		}
 		ret

lightning/src/util/events.rs

@@ -34,6 +34,8 @@ use bitcoin::blockdata::script::Script;
 use bitcoin::hashes::Hash;
 use bitcoin::hashes::sha256::Hash as Sha256;
 use bitcoin::secp256k1::PublicKey;
+#[cfg(anchors)]
+use bitcoin::secp256k1::ecdsa::Signature;
 use crate::io;
 use crate::prelude::*;
 use core::time::Duration;
@@ -228,6 +230,37 @@ pub struct AnchorDescriptor {
 	pub outpoint: OutPoint,
 }
 
+#[cfg(anchors)]
+/// A descriptor used to sign for a commitment transaction's HTLC output.
+#[derive(Clone, Debug)]
+pub struct HTLCDescriptor {
+	/// A unique identifier used along with `channel_value_satoshis` to re-derive the
+	/// [`InMemorySigner`] required to sign `input`.
+	///
+	/// [`InMemorySigner`]: crate::chain::keysinterface::InMemorySigner
+	pub channel_keys_id: [u8; 32],
+	/// The value in satoshis of the channel we're attempting to spend the anchor output of. This is
+	/// used along with `channel_keys_id` to re-derive the [`InMemorySigner`] required to sign
+	/// `input`.
+	///
+	/// [`InMemorySigner`]: crate::chain::keysinterface::InMemorySigner
+	pub channel_value_satoshis: u64,
+	/// The number of the commitment transaction in which the HTLC output lives.
+	pub per_commitment_number: u64,
+	/// The details of the HTLC as it appears in a commitment transaction.
+	pub htlc: HTLCOutputInCommitment,
+	/// The preimage, if one exists, to claim the HTLC output with.
+	pub preimage: Option<PaymentPreimage>,
+	/// The counterparty's base HTLC key of the channel. This is required to reconstruct the HTLC
+	/// output's witness script.
+	pub counterparty_base_htlc_key: PublicKey,
+	/// The counterparty's base revocation key of the channel. This is required to reconstruct the
+	/// HTLC output's witness script.
+	pub counterparty_base_revocation_key: PublicKey,
+	/// The counterparty's signature required to spend the HTLC output.
+	pub counterparty_sig: Signature
+}
+
 #[cfg(anchors)]
 /// Represents the different types of transactions, originating from LDK, to be bumped.
 #[derive(Clone, Debug)]
@@ -247,7 +280,10 @@ pub enum BumpTransactionEvent {
 	/// The consumer should be able to sign for any of the additional inputs included within the
 	/// child anchor transaction. To sign its anchor input, an [`InMemorySigner`] should be
 	/// re-derived through [`KeysManager::derive_channel_keys`] with the help of
-	/// [`AnchorDescriptor::channel_keys_id`] and [`AnchorDescriptor::channel_value_satoshis`].
+	/// [`AnchorDescriptor::channel_keys_id`] and [`AnchorDescriptor::channel_value_satoshis`]. The
+	/// anchor input signature can be computed with [`InMemorySigner::sign_holder_anchor_input`],
+	/// which can then be provided to [`build_anchor_input_witness`] along with the `funding_pubkey`
+	/// to obtain the full witness required to spend.
 	///
 	/// It is possible to receive more than one instance of this event if a valid child anchor
 	/// transaction is never broadcast or is but not with a sufficient fee to be mined. Care should
@@ -268,6 +304,8 @@ pub enum BumpTransactionEvent {
 	///
 	/// [`InMemorySigner`]: crate::chain::keysinterface::InMemorySigner
 	/// [`KeysManager::derive_channel_keys`]: crate::chain::keysinterface::KeysManager::derive_channel_keys
+	/// [`InMemorySigner::sign_holder_anchor_input`]: crate::chain::keysinterface::InMemorySigner::sign_holder_anchor_input
+	/// [`build_anchor_input_witness`]: crate::ln::chan_utils::build_anchor_input_witness
 	ChannelClose {
 		/// The target feerate that the transaction package, which consists of the commitment
 		/// transaction and the to-be-crafted child anchor transaction, must meet.
@@ -286,6 +324,40 @@ pub enum BumpTransactionEvent {
 		/// commitment transaction confirms.
 		pending_htlcs: Vec<HTLCOutputInCommitment>,
 	},
+	/// Indicates that a channel featuring anchor outputs has HTLC(s) that need to be resolved
+	/// onchain. With the zero-HTLC-transaction-fee variant of anchor outputs, the pre-signed HTLC
+	/// transactions have a zero fee, thus requiring additional inputs and/or outputs to be attached
+	/// for a timely confirmation within the chain. These additional inputs and/or outputs must be
+	/// appended to the enclosed `tx_template` to meet the target feerate. Failure to meet the
+	/// target feerate decreases the confirmation odds of the transaction, possibly resulting in a
+	/// loss of funds. Once the transaction is amended to meet the target feerate, it must be signed
+	/// for and broadcast by the consumer of the event.
+	///
+	/// The consumer should be able to sign for any of the additional inputs added to `tx_template`.
+	/// To sign HTLC inputs, an [`InMemorySigner`] should be re-derived through
+	/// [`KeysManager::derive_channel_keys`] with the help of `channel_keys_id` and
+	/// `channel_value_satoshis`. Each HTLC input's signature can be computed with
+	/// [`InMemorySigner::sign_holder_htlc_transaction`], which can then be provided to
+	/// [`build_htlc_input_witness`] along with the enclosed [`HTLCDescriptor`] to obtain the full
+	/// witness required to spend.
+	///
+	/// It is possible to receive more than one instance of this event if a valid HTLC transaction
+	/// is never broadcast or is but not with a sufficient fee to be mined. Care should be taken by
+	/// the consumer of the event to ensure any future iterations of the HTLC transaction adhere to
+	/// the [Replace-By-Fee rules](https://github.com/bitcoin/bitcoin/blob/master/doc/policy/mempool-replacements.md)
+	/// for fee bumps to be accepted into the mempool, and eventually the chain. As the frequency of
+	/// these events is not user-controlled, users may ignore/drop the event if they are no longer
+	/// able to commit external confirmed funds to the HTLC transaction.
+	///
+	/// [`InMemorySigner`]: crate::chain::keysinterface::InMemorySigner
+	/// [`KeysManager::derive_channel_keys`]: crate::chain::keysinterface::KeysManager::derive_channel_keys
+	/// [`InMemorySigner::sign_holder_htlc_transaction`]: crate::chain::keysinterface::InMemorySigner::sign_holder_htlc_transaction
+	/// [`build_htlc_input_witness`]: crate::ln::chan_utils::build_htlc_input_witness
+	HTLCResolution {
+		target_feerate_sat_per_1000_weight: u32,
+		tx_template: Transaction,
+		htlc_descriptors: Vec<HTLCDescriptor>,
+	},
 }
 
 /// An Event which you should probably take some action in response to.
@@ -890,9 +962,10 @@ impl Writeable for Event {
 			&Event::BumpTransaction(ref event)=> {
 				27u8.write(writer)?;
 				match event {
-					// We never write the ChannelClose events as they'll be replayed upon restarting
-					// anyway if the commitment transaction remains unconfirmed.
+					// We never write the ChannelClose|HTLCResolution events as they'll be replayed
+					// upon restarting anyway if they remain unresolved.
 					BumpTransactionEvent::ChannelClose { .. } => {}
+					BumpTransactionEvent::HTLCResolution { .. } => {}
 				}
 			}
 			&Event::ChannelReady { ref channel_id, ref user_channel_id, ref counterparty_node_id, ref channel_type } => {