Merge pull request #11334 from gijswijs/fee-ceiling-clamp
What changed, and why it matters
This commit adds an upper limit (ceiling) to fee estimates that LND pulls from an external web API. Previously, only a lower bound existed, so a malicious or malfunctioning fee API could return extremely high fee rates. Those inflated rates could then flow into wallet operations and cause users to overpay transaction fees. The patch clamps both per-block fee estimates and the minimum relay fee rate to a maximum of 10,000 sat/vbyte. It also ties the sweeper's maximum allowed fee rate to the same ceiling so the two limits stay consistent.
Treat this as a security hardening fix. Users relying on --fee.url should upgrade to a release containing this commit. Operators should verify their external fee API source is trustworthy and monitor logs for 'exceeds fee ceiling' warnings, which may indicate API misbehavior.
Security signals we found
Untrusted external input (fee API) was previously only lower-bounded, allowing unbounded high values
High fee estimates can propagate into wallet signing and fee-sensitive operations
New ceiling bounds both block-target estimates and min_relay_feerate
Sweeper max fee rate is now derived from the same ceiling to prevent limit divergence
Release notes explicitly describe security relevance: out-of-range API values could propagate into fee-sensitive wallet operations
Evidence from the diff
The change introduces chainfee.FeePerKwCeiling (2,500,000 sat/kw, equivalent to 10,000 sat/vb) in lnwallet/chainfee/rates.go. In lnwallet/chainfee/estimator.go, WebAPIEstimator.EstimateFeePerKW now clamps the returned satPerKw value to this ceiling, and updateFeeEstimates clamps MinRelayFeerate to [FeePerKwFloor, FeePerKwCeiling] before storing it. lncfg/sweeper.go changes MaxAllowedFeeRate from a hard-coded 10,000 to a derived value based on chainfee.FeePerKwCeiling, ensuring the sweeper config and chainfee ceiling cannot diverge. Tests are added for both the estimate ceiling and relay-fee clamping behavior. The release notes describe the change as preventing out-of-range external API values from propagating into fee-sensitive wallet operations.
Changed components
lnwallet/chainfee/estimator.golnwallet/chainfee/rates.golncfg/sweeper.golnwallet/chainfee/estimator_test.godocs/release-notes/release-notes-0.20.6.mddocs/release-notes/release-notes-0.21.5.mdInspect captured patch +175 / −3
### docs/release-notes/release-notes-0.20.6.md
@@ -39,6 +39,13 @@
failing validation because the KV and SQL stores use different empty byte
slice representations.
+* Fee estimates returned by the external `--fee.url` API are [now clamped
+ to a ceiling](https://github.com/lightningnetwork/lnd/pull/11334) of
+ 10,000 sat/vb (`chainfee.FeePerKwCeiling`). Previously the estimates were
+ only floor-clamped, so out-of-range values from the external API could
+ propagate into fee-sensitive wallet operations. The API's
+ `min_relay_feerate` is now clamped to the same bounds.
+
# New Features
## Functional Enhancements
### docs/release-notes/release-notes-0.21.5.md
@@ -53,6 +53,13 @@
failing validation because the KV and SQL stores use different empty byte
slice representations.
+* Fee estimates returned by the external `--fee.url` API are [now clamped
+ to a ceiling](https://github.com/lightningnetwork/lnd/pull/11334) of
+ 10,000 sat/vb (`chainfee.FeePerKwCeiling`). Previously the estimates were
+ only floor-clamped, so out-of-range values from the external API could
+ propagate into fee-sensitive wallet operations. The API's
+ `min_relay_feerate` is now clamped to the same bounds.
+
# New Features
## Functional Enhancements
### lncfg/sweeper.go
@@ -4,6 +4,7 @@ import (
"fmt"
"time"
+ "github.com/btcsuite/btcd/blockchain"
"github.com/lightningnetwork/lnd/contractcourt"
"github.com/lightningnetwork/lnd/lnwallet/chainfee"
"github.com/lightningnetwork/lnd/sweep"
@@ -15,8 +16,11 @@ const (
MaxFeeRateFloor chainfee.SatPerVByte = 100
// MaxAllowedFeeRate is the largest fee rate in sat/vb that we allow
- // when configuring the MaxFeeRate.
- MaxAllowedFeeRate = 10_000
+ // when configuring the MaxFeeRate. It is derived from the chainfee
+ // ceiling so the two values can never diverge.
+ MaxAllowedFeeRate = chainfee.SatPerVByte(
+ chainfee.FeePerKwCeiling * blockchain.WitnessScaleFactor / 1000,
+ )
)
//nolint:ll
### lnwallet/chainfee/estimator.go
@@ -829,6 +829,17 @@ func (w *WebAPIEstimator) EstimateFeePerKW(numBlocks uint32) (
satPerKw = FeePerKwFloor
}
+ // Similarly, if the result is too high, then we'll clamp it to our
+ // fee ceiling. The web API is an untrusted, external data source, so
+ // we bound its input to sane values before it reaches wallet code.
+ if satPerKw > FeePerKwCeiling {
+ log.Warnf("Web API fee estimate of %v exceeds fee ceiling, "+
+ "clamping to %v", int64(satPerKw),
+ int64(FeePerKwCeiling))
+
+ satPerKw = FeePerKwCeiling
+ }
+
log.Debugf("Web API returning %v sat/kw for conf target of %v",
int64(satPerKw), numBlocks)
@@ -1014,9 +1025,25 @@ func (w *WebAPIEstimator) updateFeeEstimates() {
return string(resp)
}))
+ // Clamp the relay fee to sane bounds, just like the block target
+ // estimates. The web API is an untrusted, external data source, so
+ // we bound its input here as well before it reaches wallet code.
+ minRelayFee := resp.MinRelayFeerate.FeePerKWeight()
+ switch {
+ case minRelayFee < FeePerKwFloor:
+ minRelayFee = FeePerKwFloor
+
+ case minRelayFee > FeePerKwCeiling:
+ log.Warnf("Web API min relay feerate of %v exceeds fee "+
+ "ceiling, clamping to %v", int64(minRelayFee),
+ int64(FeePerKwCeiling))
+
+ minRelayFee = FeePerKwCeiling
+ }
+
w.feesMtx.Lock()
w.feeByBlockTarget = resp.FeeByBlockTarget
- w.minRelayFeerate = resp.MinRelayFeerate
+ w.minRelayFeerate = minRelayFee.FeePerKVByte()
w.feesMtx.Unlock()
}
### lnwallet/chainfee/estimator_test.go
@@ -289,6 +289,127 @@ func TestWebAPIFeeEstimator(t *testing.T) {
feeSource.AssertExpectations(t)
}
+// TestWebAPIFeeEstimatorCeiling checks that the WebAPIEstimator clamps fee
+// rates returned by the external API to FeePerKwCeiling, so that
+// out-of-range API responses are bounded.
+func TestWebAPIFeeEstimatorCeiling(t *testing.T) {
+ t.Parallel()
+
+ var (
+ minTarget uint32 = 2
+ maxTarget uint32 = 6
+
+ // Fee rates are in sat/kb. The sane rate is below the ceiling,
+ // while the absurd rate of 10^7 sat/kw is far above it.
+ saneFeeRate = uint32(FeePerKwCeiling.FeePerKVByte()) - 4000
+ absurdFeeRate = uint32(FeePerKwCeiling.FeePerKVByte()) * 4
+
+ minFeeUpdateTimeout = 5 * time.Minute
+ maxFeeUpdateTimeout = 20 * time.Minute
+ )
+
+ feeRates := map[uint32]uint32{
+ minTarget: absurdFeeRate,
+ maxTarget: saneFeeRate,
+ }
+ resp := WebAPIResponse{
+ FeeByBlockTarget: feeRates,
+ }
+
+ feeSource := &mockFeeSource{}
+ feeSource.On("GetFeeInfo").Return(resp, nil)
+
+ estimator, err := NewWebAPIEstimator(
+ feeSource, false, minFeeUpdateTimeout, maxFeeUpdateTimeout,
+ )
+ require.NoError(t, err)
+ require.NoError(t, estimator.Start(), "unable to start fee estimator")
+
+ // The absurd fee rate must be clamped to the ceiling.
+ est, err := estimator.EstimateFeePerKW(minTarget)
+ require.NoError(t, err)
+ require.Equal(t, FeePerKwCeiling, est)
+
+ // The sane fee rate below the ceiling must pass through untouched.
+ est, err = estimator.EstimateFeePerKW(maxTarget)
+ require.NoError(t, err)
+ require.Equal(t, SatPerKVByte(saneFeeRate).FeePerKWeight(), est)
+
+ require.NoError(t, estimator.Stop(), "unable to stop fee estimator")
+
+ feeSource.AssertExpectations(t)
+}
+
+// TestWebAPIEstimatorRelayFeeClamp checks that the WebAPIEstimator clamps
+// the min relay feerate returned by the external API to sane bounds, so
+// that out-of-range API responses are bounded.
+func TestWebAPIEstimatorRelayFeeClamp(t *testing.T) {
+ t.Parallel()
+
+ var (
+ minFeeUpdateTimeout = 5 * time.Minute
+ maxFeeUpdateTimeout = 20 * time.Minute
+
+ saneRelayFee = SatPerKVByte(2000)
+ absurdRelayFee = FeePerKwCeiling.FeePerKVByte() * 4
+ )
+
+ testCases := []struct {
+ name string
+ relayFee SatPerKVByte
+ expectedFee SatPerKWeight
+ }{
+ {
+ // An absent relay fee defaults to the floor.
+ name: "absent relay fee",
+ relayFee: 0,
+ expectedFee: FeePerKwFloor,
+ },
+ {
+ // A sane relay fee passes through untouched.
+ name: "sane relay fee",
+ relayFee: saneRelayFee,
+ expectedFee: saneRelayFee.FeePerKWeight(),
+ },
+ {
+ // An absurd relay fee is clamped to the ceiling.
+ name: "absurd relay fee",
+ relayFee: absurdRelayFee,
+ expectedFee: FeePerKwCeiling,
+ },
+ }
+
+ for _, tc := range testCases {
+ t.Run(tc.name, func(t *testing.T) {
+ resp := WebAPIResponse{
+ FeeByBlockTarget: map[uint32]uint32{
+ 6: 2000,
+ },
+ MinRelayFeerate: tc.relayFee,
+ }
+
+ feeSource := &mockFeeSource{}
+ feeSource.On("GetFeeInfo").Return(resp, nil)
+
+ estimator, err := NewWebAPIEstimator(
+ feeSource, false, minFeeUpdateTimeout,
+ maxFeeUpdateTimeout,
+ )
+ require.NoError(t, err)
+ require.NoError(t, estimator.Start(),
+ "unable to start fee estimator")
+
+ relayFee := estimator.RelayFeePerKW()
+ require.Equal(t, tc.expectedFee, relayFee)
+
+ require.NoError(t, estimator.Stop(),
+ "unable to stop fee estimator")
+
+ feeSource.AssertExpectations(t)
+ })
+ }
+}
+
// TestGetCachedFee checks that the fee caching logic works as expected.
func TestGetCachedFee(t *testing.T) {
var (
### lnwallet/chainfee/rates.go
@@ -17,6 +17,12 @@ const (
// transaction that we should ever _create_. This is the equivalent
// of 1 sat/byte in sat/kw.
AbsoluteFeePerKwFloor SatPerKWeight = 250
+
+ // FeePerKwCeiling is the highest fee rate in sat/kw that we should
+ // use for estimating transaction fees before signing. This is the
+ // equivalent of 10,000 sat/vb, which matches the highest fee rate
+ // the sweeper can be configured with.
+ FeePerKwCeiling SatPerKWeight = 2_500_000
)
// SatPerVByte represents a fee rate in sat/vbyte.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.