Advise extract_tx_unchecked_fee_rate in sign_psbt docs
What changed, and why it matters
This commit only updates documentation comments in LDK's wallet utility code. It tells wallet developers not to use a standard Bitcoin library method (psbt.extract_tx()) when implementing the sign_psbt() function, because that method rejects transactions with very high fees. In certain legitimate Lightning scenarios—like a child transaction paying fees for both itself and its parent force-close transaction—the fee rate can exceed the library's cap. Using the wrong method would cause the wallet to refuse to sign, preventing a force-close transaction from being broadcast. The commit itself does not change any code behavior, only the guidance given to implementers.
No immediate code deployment is needed, but downstream wallet implementors using these traits should review their sign_psbt() implementations to ensure they use extract_tx_unchecked_fee_rate() rather than extract_tx(). Projects on LDK v0.0.124-beta or later that followed the old documentation are at risk of failing to broadcast force-close transactions under high-fee conditions.
Security signals we found
Documentation-only change correcting security-relevant integration guidance
Incorrect wallet integration could cause denial of service for force-close broadcast
References a real fee-rate validation pitfall introduced by rust-bitcoin 0.31 upgrade
Evidence from the diff
The patch updates doc comments on four traits (CoinSelectionSource, WalletSource, WalletSourceSync, CoinSelectionSourceSync) in lightning/src/util/wallet_utils.rs. It replaces advice to call psbt.extract_tx() with advice to call psbt.extract_tx_unchecked_fee_rate(), and explains that extract_tx() rejects transactions paying more than 25,000 sat/vB. Since rust-bitcoin 0.31 (introduced in LDK v0.0.124-beta), extract_tx() enforces this fee cap, while LDK’s internal callers were already switched to the unchecked variant. The documented path could cause wallet implementations to fail signing package-child transactions whose standalone feerate legitimately exceeds the cap, such as an anchor CPFP child for a ChannelClose that pays for the commitment transaction’s fee too. This is a documentation fix; no runtime code is changed.
Changed components
lightning/src/util/wallet_utils.rsCoinSelectionSource::sign_psbtWalletSource::sign_psbtWalletSourceSync::sign_psbtCoinSelectionSourceSync::sign_psbtInspect captured patch +32 / −8
### lightning/src/util/wallet_utils.rs
@@ -399,8 +399,14 @@ pub trait CoinSelectionSource {
/// Signs and provides the full witness for all inputs within the transaction known to the
/// trait (i.e., any provided via [`CoinSelectionSource::select_confirmed_utxos`]).
///
- /// If your wallet does not support signing PSBTs you can call `psbt.extract_tx()` to get the
- /// unsigned transaction and then sign it with your wallet.
+ /// If your wallet does not support signing PSBTs you can call
+ /// `psbt.extract_tx_unchecked_fee_rate()` to get the unsigned transaction and then sign it
+ /// with your wallet.
+ ///
+ /// Do not use `psbt.extract_tx()`, which rejects transactions paying more than 25,000 sat/vB:
+ /// the transaction may be the child of a package whose fee also pays for the parent
+ /// transaction (e.g., when bumping a commitment transaction's feerate), such that its own
+ /// feerate can exceed that limit.
fn sign_psbt<'a>(
&'a self, psbt: Psbt,
) -> impl Future<Output = Result<Transaction, ()>> + MaybeSend + 'a;
@@ -457,8 +463,14 @@ pub trait WalletSource {
/// the transaction known to the wallet (i.e., any provided via
/// [`WalletSource::list_confirmed_utxos`]).
///
- /// If your wallet does not support signing PSBTs you can call `psbt.extract_tx()` to get the
- /// unsigned transaction and then sign it with your wallet.
+ /// If your wallet does not support signing PSBTs you can call
+ /// `psbt.extract_tx_unchecked_fee_rate()` to get the unsigned transaction and then sign it
+ /// with your wallet.
+ ///
+ /// Do not use `psbt.extract_tx()`, which rejects transactions paying more than 25,000 sat/vB:
+ /// the transaction may be the child of a package whose fee also pays for the parent
+ /// transaction (e.g., when bumping a commitment transaction's feerate), such that its own
+ /// feerate can exceed that limit.
///
/// [`TxIn::script_sig`]: bitcoin::TxIn::script_sig
/// [`TxIn::witness`]: bitcoin::TxIn::witness
@@ -800,8 +812,14 @@ pub trait WalletSourceSync {
/// the transaction known to the wallet (i.e., any provided via
/// [`WalletSource::list_confirmed_utxos`]).
///
- /// If your wallet does not support signing PSBTs you can call `psbt.extract_tx()` to get the
- /// unsigned transaction and then sign it with your wallet.
+ /// If your wallet does not support signing PSBTs you can call
+ /// `psbt.extract_tx_unchecked_fee_rate()` to get the unsigned transaction and then sign it
+ /// with your wallet.
+ ///
+ /// Do not use `psbt.extract_tx()`, which rejects transactions paying more than 25,000 sat/vB:
+ /// the transaction may be the child of a package whose fee also pays for the parent
+ /// transaction (e.g., when bumping a commitment transaction's feerate), such that its own
+ /// feerate can exceed that limit.
///
/// [`TxIn::script_sig`]: bitcoin::TxIn::script_sig
/// [`TxIn::witness`]: bitcoin::TxIn::witness
@@ -992,8 +1010,14 @@ pub trait CoinSelectionSourceSync {
/// Signs and provides the full witness for all inputs within the transaction known to the
/// trait (i.e., any provided via [`CoinSelectionSourceSync::select_confirmed_utxos`]).
///
- /// If your wallet does not support signing PSBTs you can call `psbt.extract_tx()` to get the
- /// unsigned transaction and then sign it with your wallet.
+ /// If your wallet does not support signing PSBTs you can call
+ /// `psbt.extract_tx_unchecked_fee_rate()` to get the unsigned transaction and then sign it
+ /// with your wallet.
+ ///
+ /// Do not use `psbt.extract_tx()`, which rejects transactions paying more than 25,000 sat/vB:
+ /// the transaction may be the child of a package whose fee also pays for the parent
+ /// transaction (e.g., when bumping a commitment transaction's feerate), such that its own
+ /// feerate can exceed that limit.
fn sign_psbt(&self, psbt: Psbt) -> Result<Transaction, ()>;
}
Why this scored 60/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.