]> git.bitcoin.ninja Git - rust-lightning/blob - lightning/src/events/bump_transaction.rs
Merge pull request #2111 from TheBlueMatt/2023-03-sent-persist-order-prep
[rust-lightning] / 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::sign::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::sign::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::sign::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::sign::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::sign::InMemorySigner
58         /// [`ChannelSigner::provide_channel_parameters`]: crate::sign::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::sign::InMemorySigner
172         /// [`KeysManager::derive_channel_keys`]: crate::sign::KeysManager::derive_channel_keys
173         /// [`EcdsaChannelSigner::sign_holder_anchor_input`]: crate::sign::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::sign::InMemorySigner
221         /// [`KeysManager::derive_channel_keys`]: crate::sign::KeysManager::derive_channel_keys
222         /// [`EcdsaChannelSigner::sign_holder_htlc_transaction`]: crate::sign::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                 /// The locktime required for the resulting HTLC transaction.
231                 tx_lock_time: PackedLockTime,
232         },
233 }