Add BumpTransaction event handler

This allows users to bump their commitments and HTLC transactions
without having to worry about all the little details to do so. Instead,
we'll just require that they implement the `CoinSelectionSource` trait
over their wallet/UTXO source, granting the event handler permission to
spend confirmed UTXOs for the transactions it'll produce.

While the event handler should in most cases produce valid transactions,
assuming the provided confirmed UTXOs are valid, it may not produce
relayable transactions due to not satisfying certain Replace-By-Fee
(RBF) mempool policy requirements. Some of these require that the
replacement transactions have a higher feerate and absolute fee than the
conflicting transactions it aims to replace. To make sure we adhere to
these requirements, we'd have to persist some state for all transactions
the event handler has produced, greatly increasing its complexity. While
we may consider implementing so in the future, we choose to go with a
simple initial version that relies on the OnchainTxHandler's bumping
frequency. For each new bumping attempt, the OnchainTxHandler proposes a
25% feerate increase to ensure transactions can propagate under
constrained mempool circumstances.

Author: wpaulino

lightning/src/events/bump_transaction.rs

@@ -9,12 +9,26 @@
 
 //! Utitilies for bumping transactions originating from [`super::Event`]s.
 
+use core::convert::TryInto;
+use core::ops::Deref;
+
+use crate::chain::chaininterface::BroadcasterInterface;
 use crate::chain::ClaimId;
+use crate::sign::{ChannelSigner, EcdsaChannelSigner, SignerProvider};
+use crate::io_extras::sink;
 use crate::ln::PaymentPreimage;
 use crate::ln::chan_utils;
-use crate::ln::chan_utils::{ChannelTransactionParameters, HTLCOutputInCommitment};
+use crate::ln::chan_utils::{
+	ANCHOR_INPUT_WITNESS_WEIGHT, HTLC_SUCCESS_INPUT_ANCHOR_WITNESS_WEIGHT,
+	HTLC_TIMEOUT_INPUT_ANCHOR_WITNESS_WEIGHT, ChannelTransactionParameters, HTLCOutputInCommitment
+};
+use crate::events::Event;
+use crate::prelude::HashMap;
+use crate::util::logger::Logger;
 
-use bitcoin::{OutPoint, PackedLockTime, Script, Transaction, Txid, TxIn, TxOut, Witness};
+use bitcoin::{OutPoint, PackedLockTime, Sequence, Script, Transaction, Txid, TxIn, TxOut, Witness};
+use bitcoin::blockdata::constants::WITNESS_SCALE_FACTOR;
+use bitcoin::consensus::Encodable;
 use bitcoin::secp256k1;
 use bitcoin::secp256k1::{PublicKey, Secp256k1};
 use bitcoin::secp256k1::ecdsa::Signature;
@@ -252,3 +266,338 @@ pub enum BumpTransactionEvent {
 		tx_lock_time: PackedLockTime,
 	},
 }
