|
| 1 | +//! Defines ECDSA-specific signer types. |
| 2 | +
|
| 3 | +use bitcoin::blockdata::transaction::Transaction; |
| 4 | + |
| 5 | +use bitcoin::secp256k1::{PublicKey, Secp256k1, SecretKey}; |
| 6 | +use bitcoin::secp256k1::ecdsa::Signature; |
| 7 | +use bitcoin::secp256k1; |
| 8 | + |
| 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; |
| 13 | + |
| 14 | +use crate::prelude::*; |
| 15 | +use crate::sign::{ChannelSigner, HTLCDescriptor}; |
| 16 | + |
| 17 | +/// A trait to sign Lightning channel transactions as described in |
| 18 | +/// [BOLT 3](https://github.com/lightning/bolts/blob/master/03-transactions.md). |
| 19 | +/// |
| 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. |
| 26 | + /// |
| 27 | + /// Note that if signing fails or is rejected, the channel will be force-closed. |
| 28 | + /// |
| 29 | + /// Policy checks should be implemented in this function, including checking the amount |
| 30 | + /// sent to us and checking the HTLCs. |
| 31 | + /// |
| 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. |
| 35 | + /// |
| 36 | + /// Note that all the relevant preimages will be provided, but there may also be additional |
| 37 | + /// irrelevant or duplicate preimages. |
| 38 | + // |
| 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 | + /// Validate the counterparty's revocation. |
| 44 | + /// |
| 45 | + /// This is required in order for the signer to make sure that the state has moved |
| 46 | + /// forward and it is safe to sign the next counterparty commitment. |
| 47 | + fn validate_counterparty_revocation(&self, idx: u64, secret: &SecretKey) -> Result<(), ()>; |
| 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 | + // TODO: Document the things someone using this interface should enforce before signing. |
| 59 | + fn sign_holder_commitment(&self, commitment_tx: &HolderCommitmentTransaction, |
| 60 | + secp_ctx: &Secp256k1<secp256k1::All>) -> Result<Signature, ()>; |
| 61 | + /// Same as [`sign_holder_commitment`], but exists only for tests to get access to holder |
| 62 | + /// commitment transactions which will be broadcasted later, after the channel has moved on to a |
| 63 | + /// newer state. Thus, needs its own method as [`sign_holder_commitment`] may enforce that we |
| 64 | + /// only ever get called once. |
| 65 | + #[cfg(any(test,feature = "unsafe_revoked_tx_signing"))] |
| 66 | + fn unsafe_sign_holder_commitment(&self, commitment_tx: &HolderCommitmentTransaction, |
| 67 | + secp_ctx: &Secp256k1<secp256k1::All>) -> Result<Signature, ()>; |
| 68 | + /// Create a signature for the given input in a transaction spending an HTLC transaction output |
| 69 | + /// or a commitment transaction `to_local` output when our counterparty broadcasts an old state. |
| 70 | + /// |
| 71 | + /// A justice transaction may claim multiple outputs at the same time if timelocks are |
| 72 | + /// similar, but only a signature for the input at index `input` should be signed for here. |
| 73 | + /// It may be called multiple times for same output(s) if a fee-bump is needed with regards |
| 74 | + /// to an upcoming timelock expiration. |
| 75 | + /// |
| 76 | + /// Amount is value of the output spent by this input, committed to in the BIP 143 signature. |
| 77 | + /// |
| 78 | + /// `per_commitment_key` is revocation secret which was provided by our counterparty when they |
| 79 | + /// revoked the state which they eventually broadcast. It's not a _holder_ secret key and does |
| 80 | + /// not allow the spending of any funds by itself (you need our holder `revocation_secret` to do |
| 81 | + /// so). |
| 82 | + fn sign_justice_revoked_output(&self, justice_tx: &Transaction, input: usize, amount: u64, |
| 83 | + per_commitment_key: &SecretKey, secp_ctx: &Secp256k1<secp256k1::All> |
| 84 | + ) -> 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. |
| 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 143 |
| 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 143 signatures). |
| 103 | + fn sign_justice_revoked_htlc(&self, justice_tx: &Transaction, input: usize, amount: u64, |
| 104 | + per_commitment_key: &SecretKey, htlc: &HTLCOutputInCommitment, |
| 105 | + secp_ctx: &Secp256k1<secp256k1::All>) -> Result<Signature, ()>; |
| 106 | + /// Computes the signature for a commitment transaction's HTLC output used as an input within |
| 107 | + /// `htlc_tx`, which spends the commitment transaction at index `input`. The signature returned |
| 108 | + /// must be be computed using [`EcdsaSighashType::All`]. |
| 109 | + /// |
| 110 | + /// Note that this may be called for HTLCs in the penultimate commitment transaction if a |
| 111 | + /// [`ChannelMonitor`] [replica](https://github.com/lightningdevkit/rust-lightning/blob/main/GLOSSARY.md#monitor-replicas) |
| 112 | + /// broadcasts it before receiving the update for the latest commitment transaction. |
| 113 | + /// |
| 114 | + /// [`EcdsaSighashType::All`]: bitcoin::blockdata::transaction::EcdsaSighashType::All |
| 115 | + /// [`ChannelMonitor`]: crate::chain::channelmonitor::ChannelMonitor |
| 116 | + fn sign_holder_htlc_transaction(&self, htlc_tx: &Transaction, input: usize, |
| 117 | + htlc_descriptor: &HTLCDescriptor, secp_ctx: &Secp256k1<secp256k1::All> |
| 118 | + ) -> Result<Signature, ()>; |
| 119 | + /// Create a signature for a claiming transaction for a HTLC output on a counterparty's commitment |
| 120 | + /// transaction, either offered or received. |
| 121 | + /// |
| 122 | + /// Such a transaction may claim multiples offered outputs at same time if we know the |
| 123 | + /// preimage for each when we create it, but only the input at index `input` should be |
| 124 | + /// signed for here. It may be called multiple times for same output(s) if a fee-bump is |
| 125 | + /// needed with regards to an upcoming timelock expiration. |
| 126 | + /// |
| 127 | + /// `witness_script` is either an offered or received script as defined in BOLT3 for HTLC |
| 128 | + /// outputs. |
| 129 | + /// |
| 130 | + /// `amount` is value of the output spent by this input, committed to in the BIP 143 signature. |
| 131 | + /// |
| 132 | + /// `per_commitment_point` is the dynamic point corresponding to the channel state |
| 133 | + /// detected onchain. It has been generated by our counterparty and is used to derive |
| 134 | + /// channel state keys, which are then included in the witness script and committed to in the |
| 135 | + /// BIP 143 signature. |
| 136 | + fn sign_counterparty_htlc_transaction(&self, htlc_tx: &Transaction, input: usize, amount: u64, |
| 137 | + per_commitment_point: &PublicKey, htlc: &HTLCOutputInCommitment, |
| 138 | + secp_ctx: &Secp256k1<secp256k1::All>) -> Result<Signature, ()>; |
| 139 | + /// Create a signature for a (proposed) closing transaction. |
| 140 | + /// |
| 141 | + /// Note that, due to rounding, there may be one "missing" satoshi, and either party may have |
| 142 | + /// chosen to forgo their output as dust. |
| 143 | + fn sign_closing_transaction(&self, closing_tx: &ClosingTransaction, |
| 144 | + secp_ctx: &Secp256k1<secp256k1::All>) -> Result<Signature, ()>; |
| 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 | + /// Signs a channel announcement message with our funding key proving it comes from one of the |
| 151 | + /// channel participants. |
| 152 | + /// |
| 153 | + /// Channel announcements also require a signature from each node's network key. Our node |
| 154 | + /// signature is computed through [`NodeSigner::sign_gossip_message`]. |
| 155 | + /// |
| 156 | + /// Note that if this fails or is rejected, the channel will not be publicly announced and |
| 157 | + /// our counterparty may (though likely will not) close the channel on us for violating the |
| 158 | + /// protocol. |
| 159 | + /// |
| 160 | + /// [`NodeSigner::sign_gossip_message`]: crate::sign::NodeSigner::sign_gossip_message |
| 161 | + fn sign_channel_announcement_with_funding_key( |
| 162 | + &self, msg: &UnsignedChannelAnnouncement, secp_ctx: &Secp256k1<secp256k1::All> |
| 163 | + ) -> Result<Signature, ()>; |
| 164 | +} |
| 165 | + |
| 166 | +/// A writeable signer. |
| 167 | +/// |
| 168 | +/// There will always be two instances of a signer per channel, one occupied by the |
| 169 | +/// [`ChannelManager`] and another by the channel's [`ChannelMonitor`]. |
| 170 | +/// |
| 171 | +/// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager |
| 172 | +/// [`ChannelMonitor`]: crate::chain::channelmonitor::ChannelMonitor |
| 173 | +pub trait WriteableEcdsaChannelSigner: EcdsaChannelSigner + Writeable {} |
0 commit comments