Add BumpTransaction event handler
authorWilmer Paulino <wilmer@wilmerpaulino.com>
Thu, 27 Apr 2023 00:42:35 +0000 (17:42 -0700)
committerWilmer Paulino <wilmer@wilmerpaulino.com>
Mon, 19 Jun 2023 21:05:45 +0000 (14:05 -0700)
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.

lightning/src/events/bump_transaction.rs
lightning/src/events/mod.rs
lightning/src/ln/chan_utils.rs

index d627132eaced34606f35b55062b4159d7670d6c5..55e0171aa19b3aa493cf7b9ad1117d0840988ce4 100644 (file)
@@ -9,16 +9,44 @@
 
 //! 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, PubkeyHash, Sequence, Script, Transaction, Txid, TxIn, TxOut, Witness, WPubkeyHash};
+use bitcoin::blockdata::constants::WITNESS_SCALE_FACTOR;
+use bitcoin::consensus::Encodable;
 use bitcoin::secp256k1;
 use bitcoin::secp256k1::{PublicKey, Secp256k1};
 use bitcoin::secp256k1::ecdsa::Signature;
 
+const EMPTY_SCRIPT_SIG_WEIGHT: u64 = 1 /* empty script_sig */ * WITNESS_SCALE_FACTOR as u64;
+
+const BASE_INPUT_SIZE: u64 = 32 /* txid */ + 4 /* vout */ + 4 /* sequence */;
+
+const BASE_INPUT_WEIGHT: u64 = BASE_INPUT_SIZE * WITNESS_SCALE_FACTOR as u64;
+
+// TODO: Define typed abstraction over feerates to handle their conversions.
+fn compute_feerate_sat_per_1000_weight(fee_sat: u64, weight: u64) -> u32 {
+       (fee_sat * 1000 / weight).try_into().unwrap_or(u32::max_value())
+}
+const fn fee_for_weight(feerate_sat_per_1000_weight: u32, weight: u64) -> u64 {
+       ((feerate_sat_per_1000_weight as u64 * weight) + 1000 - 1) / 1000
+}
+
 /// A descriptor used to sign for a commitment transaction's anchor output.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct AnchorDescriptor {
@@ -245,3 +273,367 @@ 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`]. It is guaranteed to be a SegWit input, so it
+/// must have an empty [`TxIn::script_sig`] when spent.
+pub struct Input {
+       /// The unique identifier of the input.
+       pub outpoint: OutPoint,
+       /// The upper-bound weight consumed by the input's full [`TxIn::script_sig`] and
+       /// [`TxIn::witness`], each with their lengths included, required to satisfy the output's
+       /// script.
+       pub satisfaction_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 input's full [`TxIn::script_sig`] and [`TxIn::witness`], each
+       /// with their lengths included, required to satisfy the output's script. The weight consumed by
+       /// the input's `script_sig` must account for [`WITNESS_SCALE_FACTOR`].
+       pub satisfaction_weight: u64,
+}
+
+impl Utxo {
+       const P2WPKH_WITNESS_WEIGHT: u64 = 1 /* num stack items */ +
+               1 /* sig length */ +
+               73 /* sig including sighash flag */ +
+               1 /* pubkey length */ +
+               33 /* pubkey */;
+
+       /// Returns a `Utxo` with the `satisfaction_weight` estimate for a legacy P2PKH output.
+       pub fn new_p2pkh(outpoint: OutPoint, value: u64, pubkey_hash: &PubkeyHash) -> Self {
+               let script_sig_size = 1 /* script_sig length */ +
+                       1 /* OP_PUSH73 */ +
+                       73 /* sig including sighash flag */ +
+                       1 /* OP_PUSH33 */ +
+                       33 /* pubkey */;
+               Self {
+                       outpoint,
+                       output: TxOut {
+                               value,
+                               script_pubkey: Script::new_p2pkh(pubkey_hash),
+                       },
+                       satisfaction_weight: script_sig_size * WITNESS_SCALE_FACTOR as u64 + 1 /* empty witness */,
+               }
+       }
+
+       /// Returns a `Utxo` with the `satisfaction_weight` estimate for a P2WPKH nested in P2SH output.
+       pub fn new_nested_p2wpkh(outpoint: OutPoint, value: u64, pubkey_hash: &WPubkeyHash) -> Self {
+               let script_sig_size = 1 /* script_sig length */ +
+                       1 /* OP_0 */ +
+                       1 /* OP_PUSH20 */ +
+                       20 /* pubkey_hash */;
+               Self {
+                       outpoint,
+                       output: TxOut {
+                               value,
+                               script_pubkey: Script::new_p2sh(&Script::new_v0_p2wpkh(pubkey_hash).script_hash()),
+                       },
+                       satisfaction_weight: script_sig_size * WITNESS_SCALE_FACTOR as u64 + Self::P2WPKH_WITNESS_WEIGHT,
+               }
+       }
+
+       /// Returns a `Utxo` with the `satisfaction_weight` estimate for a SegWit v0 P2WPKH output.
+       pub fn new_v0_p2wpkh(outpoint: OutPoint, value: u64, pubkey_hash: &WPubkeyHash) -> Self {
+               Self {
+                       outpoint,
+                       output: TxOut {
+                               value,
+                               script_pubkey: Script::new_v0_p2wpkh(pubkey_hash),
+                       },
+                       satisfaction_weight: EMPTY_SCRIPT_SIG_WEIGHT + Self::P2WPKH_WITNESS_WEIGHT,
+               }
+       }
+}
+
+/// 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`. It should not be
+       /// spent until the transaction it belongs to confirms to ensure mempool descendant limits are
+       /// not met. This implies no other party should be able to spend it except us.
+       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, but must not be returned as part of the result.
+       /// 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::satisfaction_weight`] only tracks the weight of
+       /// the input's `script_sig` and `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` must map to the set of external UTXOs assigned 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 implementation, but it must strive to keep the
+       /// set of other claims being double spent to a minimum.
+       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) {
+               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(change_output) = coin_selection.change_output.take() {
+                       tx.output.push(change_output);
+               } else if tx.output.is_empty() {
+                       // 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(&[]),
+                       });
+               }
+       }
+
+       /// 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,
+                       satisfaction_weight: commitment_tx.weight() as u64 + ANCHOR_INPUT_WITNESS_WEIGHT + EMPTY_SCRIPT_SIG_WEIGHT,
+               }];
+               let coin_selection = self.utxo_source.select_confirmed_utxos(
+                       claim_id, &must_spend, &[], target_feerate_sat_per_1000_weight,
+               )?;
+
+               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);
+               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_sat_per_1000_weight: u32 = compute_feerate_sat_per_1000_weight(
+                       commitment_tx_fee_sat, commitment_tx.weight() as u64,
+               );
+               if commitment_tx_sat_per_1000_weight >= package_target_feerate_sat_per_1000_weight {
+                       // 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(());
+               }
+
+               let mut anchor_tx = self.build_anchor_tx(
+                       claim_id, package_target_feerate_sat_per_1000_weight, 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(),
+                               satisfaction_weight: EMPTY_SCRIPT_SIG_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);
+               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);
+                               }
+                       }
+               }
+       }
+}
index 76a7f884ad27ceb3a1550e1b7235bf7dc8795f6d..88b3239b7ef8fed29e3134f9d0216de7495c0440 100644 (file)
@@ -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;
index b3b87146792af6bed47fcbf236192e7cb8aa7982..6ca5c929f1d6eccb4306a6403313fd21d0044362 100644 (file)
@@ -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 {