Add BumpTransaction event handler

Author: wpaulino

lightning/src/events/bump_transaction.rs

@@ -9,11 +9,28 @@
 
 //! 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::keysinterface::{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 crate::util::ser::Writeable;
 
-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::hashes::{Hash, HashEngine};
+use bitcoin::hashes::sha256::Hash as Sha256Hash;
 use bitcoin::secp256k1;
 use bitcoin::secp256k1::{PublicKey, Secp256k1};
 use bitcoin::secp256k1::ecdsa::Signature;
@@ -231,3 +248,365 @@ pub enum BumpTransactionEvent {
 		tx_lock_time: PackedLockTime,
 	},
 }
+
+/// A unique identifier used to track bumps for a transaction. The same identifier is always used
+/// for all bumps of the same transaction.
+#[derive(Copy, Clone, Hash, PartialEq, Eq)]
+pub struct BumpId([u8; 32]);
+
+impl BumpId {
+	fn from_txid(txid: Txid) -> Self {
+		Self(txid.into_inner())
+	}
+
+	fn from_htlc_descriptors(htlc_descriptors: &[HTLCDescriptor]) -> Self {
+		let mut engine = Sha256Hash::engine();
+		for htlc_descriptor in htlc_descriptors {
+			let htlc_outpoint = OutPoint {
+				txid: htlc_descriptor.commitment_txid,
+				vout: htlc_descriptor.htlc.transaction_output_index.unwrap()
+			};
+			engine.input(&htlc_outpoint.encode());
+		}
+		Self(Sha256Hash::from_engine(engine).into_inner())
+	}
+}
+
+/// 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 realize 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.
+	fn select_confirmed_utxos(
+		&self, bump_id: BumpId, 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, bump_id: BumpId, 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: Prevent change address inflation.
+		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(
+			bump_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, 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(());
+		}
+
+		let bump_id = BumpId::from_txid(commitment_tx.txid());
+		// 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(
+			bump_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, bump_id: BumpId, 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(
+			bump_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, target_feerate_sat_per_1000_weight: u32, htlc_descriptors: &[HTLCDescriptor],
+		tx_lock_time: PackedLockTime,
+	) -> Result<(), ()> {
+		let bump_id = BumpId::from_htlc_descriptors(htlc_descriptors);
+		let (mut htlc_tx, signers) = self.build_htlc_tx(
+			bump_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 {
+				package_target_feerate_sat_per_1000_weight, commitment_tx, anchor_descriptor,
+				commitment_tx_fee_satoshis,	..
+			} => {
+				if let Err(_) = self.handle_channel_close(
+					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 {
+				target_feerate_sat_per_1000_weight, htlc_descriptors, tx_lock_time,
+			} => {
+				if let Err(_) = self.handle_htlc_resolution(
+					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);
+				}
+			}
+		}
+	}
+}