X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning%2Fsrc%2Fsign%2Fecdsa.rs;h=aa22eb366f3065e23199678988329bc63bab347a;hb=b6059e9f3942498b0cbf056f25bc3ed37d4cc2bc;hp=c9677c8ba250245084e7ddf1dbed8b5be59b194b;hpb=88ce7d6575dd376e98e680d0c0813c7b79151773;p=rust-lightning diff --git a/lightning/src/sign/ecdsa.rs b/lightning/src/sign/ecdsa.rs index c9677c8b..aa22eb36 100644 --- a/lightning/src/sign/ecdsa.rs +++ b/lightning/src/sign/ecdsa.rs @@ -2,16 +2,20 @@ use bitcoin::blockdata::transaction::Transaction; -use bitcoin::secp256k1::{PublicKey, Secp256k1, SecretKey}; -use bitcoin::secp256k1::ecdsa::Signature; use bitcoin::secp256k1; +use bitcoin::secp256k1::ecdsa::Signature; +use bitcoin::secp256k1::{PublicKey, Secp256k1, SecretKey}; -use crate::util::ser::Writeable; -use crate::ln::PaymentPreimage; -use crate::ln::chan_utils::{HTLCOutputInCommitment, HolderCommitmentTransaction, CommitmentTransaction, ClosingTransaction}; +use crate::ln::chan_utils::{ + ClosingTransaction, CommitmentTransaction, HTLCOutputInCommitment, HolderCommitmentTransaction, +}; use crate::ln::msgs::UnsignedChannelAnnouncement; +use crate::ln::PaymentPreimage; +use crate::util::ser::Writeable; +#[allow(unused_imports)] use crate::prelude::*; + use crate::sign::{ChannelSigner, HTLCDescriptor}; /// A trait to sign Lightning channel transactions as described in @@ -29,22 +33,19 @@ pub trait EcdsaChannelSigner: ChannelSigner { /// Policy checks should be implemented in this function, including checking the amount /// sent to us and checking the HTLCs. /// - /// The preimages of outgoing HTLCs that were fulfilled since the last commitment are provided. - /// A validating signer should ensure that an HTLC output is removed only when the matching - /// preimage is provided, or when the value to holder is restored. + /// The preimages of outbound and inbound HTLCs that were fulfilled since the last commitment + /// are provided. A validating signer should ensure that an outbound HTLC output is removed + /// only when the matching preimage is provided and after the corresponding inbound HTLC has + /// been removed for forwarded payments. /// /// Note that all the relevant preimages will be provided, but there may also be additional /// irrelevant or duplicate preimages. // // TODO: Document the things someone using this interface should enforce before signing. - fn sign_counterparty_commitment(&self, commitment_tx: &CommitmentTransaction, - preimages: Vec, secp_ctx: &Secp256k1 + fn sign_counterparty_commitment( + &self, commitment_tx: &CommitmentTransaction, inbound_htlc_preimages: Vec, + outbound_htlc_preimages: Vec, secp_ctx: &Secp256k1, ) -> Result<(Signature, Vec), ()>; - /// Validate the counterparty's revocation. - /// - /// This is required in order for the signer to make sure that the state has moved - /// forward and it is safe to sign the next counterparty commitment. - fn validate_counterparty_revocation(&self, idx: u64, secret: &SecretKey) -> Result<(), ()>; /// Creates a signature for a holder's commitment transaction. /// /// This will be called @@ -54,17 +55,26 @@ pub trait EcdsaChannelSigner: ChannelSigner { /// This may be called multiple times for the same transaction. /// /// An external signer implementation should check that the commitment has not been revoked. + /// + /// An `Err` can be returned to signal that the signer is unavailable/cannot produce a valid + /// signature and should be retried later. Once the signer is ready to provide a signature after + /// previously returning an `Err`, [`ChannelMonitor::signer_unblocked`] must be called on its + /// monitor. + /// + /// [`ChannelMonitor::signer_unblocked`]: crate::chain::channelmonitor::ChannelMonitor::signer_unblocked // // TODO: Document the things someone using this interface should enforce before signing. - fn sign_holder_commitment(&self, commitment_tx: &HolderCommitmentTransaction, - secp_ctx: &Secp256k1) -> Result; + fn sign_holder_commitment( + &self, commitment_tx: &HolderCommitmentTransaction, secp_ctx: &Secp256k1, + ) -> Result; /// Same as [`sign_holder_commitment`], but exists only for tests to get access to holder /// commitment transactions which will be broadcasted later, after the channel has moved on to a /// newer state. Thus, needs its own method as [`sign_holder_commitment`] may enforce that we /// only ever get called once. - #[cfg(any(test,feature = "unsafe_revoked_tx_signing"))] - fn unsafe_sign_holder_commitment(&self, commitment_tx: &HolderCommitmentTransaction, - secp_ctx: &Secp256k1) -> Result; + #[cfg(any(test, feature = "unsafe_revoked_tx_signing"))] + fn unsafe_sign_holder_commitment( + &self, commitment_tx: &HolderCommitmentTransaction, secp_ctx: &Secp256k1, + ) -> Result; /// Create a signature for the given input in a transaction spending an HTLC transaction output /// or a commitment transaction `to_local` output when our counterparty broadcasts an old state. /// @@ -79,8 +89,16 @@ pub trait EcdsaChannelSigner: ChannelSigner { /// revoked the state which they eventually broadcast. It's not a _holder_ secret key and does /// not allow the spending of any funds by itself (you need our holder `revocation_secret` to do /// so). - fn sign_justice_revoked_output(&self, justice_tx: &Transaction, input: usize, amount: u64, - per_commitment_key: &SecretKey, secp_ctx: &Secp256k1 + /// + /// An `Err` can be returned to signal that the signer is unavailable/cannot produce a valid + /// signature and should be retried later. Once the signer is ready to provide a signature after + /// previously returning an `Err`, [`ChannelMonitor::signer_unblocked`] must be called on its + /// monitor. + /// + /// [`ChannelMonitor::signer_unblocked`]: crate::chain::channelmonitor::ChannelMonitor::signer_unblocked + fn sign_justice_revoked_output( + &self, justice_tx: &Transaction, input: usize, amount: u64, per_commitment_key: &SecretKey, + secp_ctx: &Secp256k1, ) -> Result; /// Create a signature for the given input in a transaction spending a commitment transaction /// HTLC output when our counterparty broadcasts an old state. @@ -100,9 +118,17 @@ pub trait EcdsaChannelSigner: ChannelSigner { /// /// `htlc` holds HTLC elements (hash, timelock), thus changing the format of the witness script /// (which is committed to in the BIP 143 signatures). - fn sign_justice_revoked_htlc(&self, justice_tx: &Transaction, input: usize, amount: u64, - per_commitment_key: &SecretKey, htlc: &HTLCOutputInCommitment, - secp_ctx: &Secp256k1) -> Result; + /// + /// An `Err` can be returned to signal that the signer is unavailable/cannot produce a valid + /// signature and should be retried later. Once the signer is ready to provide a signature after + /// previously returning an `Err`, [`ChannelMonitor::signer_unblocked`] must be called on its + /// monitor. + /// + /// [`ChannelMonitor::signer_unblocked`]: crate::chain::channelmonitor::ChannelMonitor::signer_unblocked + fn sign_justice_revoked_htlc( + &self, justice_tx: &Transaction, input: usize, amount: u64, per_commitment_key: &SecretKey, + htlc: &HTLCOutputInCommitment, secp_ctx: &Secp256k1, + ) -> Result; /// Computes the signature for a commitment transaction's HTLC output used as an input within /// `htlc_tx`, which spends the commitment transaction at index `input`. The signature returned /// must be be computed using [`EcdsaSighashType::All`]. @@ -111,10 +137,17 @@ pub trait EcdsaChannelSigner: ChannelSigner { /// [`ChannelMonitor`] [replica](https://github.com/lightningdevkit/rust-lightning/blob/main/GLOSSARY.md#monitor-replicas) /// broadcasts it before receiving the update for the latest commitment transaction. /// + /// An `Err` can be returned to signal that the signer is unavailable/cannot produce a valid + /// signature and should be retried later. Once the signer is ready to provide a signature after + /// previously returning an `Err`, [`ChannelMonitor::signer_unblocked`] must be called on its + /// monitor. + /// /// [`EcdsaSighashType::All`]: bitcoin::sighash::EcdsaSighashType::All /// [`ChannelMonitor`]: crate::chain::channelmonitor::ChannelMonitor - fn sign_holder_htlc_transaction(&self, htlc_tx: &Transaction, input: usize, - htlc_descriptor: &HTLCDescriptor, secp_ctx: &Secp256k1 + /// [`ChannelMonitor::signer_unblocked`]: crate::chain::channelmonitor::ChannelMonitor::signer_unblocked + fn sign_holder_htlc_transaction( + &self, htlc_tx: &Transaction, input: usize, htlc_descriptor: &HTLCDescriptor, + secp_ctx: &Secp256k1, ) -> Result; /// Create a signature for a claiming transaction for a HTLC output on a counterparty's commitment /// transaction, either offered or received. @@ -133,17 +166,33 @@ pub trait EcdsaChannelSigner: ChannelSigner { /// detected onchain. It has been generated by our counterparty and is used to derive /// channel state keys, which are then included in the witness script and committed to in the /// BIP 143 signature. - fn sign_counterparty_htlc_transaction(&self, htlc_tx: &Transaction, input: usize, amount: u64, - per_commitment_point: &PublicKey, htlc: &HTLCOutputInCommitment, - secp_ctx: &Secp256k1) -> Result; + /// + /// An `Err` can be returned to signal that the signer is unavailable/cannot produce a valid + /// signature and should be retried later. Once the signer is ready to provide a signature after + /// previously returning an `Err`, [`ChannelMonitor::signer_unblocked`] must be called on its + /// monitor. + /// + /// [`ChannelMonitor::signer_unblocked`]: crate::chain::channelmonitor::ChannelMonitor::signer_unblocked + fn sign_counterparty_htlc_transaction( + &self, htlc_tx: &Transaction, input: usize, amount: u64, per_commitment_point: &PublicKey, + htlc: &HTLCOutputInCommitment, secp_ctx: &Secp256k1, + ) -> Result; /// Create a signature for a (proposed) closing transaction. /// /// Note that, due to rounding, there may be one "missing" satoshi, and either party may have /// chosen to forgo their output as dust. - fn sign_closing_transaction(&self, closing_tx: &ClosingTransaction, - secp_ctx: &Secp256k1) -> Result; + fn sign_closing_transaction( + &self, closing_tx: &ClosingTransaction, secp_ctx: &Secp256k1, + ) -> Result; /// Computes the signature for a commitment transaction's anchor output used as an /// input within `anchor_tx`, which spends the commitment transaction, at index `input`. + /// + /// An `Err` can be returned to signal that the signer is unavailable/cannot produce a valid + /// signature and should be retried later. Once the signer is ready to provide a signature after + /// previously returning an `Err`, [`ChannelMonitor::signer_unblocked`] must be called on its + /// monitor. + /// + /// [`ChannelMonitor::signer_unblocked`]: crate::chain::channelmonitor::ChannelMonitor::signer_unblocked fn sign_holder_anchor_input( &self, anchor_tx: &Transaction, input: usize, secp_ctx: &Secp256k1, ) -> Result; @@ -159,7 +208,7 @@ pub trait EcdsaChannelSigner: ChannelSigner { /// /// [`NodeSigner::sign_gossip_message`]: crate::sign::NodeSigner::sign_gossip_message fn sign_channel_announcement_with_funding_key( - &self, msg: &UnsignedChannelAnnouncement, secp_ctx: &Secp256k1 + &self, msg: &UnsignedChannelAnnouncement, secp_ctx: &Secp256k1, ) -> Result; }