+
+/// An input that must be included in a transaction when performing coin selection through
+/// [`CoinSelectionSource::select_confirmed_utxos`].
+pub struct Input {
+	/// The unique identifier of the input.
+	pub outpoint: OutPoint,
+	/// The upper-bound weight consumed by the input's full witness required to satisfy its
+	/// corresponding output's script.
+	pub witness_weight: u64,
+}
+
+/// An unspent transaction output that is available to spend resulting from a successful
+/// [`CoinSelection`] attempt.
+#[derive(Clone, Debug)]
+pub struct Utxo {
+	/// The unique identifier of the output.
+	pub outpoint: OutPoint,
+	/// The output to spend.
+	pub output: TxOut,
+	/// The upper-bound weight consumed by the corresponding input's full witness required to
+	/// satisfy the output's script.
+	pub witness_weight: u64,
+}
+
+/// The result of a successful coin selection attempt for a transaction requiring additional UTXOs
+/// to cover its fees.
+pub struct CoinSelection {
+	/// The set of UTXOs (with at least 1 confirmation) to spend and use within a transaction
+	/// requiring additional fees.
+	confirmed_utxos: Vec<Utxo>,
+	/// An additional output tracking whether any change remained after coin selection. This output
+	/// should always have a value above dust for its given `script_pubkey`. Its `script_pubkey`
+	/// should be solely controlled by the same entity from which the `confirmed_utxos` were
+	/// sourced. It should not be spent until the transaction it belongs to confirms to ensure
+	/// mempool descendant limits are not met.
+	change_output: Option<TxOut>,
+}
+
+/// An abstraction over a bitcoin wallet that can perform coin selection over a set of UTXOs and can
+/// sign for them. The coin selection method aims to mimic Bitcoin Core's `fundrawtransaction` RPC,
+/// which most wallets should be able to satisfy.
+pub trait CoinSelectionSource {
+	/// Performs coin selection of a set of UTXOs, with at least 1 confirmation each, that are
+	/// available to spend. Implementations are free to pick their coin selection algorithm of
+	/// choice, as long as the following requirements are met:
+	///
+	/// 1. `must_spend` contains a set of [`Input`]s that must be included in the transaction
+	///    throughout coin selection.
+	/// 2. `must_pay_to` contains a set of [`TxOut`]s that must be included in the transaction
+	///    throughout coin selection. In some cases, like when funding an anchor transaction, this
+	///    set is empty. Implementations should ensure they handle this correctly on their end,
+	///    e.g., Bitcoin Core's `fundrawtransaction` RPC requires at least one output to be
+	///    provided, in which case a zero-value empty OP_RETURN output can be used instead.
+	/// 3. Enough inputs must be selected/contributed for the resulting transaction (including the
+	///    inputs and outputs noted above) to meet `target_feerate_sat_per_1000_weight`.
+	///
+	/// Implementations must take note that [`Input::witness_weight`] only tracks the weight of the
+	/// input's witness. Some wallets, like Bitcoin Core's, may require providing the full input
+	/// weight. Failing to do so may lead to underestimating fee bumps and delaying block inclusion.
+	///
+	/// The `claim_id` uniquely identifies a claim, and should be used to assign a set of UTXOs to
+	/// the claim, such that they can be re-used within new fee-bumped iterations of the original
+	/// claiming transaction, ensuring that claims don't double spend each other. If a specific
+	/// `claim_id` has never had a transaction associated with it, and all of the available UTXOs
+	/// have already been assigned to other claims, implementations must be willing to double spend
+	/// their UTXOs.
+	///
+	/// The choice of which UTXOs to double spend is left to the implementor. Some example
+	/// heuristics to free UTXOs include:
+	///
+	/// - Freeing the UTXOs of the lowest value claim after fees at the current feerate.
+	/// - Freeing the UTXOs of the HTLC claim, if any, with the nearest expiration.
+	fn select_confirmed_utxos(
+		&self, claim_id: ClaimId, must_spend: &[Input], must_pay_to: &[TxOut],
+		target_feerate_sat_per_1000_weight: u32,
+	) -> Result<CoinSelection, ()>;
+	/// Signs and provides the full witness for all inputs within the transaction known to the
+	/// trait (i.e., any provided via [`CoinSelectionSource::select_confirmed_utxos`]).
+	fn sign_tx(&self, tx: &mut Transaction) -> Result<(), ()>;
+}
+
+/// A handler for [`Event::BumpTransaction`] events that sources confirmed UTXOs from a
+/// [`CoinSelectionSource`] to fee bump transactions via Child-Pays-For-Parent (CPFP) or
+/// Replace-By-Fee (RBF).
+pub struct BumpTransactionEventHandler<B: Deref, C: Deref, SP: Deref, L: Deref>
+where
+	B::Target: BroadcasterInterface,
+	C::Target: CoinSelectionSource,
+	SP::Target: SignerProvider,
+	L::Target: Logger,
+{
+	broadcaster: B,
+	utxo_source: C,
+	signer_provider: SP,
+	logger: L,
+	secp: Secp256k1<secp256k1::All>,
+}
+
+impl<B: Deref, C: Deref, SP: Deref, L: Deref> BumpTransactionEventHandler<B, C, SP, L>
+where
+	B::Target: BroadcasterInterface,
+	C::Target: CoinSelectionSource,
+	SP::Target: SignerProvider,
+	L::Target: Logger,
+{
+	/// Returns a new instance capable of handling [`Event::BumpTransaction`] events.
+	pub fn new(broadcaster: B, utxo_source: C, signer_provider: SP, logger: L) -> Self {
+		Self {
+			broadcaster,
+			utxo_source,
+			signer_provider,
+			logger,
+			secp: Secp256k1::new(),
+		}
+	}
+
+	/// Updates a transaction with the result of a successful coin selection attempt.
+	fn process_coin_selection(
+		&self, tx: &mut Transaction, mut coin_selection: CoinSelection,
+		mut override_change_output: Option<impl FnOnce(&mut Transaction, &mut CoinSelection)>,
+	) {
+		for utxo in coin_selection.confirmed_utxos.drain(..) {
+			tx.input.push(TxIn {
+				previous_output: utxo.outpoint,
+				script_sig: Script::new(),
+				sequence: Sequence::ZERO,
+				witness: Witness::new(),
+			});
+		}
+		if let Some(override_change_output) = override_change_output.take() {
+			override_change_output(tx, &mut coin_selection)
+		} else if let Some(change_output) = coin_selection.change_output.take() {
+			tx.output.push(change_output);
+		}
+	}
+
+	/// Returns an unsigned transaction spending an anchor output of the commitment transaction, and
+	/// any additional UTXOs sourced, to bump the commitment transaction's fee.
+	fn build_anchor_tx(
+		&self, claim_id: ClaimId, target_feerate_sat_per_1000_weight: u32,
+		commitment_tx: &Transaction, anchor_descriptor: &AnchorDescriptor,
+	) -> Result<Transaction, ()> {
+		let must_spend = vec![Input {
+			outpoint: anchor_descriptor.outpoint,
+			witness_weight: commitment_tx.weight() as u64 + ANCHOR_INPUT_WITNESS_WEIGHT,
+		}];
+		let coin_selection = self.utxo_source.select_confirmed_utxos(
+			claim_id, &must_spend, &[], target_feerate_sat_per_1000_weight,
+		)?;
+		let override_change_output = |tx: &mut Transaction, coin_selection: &mut CoinSelection| {
+			if let Some(change_output) = coin_selection.change_output.take() {
+				tx.output.push(change_output);
+			} else {
+				// We weren't provided a change output, likely because the input set was a perfect
+				// match, but we still need to have at least one output in the transaction for it to
+				// be considered standard. We choose to go with an empty OP_RETURN as it is the
+				// cheapest way to include a dummy output.
+				tx.output.push(TxOut {
+					value: 0,
+					script_pubkey: Script::new_op_return(&[]),
+				});
+			}
+		};
+
+		let mut tx = Transaction {
+			version: 2,
+			lock_time: PackedLockTime::ZERO, // TODO: Use next best height.
+			input: vec![TxIn {
+				previous_output: anchor_descriptor.outpoint,
+				script_sig: Script::new(),
+				sequence: Sequence::ZERO,
+				witness: Witness::new(),
+			}],
+			output: vec![],
+		};
+		self.process_coin_selection(&mut tx, coin_selection, Some(override_change_output));
+		Ok(tx)
+	}
+
+	/// Handles a [`BumpTransactionEvent::ChannelClose`] event variant by producing a fully-signed
+	/// transaction spending an anchor output of the commitment transaction to bump its fee and
+	/// broadcasts them to the network as a package.
+	fn handle_channel_close(
+		&self, claim_id: ClaimId, package_target_feerate_sat_per_1000_weight: u32,
+		commitment_tx: &Transaction, commitment_tx_fee_sat: u64, anchor_descriptor: &AnchorDescriptor,
+	) -> Result<(), ()> {
+		// Compute the feerate the anchor transaction must meet to meet the overall feerate for the
+		// package (commitment + anchor transactions).
+		let commitment_tx_feerate: u32 = (commitment_tx_fee_sat * 1000 / commitment_tx.weight() as u64)
+			.try_into().unwrap_or(u32::max_value());
+		let feerate_diff = package_target_feerate_sat_per_1000_weight.saturating_sub(commitment_tx_feerate);
+		if feerate_diff == 0 {
+			// If the commitment transaction already has a feerate high enough on its own, broadcast
+			// it as is without a child.
+			self.broadcaster.broadcast_transactions(&[&commitment_tx]);
+			return Ok(());
+		}
+
+		// TODO: Use the one in `crate::chain::chaininterface` once it's correct.
+		const MIN_RELAY_FEERATE: u32 = bitcoin::policy::DEFAULT_MIN_RELAY_TX_FEE /
+			WITNESS_SCALE_FACTOR as u32;
+		let target_anchor_tx_feerate = if feerate_diff < MIN_RELAY_FEERATE {
+			// Transactions generally won't propagate if the minimum feerate is not met, so use it
+			// as a lower bound.
+			MIN_RELAY_FEERATE
+		} else {
+			feerate_diff
+		};
+		let mut anchor_tx = self.build_anchor_tx(
+			claim_id, target_anchor_tx_feerate, commitment_tx, anchor_descriptor,
+		)?;
+
+		debug_assert_eq!(anchor_tx.output.len(), 1);
+		self.utxo_source.sign_tx(&mut anchor_tx)?;
+		let signer = self.signer_provider.derive_channel_signer(
+			anchor_descriptor.channel_value_satoshis, anchor_descriptor.channel_keys_id,
+		);
+		let anchor_sig = signer.sign_holder_anchor_input(&anchor_tx, 0, &self.secp)?;
+		anchor_tx.input[0].witness =
+			chan_utils::build_anchor_input_witness(&signer.pubkeys().funding_pubkey, &anchor_sig);
+
+		self.broadcaster.broadcast_transactions(&[&commitment_tx, &anchor_tx]);
+		Ok(())
+	}
+
+	/// Returns an unsigned, fee-bumped HTLC transaction, along with the set of signers required to
+	/// fulfill the witness for each HTLC input within it.
+	fn build_htlc_tx(
+		&self, claim_id: ClaimId, target_feerate_sat_per_1000_weight: u32,
+		htlc_descriptors: &[HTLCDescriptor], tx_lock_time: PackedLockTime,
+	) -> Result<(Transaction, HashMap<[u8; 32], <SP::Target as SignerProvider>::Signer>), ()> {
+		let mut tx = Transaction {
+			version: 2,
+			lock_time: tx_lock_time,
+			input: vec![],
+			output: vec![],
+		};
+		// Unfortunately, we need to derive the signer for each HTLC ahead of time to obtain its
+		// input.
+		let mut signers = HashMap::new();
+		let mut must_spend = Vec::with_capacity(htlc_descriptors.len());
+		for htlc_descriptor in htlc_descriptors {
+			let signer = signers.entry(htlc_descriptor.channel_keys_id)
+				.or_insert_with(||
+					self.signer_provider.derive_channel_signer(
+						htlc_descriptor.channel_value_satoshis, htlc_descriptor.channel_keys_id,
+					)
+				);
+			let per_commitment_point = signer.get_per_commitment_point(
+				htlc_descriptor.per_commitment_number, &self.secp
+			);
+
+			let htlc_input = htlc_descriptor.unsigned_tx_input();
+			must_spend.push(Input {
+				outpoint: htlc_input.previous_output.clone(),
+				witness_weight: if htlc_descriptor.preimage.is_some() {
+					HTLC_SUCCESS_INPUT_ANCHOR_WITNESS_WEIGHT
+				} else {
+					HTLC_TIMEOUT_INPUT_ANCHOR_WITNESS_WEIGHT
+				},
+			});
+			tx.input.push(htlc_input);
+			let htlc_output = htlc_descriptor.tx_output(&per_commitment_point, &self.secp);
+			tx.output.push(htlc_output);
+		}
+
+		let coin_selection = self.utxo_source.select_confirmed_utxos(
+			claim_id, &must_spend, &tx.output, target_feerate_sat_per_1000_weight,
+		)?;
+		self.process_coin_selection(
+			&mut tx, coin_selection, None::<fn(&mut Transaction, &mut CoinSelection)>
+		);
+		Ok((tx, signers))
+	}
+
+	/// Handles a [`BumpTransactionEvent::HTLCResolution`] event variant by producing a
+	/// fully-signed, fee-bumped HTLC transaction that is broadcast to the network.
+	fn handle_htlc_resolution(
+		&self, claim_id: ClaimId, target_feerate_sat_per_1000_weight: u32,
+		htlc_descriptors: &[HTLCDescriptor], tx_lock_time: PackedLockTime,
+	) -> Result<(), ()> {
+		let (mut htlc_tx, signers) = self.build_htlc_tx(
+			claim_id, target_feerate_sat_per_1000_weight, htlc_descriptors, tx_lock_time,
+		)?;
+
+		self.utxo_source.sign_tx(&mut htlc_tx)?;
+		for (idx, htlc_descriptor) in htlc_descriptors.iter().enumerate() {
+			let signer = signers.get(&htlc_descriptor.channel_keys_id).unwrap();
+			let htlc_sig = signer.sign_holder_htlc_transaction(
+				&htlc_tx, idx, htlc_descriptor, &self.secp
+			)?;
+			let per_commitment_point = signer.get_per_commitment_point(
+				htlc_descriptor.per_commitment_number, &self.secp
+			);
+			let witness_script = htlc_descriptor.witness_script(&per_commitment_point, &self.secp);
+			htlc_tx.input[idx].witness = htlc_descriptor.tx_input_witness(&htlc_sig, &witness_script);
+		}
+
+		self.broadcaster.broadcast_transactions(&[&htlc_tx]);
+		Ok(())
+	}
+
+	/// Handles all variants of [`BumpTransactionEvent`], immediately returning otherwise.
+	pub fn handle_event(&self, event: &Event) {
+		let event = if let Event::BumpTransaction(event) = event {
+			event
+		} else {
+			return;
+		};
+		match event {
+			BumpTransactionEvent::ChannelClose {
+				claim_id, package_target_feerate_sat_per_1000_weight, commitment_tx,
+				anchor_descriptor, commitment_tx_fee_satoshis,	..
+			} => {
+				if let Err(_) = self.handle_channel_close(
+					*claim_id, *package_target_feerate_sat_per_1000_weight, commitment_tx,
+					*commitment_tx_fee_satoshis, anchor_descriptor,
+				) {
+					log_error!(self.logger, "Failed bumping commitment transaction fee for {}",
+						commitment_tx.txid());
+				}
+			}
+			BumpTransactionEvent::HTLCResolution {
+				claim_id, target_feerate_sat_per_1000_weight, htlc_descriptors, tx_lock_time,
+			} => {
+				if let Err(_) = self.handle_htlc_resolution(
+					*claim_id, *target_feerate_sat_per_1000_weight, htlc_descriptors, *tx_lock_time,
+				) {
+					log_error!(self.logger, "Failed bumping HTLC transaction fee for commitment {}",
+						htlc_descriptors[0].commitment_txid);
+				}
+			}
+		}
+	}
+}

