Merge PR 'Advise extract_tx_unchecked_fee_rate in sign_psbt docs' (#5599)
What changed, and why it matters
This change only updates documentation comments for the sign_psbt methods in wallet utilities. It advises developers to use extract_tx_unchecked_fee_rate() instead of extract_tx() when signing PSBTs outside the library, because extract_tx() can reject transactions with very high fee rates that are legitimate in Lightning child-pays-for-parent fee-bumping scenarios. It is a documentation-only fix with no code behavior change.
No immediate action required. Developers implementing these traits should follow the updated documentation guidance and use extract_tx_unchecked_fee_rate() when extracting a transaction for external signing in fee-bumping contexts.
Security signals we found
Documentation-only change
Mentions 25,000 sat/vB fee-rate limit in rust-bitcoin's extract_tx
Relates to CPFP / package fee bumping for Lightning commitment transactions
No functional code changes
Evidence from the diff
The commit modifies rustdoc comments on four sign_psbt trait methods (CoinSelectionSource, WalletSource, WalletSourceSync, CoinSelectionSourceSync). It replaces the recommendation to call psbt.extract_tx() with psbt.extract_tx_unchecked_fee_rate(), and explains that extract_tx() enforces a 25,000 sat/vB fee-rate cap that can incorrectly reject CPFP-style transactions such as commitment transaction fee bumps. No executable code, signatures, or validation logic were changed.
Changed components
lightning/src/util/wallet_utils.rs documentationInspect 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 18/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.