Skip to content

Introduce FundingTransactionReadyForSignatures event #3889

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
+215 −68
Open

Introduce FundingTransactionReadyForSignatures event #3889

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
dbed102
Introduce `FundingTransactionReadyForSignatures` event
dunxen Apr 14, 2025
32e93ac
f only emit FundingTransactionReadyForSigning on initial commitment_s…
dunxen Jul 8, 2025
894caef
f remove TODOs sighash_all checks
dunxen Jul 8, 2025
a9e1a3a
Use bool for `monitor_pending_tx_signatures` over `Option<TxSignatures>`
dunxen Jul 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 48 additions & 0 deletions lightning/src/events/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1654,6 +1654,48 @@ pub enum Event {
/// [`ChannelManager::send_static_invoice`]: crate::ln::channelmanager::ChannelManager::send_static_invoice
reply_path: Responder,
},
/// Indicates that a channel funding transaction constructed interactively is ready to be
/// signed. This event will only be triggered if at least one input was contributed.
///
/// The transaction contains all inputs provided by both parties along with the channel's funding
/// output and a change output if applicable.
///
/// No part of the transaction should be changed before signing as the content of the transaction
/// has already been negotiated with the counterparty.
///
/// Each signature MUST use the `SIGHASH_ALL` flag to avoid invalidation of the initial commitment and
/// hence possible loss of funds.
///
/// After signing, call [`ChannelManager::funding_transaction_signed`] with the (partially) signed
/// funding transaction.
///
/// Generated in [`ChannelManager`] message handling.
///
/// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
/// [`ChannelManager::funding_transaction_signed`]: crate::ln::channelmanager::ChannelManager::funding_transaction_signed
FundingTransactionReadyForSigning {
/// The channel_id of the channel which you'll need to pass back into
/// [`ChannelManager::funding_transaction_signed`].
///
/// [`ChannelManager::funding_transaction_signed`]: crate::ln::channelmanager::ChannelManager::funding_transaction_signed
channel_id: ChannelId,
/// The counterparty's node_id, which you'll need to pass back into
/// [`ChannelManager::funding_transaction_signed`].
///
/// [`ChannelManager::funding_transaction_signed`]: crate::ln::channelmanager::ChannelManager::funding_transaction_signed
counterparty_node_id: PublicKey,
/// The `user_channel_id` value passed in for outbound channels, or for inbound channels if
/// [`UserConfig::manually_accept_inbound_channels`] config flag is set to true. Otherwise
/// `user_channel_id` will be randomized for inbound channels.
///
/// [`UserConfig::manually_accept_inbound_channels`]: crate::util::config::UserConfig::manually_accept_inbound_channels
user_channel_id: u128,
/// The unsigned transaction to be signed and passed back to
/// [`ChannelManager::funding_transaction_signed`].
///
/// [`ChannelManager::funding_transaction_signed`]: crate::ln::channelmanager::ChannelManager::funding_transaction_signed
unsigned_transaction: Transaction,
},
}

