Yield BumpHTLCResolution events

Author: wpaulino

lightning/src/chain/channelmonitor.rs

@@ -44,7 +44,7 @@ use crate::chain::chaininterface::{BroadcasterInterface, FeeEstimator, LowerBoun
 use crate::chain::transaction::{OutPoint, TransactionData};
 use crate::chain::keysinterface::{SpendableOutputDescriptor, StaticPaymentOutputDescriptor, DelayedPaymentOutputDescriptor, Sign, KeysInterface};
 #[cfg(anchors)]
-use crate::chain::onchaintx::ClaimEvent;
+use crate::chain::onchaintx::{ClaimEvent, ExternalHTLCClaim};
 use crate::chain::onchaintx::OnchainTxHandler;
 use crate::chain::package::{CounterpartyOfferedHTLCOutput, CounterpartyReceivedHTLCOutput, HolderFundingOutput, HolderHTLCOutput, PackageSolvingData, PackageTemplate, RevokedOutput, RevokedHTLCOutput};
 use crate::chain::Filter;
@@ -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};
@@ -2371,7 +2371,31 @@ 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 {
+						match htlc {
+							ExternalHTLCClaim::SecondStage {
+								amount, per_commitment_number, redeem_script, preimage, counterparty_sig
+							} => htlc_descriptors.push(HTLCDescriptor::SecondStage {
+								channel_keys_id: self.channel_keys_id,
+								channel_value_satoshis: self.channel_value_satoshis,
+								amount,
+								per_commitment_number,
+								redeem_script,
+								preimage,
+								counterparty_sig,
+							}),
+						}
+					}
+					ret.push(Event::BumpTransaction(BumpTransactionEvent::HTLCResolution {
+						target_feerate_sat_per_1000_weight,
+						tx_template,
+						htlc_descriptors,
+					}));
+				}
 			}
 		}
 		ret

lightning/src/util/events.rs

@@ -31,6 +31,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;
@@ -244,7 +246,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
@@ -265,6 +270,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.
@@ -283,6 +290,55 @@ 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. Consumers must ensure the
+	/// order of pre-existing inputs and outputs within `tx_template` are not changed, as it is
+	/// crucial to the validity of the transaction itself. Failure to meet the target feerate
+	/// decreases the confirmation odds of the transaction, possinly 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
+	/// `AnchorDescriptor::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>,
+	},
+}
+
+#[derive(Clone, Debug)]
+pub enum HTLCDescriptor {
+	SecondStage {
+		channel_keys_id: [u8; 32],
+		channel_value_satoshis: u64,
+		amount: u64,
+		per_commitment_number: u64,
+		redeem_script: Script,
+		preimage: Option<PaymentPreimage>,
+		counterparty_sig: Signature
+	}
 }
 
 /// An Event which you should probably take some action in response to.
@@ -853,9 +909,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 { .. } => {}
 				}
 			}
 			// Note that, going forward, all new events must only write data inside of