lightning/src/events/mod.rs

@@ -33,8 +33,6 @@ use crate::util::string::UntrustedString;
 use crate::routing::router::{BlindedTail, Path, RouteHop, RouteParameters};
 
 use bitcoin::{PackedLockTime, Transaction, OutPoint};
-#[cfg(anchors)]
-use bitcoin::{Txid, TxIn, TxOut, Witness};
 use bitcoin::blockdata::script::Script;
 use bitcoin::hashes::Hash;
 use bitcoin::hashes::sha256::Hash as Sha256;

lightning/src/ln/chan_utils.rs

@@ -57,6 +57,15 @@ pub(crate) const MIN_ACCEPTED_HTLC_SCRIPT_WEIGHT: usize = 136;
 /// This is the maximum post-anchor value.
 pub const MAX_ACCEPTED_HTLC_SCRIPT_WEIGHT: usize = 143;
 
+/// The upper bound weight of an anchor input.
+pub const ANCHOR_INPUT_WITNESS_WEIGHT: u64 = 116;
+/// The upper bound weight of an HTLC timeout input from a commitment transaction with anchor
+/// outputs.
+pub const HTLC_TIMEOUT_INPUT_ANCHOR_WITNESS_WEIGHT: u64 = 288;
+/// The upper bound weight of an HTLC success input from a commitment transaction with anchor
+/// outputs.
+pub const HTLC_SUCCESS_INPUT_ANCHOR_WITNESS_WEIGHT: u64 = 327;
+
 /// Gets the weight for an HTLC-Success transaction.
 #[inline]
 pub fn htlc_success_tx_weight(opt_anchors: bool) -> u64 {