use crate::ln::chan_utils::{HTLCOutputInCommitment, HolderCommitmentTransaction, CommitmentTransaction, ClosingTransaction};
use crate::ln::msgs::UnsignedChannelAnnouncement;
+#[allow(unused_imports)]
use crate::prelude::*;
+
use crate::sign::{ChannelSigner, HTLCDescriptor};
/// A trait to sign Lightning channel transactions as described in
/// 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<PaymentPreimage>, secp_ctx: &Secp256k1<secp256k1::All>
+ inbound_htlc_preimages: Vec<PaymentPreimage>,
+ outbound_htlc_preimages: Vec<PaymentPreimage>, secp_ctx: &Secp256k1<secp256k1::All>,
) -> Result<(Signature, Vec<Signature>), ()>;
- /// 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
/// 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,
/// 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).
+ ///
+ /// 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<secp256k1::All>
) -> Result<Signature, ()>;
///
/// `htlc` holds HTLC elements (hash, timelock), thus changing the format of the witness script
/// (which is committed to in the BIP 143 signatures).
+ ///
+ /// 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<secp256k1::All>) -> Result<Signature, ()>;
/// [`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
+ /// [`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<secp256k1::All>
) -> Result<Signature, ()>;
/// 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.
+ ///
+ /// 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<secp256k1::All>) -> Result<Signature, ()>;
secp_ctx: &Secp256k1<secp256k1::All>) -> Result<Signature, ()>;
/// 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<secp256k1::All>,
) -> Result<Signature, ()>;