lightning/sign/
ecdsa.rs

1//! Defines ECDSA-specific signer types.
2
3use bitcoin::transaction::Transaction;
4
5use bitcoin::secp256k1;
6use bitcoin::secp256k1::ecdsa::Signature;
7use bitcoin::secp256k1::{PublicKey, Secp256k1, SecretKey};
8
9use crate::ln::chan_utils::{
10	ChannelTransactionParameters, ClosingTransaction, CommitmentTransaction,
11	HTLCOutputInCommitment, HolderCommitmentTransaction,
12};
13use crate::ln::msgs::UnsignedChannelAnnouncement;
14use crate::types::payment::PaymentPreimage;
15
16#[allow(unused_imports)]
17use crate::prelude::*;
18
19use crate::sign::{ChannelSigner, HTLCDescriptor};
20
21/// A trait to sign Lightning channel transactions as described in
22/// [BOLT 3](https://github.com/lightning/bolts/blob/master/03-transactions.md).
23///
24/// Signing services could be implemented on a hardware wallet and should implement signing
25/// policies in order to be secure. Please refer to the [VLS Policy
26/// Controls](https://gitlab.com/lightning-signer/validating-lightning-signer/-/blob/main/docs/policy-controls.md)
27/// for an example of such policies.
28///
29/// Like [`ChannelSigner`], many of the methods allow errors to be returned to support async
30/// signing. In such cases, the signing operation can be replayed by calling
31/// [`ChannelManager::signer_unblocked`] or [`ChainMonitor::signer_unblocked`] (see individual
32/// method documentation for which method should be called) once the result is ready, at which
33/// point the channel operation will resume.
34///
35/// [`ChannelManager::signer_unblocked`]: crate::ln::channelmanager::ChannelManager::signer_unblocked
36/// [`ChainMonitor::signer_unblocked`]: crate::chain::chainmonitor::ChainMonitor::signer_unblocked
37pub trait EcdsaChannelSigner: ChannelSigner {
38	/// Create a signature for a counterparty's commitment transaction and associated HTLC transactions.
39	///
40	/// Policy checks should be implemented in this function, including checking the amount
41	/// sent to us and checking the HTLCs.
42	///
43	/// The preimages of outbound and inbound HTLCs that were fulfilled since the last commitment
44	/// are provided. A validating signer should ensure that an outbound HTLC output is removed
45	/// only when the matching preimage is provided and after the corresponding inbound HTLC has
46	/// been removed for forwarded payments.
47	///
48	/// Note that all the relevant preimages will be provided, but there may also be additional
49	/// irrelevant or duplicate preimages.
50	///
51	/// An `Err` can be returned to signal that the signer is unavailable/cannot produce a valid
52	/// signature and should be retried later. Once the signer is ready to provide a signature after
53	/// previously returning an `Err`, [`ChannelManager::signer_unblocked`] must be called.
54	///
55	/// [`ChannelManager::signer_unblocked`]: crate::ln::channelmanager::ChannelManager::signer_unblocked
56	fn sign_counterparty_commitment(
57		&self, channel_parameters: &ChannelTransactionParameters,
58		commitment_tx: &CommitmentTransaction, inbound_htlc_preimages: Vec<PaymentPreimage>,
59		outbound_htlc_preimages: Vec<PaymentPreimage>, secp_ctx: &Secp256k1<secp256k1::All>,
60	) -> Result<(Signature, Vec<Signature>), ()>;
61	/// Creates a signature for a holder's commitment transaction.
62	///
63	/// This will be called
64	/// - with a non-revoked `commitment_tx`.
65	/// - with the latest `commitment_tx` when we initiate a force-close.
66	///
67	/// This may be called multiple times for the same transaction.
68	///
69	/// An external signer implementation should check that the commitment has not been revoked.
70	///
71	/// An `Err` can be returned to signal that the signer is unavailable/cannot produce a valid
72	/// signature and should be retried later. Once the signer is ready to provide a signature after
73	/// previously returning an `Err`, [`ChannelMonitor::signer_unblocked`] must be called on its
74	/// monitor or [`ChainMonitor::signer_unblocked`] called to attempt unblocking all monitors.
75	///
76	/// [`ChannelMonitor::signer_unblocked`]: crate::chain::channelmonitor::ChannelMonitor::signer_unblocked
77	/// [`ChainMonitor::signer_unblocked`]: crate::chain::chainmonitor::ChainMonitor::signer_unblocked
78	fn sign_holder_commitment(
79		&self, channel_parameters: &ChannelTransactionParameters,
80		commitment_tx: &HolderCommitmentTransaction, secp_ctx: &Secp256k1<secp256k1::All>,
81	) -> Result<Signature, ()>;
82	/// Same as [`sign_holder_commitment`], but exists only for tests to get access to holder
83	/// commitment transactions which will be broadcasted later, after the channel has moved on to a
84	/// newer state. Thus, needs its own method as [`sign_holder_commitment`] may enforce that we
85	/// only ever get called once.
86	///
87	/// This method is *not* async as it is intended only for testing purposes.
88	#[cfg(any(test, feature = "_test_utils", feature = "unsafe_revoked_tx_signing"))]
89	fn unsafe_sign_holder_commitment(
90		&self, channel_parameters: &ChannelTransactionParameters,
91		commitment_tx: &HolderCommitmentTransaction, secp_ctx: &Secp256k1<secp256k1::All>,
92	) -> Result<Signature, ()>;
93	/// Create a signature for the given input in a transaction spending an HTLC transaction output
94	/// or a commitment transaction `to_local` output when our counterparty broadcasts an old state.
95	///
96	/// A justice transaction may claim multiple outputs at the same time if timelocks are
97	/// similar, but only a signature for the input at index `input` should be signed for here.
98	/// It may be called multiple times for same output(s) if a fee-bump is needed with regards
99	/// to an upcoming timelock expiration.
100	///
101	/// Amount is value of the output spent by this input, committed to in the BIP 143 signature.
102	///
103	/// `per_commitment_key` is revocation secret which was provided by our counterparty when they
104	/// revoked the state which they eventually broadcast. It's not a _holder_ secret key and does
105	/// not allow the spending of any funds by itself (you need our holder `revocation_secret` to do
106	/// so).
107	///
108	/// An `Err` can be returned to signal that the signer is unavailable/cannot produce a valid
109	/// signature and should be retried later. Once the signer is ready to provide a signature after
110	/// previously returning an `Err`, [`ChannelMonitor::signer_unblocked`] must be called on its
111	/// monitor or [`ChainMonitor::signer_unblocked`] called to attempt unblocking all monitors.
112	///
113	/// [`ChannelMonitor::signer_unblocked`]: crate::chain::channelmonitor::ChannelMonitor::signer_unblocked
114	/// [`ChainMonitor::signer_unblocked`]: crate::chain::chainmonitor::ChainMonitor::signer_unblocked
115	fn sign_justice_revoked_output(
116		&self, channel_parameters: &ChannelTransactionParameters, justice_tx: &Transaction,
117		input: usize, amount: u64, per_commitment_key: &SecretKey,
118		secp_ctx: &Secp256k1<secp256k1::All>,
119	) -> Result<Signature, ()>;
120	/// Create a signature for the given input in a transaction spending a commitment transaction
121	/// HTLC output when our counterparty broadcasts an old state.
122	///
123	/// A justice transaction may claim multiple outputs at the same time if timelocks are
124	/// similar, but only a signature for the input at index `input` should be signed for here.
125	/// It may be called multiple times for same output(s) if a fee-bump is needed with regards
126	/// to an upcoming timelock expiration.
127	///
128	/// `amount` is the value of the output spent by this input, committed to in the BIP 143
129	/// signature.
130	///
131	/// `per_commitment_key` is revocation secret which was provided by our counterparty when they
132	/// revoked the state which they eventually broadcast. It's not a _holder_ secret key and does
133	/// not allow the spending of any funds by itself (you need our holder revocation_secret to do
134	/// so).
135	///
136	/// `htlc` holds HTLC elements (hash, timelock), thus changing the format of the witness script
137	/// (which is committed to in the BIP 143 signatures).
138	///
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
142	/// monitor or [`ChainMonitor::signer_unblocked`] called to attempt unblocking all monitors.
143	///
144	/// [`ChannelMonitor::signer_unblocked`]: crate::chain::channelmonitor::ChannelMonitor::signer_unblocked
145	/// [`ChainMonitor::signer_unblocked`]: crate::chain::chainmonitor::ChainMonitor::signer_unblocked
146	fn sign_justice_revoked_htlc(
147		&self, channel_parameters: &ChannelTransactionParameters, justice_tx: &Transaction,
148		input: usize, amount: u64, per_commitment_key: &SecretKey, htlc: &HTLCOutputInCommitment,
149		secp_ctx: &Secp256k1<secp256k1::All>,
150	) -> Result<Signature, ()>;
151	/// Computes the signature for a commitment transaction's HTLC output used as an input within
152	/// `htlc_tx`, which spends the commitment transaction at index `input`. The signature returned
153	/// must be be computed using [`EcdsaSighashType::All`].
154	///
155	/// Note that this may be called for HTLCs in the penultimate commitment transaction if a
156	/// [`ChannelMonitor`] [replica](https://github.com/lightningdevkit/rust-lightning/blob/main/GLOSSARY.md#monitor-replicas)
157	/// broadcasts it before receiving the update for the latest commitment transaction.
158	///
159	/// An `Err` can be returned to signal that the signer is unavailable/cannot produce a valid
160	/// signature and should be retried later. Once the signer is ready to provide a signature after
161	/// previously returning an `Err`, [`ChannelMonitor::signer_unblocked`] must be called on its
162	/// monitor or [`ChainMonitor::signer_unblocked`] called to attempt unblocking all monitors.
163	///
164	/// [`EcdsaSighashType::All`]: bitcoin::sighash::EcdsaSighashType::All
165	/// [`ChannelMonitor`]: crate::chain::channelmonitor::ChannelMonitor
166	/// [`ChannelMonitor::signer_unblocked`]: crate::chain::channelmonitor::ChannelMonitor::signer_unblocked
167	/// [`ChainMonitor::signer_unblocked`]: crate::chain::chainmonitor::ChainMonitor::signer_unblocked
168	fn sign_holder_htlc_transaction(
169		&self, htlc_tx: &Transaction, input: usize, htlc_descriptor: &HTLCDescriptor,
170		secp_ctx: &Secp256k1<secp256k1::All>,
171	) -> Result<Signature, ()>;
172	/// Create a signature for a claiming transaction for a HTLC output on a counterparty's commitment
173	/// transaction, either offered or received.
174	///
175	/// Such a transaction may claim multiples offered outputs at same time if we know the
176	/// preimage for each when we create it, but only the input at index `input` should be
177	/// signed for here. It may be called multiple times for same output(s) if a fee-bump is
178	/// needed with regards to an upcoming timelock expiration.
179	///
180	/// `witness_script` is either an offered or received script as defined in BOLT3 for HTLC
181	/// outputs.
182	///
183	/// `amount` is value of the output spent by this input, committed to in the BIP 143 signature.
184	///
185	/// `per_commitment_point` is the dynamic point corresponding to the channel state
186	/// detected onchain. It has been generated by our counterparty and is used to derive
187	/// channel state keys, which are then included in the witness script and committed to in the
188	/// BIP 143 signature.
189	///
190	/// An `Err` can be returned to signal that the signer is unavailable/cannot produce a valid
191	/// signature and should be retried later. Once the signer is ready to provide a signature after
192	/// previously returning an `Err`, [`ChannelMonitor::signer_unblocked`] must be called on its
193	/// monitor or [`ChainMonitor::signer_unblocked`] called to attempt unblocking all monitors.
194	///
195	/// [`ChannelMonitor::signer_unblocked`]: crate::chain::channelmonitor::ChannelMonitor::signer_unblocked
196	/// [`ChainMonitor::signer_unblocked`]: crate::chain::chainmonitor::ChainMonitor::signer_unblocked
197	fn sign_counterparty_htlc_transaction(
198		&self, channel_parameters: &ChannelTransactionParameters, htlc_tx: &Transaction,
199		input: usize, amount: u64, per_commitment_point: &PublicKey, htlc: &HTLCOutputInCommitment,
200		secp_ctx: &Secp256k1<secp256k1::All>,
201	) -> Result<Signature, ()>;
202	/// Create a signature for a (proposed) closing transaction.
203	///
204	/// Note that, due to rounding, there may be one "missing" satoshi, and either party may have
205	/// chosen to forgo their output as dust.
206	///
207	/// An `Err` can be returned to signal that the signer is unavailable/cannot produce a valid
208	/// signature and should be retried later. Once the signer is ready to provide a signature after
209	/// previously returning an `Err`, [`ChannelManager::signer_unblocked`] must be called.
210	///
211	/// [`ChannelManager::signer_unblocked`]: crate::ln::channelmanager::ChannelManager::signer_unblocked
212	fn sign_closing_transaction(
213		&self, channel_parameters: &ChannelTransactionParameters, closing_tx: &ClosingTransaction,
214		secp_ctx: &Secp256k1<secp256k1::All>,
215	) -> Result<Signature, ()>;
216	/// Computes the signature for a commitment transaction's keyed anchor output used as an
217	/// input within `anchor_tx`, which spends the commitment transaction, at index `input`.
218	///
219	/// An `Err` can be returned to signal that the signer is unavailable/cannot produce a valid
220	/// signature and should be retried later. Once the signer is ready to provide a signature after
221	/// previously returning an `Err`, [`ChannelMonitor::signer_unblocked`] must be called on its
222	/// monitor or [`ChainMonitor::signer_unblocked`] called to attempt unblocking all monitors.
223	///
224	/// [`ChannelMonitor::signer_unblocked`]: crate::chain::channelmonitor::ChannelMonitor::signer_unblocked
225	/// [`ChainMonitor::signer_unblocked`]: crate::chain::chainmonitor::ChainMonitor::signer_unblocked
226	fn sign_holder_keyed_anchor_input(
227		&self, channel_parameters: &ChannelTransactionParameters, anchor_tx: &Transaction,
228		input: usize, secp_ctx: &Secp256k1<secp256k1::All>,
229	) -> Result<Signature, ()>;
230	/// Signs a channel announcement message with our funding key proving it comes from one of the
231	/// channel participants.
232	///
233	/// Channel announcements also require a signature from each node's network key. Our node
234	/// signature is computed through [`NodeSigner::sign_gossip_message`].
235	///
236	/// This method is *not* asynchronous. If an `Err` is returned, the channel will not be
237	/// publicly announced and our counterparty may (though likely will not) close the channel on
238	/// us for violating the protocol.
239	///
240	/// [`NodeSigner::sign_gossip_message`]: crate::sign::NodeSigner::sign_gossip_message
241	fn sign_channel_announcement_with_funding_key(
242		&self, channel_parameters: &ChannelTransactionParameters,
243		msg: &UnsignedChannelAnnouncement, secp_ctx: &Secp256k1<secp256k1::All>,
244	) -> Result<Signature, ()>;
245
246	/// Signs the shared input of a splice transaction with our funding key.
247	///
248	/// In splicing, the previous funding transaction output is spent as the input of
249	/// the new funding transaction, and is a 2-of-2 multisig.
250	///
251	/// `channel_parameters`: The [`ChannelTransactionParameters`] for the channel's current funding
252	/// transaction that is being spent in the splice transaction to sign. A new set of
253	/// [`ChannelTransactionParameters`] will become available for the new funding transaction.
254	///
255	/// `input_index`: The index of the input within the new funding transaction `tx`,
256	///    spending the previous funding transaction's output
257	fn sign_splice_shared_input(
258		&self, channel_parameters: &ChannelTransactionParameters, tx: &Transaction,
259		input_index: usize, secp_ctx: &Secp256k1<secp256k1::All>,
260	) -> Signature;
261}
lightning/sign/ecdsa.rs

lightning/sign/
ecdsa.rs
