1 //! Defines a Taproot-specific signer type.
4 use bitcoin::blockdata::transaction::Transaction;
5 use bitcoin::secp256k1;
6 use bitcoin::secp256k1::{schnorr::Signature, PublicKey, Secp256k1, SecretKey};
8 use musig2::types::{PartialSignature, PublicNonce};
10 use crate::ln::chan_utils::{
11 ClosingTransaction, CommitmentTransaction, HTLCOutputInCommitment, HolderCommitmentTransaction,
13 use crate::ln::msgs::PartialSignatureWithNonce;
14 use crate::ln::PaymentPreimage;
15 use crate::sign::{ChannelSigner, HTLCDescriptor};
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
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>,
27 /// Create a signature for a counterparty's commitment transaction and associated HTLC transactions.
29 /// Note that if signing fails or is rejected, the channel will be force-closed.
31 /// Policy checks should be implemented in this function, including checking the amount
32 /// sent to us and checking the HTLCs.
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.
39 /// Note that all the relevant preimages will be provided, but there may also be additional
40 /// irrelevant or duplicate preimages.
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>), ()>;
49 /// Creates a signature for a holder's commitment transaction.
51 /// This will be called
52 /// - with a non-revoked `commitment_tx`.
53 /// - with the latest `commitment_tx` when we initiate a force-close.
55 /// This may be called multiple times for the same transaction.
57 /// An external signer implementation should check that the commitment has not been revoked.
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, ()>;
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.
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.
74 /// Amount is value of the output spent by this input, committed to in the BIP 341 signature.
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
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, ()>;
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.
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.
93 /// `amount` is the value of the output spent by this input, committed to in the BIP 341
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
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, ()>;
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`].
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.
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, ()>;
124 /// Create a signature for a claiming transaction for a HTLC output on a counterparty's commitment
125 /// transaction, either offered or received.
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.
132 /// `witness_script` is either an offered or received script as defined in BOLT3 for HTLC
135 /// `amount` is value of the output spent by this input, committed to in the BIP 341 signature.
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, ()>;
146 /// Create a signature for a (proposed) closing transaction.
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, ()>;
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, ()>;
160 // TODO: sign channel announcement