impl Writeable for Event {
Expand Down Expand Up @@ -2095,6 +2137,10 @@ impl Writeable for Event {
47u8.write(writer)?;
// Never write StaticInvoiceRequested events as buffered onion messages aren't serialized.
},
&Event::FundingTransactionReadyForSigning { .. } => {
49u8.write(writer)?;
// We never write out FundingTransactionReadyForSigning events as they will be regenerated necessary.
},
// Note that, going forward, all new events must only write data inside of
// `write_tlv_fields`. Versions 0.0.101+ will ignore odd-numbered events that write
// data via `write_tlv_fields`.
Expand Down Expand Up @@ -2672,6 +2718,8 @@ impl MaybeReadable for Event {
// Note that we do not write a length-prefixed TLV for StaticInvoiceRequested events.
#[cfg(async_payments)]
47u8 => Ok(None),
// Note that we do not write a length-prefixed TLV for FundingTransactionReadyForSigning events.
49u8 => Ok(None),
// Versions prior to 0.0.100 did not ignore odd types, instead returning InvalidValue.
// Version 0.0.100 failed to properly ignore odd types, possibly resulting in corrupt
// reads.
Expand Down
120 changes: 62 additions & 58 deletions lightning/src/ln/channel.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ use bitcoin::constants::ChainHash;
use bitcoin::script::{Builder, Script, ScriptBuf, WScriptHash};
use bitcoin::sighash::EcdsaSighashType;
use bitcoin::transaction::{Transaction, TxIn, TxOut};
use bitcoin::Weight;
use bitcoin::{Weight, Witness};

use bitcoin::hash_types::{BlockHash, Txid};
use bitcoin::hashes::sha256::Hash as Sha256;
Expand All @@ -36,7 +36,7 @@ use crate::chain::channelmonitor::{
use crate::chain::transaction::{OutPoint, TransactionData};
use crate::chain::BestBlock;
use crate::events::bump_transaction::BASE_INPUT_WEIGHT;
use crate::events::{ClosureReason, Event};
use crate::events::ClosureReason;
use crate::ln::chan_utils;
#[cfg(splicing)]
use crate::ln::chan_utils::FUNDING_TRANSACTION_WITNESS_WEIGHT;
Expand Down Expand Up @@ -1766,7 +1766,7 @@ where

pub fn funding_tx_constructed<L: Deref>(
&mut self, signing_session: InteractiveTxSigningSession, logger: &L,
) -> Result<(msgs::CommitmentSigned, Option<Event>), ChannelError>
) -> Result<msgs::CommitmentSigned, ChannelError>
where
L::Target: Logger,
{
Expand All @@ -1788,7 +1788,7 @@ where
#[rustfmt::skip]
pub fn commitment_signed<L: Deref>(
&mut self, msg: &msgs::CommitmentSigned, best_block: BestBlock, signer_provider: &SP, logger: &L
) -> Result<(Option<ChannelMonitor<<SP::Target as SignerProvider>::EcdsaSigner>>, Option<ChannelMonitorUpdate>), ChannelError>
) -> Result<(Option<ChannelMonitor<<SP::Target as SignerProvider>::EcdsaSigner>>, Option<ChannelMonitorUpdate>, Option<Transaction>), ChannelError>
where
L::Target: Logger
{
Expand All @@ -1815,7 +1815,7 @@ where
pending_splice: None,
};
let res = funded_channel.commitment_signed_initial_v2(msg, best_block, signer_provider, logger)
.map(|monitor| (Some(monitor), None))
.map(|(monitor, funding_tx_opt)| (Some(monitor), None, funding_tx_opt))
// TODO: Change to `inspect_err` when MSRV is high enough.
.map_err(|err| {
// We always expect a `ChannelError` close.
Expand All @@ -1842,15 +1842,15 @@ where
let res = if has_negotiated_pending_splice && !session_received_commitment_signed {
funded_channel
.splice_initial_commitment_signed(msg, logger)
.map(|monitor_update_opt| (None, monitor_update_opt))
.map(|monitor_update_opt| (None, monitor_update_opt, None))
} else {
funded_channel.commitment_signed(msg, logger)
.map(|monitor_update_opt| (None, monitor_update_opt))
.map(|monitor_update_opt| (None, monitor_update_opt, None))
};

#[cfg(not(splicing))]
let res = funded_channel.commitment_signed(msg, logger)
.map(|monitor_update_opt| (None, monitor_update_opt));
.map(|monitor_update_opt| (None, monitor_update_opt, None));

self.phase = ChannelPhase::Funded(funded_channel);
res
Expand Down Expand Up @@ -2317,7 +2317,7 @@ where
monitor_pending_failures: Vec<(HTLCSource, PaymentHash, HTLCFailReason)>,
monitor_pending_finalized_fulfills: Vec<HTLCSource>,
monitor_pending_update_adds: Vec<msgs::UpdateAddHTLC>,
monitor_pending_tx_signatures: Option<msgs::TxSignatures>,
monitor_pending_tx_signatures: bool,

/// If we went to send a revoke_and_ack but our signer was unable to give us a signature,
/// we should retry at some point in the future when the signer indicates it may have a
Expand Down Expand Up @@ -2928,7 +2928,7 @@ where
#[rustfmt::skip]
pub fn funding_tx_constructed<L: Deref>(
&mut self, mut signing_session: InteractiveTxSigningSession, logger: &L
) -> Result<(msgs::CommitmentSigned, Option<Event>), ChannelError>
) -> Result<msgs::CommitmentSigned, ChannelError>
where
L::Target: Logger
{
Expand Down Expand Up @@ -2970,7 +2970,8 @@ where
},
};

let funding_ready_for_sig_event = if signing_session.local_inputs_count() == 0 {
// Check that we have the expected number of local inputs
if signing_session.local_inputs_count() == 0 {
debug_assert_eq!(our_funding_satoshis, 0);
if signing_session.provide_holder_witnesses(self.context.channel_id, Vec::new()).is_err() {
debug_assert!(
Expand All @@ -2982,31 +2983,7 @@ where
ClosureReason::HolderForceClosed { broadcasted_latest_txn: Some(false) }
)));
}
None
} else {
// TODO(dual_funding): Send event for signing if we've contributed funds.
// Inform the user that SIGHASH_ALL must be used for all signatures when contributing
// inputs/signatures.
// Also warn the user that we don't do anything to prevent the counterparty from
// providing non-standard witnesses which will prevent the funding transaction from
// confirming. This warning must appear in doc comments wherever the user is contributing
// funds, whether they are initiator or acceptor.
//
// The following warning can be used when the APIs allowing contributing inputs become available:
// <div class="warning">
// WARNING: LDK makes no attempt to prevent the counterparty from using non-standard inputs which
// will prevent the funding transaction from being relayed on the bitcoin network and hence being
// confirmed.
// </div>
debug_assert!(
false,
"We don't support users providing inputs but somehow we had more than zero inputs",
);
return Err(ChannelError::Close((
"V2 channel rejected due to sender error".into(),
ClosureReason::HolderForceClosed { broadcasted_latest_txn: Some(false) }
)));
};
}

