git.bitcoin.ninja Git - rust-lightning/blob - lightning/src/events/bump_transaction.rs

   1 // This file is Copyright its original authors, visible in version control
   2 // history.
   3 //
   4 // This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE
   5 // or http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   6 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
   7 // You may not use this file except in accordance with one or both of these
   8 // licenses.
   9
  10 //! Utitilies for bumping transactions originating from [`super::Event`]s.
  11
  12 use crate::ln::PaymentPreimage;
  13 use crate::ln::chan_utils;
  14 use crate::ln::chan_utils::{ChannelTransactionParameters, HTLCOutputInCommitment};
  15
  16 use bitcoin::{OutPoint, PackedLockTime, Script, Transaction, Txid, TxIn, TxOut, Witness};
  17 use bitcoin::secp256k1;
  18 use bitcoin::secp256k1::{PublicKey, Secp256k1};
  19 use bitcoin::secp256k1::ecdsa::Signature;
  20
  21 /// A descriptor used to sign for a commitment transaction's anchor output.
  22 #[derive(Clone, Debug, PartialEq, Eq)]
  23 pub struct AnchorDescriptor {
  24         /// A unique identifier used along with `channel_value_satoshis` to re-derive the
  25         /// [`InMemorySigner`] required to sign `input`.
  26         ///
  27         /// [`InMemorySigner`]: crate::chain::keysinterface::InMemorySigner
  28         pub channel_keys_id: [u8; 32],
  29         /// The value in satoshis of the channel we're attempting to spend the anchor output of. This is
  30         /// used along with `channel_keys_id` to re-derive the [`InMemorySigner`] required to sign
  31         /// `input`.
  32         ///
  33         /// [`InMemorySigner`]: crate::chain::keysinterface::InMemorySigner
  34         pub channel_value_satoshis: u64,
  35         /// The transaction input's outpoint corresponding to the commitment transaction's anchor
  36         /// output.
  37         pub outpoint: OutPoint,
  38 }
  39
  40 /// A descriptor used to sign for a commitment transaction's HTLC output.
  41 #[derive(Clone, Debug, PartialEq, Eq)]
  42 pub struct HTLCDescriptor {
  43         /// A unique identifier used along with `channel_value_satoshis` to re-derive the
  44         /// [`InMemorySigner`] required to sign `input`.
  45         ///
  46         /// [`InMemorySigner`]: crate::chain::keysinterface::InMemorySigner
  47         pub channel_keys_id: [u8; 32],
  48         /// The value in satoshis of the channel we're attempting to spend the anchor output of. This is
  49         /// used along with `channel_keys_id` to re-derive the [`InMemorySigner`] required to sign
  50         /// `input`.
  51         ///
  52         /// [`InMemorySigner`]: crate::chain::keysinterface::InMemorySigner
  53         pub channel_value_satoshis: u64,
  54         /// The necessary channel parameters that need to be provided to the re-derived
  55         /// [`InMemorySigner`] through [`ChannelSigner::provide_channel_parameters`].
  56         ///
  57         /// [`InMemorySigner`]: crate::chain::keysinterface::InMemorySigner
  58         /// [`ChannelSigner::provide_channel_parameters`]: crate::chain::keysinterface::ChannelSigner::provide_channel_parameters
  59         pub channel_parameters: ChannelTransactionParameters,
  60         /// The txid of the commitment transaction in which the HTLC output lives.
  61         pub commitment_txid: Txid,
  62         /// The number of the commitment transaction in which the HTLC output lives.
  63         pub per_commitment_number: u64,
  64         /// The details of the HTLC as it appears in the commitment transaction.
  65         pub htlc: HTLCOutputInCommitment,
  66         /// The preimage, if `Some`, to claim the HTLC output with. If `None`, the timeout path must be
  67         /// taken.
  68         pub preimage: Option<PaymentPreimage>,
  69         /// The counterparty's signature required to spend the HTLC output.
  70         pub counterparty_sig: Signature
  71 }
  72
  73 impl HTLCDescriptor {
  74         /// Returns the unsigned transaction input spending the HTLC output in the commitment
  75         /// transaction.
  76         pub fn unsigned_tx_input(&self) -> TxIn {
  77                 chan_utils::build_htlc_input(&self.commitment_txid, &self.htlc, true /* opt_anchors */)
  78         }
  79
  80         /// Returns the delayed output created as a result of spending the HTLC output in the commitment
  81         /// transaction.
  82         pub fn tx_output<C: secp256k1::Signing + secp256k1::Verification>(
  83                 &self, per_commitment_point: &PublicKey, secp: &Secp256k1<C>
  84         ) -> TxOut {
  85                 let channel_params = self.channel_parameters.as_holder_broadcastable();
  86                 let broadcaster_keys = channel_params.broadcaster_pubkeys();
  87                 let counterparty_keys = channel_params.countersignatory_pubkeys();
  88                 let broadcaster_delayed_key = chan_utils::derive_public_key(
  89                         secp, per_commitment_point, &broadcaster_keys.delayed_payment_basepoint
  90                 );
  91                 let counterparty_revocation_key = chan_utils::derive_public_revocation_key(
  92                         secp, per_commitment_point, &counterparty_keys.revocation_basepoint
  93                 );
  94                 chan_utils::build_htlc_output(
  95                         0 /* feerate_per_kw */, channel_params.contest_delay(), &self.htlc, true /* opt_anchors */,
  96                         false /* use_non_zero_fee_anchors */, &broadcaster_delayed_key, &counterparty_revocation_key
  97                 )
  98         }
  99
 100         /// Returns the witness script of the HTLC output in the commitment transaction.
 101         pub fn witness_script<C: secp256k1::Signing + secp256k1::Verification>(
 102                 &self, per_commitment_point: &PublicKey, secp: &Secp256k1<C>
 103         ) -> Script {
 104                 let channel_params = self.channel_parameters.as_holder_broadcastable();
 105                 let broadcaster_keys = channel_params.broadcaster_pubkeys();
 106                 let counterparty_keys = channel_params.countersignatory_pubkeys();
 107                 let broadcaster_htlc_key = chan_utils::derive_public_key(
 108                         secp, per_commitment_point, &broadcaster_keys.htlc_basepoint
 109                 );
 110                 let counterparty_htlc_key = chan_utils::derive_public_key(
 111                         secp, per_commitment_point, &counterparty_keys.htlc_basepoint
 112                 );
 113                 let counterparty_revocation_key = chan_utils::derive_public_revocation_key(
 114                         secp, per_commitment_point, &counterparty_keys.revocation_basepoint
 115                 );
 116                 chan_utils::get_htlc_redeemscript_with_explicit_keys(
 117                         &self.htlc, true /* opt_anchors */, &broadcaster_htlc_key, &counterparty_htlc_key,
 118                         &counterparty_revocation_key,
 119                 )
 120         }
 121
 122         /// Returns the fully signed witness required to spend the HTLC output in the commitment
 123         /// transaction.
 124         pub fn tx_input_witness(&self, signature: &Signature, witness_script: &Script) -> Witness {
 125                 chan_utils::build_htlc_input_witness(
 126                         signature, &self.counterparty_sig, &self.preimage, witness_script, true /* opt_anchors */
 127                 )
 128         }
 129 }
 130
 131 /// Represents the different types of transactions, originating from LDK, to be bumped.
 132 #[derive(Clone, Debug, PartialEq, Eq)]
 133 pub enum BumpTransactionEvent {
 134         /// Indicates that a channel featuring anchor outputs is to be closed by broadcasting the local
 135         /// commitment transaction. Since commitment transactions have a static feerate pre-agreed upon,
 136         /// they may need additional fees to be attached through a child transaction using the popular
 137         /// [Child-Pays-For-Parent](https://bitcoinops.org/en/topics/cpfp) fee bumping technique. This
 138         /// child transaction must include the anchor input described within `anchor_descriptor` along
 139         /// with additional inputs to meet the target feerate. Failure to meet the target feerate
 140         /// decreases the confirmation odds of the transaction package (which includes the commitment
 141         /// and child anchor transactions), possibly resulting in a loss of funds. Once the transaction
 142         /// is constructed, it must be fully signed for and broadcast by the consumer of the event
 143         /// along with the `commitment_tx` enclosed. Note that the `commitment_tx` must always be
 144         /// broadcast first, as the child anchor transaction depends on it.
 145         ///
 146         /// The consumer should be able to sign for any of the additional inputs included within the
 147         /// child anchor transaction. To sign its anchor input, an [`InMemorySigner`] should be
 148         /// re-derived through [`KeysManager::derive_channel_keys`] with the help of
 149         /// [`AnchorDescriptor::channel_keys_id`] and [`AnchorDescriptor::channel_value_satoshis`]. The
 150         /// anchor input signature can be computed with [`EcdsaChannelSigner::sign_holder_anchor_input`],
 151         /// which can then be provided to [`build_anchor_input_witness`] along with the `funding_pubkey`
 152         /// to obtain the full witness required to spend.
 153         ///
 154         /// It is possible to receive more than one instance of this event if a valid child anchor
 155         /// transaction is never broadcast or is but not with a sufficient fee to be mined. Care should
 156         /// be taken by the consumer of the event to ensure any future iterations of the child anchor
 157         /// transaction adhere to the [Replace-By-Fee
 158         /// rules](https://github.com/bitcoin/bitcoin/blob/master/doc/policy/mempool-replacements.md)
 159         /// for fee bumps to be accepted into the mempool, and eventually the chain. As the frequency of
 160         /// these events is not user-controlled, users may ignore/drop the event if they are no longer
 161         /// able to commit external confirmed funds to the child anchor transaction.
 162         ///
 163         /// The set of `pending_htlcs` on the commitment transaction to be broadcast can be inspected to
 164         /// determine whether a significant portion of the channel's funds are allocated to HTLCs,
 165         /// enabling users to make their own decisions regarding the importance of the commitment
 166         /// transaction's confirmation. Note that this is not required, but simply exists as an option
 167         /// for users to override LDK's behavior. On commitments with no HTLCs (indicated by those with
 168         /// an empty `pending_htlcs`), confirmation of the commitment transaction can be considered to
 169         /// be not urgent.
 170         ///
 171         /// [`InMemorySigner`]: crate::chain::keysinterface::InMemorySigner
 172         /// [`KeysManager::derive_channel_keys`]: crate::chain::keysinterface::KeysManager::derive_channel_keys
 173         /// [`EcdsaChannelSigner::sign_holder_anchor_input`]: crate::chain::keysinterface::EcdsaChannelSigner::sign_holder_anchor_input
 174         /// [`build_anchor_input_witness`]: crate::ln::chan_utils::build_anchor_input_witness
 175         ChannelClose {
 176                 /// The target feerate that the transaction package, which consists of the commitment
 177                 /// transaction and the to-be-crafted child anchor transaction, must meet.
 178                 package_target_feerate_sat_per_1000_weight: u32,
 179                 /// The channel's commitment transaction to bump the fee of. This transaction should be
 180                 /// broadcast along with the anchor transaction constructed as a result of consuming this
 181                 /// event.
 182                 commitment_tx: Transaction,
 183                 /// The absolute fee in satoshis of the commitment transaction. This can be used along the
 184                 /// with weight of the commitment transaction to determine its feerate.
 185                 commitment_tx_fee_satoshis: u64,
 186                 /// The descriptor to sign the anchor input of the anchor transaction constructed as a
 187                 /// result of consuming this event.
 188                 anchor_descriptor: AnchorDescriptor,
 189                 /// The set of pending HTLCs on the commitment transaction that need to be resolved once the
 190                 /// commitment transaction confirms.
 191                 pending_htlcs: Vec<HTLCOutputInCommitment>,
 192         },
 193         /// Indicates that a channel featuring anchor outputs has unilaterally closed on-chain by a
 194         /// holder commitment transaction and its HTLC(s) need to be resolved on-chain. With the
 195         /// zero-HTLC-transaction-fee variant of anchor outputs, the pre-signed HTLC
 196         /// transactions have a zero fee, thus requiring additional inputs and/or outputs to be attached
 197         /// for a timely confirmation within the chain. These additional inputs and/or outputs must be
 198         /// appended to the resulting HTLC transaction to meet the target feerate. Failure to meet the
 199         /// target feerate decreases the confirmation odds of the transaction, possibly resulting in a
 200         /// loss of funds. Once the transaction meets the target feerate, it must be signed for and
 201         /// broadcast by the consumer of the event.
 202         ///
 203         /// The consumer should be able to sign for any of the non-HTLC inputs added to the resulting
 204         /// HTLC transaction. To sign HTLC inputs, an [`InMemorySigner`] should be re-derived through
 205         /// [`KeysManager::derive_channel_keys`] with the help of `channel_keys_id` and
 206         /// `channel_value_satoshis`. Each HTLC input's signature can be computed with
 207         /// [`EcdsaChannelSigner::sign_holder_htlc_transaction`], which can then be provided to
 208         /// [`HTLCDescriptor::tx_input_witness`] to obtain the fully signed witness required to spend.
 209         ///
 210         /// It is possible to receive more than one instance of this event if a valid HTLC transaction
 211         /// is never broadcast or is but not with a sufficient fee to be mined. Care should be taken by
 212         /// the consumer of the event to ensure any future iterations of the HTLC transaction adhere to
 213         /// the [Replace-By-Fee
 214         /// rules](https://github.com/bitcoin/bitcoin/blob/master/doc/policy/mempool-replacements.md)
 215         /// for fee bumps to be accepted into the mempool, and eventually the chain. As the frequency of
 216         /// these events is not user-controlled, users may ignore/drop the event if either they are no
 217         /// longer able to commit external confirmed funds to the HTLC transaction or the fee committed
 218         /// to the HTLC transaction is greater in value than the HTLCs being claimed.
 219         ///
 220         /// [`InMemorySigner`]: crate::chain::keysinterface::InMemorySigner
 221         /// [`KeysManager::derive_channel_keys`]: crate::chain::keysinterface::KeysManager::derive_channel_keys
 222         /// [`EcdsaChannelSigner::sign_holder_htlc_transaction`]: crate::chain::keysinterface::EcdsaChannelSigner::sign_holder_htlc_transaction
 223         /// [`HTLCDescriptor::tx_input_witness`]: HTLCDescriptor::tx_input_witness
 224         HTLCResolution {
 225                 /// The target feerate that the resulting HTLC transaction must meet.
 226                 target_feerate_sat_per_1000_weight: u32,
 227                 /// The set of pending HTLCs on the confirmed commitment that need to be claimed, preferably
 228                 /// by the same transaction.
 229                 htlc_descriptors: Vec<HTLCDescriptor>,
 230         },
 231 }