1 //! Defines ECDSA-specific signer types.
3 use bitcoin::blockdata::transaction::Transaction;
5 use bitcoin::secp256k1;
6 use bitcoin::secp256k1::ecdsa::Signature;
7 use bitcoin::secp256k1::{PublicKey, Secp256k1, SecretKey};
9 use crate::ln::chan_utils::{
10 ClosingTransaction, CommitmentTransaction, HTLCOutputInCommitment, HolderCommitmentTransaction,
12 use crate::ln::msgs::UnsignedChannelAnnouncement;
13 use crate::ln::types::PaymentPreimage;
15 #[allow(unused_imports)]
16 use crate::prelude::*;
18 use crate::sign::{ChannelSigner, HTLCDescriptor};
20 /// A trait to sign Lightning channel transactions as described in
21 /// [BOLT 3](https://github.com/lightning/bolts/blob/master/03-transactions.md).
23 /// Signing services could be implemented on a hardware wallet and should implement signing
24 /// policies in order to be secure. Please refer to the [VLS Policy
25 /// Controls](https://gitlab.com/lightning-signer/validating-lightning-signer/-/blob/main/docs/policy-controls.md)
26 /// for an example of such policies.
27 pub trait EcdsaChannelSigner: ChannelSigner {
28 /// Create a signature for a counterparty's commitment transaction and associated HTLC transactions.
30 /// Note that if signing fails or is rejected, the channel will be force-closed.
32 /// Policy checks should be implemented in this function, including checking the amount
33 /// sent to us and checking the HTLCs.
35 /// The preimages of outbound and inbound HTLCs that were fulfilled since the last commitment
36 /// are provided. A validating signer should ensure that an outbound HTLC output is removed
37 /// only when the matching preimage is provided and after the corresponding inbound HTLC has
38 /// been removed for forwarded payments.
40 /// Note that all the relevant preimages will be provided, but there may also be additional
41 /// irrelevant or duplicate preimages.
43 // TODO: Document the things someone using this interface should enforce before signing.
44 fn sign_counterparty_commitment(
45 &self, commitment_tx: &CommitmentTransaction, inbound_htlc_preimages: Vec<PaymentPreimage>,
46 outbound_htlc_preimages: Vec<PaymentPreimage>, secp_ctx: &Secp256k1<secp256k1::All>,
47 ) -> Result<(Signature, Vec<Signature>), ()>;
48 /// Creates a signature for a holder's commitment transaction.
50 /// This will be called
51 /// - with a non-revoked `commitment_tx`.
52 /// - with the latest `commitment_tx` when we initiate a force-close.
54 /// This may be called multiple times for the same transaction.
56 /// An external signer implementation should check that the commitment has not been revoked.
58 /// An `Err` can be returned to signal that the signer is unavailable/cannot produce a valid
59 /// signature and should be retried later. Once the signer is ready to provide a signature after
60 /// previously returning an `Err`, [`ChannelMonitor::signer_unblocked`] must be called on its
63 /// [`ChannelMonitor::signer_unblocked`]: crate::chain::channelmonitor::ChannelMonitor::signer_unblocked
65 // TODO: Document the things someone using this interface should enforce before signing.
66 fn sign_holder_commitment(
67 &self, commitment_tx: &HolderCommitmentTransaction, secp_ctx: &Secp256k1<secp256k1::All>,
68 ) -> Result<Signature, ()>;
69 /// Same as [`sign_holder_commitment`], but exists only for tests to get access to holder
70 /// commitment transactions which will be broadcasted later, after the channel has moved on to a
71 /// newer state. Thus, needs its own method as [`sign_holder_commitment`] may enforce that we
72 /// only ever get called once.
73 #[cfg(any(test, feature = "unsafe_revoked_tx_signing"))]
74 fn unsafe_sign_holder_commitment(
75 &self, commitment_tx: &HolderCommitmentTransaction, secp_ctx: &Secp256k1<secp256k1::All>,
76 ) -> Result<Signature, ()>;
77 /// Create a signature for the given input in a transaction spending an HTLC transaction output
78 /// or a commitment transaction `to_local` output when our counterparty broadcasts an old state.
80 /// A justice transaction may claim multiple outputs at the same time if timelocks are
81 /// similar, but only a signature for the input at index `input` should be signed for here.
82 /// It may be called multiple times for same output(s) if a fee-bump is needed with regards
83 /// to an upcoming timelock expiration.
85 /// Amount is value of the output spent by this input, committed to in the BIP 143 signature.
87 /// `per_commitment_key` is revocation secret which was provided by our counterparty when they
88 /// revoked the state which they eventually broadcast. It's not a _holder_ secret key and does
89 /// not allow the spending of any funds by itself (you need our holder `revocation_secret` to do
92 /// An `Err` can be returned to signal that the signer is unavailable/cannot produce a valid
93 /// signature and should be retried later. Once the signer is ready to provide a signature after
94 /// previously returning an `Err`, [`ChannelMonitor::signer_unblocked`] must be called on its
97 /// [`ChannelMonitor::signer_unblocked`]: crate::chain::channelmonitor::ChannelMonitor::signer_unblocked
98 fn sign_justice_revoked_output(
99 &self, justice_tx: &Transaction, input: usize, amount: u64, per_commitment_key: &SecretKey,
100 secp_ctx: &Secp256k1<secp256k1::All>,
101 ) -> Result<Signature, ()>;
102 /// Create a signature for the given input in a transaction spending a commitment transaction
103 /// HTLC output when our counterparty broadcasts an old state.
105 /// A justice transaction may claim multiple outputs at the same time if timelocks are
106 /// similar, but only a signature for the input at index `input` should be signed for here.
107 /// It may be called multiple times for same output(s) if a fee-bump is needed with regards
108 /// to an upcoming timelock expiration.
110 /// `amount` is the value of the output spent by this input, committed to in the BIP 143
113 /// `per_commitment_key` is revocation secret which was provided by our counterparty when they
114 /// revoked the state which they eventually broadcast. It's not a _holder_ secret key and does
115 /// not allow the spending of any funds by itself (you need our holder revocation_secret to do
118 /// `htlc` holds HTLC elements (hash, timelock), thus changing the format of the witness script
119 /// (which is committed to in the BIP 143 signatures).
121 /// An `Err` can be returned to signal that the signer is unavailable/cannot produce a valid
122 /// signature and should be retried later. Once the signer is ready to provide a signature after
123 /// previously returning an `Err`, [`ChannelMonitor::signer_unblocked`] must be called on its
126 /// [`ChannelMonitor::signer_unblocked`]: crate::chain::channelmonitor::ChannelMonitor::signer_unblocked
127 fn sign_justice_revoked_htlc(
128 &self, justice_tx: &Transaction, input: usize, amount: u64, per_commitment_key: &SecretKey,
129 htlc: &HTLCOutputInCommitment, secp_ctx: &Secp256k1<secp256k1::All>,
130 ) -> Result<Signature, ()>;
131 /// Computes the signature for a commitment transaction's HTLC output used as an input within
132 /// `htlc_tx`, which spends the commitment transaction at index `input`. The signature returned
133 /// must be be computed using [`EcdsaSighashType::All`].
135 /// Note that this may be called for HTLCs in the penultimate commitment transaction if a
136 /// [`ChannelMonitor`] [replica](https://github.com/lightningdevkit/rust-lightning/blob/main/GLOSSARY.md#monitor-replicas)
137 /// broadcasts it before receiving the update for the latest commitment transaction.
139 /// An `Err` can be returned to signal that the signer is unavailable/cannot produce a valid
140 /// signature and should be retried later. Once the signer is ready to provide a signature after
141 /// previously returning an `Err`, [`ChannelMonitor::signer_unblocked`] must be called on its
144 /// [`EcdsaSighashType::All`]: bitcoin::sighash::EcdsaSighashType::All
145 /// [`ChannelMonitor`]: crate::chain::channelmonitor::ChannelMonitor
146 /// [`ChannelMonitor::signer_unblocked`]: crate::chain::channelmonitor::ChannelMonitor::signer_unblocked
147 fn sign_holder_htlc_transaction(
148 &self, htlc_tx: &Transaction, input: usize, htlc_descriptor: &HTLCDescriptor,
149 secp_ctx: &Secp256k1<secp256k1::All>,
150 ) -> Result<Signature, ()>;
151 /// Create a signature for a claiming transaction for a HTLC output on a counterparty's commitment
152 /// transaction, either offered or received.
154 /// Such a transaction may claim multiples offered outputs at same time if we know the
155 /// preimage for each when we create it, but only the input at index `input` should be
156 /// signed for here. It may be called multiple times for same output(s) if a fee-bump is
157 /// needed with regards to an upcoming timelock expiration.
159 /// `witness_script` is either an offered or received script as defined in BOLT3 for HTLC
162 /// `amount` is value of the output spent by this input, committed to in the BIP 143 signature.
164 /// `per_commitment_point` is the dynamic point corresponding to the channel state
165 /// detected onchain. It has been generated by our counterparty and is used to derive
166 /// channel state keys, which are then included in the witness script and committed to in the
167 /// BIP 143 signature.
169 /// An `Err` can be returned to signal that the signer is unavailable/cannot produce a valid
170 /// signature and should be retried later. Once the signer is ready to provide a signature after
171 /// previously returning an `Err`, [`ChannelMonitor::signer_unblocked`] must be called on its
174 /// [`ChannelMonitor::signer_unblocked`]: crate::chain::channelmonitor::ChannelMonitor::signer_unblocked
175 fn sign_counterparty_htlc_transaction(
176 &self, htlc_tx: &Transaction, input: usize, amount: u64, per_commitment_point: &PublicKey,
177 htlc: &HTLCOutputInCommitment, secp_ctx: &Secp256k1<secp256k1::All>,
178 ) -> Result<Signature, ()>;
179 /// Create a signature for a (proposed) closing transaction.
181 /// Note that, due to rounding, there may be one "missing" satoshi, and either party may have
182 /// chosen to forgo their output as dust.
183 fn sign_closing_transaction(
184 &self, closing_tx: &ClosingTransaction, secp_ctx: &Secp256k1<secp256k1::All>,
185 ) -> Result<Signature, ()>;
186 /// Computes the signature for a commitment transaction's anchor output used as an
187 /// input within `anchor_tx`, which spends the commitment transaction, at index `input`.
189 /// An `Err` can be returned to signal that the signer is unavailable/cannot produce a valid
190 /// signature and should be retried later. Once the signer is ready to provide a signature after
191 /// previously returning an `Err`, [`ChannelMonitor::signer_unblocked`] must be called on its
194 /// [`ChannelMonitor::signer_unblocked`]: crate::chain::channelmonitor::ChannelMonitor::signer_unblocked
195 fn sign_holder_anchor_input(
196 &self, anchor_tx: &Transaction, input: usize, secp_ctx: &Secp256k1<secp256k1::All>,
197 ) -> Result<Signature, ()>;
198 /// Signs a channel announcement message with our funding key proving it comes from one of the
199 /// channel participants.
201 /// Channel announcements also require a signature from each node's network key. Our node
202 /// signature is computed through [`NodeSigner::sign_gossip_message`].
204 /// Note that if this fails or is rejected, the channel will not be publicly announced and
205 /// our counterparty may (though likely will not) close the channel on us for violating the
208 /// [`NodeSigner::sign_gossip_message`]: crate::sign::NodeSigner::sign_gossip_message
209 fn sign_channel_announcement_with_funding_key(
210 &self, msg: &UnsignedChannelAnnouncement, secp_ctx: &Secp256k1<secp256k1::All>,
211 ) -> Result<Signature, ()>;