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

   1 //! Defines a Taproot-specific signer type.
   2
   3 use alloc::vec::Vec;
   4 use bitcoin::blockdata::transaction::Transaction;
   5 use bitcoin::secp256k1;
   6 use bitcoin::secp256k1::{schnorr::Signature, PublicKey, Secp256k1, SecretKey};
   7
   8 use musig2::types::{PartialSignature, PublicNonce};
   9
  10 use crate::ln::chan_utils::{
  11         ClosingTransaction, CommitmentTransaction, HTLCOutputInCommitment, HolderCommitmentTransaction,
  12 };
  13 use crate::ln::msgs::PartialSignatureWithNonce;
  14 use crate::ln::PaymentPreimage;
  15 use crate::sign::{ChannelSigner, HTLCDescriptor};
  16
  17 /// A Taproot-specific signer type that defines signing-related methods that are either unique to
  18 /// Taproot or have argument or return types that differ from the ones an ECDSA signer would be
  19 /// expected to have.
  20 pub trait TaprootChannelSigner: ChannelSigner {
  21         /// Generate a local nonce pair, which requires committing to ahead of time.
  22         /// The counterparty needs the public nonce generated herein to compute a partial signature.
  23         fn generate_local_nonce_pair(
  24                 &self, commitment_number: u64, secp_ctx: &Secp256k1<secp256k1::All>,
  25         ) -> PublicNonce;
  26
  27         /// Create a signature for a counterparty's commitment transaction and associated HTLC transactions.
  28         ///
  29         /// Note that if signing fails or is rejected, the channel will be force-closed.
  30         ///
  31         /// Policy checks should be implemented in this function, including checking the amount
  32         /// sent to us and checking the HTLCs.
  33         ///
  34         /// The preimages of outbound and inbound HTLCs that were fulfilled since the last commitment
  35         /// are provided. A validating signer should ensure that an outbound HTLC output is removed
  36         /// only when the matching preimage is provided and after the corresponding inbound HTLC has
  37         /// been removed for forwarded payments.
  38         ///
  39         /// Note that all the relevant preimages will be provided, but there may also be additional
  40         /// irrelevant or duplicate preimages.
  41         //
  42         // TODO: Document the things someone using this interface should enforce before signing.
  43         fn partially_sign_counterparty_commitment(
  44                 &self, counterparty_nonce: PublicNonce, commitment_tx: &CommitmentTransaction,
  45                 inbound_htlc_preimages: Vec<PaymentPreimage>,
  46                 outbound_htlc_preimages: Vec<PaymentPreimage>, secp_ctx: &Secp256k1<secp256k1::All>,
  47         ) -> Result<(PartialSignatureWithNonce, Vec<Signature>), ()>;
  48
  49         /// Creates a signature for a holder's commitment transaction.
  50         ///
  51         /// This will be called
  52         /// - with a non-revoked `commitment_tx`.
  53         /// - with the latest `commitment_tx` when we initiate a force-close.
  54         ///
  55         /// This may be called multiple times for the same transaction.
  56         ///
  57         /// An external signer implementation should check that the commitment has not been revoked.
  58         ///
  59         // TODO: Document the things someone using this interface should enforce before signing.
  60         fn finalize_holder_commitment(
  61                 &self, commitment_tx: &HolderCommitmentTransaction,
  62                 counterparty_partial_signature: PartialSignatureWithNonce,
  63                 secp_ctx: &Secp256k1<secp256k1::All>,
  64         ) -> Result<PartialSignature, ()>;
  65
  66         /// Create a signature for the given input in a transaction spending an HTLC transaction output
  67         /// or a commitment transaction `to_local` output when our counterparty broadcasts an old state.
  68         ///
  69         /// A justice transaction may claim multiple outputs at the same time if timelocks are
  70         /// similar, but only a signature for the input at index `input` should be signed for here.
  71         /// It may be called multiple times for same output(s) if a fee-bump is needed with regards
  72         /// to an upcoming timelock expiration.
  73         ///
  74         /// Amount is value of the output spent by this input, committed to in the BIP 341 signature.
  75         ///
  76         /// `per_commitment_key` is revocation secret which was provided by our counterparty when they
  77         /// revoked the state which they eventually broadcast. It's not a _holder_ secret key and does
  78         /// not allow the spending of any funds by itself (you need our holder `revocation_secret` to do
  79         /// so).
  80         fn sign_justice_revoked_output(
  81                 &self, justice_tx: &Transaction, input: usize, amount: u64, per_commitment_key: &SecretKey,
  82                 secp_ctx: &Secp256k1<secp256k1::All>,
  83         ) -> Result<Signature, ()>;
  84
  85         /// Create a signature for the given input in a transaction spending a commitment transaction
  86         /// HTLC output when our counterparty broadcasts an old state.
  87         ///
  88         /// A justice transaction may claim multiple outputs at the same time if timelocks are
  89         /// similar, but only a signature for the input at index `input` should be signed for here.
  90         /// It may be called multiple times for same output(s) if a fee-bump is needed with regards
  91         /// to an upcoming timelock expiration.
  92         ///
  93         /// `amount` is the value of the output spent by this input, committed to in the BIP 341
  94         /// signature.
  95         ///
  96         /// `per_commitment_key` is revocation secret which was provided by our counterparty when they
  97         /// revoked the state which they eventually broadcast. It's not a _holder_ secret key and does
  98         /// not allow the spending of any funds by itself (you need our holder revocation_secret to do
  99         /// so).
 100         ///
 101         /// `htlc` holds HTLC elements (hash, timelock), thus changing the format of the witness script
 102         /// (which is committed to in the BIP 341 signatures).
 103         fn sign_justice_revoked_htlc(
 104                 &self, justice_tx: &Transaction, input: usize, amount: u64, per_commitment_key: &SecretKey,
 105                 htlc: &HTLCOutputInCommitment, secp_ctx: &Secp256k1<secp256k1::All>,
 106         ) -> Result<Signature, ()>;
 107
 108         /// Computes the signature for a commitment transaction's HTLC output used as an input within
 109         /// `htlc_tx`, which spends the commitment transaction at index `input`. The signature returned
 110         /// must be be computed using [`TapSighashType::Default`].
 111         ///
 112         /// Note that this may be called for HTLCs in the penultimate commitment transaction if a
 113         /// [`ChannelMonitor`] [replica](https://github.com/lightningdevkit/rust-lightning/blob/main/GLOSSARY.md#monitor-replicas)
 114         /// broadcasts it before receiving the update for the latest commitment transaction.
 115         ///
 116         ///
 117         /// [`TapSighashType::Default`]: bitcoin::sighash::TapSighashType::Default
 118         /// [`ChannelMonitor`]: crate::chain::channelmonitor::ChannelMonitor
 119         fn sign_holder_htlc_transaction(
 120                 &self, htlc_tx: &Transaction, input: usize, htlc_descriptor: &HTLCDescriptor,
 121                 secp_ctx: &Secp256k1<secp256k1::All>,
 122         ) -> Result<Signature, ()>;
 123
 124         /// Create a signature for a claiming transaction for a HTLC output on a counterparty's commitment
 125         /// transaction, either offered or received.
 126         ///
 127         /// Such a transaction may claim multiples offered outputs at same time if we know the
 128         /// preimage for each when we create it, but only the input at index `input` should be
 129         /// signed for here. It may be called multiple times for same output(s) if a fee-bump is
 130         /// needed with regards to an upcoming timelock expiration.
 131         ///
 132         /// `witness_script` is either an offered or received script as defined in BOLT3 for HTLC
 133         /// outputs.
 134         ///
 135         /// `amount` is value of the output spent by this input, committed to in the BIP 341 signature.
 136         ///
 137         /// `per_commitment_point` is the dynamic point corresponding to the channel state
 138         /// detected onchain. It has been generated by our counterparty and is used to derive
 139         /// channel state keys, which are then included in the witness script and committed to in the
 140         /// BIP 341 signature.
 141         fn sign_counterparty_htlc_transaction(
 142                 &self, htlc_tx: &Transaction, input: usize, amount: u64, per_commitment_point: &PublicKey,
 143                 htlc: &HTLCOutputInCommitment, secp_ctx: &Secp256k1<secp256k1::All>,
 144         ) -> Result<Signature, ()>;
 145
 146         /// Create a signature for a (proposed) closing transaction.
 147         ///
 148         /// Note that, due to rounding, there may be one "missing" satoshi, and either party may have
 149         /// chosen to forgo their output as dust.
 150         fn partially_sign_closing_transaction(
 151                 &self, closing_tx: &ClosingTransaction, secp_ctx: &Secp256k1<secp256k1::All>,
 152         ) -> Result<PartialSignature, ()>;
 153
 154         /// Computes the signature for a commitment transaction's anchor output used as an
 155         /// input within `anchor_tx`, which spends the commitment transaction, at index `input`.
 156         fn sign_holder_anchor_input(
 157                 &self, anchor_tx: &Transaction, input: usize, secp_ctx: &Secp256k1<secp256k1::All>,
 158         ) -> Result<Signature, ()>;
 159
 160         // TODO: sign channel announcement
 161 }