let mut channel_state = ChannelState::FundingNegotiated(FundingNegotiatedFlags::new());
channel_state.set_interactive_signing();
Expand All @@ -3016,7 +2993,7 @@ where
self.interactive_tx_constructor.take();
self.interactive_tx_signing_session = Some(signing_session);

Ok((commitment_signed, funding_ready_for_sig_event))
Ok(commitment_signed)
}
}

Expand Down Expand Up @@ -3298,7 +3275,7 @@ where
monitor_pending_failures: Vec::new(),
monitor_pending_finalized_fulfills: Vec::new(),
monitor_pending_update_adds: Vec::new(),
monitor_pending_tx_signatures: None,
monitor_pending_tx_signatures: false,

signer_pending_revoke_and_ack: false,
signer_pending_commitment_update: false,
Expand Down Expand Up @@ -3544,7 +3521,7 @@ where
monitor_pending_failures: Vec::new(),
monitor_pending_finalized_fulfills: Vec::new(),
monitor_pending_update_adds: Vec::new(),
monitor_pending_tx_signatures: None,
monitor_pending_tx_signatures: false,

signer_pending_revoke_and_ack: false,
signer_pending_commitment_update: false,
Expand Down Expand Up @@ -6653,7 +6630,7 @@ where
#[rustfmt::skip]
pub fn commitment_signed_initial_v2<L: Deref>(
&mut self, msg: &msgs::CommitmentSigned, best_block: BestBlock, signer_provider: &SP, logger: &L
) -> Result<ChannelMonitor<<SP::Target as SignerProvider>::EcdsaSigner>, ChannelError>
) -> Result<(ChannelMonitor<<SP::Target as SignerProvider>::EcdsaSigner>, Option<Transaction>), ChannelError>
where L::Target: Logger
{
if !self.context.channel_state.is_interactive_signing()
Expand All @@ -6677,15 +6654,18 @@ where

self.monitor_updating_paused(false, false, false, Vec::new(), Vec::new(), Vec::new());

if let Some(tx_signatures) = self.interactive_tx_signing_session.as_mut().and_then(
if let Some(_) = self.interactive_tx_signing_session.as_mut().and_then(
|session| session.received_commitment_signed()
) {
// We're up first for submitting our tx_signatures, but our monitor has not persisted yet
// so they'll be sent as soon as that's done.
self.context.monitor_pending_tx_signatures = Some(tx_signatures);
self.context.monitor_pending_tx_signatures = true;
}
// Only build the unsigned transaction for signing if there are any holder inputs to actually sign
let funding_tx_opt = self.interactive_tx_signing_session.as_ref().and_then(|session|
session.local_inputs_count().gt(&0).then_some(session.unsigned_tx().build_unsigned_tx()));

Ok(channel_monitor)
Ok((channel_monitor, funding_tx_opt))
}

/// Handles an incoming `commitment_signed` message for the first commitment transaction of the
Expand Down Expand Up @@ -6772,7 +6752,7 @@ where
.expect("Signing session must exist for negotiated pending splice")
.received_commitment_signed();
self.monitor_updating_paused(false, false, false, Vec::new(), Vec::new(), Vec::new());
self.context.monitor_pending_tx_signatures = tx_signatures;
self.context.monitor_pending_tx_signatures = tx_signatures.is_some();

Ok(self.push_ret_blockable_mon_update(monitor_update))
}
Expand Down Expand Up @@ -7612,6 +7592,37 @@ where
}
}

