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