1 //! Defines ECDSA-specific signer types.
3 use bitcoin::blockdata::transaction::Transaction;
5 use bitcoin::secp256k1::{PublicKey, Secp256k1, SecretKey};
6 use bitcoin::secp256k1::ecdsa::Signature;
7 use bitcoin::secp256k1;
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;
14 use crate::prelude::*;
15 use crate::sign::{ChannelSigner, HTLCDescriptor};
17 /// A trait to sign Lightning channel transactions as described in
18 /// [BOLT 3](https://github.com/lightning/bolts/blob/master/03-transactions.md).
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.
27 /// Note that if signing fails or is rejected, the channel will be force-closed.
29 /// Policy checks should be implemented in this function, including checking the amount
30 /// sent to us and checking the HTLCs.
32 /// The preimages of outgoing HTLCs that were fulfilled since the last commitment are provided.
33 /// A validating signer should ensure that an HTLC output is removed only when the matching
34 /// preimage is provided, or when the value to holder is restored.
36 /// Note that all the relevant preimages will be provided, but there may also be additional
37 /// irrelevant or duplicate preimages.
39 // TODO: Document the things someone using this interface should enforce before signing.
40 fn sign_counterparty_commitment(&self, commitment_tx: &CommitmentTransaction,
41 preimages: Vec<PaymentPreimage>, secp_ctx: &Secp256k1<secp256k1::All>
42 ) -> Result<(Signature, Vec<Signature>), ()>;
43 /// Creates a signature for a holder's commitment transaction.
45 /// This will be called
46 /// - with a non-revoked `commitment_tx`.
47 /// - with the latest `commitment_tx` when we initiate a force-close.
49 /// This may be called multiple times for the same transaction.
51 /// An external signer implementation should check that the commitment has not been revoked.
53 // TODO: Document the things someone using this interface should enforce before signing.
54 fn sign_holder_commitment(&self, commitment_tx: &HolderCommitmentTransaction,
55 secp_ctx: &Secp256k1<secp256k1::All>) -> Result<Signature, ()>;
56 /// Same as [`sign_holder_commitment`], but exists only for tests to get access to holder
57 /// commitment transactions which will be broadcasted later, after the channel has moved on to a
58 /// newer state. Thus, needs its own method as [`sign_holder_commitment`] may enforce that we
59 /// only ever get called once.
60 #[cfg(any(test,feature = "unsafe_revoked_tx_signing"))]
61 fn unsafe_sign_holder_commitment(&self, commitment_tx: &HolderCommitmentTransaction,
62 secp_ctx: &Secp256k1<secp256k1::All>) -> Result<Signature, ()>;
63 /// Create a signature for the given input in a transaction spending an HTLC transaction output
64 /// or a commitment transaction `to_local` output when our counterparty broadcasts an old state.
66 /// A justice transaction may claim multiple outputs at the same time if timelocks are
67 /// similar, but only a signature for the input at index `input` should be signed for here.
68 /// It may be called multiple times for same output(s) if a fee-bump is needed with regards
69 /// to an upcoming timelock expiration.
71 /// Amount is value of the output spent by this input, committed to in the BIP 143 signature.
73 /// `per_commitment_key` is revocation secret which was provided by our counterparty when they
74 /// revoked the state which they eventually broadcast. It's not a _holder_ secret key and does
75 /// not allow the spending of any funds by itself (you need our holder `revocation_secret` to do
77 fn sign_justice_revoked_output(&self, justice_tx: &Transaction, input: usize, amount: u64,
78 per_commitment_key: &SecretKey, secp_ctx: &Secp256k1<secp256k1::All>
79 ) -> Result<Signature, ()>;
80 /// Create a signature for the given input in a transaction spending a commitment transaction
81 /// HTLC output when our counterparty broadcasts an old state.
83 /// A justice transaction may claim multiple outputs at the same time if timelocks are
84 /// similar, but only a signature for the input at index `input` should be signed for here.
85 /// It may be called multiple times for same output(s) if a fee-bump is needed with regards
86 /// to an upcoming timelock expiration.
88 /// `amount` is the value of the output spent by this input, committed to in the BIP 143
91 /// `per_commitment_key` is revocation secret which was provided by our counterparty when they
92 /// revoked the state which they eventually broadcast. It's not a _holder_ secret key and does
93 /// not allow the spending of any funds by itself (you need our holder revocation_secret to do
96 /// `htlc` holds HTLC elements (hash, timelock), thus changing the format of the witness script
97 /// (which is committed to in the BIP 143 signatures).
98 fn sign_justice_revoked_htlc(&self, justice_tx: &Transaction, input: usize, amount: u64,
99 per_commitment_key: &SecretKey, htlc: &HTLCOutputInCommitment,
100 secp_ctx: &Secp256k1<secp256k1::All>) -> Result<Signature, ()>;
101 /// Computes the signature for a commitment transaction's HTLC output used as an input within
102 /// `htlc_tx`, which spends the commitment transaction at index `input`. The signature returned
103 /// must be be computed using [`EcdsaSighashType::All`].
105 /// Note that this may be called for HTLCs in the penultimate commitment transaction if a
106 /// [`ChannelMonitor`] [replica](https://github.com/lightningdevkit/rust-lightning/blob/main/GLOSSARY.md#monitor-replicas)
107 /// broadcasts it before receiving the update for the latest commitment transaction.
109 /// [`EcdsaSighashType::All`]: bitcoin::sighash::EcdsaSighashType::All
110 /// [`ChannelMonitor`]: crate::chain::channelmonitor::ChannelMonitor
111 fn sign_holder_htlc_transaction(&self, htlc_tx: &Transaction, input: usize,
112 htlc_descriptor: &HTLCDescriptor, secp_ctx: &Secp256k1<secp256k1::All>
113 ) -> Result<Signature, ()>;
114 /// Create a signature for a claiming transaction for a HTLC output on a counterparty's commitment
115 /// transaction, either offered or received.
117 /// Such a transaction may claim multiples offered outputs at same time if we know the
118 /// preimage for each when we create it, but only the input at index `input` should be
119 /// signed for here. It may be called multiple times for same output(s) if a fee-bump is
120 /// needed with regards to an upcoming timelock expiration.
122 /// `witness_script` is either an offered or received script as defined in BOLT3 for HTLC
125 /// `amount` is value of the output spent by this input, committed to in the BIP 143 signature.
127 /// `per_commitment_point` is the dynamic point corresponding to the channel state
128 /// detected onchain. It has been generated by our counterparty and is used to derive
129 /// channel state keys, which are then included in the witness script and committed to in the
130 /// BIP 143 signature.
131 fn sign_counterparty_htlc_transaction(&self, htlc_tx: &Transaction, input: usize, amount: u64,
132 per_commitment_point: &PublicKey, htlc: &HTLCOutputInCommitment,
133 secp_ctx: &Secp256k1<secp256k1::All>) -> Result<Signature, ()>;
134 /// Create a signature for a (proposed) closing transaction.
136 /// Note that, due to rounding, there may be one "missing" satoshi, and either party may have
137 /// chosen to forgo their output as dust.
138 fn sign_closing_transaction(&self, closing_tx: &ClosingTransaction,
139 secp_ctx: &Secp256k1<secp256k1::All>) -> Result<Signature, ()>;
140 /// Computes the signature for a commitment transaction's anchor output used as an
141 /// input within `anchor_tx`, which spends the commitment transaction, at index `input`.
142 fn sign_holder_anchor_input(
143 &self, anchor_tx: &Transaction, input: usize, secp_ctx: &Secp256k1<secp256k1::All>,
144 ) -> Result<Signature, ()>;
145 /// Signs a channel announcement message with our funding key proving it comes from one of the
146 /// channel participants.
148 /// Channel announcements also require a signature from each node's network key. Our node
149 /// signature is computed through [`NodeSigner::sign_gossip_message`].
151 /// Note that if this fails or is rejected, the channel will not be publicly announced and
152 /// our counterparty may (though likely will not) close the channel on us for violating the
155 /// [`NodeSigner::sign_gossip_message`]: crate::sign::NodeSigner::sign_gossip_message
156 fn sign_channel_announcement_with_funding_key(
157 &self, msg: &UnsignedChannelAnnouncement, secp_ctx: &Secp256k1<secp256k1::All>
158 ) -> Result<Signature, ()>;
161 /// A writeable signer.
163 /// There will always be two instances of a signer per channel, one occupied by the
164 /// [`ChannelManager`] and another by the channel's [`ChannelMonitor`].
166 /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
167 /// [`ChannelMonitor`]: crate::chain::channelmonitor::ChannelMonitor
168 pub trait WriteableEcdsaChannelSigner: EcdsaChannelSigner + Writeable {}