pub fn funding_transaction_signed<L: Deref>(
&mut self, witnesses: Vec<Witness>, logger: &L,
) -> Result<Option<msgs::TxSignatures>, APIError>
where
L::Target: Logger,
{
if let Some(ref mut signing_session) = self.interactive_tx_signing_session {
let logger = WithChannelContext::from(logger, &self.context, None);
if let Some(holder_tx_signatures) = signing_session
.provide_holder_witnesses(self.context.channel_id, witnesses)
.map_err(|err| APIError::APIMisuseError { err })?
{
if self.is_awaiting_initial_mon_persist() {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the splicing case, we'd want to check is_monitor_update_in_progress only

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's a reliable way to check if we're splicing at this point in time? is_quiescent()?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

self.pending_slice.and_then(|pending_splice| pending_splice.pending_funding.is_some())

log_debug!(logger, "Not sending tx_signatures: a monitor update is in progress. Setting monitor_pending_tx_signatures.");
self.context.monitor_pending_tx_signatures = true;
return Ok(None);
}
return Ok(Some(holder_tx_signatures));
} else {
return Ok(None);
}
} else {
return Err(APIError::APIMisuseError {
err: format!(
"Channel with id {} not expecting funding signatures",
self.context.channel_id
),
});
}
}

#[rustfmt::skip]
pub fn tx_signatures<L: Deref>(&mut self, msg: &msgs::TxSignatures, logger: &L) -> Result<(Option<Transaction>, Option<msgs::TxSignatures>), ChannelError>
where L::Target: Logger
Expand Down Expand Up @@ -7656,11 +7667,6 @@ where
ClosureReason::HolderForceClosed { broadcasted_latest_txn: Some(false) },
)));
}

// TODO(dual_funding): Check all sigs are SIGHASH_ALL.

// TODO(dual_funding): I don't see how we're going to be able to ensure witness-standardness
// for spending. Doesn't seem to be anything in rust-bitcoin.
}

let (holder_tx_signatures_opt, funding_tx_opt) = signing_session.received_tx_signatures(msg.clone())
Expand All @@ -7679,7 +7685,7 @@ where
// and sets it as pending.
if holder_tx_signatures_opt.is_some() && self.is_awaiting_initial_mon_persist() {
log_debug!(logger, "Not sending tx_signatures: a monitor update is in progress. Setting monitor_pending_tx_signatures.");
self.context.monitor_pending_tx_signatures = holder_tx_signatures_opt;
self.context.monitor_pending_tx_signatures = true;
return Ok((None, None));
}

Expand Down Expand Up @@ -7938,14 +7944,14 @@ where
// For channels established with V2 establishment we won't send a `tx_signatures` when we're in
// MonitorUpdateInProgress (and we assume the user will never directly broadcast the funding
// transaction and waits for us to do it).
let tx_signatures = self.context.monitor_pending_tx_signatures.take();
if tx_signatures.is_some() {
let tx_signatures = if self.context.monitor_pending_tx_signatures {
if self.context.channel_state.is_their_tx_signatures_sent() {
self.context.channel_state = ChannelState::AwaitingChannelReady(AwaitingChannelReadyFlags::new());
} else {
self.context.channel_state.set_our_tx_signatures_ready();
}
}
self.interactive_tx_signing_session.as_ref().and_then(|session| session.holder_tx_signatures().clone())
} else { None };

if self.context.channel_state.is_peer_disconnected() {
self.context.monitor_pending_revoke_and_ack = false;
Expand Down Expand Up @@ -8447,11 +8453,9 @@ where
if self.context.channel_state.is_monitor_update_in_progress() {
// The `monitor_pending_tx_signatures` field should have already been set in `commitment_signed_initial_v2`
// if we were up first for signing and had a monitor update in progress, but check again just in case.
debug_assert!(self.context.monitor_pending_tx_signatures.is_some(), "monitor_pending_tx_signatures should already be set");
debug_assert!(self.context.monitor_pending_tx_signatures, "monitor_pending_tx_signatures should already be set");
log_debug!(logger, "Not sending tx_signatures: a monitor update is in progress. Setting monitor_pending_tx_signatures.");
if self.context.monitor_pending_tx_signatures.is_none() {
self.context.monitor_pending_tx_signatures = session.holder_tx_signatures().clone();
}
self.context.monitor_pending_tx_signatures = true;
None
} else {
// If `holder_tx_signatures` is `None` here, the `tx_signatures` message will be sent
Expand Down Expand Up @@ -13202,7 +13206,7 @@ where
monitor_pending_failures,
monitor_pending_finalized_fulfills: monitor_pending_finalized_fulfills.unwrap(),
monitor_pending_update_adds: monitor_pending_update_adds.unwrap_or_default(),
monitor_pending_tx_signatures: None,
monitor_pending_tx_signatures: false,

signer_pending_revoke_and_ack: false,
signer_pending_commitment_update: false,
Expand Down
Loading
Loading