Merge PR 'Fix DelayedPaymentKey/HtlcKey from_basepoint docs and document justice tx witness script' (#5596)
What changed, and why it matters
This commit only changes documentation comments in two source files. It corrects the wording of how certain public keys are derived in the Lightning protocol and adds details about which witness script a signer must use when creating justice (penalty) transactions. No code logic, function signatures, or behavior were modified.
No security action required. Treat as a normal documentation improvement. Downstream signers may wish to review their implementation against the clarified documentation to ensure they derive keys and construct justice transaction witness scripts correctly.
Security signals we found
Documentation-only change
Clarifies key derivation semantics for Lightning commitment transactions
Clarifies justice transaction witness script requirements for signers
Evidence from the diff
The patch updates rustdoc comments in lightning/src/ln/channel_keys.rs for DelayedPaymentKey::from_basepoint and HtlcKey::from_basepoint, clarifying that the delayed payment key is derived from the broadcaster’s own basepoint (not the countersignatory’s) and that HTLC keys for both sides use the broadcaster’s per-commitment point. It also expands doc comments in lightning/src/sign/ecdsa.rs for sign_justice_revoked_output and sign_justice_revoked_htlc, specifying the exact witness script and TxCreationKeys construction signers must commit to. No executable code was changed.
Changed components
lightning/src/ln/channel_keys.rslightning/src/sign/ecdsa.rsInspect captured patch +44 / −6
### lightning/src/ln/channel_keys.rs
@@ -65,15 +65,18 @@ macro_rules! basepoint_impl {
};
}
macro_rules! key_impl {
- ($BasepointT:ty, $KeyName:expr) => {
+ ($BasepointT:ty, $KeyName:expr, $BasepointOwner:expr) => {
doc_comment! {
- concat!("Derive a public ", $KeyName, " using one node's `per_commitment_point` and its countersignatory's `basepoint`"),
+ concat!(
+ "Derive a public ", $KeyName, " for a commitment transaction using the `per_commitment_point`\n",
+ "of that commitment transaction's broadcaster and ", $BasepointOwner
+ ),
pub fn from_basepoint<T: secp256k1::Signing>(
secp_ctx: &Secp256k1<T>,
- countersignatory_basepoint: &$BasepointT,
+ basepoint: &$BasepointT,
per_commitment_point: &PublicKey,
) -> Self {
- Self(derive_public_key(secp_ctx, per_commitment_point, &countersignatory_basepoint.0))
+ Self(derive_public_key(secp_ctx, per_commitment_point, &basepoint.0))
}
}
@@ -130,7 +133,11 @@ key_read_write!(DelayedPaymentBasepoint);
pub struct DelayedPaymentKey(pub PublicKey);
impl DelayedPaymentKey {
- key_impl!(DelayedPaymentBasepoint, "delayedpubkey");
+ key_impl!(
+ DelayedPaymentBasepoint,
+ "delayedpubkey",
+ "that same broadcaster's own [`DelayedPaymentBasepoint`] (*not* its countersignatory's)."
+ );
}
key_read_write!(DelayedPaymentKey);
@@ -157,7 +164,14 @@ key_read_write!(HtlcBasepoint);
pub struct HtlcKey(pub PublicKey);
impl HtlcKey {
- key_impl!(HtlcBasepoint, "htlcpubkey");
+ key_impl!(
+ HtlcBasepoint,
+ "htlcpubkey",
+ "the [`HtlcBasepoint`] of the party whose HTLC key is being derived.\n\
+ \n\
+ Note that the HTLC keys of both the broadcaster and its countersignatory are derived using\n\
+ the broadcaster's `per_commitment_point`."
+ );
}
key_read_write!(HtlcKey);
### lightning/src/sign/ecdsa.rs
@@ -105,11 +105,25 @@ pub trait EcdsaChannelSigner: ChannelSigner {
/// not allow the spending of any funds by itself (you need our holder `revocation_secret` to do
/// so).
///
+ /// The witness script committed to in the signature is the one returned by
+ /// [`get_revokeable_redeemscript`] for `channel_parameters.holder_selected_contest_delay` and
+ /// the `revocation_key` and `broadcaster_delayed_payment_key` of the [`TxCreationKeys`] built
+ /// by [`TxCreationKeys::from_channel_static_keys`] on
+ /// [`channel_parameters.as_counterparty_broadcastable()`] with the per-commitment point
+ /// corresponding to `per_commitment_key`. Note that the delayed payment key is derived from the
+ /// *counterparty's* [`DelayedPaymentBasepoint`], as they are the broadcaster of the revoked
+ /// state.
+ ///
/// 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 or [`ChainMonitor::signer_unblocked`] called to attempt unblocking all monitors.
///
+ /// [`get_revokeable_redeemscript`]: crate::ln::chan_utils::get_revokeable_redeemscript
+ /// [`TxCreationKeys`]: crate::ln::chan_utils::TxCreationKeys
+ /// [`TxCreationKeys::from_channel_static_keys`]: crate::ln::chan_utils::TxCreationKeys::from_channel_static_keys
+ /// [`channel_parameters.as_counterparty_broadcastable()`]: ChannelTransactionParameters::as_counterparty_broadcastable
+ /// [`DelayedPaymentBasepoint`]: crate::ln::channel_keys::DelayedPaymentBasepoint
/// [`ChannelMonitor::signer_unblocked`]: crate::chain::channelmonitor::ChannelMonitor::signer_unblocked
/// [`ChainMonitor::signer_unblocked`]: crate::chain::chainmonitor::ChainMonitor::signer_unblocked
fn sign_justice_revoked_output(
@@ -136,11 +150,21 @@ 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).
///
+ /// The witness script committed to in the signature is the one returned by
+ /// [`get_htlc_redeemscript`] for `htlc`, `channel_parameters.channel_type_features` and the
+ /// [`TxCreationKeys`] built by [`TxCreationKeys::from_channel_static_keys`] on
+ /// [`channel_parameters.as_counterparty_broadcastable()`] with the per-commitment point
+ /// corresponding to `per_commitment_key`.
+ ///
/// 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 or [`ChainMonitor::signer_unblocked`] called to attempt unblocking all monitors.
///
+ /// [`get_htlc_redeemscript`]: crate::ln::chan_utils::get_htlc_redeemscript
+ /// [`TxCreationKeys`]: crate::ln::chan_utils::TxCreationKeys
+ /// [`TxCreationKeys::from_channel_static_keys`]: crate::ln::chan_utils::TxCreationKeys::from_channel_static_keys
+ /// [`channel_parameters.as_counterparty_broadcastable()`]: ChannelTransactionParameters::as_counterparty_broadcastable
/// [`ChannelMonitor::signer_unblocked`]: crate::chain::channelmonitor::ChannelMonitor::signer_unblocked
/// [`ChainMonitor::signer_unblocked`]: crate::chain::chainmonitor::ChainMonitor::signer_unblocked
fn sign_justice_revoked_htlc(Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.