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,350 @@ 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`.
+	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.
+	/// 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, e.g., an
+	/// implementation could choose to re-assign the UTXOs assigned to the lowest value claim.
+	fn select_confirmed_utxos(
+		&self, claim_id: ClaimId, must_spend: Vec<Input>, must_pay_to: Vec<TxOut>,
+		target_feerate_sat_per_1000_weight: u32,
+	) -> Result<CoinSelection, ()>;
+	/// Returns a script to use for change above dust resulting from a successful coin selection
+	/// attempt.
+	fn change_script(&self) -> Result<Script, ()>;
+	/// 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, ()> {
+		// Most wallets that support funding a transaction also require an output, e.g. see
+		// bitcoind's `fundrawtransaction`. Since we're just interested in spending the anchor
+		// input, without caring where the change goes, we use an output just above dust backed by
+		// the wallet's change script. If the wallet ends up producing its own change output when
+		// funding the transaction, we'll join them into one, saving the user a few satoshis.
+		//
+		// TODO: Cache `change_script` to prevent address inflation? It depends on whether the
+		// implementation is providing a fresh address on every invocation.
+		let change_script = self.utxo_source.change_script()?;
+		let dust_change_output = TxOut {
+			value: change_script.dust_value().to_sat(),
+			script_pubkey: change_script,
+		};
+
+		let must_spend = vec![Input {
+			outpoint: anchor_descriptor.outpoint,
+			witness_weight: commitment_tx.weight() as u64 + ANCHOR_INPUT_WITNESS_WEIGHT,
+		}];
+		let must_pay_to = vec![dust_change_output.clone()];
+		let coin_selection = self.utxo_source.select_confirmed_utxos(
+			claim_id, must_spend, must_pay_to, target_feerate_sat_per_1000_weight,
+		)?;
+		let override_change_output = |tx: &mut Transaction, coin_selection: &mut CoinSelection| {
+			if let Some(mut change_output) = coin_selection.change_output.take() {
+				// Replace the change output we initially added to `must_spend` with the one given
+				// to us by the user.
+				let dust_change_output_weight = dust_change_output.consensus_encode(&mut sink())
+					.unwrap() as u64;
+				let dust_change_output_fee = dust_change_output_weight *
+					target_feerate_sat_per_1000_weight as u64;
+				change_output.value += dust_change_output_fee + dust_change_output.value;
+				tx.output.push(change_output);
+			} else {
+				tx.output.push(dust_change_output);
+			}
+		};
+
+		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_transaction(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);
+
+		// TODO: Broadcast as transaction package once supported.
+		self.broadcaster.broadcast_transaction(commitment_tx);
+		self.broadcaster.broadcast_transaction(&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();
+		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
+			);
+			tx.input.push(htlc_descriptor.unsigned_tx_input());
+			let htlc_output = htlc_descriptor.tx_output(&per_commitment_point, &self.secp);
+			tx.output.push(htlc_output);
+		}
+
+		let must_spend = htlc_descriptors.iter().map(|htlc_descriptor| Input {
+			outpoint: OutPoint {
+				txid: htlc_descriptor.commitment_txid,
+				vout: htlc_descriptor.htlc.transaction_output_index.unwrap(),
+			},
+			witness_weight: if htlc_descriptor.preimage.is_some() {
+				HTLC_SUCCESS_INPUT_ANCHOR_WITNESS_WEIGHT
+			} else {
+				HTLC_TIMEOUT_INPUT_ANCHOR_WITNESS_WEIGHT
+			},
+		}).collect();
+		let must_pay_to = tx.output.clone();
+		let coin_selection = self.utxo_source.select_confirmed_utxos(
+			claim_id, must_spend, must_pay_to, 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,
+		)?;
+
+		debug_assert_eq!(htlc_tx.output.len(), htlc_descriptors.len() + 1);
+		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_transaction(&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;