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

lightning/sign/
ecdsa.rs
