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