_ Git - rust-lightning/blob - lightning/src/sign/ecdsa.rs

   1 //! Defines ECDSA-specific signer types.
   2
   3 use bitcoin::blockdata::transaction::Transaction;
   4
   5 use bitcoin::secp256k1;
   6 use bitcoin::secp256k1::ecdsa::Signature;
   7 use bitcoin::secp256k1::{PublicKey, Secp256k1, SecretKey};
   8
   9 use crate::ln::chan_utils::{
  10         ClosingTransaction, CommitmentTransaction, HTLCOutputInCommitment, HolderCommitmentTransaction,
  11 };
  12 use crate::ln::msgs::UnsignedChannelAnnouncement;
  13 use crate::ln::types::PaymentPreimage;
  14
  15 #[allow(unused_imports)]
  16 use crate::prelude::*;
  17
  18 use 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 pub trait EcdsaChannelSigner: ChannelSigner {
  28         /// Create a signature for a counterparty's commitment transaction and associated HTLC transactions.
  29         ///
  30         /// Note that if signing fails or is rejected, the channel will be force-closed.
  31         ///
  32         /// Policy checks should be implemented in this function, including checking the amount
  33         /// sent to us and checking the HTLCs.
  34         ///
  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.
  39         ///
  40         /// Note that all the relevant preimages will be provided, but there may also be additional
  41         /// irrelevant or duplicate preimages.
  42         //
  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.
  49         ///
  50         /// This will be called
  51         /// - with a non-revoked `commitment_tx`.
  52         /// - with the latest `commitment_tx` when we initiate a force-close.
  53         ///
  54         /// This may be called multiple times for the same transaction.
  55         ///
  56         /// An external signer implementation should check that the commitment has not been revoked.
  57         ///
  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
  61         /// monitor.
  62         ///
  63         /// [`ChannelMonitor::signer_unblocked`]: crate::chain::channelmonitor::ChannelMonitor::signer_unblocked
  64         //
  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.
  79         ///
  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.
  84         ///
  85         /// Amount is value of the output spent by this input, committed to in the BIP 143 signature.
  86         ///
  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
  90         /// so).
  91         ///
  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
  95         /// monitor.
  96         ///
  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.
 104         ///
 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.
 109         ///
 110         /// `amount` is the value of the output spent by this input, committed to in the BIP 143
 111         /// signature.
 112         ///
 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
 116         /// so).
 117         ///
 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).
 120         ///
 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
 124         /// monitor.
 125         ///
 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`].
 134         ///
 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.
 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.
 143         ///
 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.
 153         ///
 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.
 158         ///
 159         /// `witness_script` is either an offered or received script as defined in BOLT3 for HTLC
 160         /// outputs.
 161         ///
 162         /// `amount` is value of the output spent by this input, committed to in the BIP 143 signature.
 163         ///
 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.
 168         ///
 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
 172         /// monitor.
 173         ///
 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.
 180         ///
 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`.
 188         ///
 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
 192         /// monitor.
 193         ///
 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.
 200         ///
 201         /// Channel announcements also require a signature from each node's network key. Our node
 202         /// signature is computed through [`NodeSigner::sign_gossip_message`].
 203         ///
 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
 206         /// protocol.
 207         ///
 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, ()>;
 212 }