lnwallet: reject initial commitments that leave a channel unusable
What changed, and why it matters
This commit tightens the rules LND uses when accepting a new Lightning channel. Before, LND only applied one BOLT-02 check on opening balances. Now it also rejects channels where, because of each side's reserve setting, neither party could ever send a payment. The change prevents 'dead on arrival' channels that look valid to the spec but cannot actually be used. It is a defensive policy fix, not a response to a disclosed vulnerability or active exploit.
Treat as a hardening/policy improvement. Reviewers should confirm the new usability check does not break legitimate funding flows with asymmetric reserves, and that the funding manager handles ErrBalancesBelowReserveBase appropriately. No urgent security patch is indicated by the diff alone.
Security signals we found
Defensive validation added to funding flow
New sentinel error supports programmatic rejection handling
BOLT-02 spec compliance enforced plus stricter local policy
Prevents unusable channels from being locked on-chain
No memory-safety, cryptographic, or remote-execution signals present
Evidence from the diff
The patch adds validateInitialBalances() to ChannelReservation and calls it from LightningWallet.handleSingleContribution() once both channel contributions (and thus both channel_reserve_satoshis values) are known. It performs two checks: (1) the BOLT-02 MUST that both to_local and to_remote are <= the initiator’s channel_reserve_satoshis, and (2) a local usability check that each output clears the reserve its own side must maintain. A new sentinel error, ErrBalancesBelowReserveBase, is exposed via Unwrap() on ReservationError so the funding manager can match it without parsing strings. Comprehensive unit and property tests are added to pin both behaviors.
Changed components
lnwallet/reservation.golnwallet/wallet.golnwallet/errors.golnwallet/reservation_test.goInspect captured patch +482 / −0
### lnwallet/errors.go
@@ -22,6 +22,14 @@ type ReservationError struct {
// interface.
var _ error = (*ReservationError)(nil)
+// Unwrap returns the wrapped error, so that the sentinels a constructor wraps
+// with %w can be matched by callers with errors.Is. Callers inside the daemon
+// use it to decide whether to fail a funding flow; the remote peer only ever
+// sees Error().
+func (e ReservationError) Unwrap() error {
+ return e.error
+}
+
// ErrZeroCapacity returns an error indicating the funder attempted to put zero
// funds into the channel.
func ErrZeroCapacity() ReservationError {
@@ -98,6 +106,34 @@ func ErrPushAmountTooLarge(pushAmt lnwire.MilliSatoshi,
}
}
+// ErrBalancesBelowReserveBase is the sentinel wrapped by
+// ErrBalancesBelowReserve, so that callers can identify the rejection without
+// matching on its message text.
+var ErrBalancesBelowReserveBase = errors.New("both initial balances are " +
+ "below their channel reserve")
+
+// ErrBalancesBelowReserve returns an error indicating that a channel could
+// never be used, because neither party would hold more than the reserve it is
+// required to maintain on the initial commitment transaction. BOLT-02 requires
+// that we fail a channel whose initial outputs are both at or below the
+// reserve the initiator named in open_channel, and a channel where neither
+// side can spend is rejected for the same reason.
+//
+// Both reserves are reported so the message distinguishes the two: ourReserve
+// is the reserve the initiator requires of us, and theirReserve is the reserve
+// we require of them in accept_channel.
+func ErrBalancesBelowReserve(localBalance, theirBalance, ourReserve,
+ theirReserve btcutil.Amount) ReservationError {
+
+ return ReservationError{
+ fmt.Errorf("%w: to_local %v sat against our reserve %v sat, "+
+ "to_remote %v sat against their reserve %v sat",
+ ErrBalancesBelowReserveBase, int64(localBalance),
+ int64(ourReserve), int64(theirBalance),
+ int64(theirReserve)),
+ }
+}
+
// ErrMinHtlcTooLarge returns an error indicating that the MinHTLC value the
// remote required is too large to be accepted.
func ErrMinHtlcTooLarge(minHtlc,
### lnwallet/reservation.go
@@ -647,6 +647,67 @@ func (r *ChannelReservation) validateReserveBounds() bool {
return minChanReserve >= maxDustLimit
}
+// validateInitialBalances fails a channel that could never be used: one where
+// neither side's initial commitment output clears the reserve that side is
+// required to maintain. In that case neither party can add an HTLC without
+// dipping below its reserve, so the channel is dead on arrival.
+//
+// Two checks are made, and both are needed:
+//
+// 1. The BOLT#02 requirement, which the receiver of open_channel MUST apply:
+// both to_local and to_remote are less than or equal to
+// channel_reserve_satoshis, the single value the initiator named in
+// open_channel. That value is the reserve the initiator requires of us.
+//
+// 2. A usability check, comparing each output against the reserve its own
+// side must maintain: to_local against the reserve the initiator named for
+// us, and to_remote against the reserve we named for them in accept_channel.
+// That is what decides whether either side can actually spend, since the two
+// reserves are independent and may differ in either direction.
+//
+// Neither check implies the other. When our accept_channel reserve is the
+// lower of the two, check 1 can reject a channel the initiator could still
+// use, and the spec requires that; when our reserve is the higher, check 1
+// accepts a channel where neither side can spend, which check 2 catches. The
+// second check is therefore a local policy that is in places stricter than
+// the letter of the spec, and it is deliberately additive rather than a
+// reinterpretation of the first.
+//
+// This function should be called with the lock held.
+func (r *ChannelReservation) validateInitialBalances() error {
+ commitment := r.partialState.LocalCommitment
+ ourInitialBalance := commitment.LocalBalance.ToSatoshis()
+ theirInitialBalance := commitment.RemoteBalance.ToSatoshis()
+
+ // The reserve in our contribution is the one the initiator set in
+ // open_channel: the reserve the initiator requires OF US, which is the
+ // single value BOLT#02 compares both initial outputs against. The one
+ // in their contribution is the reserve WE named for them in
+ // accept_channel.
+ reserveInitiatorRequiresOfUs := r.ourContribution.ChanReserve
+ reserveWeRequireOfThem := r.theirContribution.ChanReserve
+
+ // Check 1: the spec's own comparison, both outputs against the
+ // initiator's reserve of us. This is a MUST, so it stays even though
+ // it can turn away a channel the initiator could still use.
+ failsSpecMUST := ourInitialBalance <= reserveInitiatorRequiresOfUs &&
+ theirInitialBalance <= reserveInitiatorRequiresOfUs
+
+ // Check 2: each output against the reserve its own side must maintain,
+ // which is exactly the condition under which neither side can spend.
+ failsUsability := ourInitialBalance <= reserveInitiatorRequiresOfUs &&
+ theirInitialBalance <= reserveWeRequireOfThem
+
+ if failsSpecMUST || failsUsability {
+ return ErrBalancesBelowReserve(
+ ourInitialBalance, theirInitialBalance,
+ reserveInitiatorRequiresOfUs, reserveWeRequireOfThem,
+ )
+ }
+
+ return nil
+}
+
// OurContribution returns the wallet's fully populated contribution to the
// pending payment channel. See 'ChannelContribution' for further details
// regarding the contents of a contribution.
### lnwallet/reservation_test.go
@@ -6,6 +6,7 @@ import (
"github.com/btcsuite/btcd/btcec/v2"
"github.com/btcsuite/btcd/btcutil/v2"
"github.com/lightningnetwork/lnd/channeldb"
+ "github.com/lightningnetwork/lnd/chanstate"
"github.com/lightningnetwork/lnd/lnwire"
"github.com/stretchr/testify/require"
)
@@ -58,3 +59,379 @@ func TestReservationAuxChanStatePopulatesNegotiatedConfigs(t *testing.T) {
require.Equal(t, *localCfg, auxState.LocalChanCfg)
require.Equal(t, *remoteCfg, auxState.RemoteChanCfg)
}
+
+// TestValidateInitialBalances checks the two conditions that fail a channel
+// whose initial commitment leaves neither side able to spend.
+//
+// The first is the BOLT#02 MUST: both initial outputs at or below the single
+// channel_reserve_satoshis the initiator named in open_channel, which is the
+// reserve the initiator requires of us. The second is the usability check:
+// each output at or below the reserve its own side must maintain. The
+// configurations below are chosen so the two differ.
+func TestValidateInitialBalances(t *testing.T) {
+ t.Parallel()
+
+ // initiatorReserve is the channel_reserve_satoshis the initiator
+ // proposed in open_channel: the reserve they require of us.
+ const initiatorReserve = btcutil.Amount(10000)
+
+ // acceptReserve is the reserve we name in accept_channel: the reserve
+ // we require of them. It is deliberately below the initiator's, which
+ // is the configuration where the spec check rejects a channel the
+ // usability check would accept.
+ const acceptReserve = btcutil.Amount(5000)
+
+ // chanCfg builds the minimal channel config validateInitialBalances
+ // reads: the reserve the party it belongs to must maintain.
+ chanCfg := func(reserve btcutil.Amount) *channeldb.ChannelConfig {
+ bounds := channeldb.ChannelStateBounds{
+ ChanReserve: reserve,
+ }
+
+ return &channeldb.ChannelConfig{
+ ChannelStateBounds: bounds,
+ }
+ }
+
+ tests := []struct {
+ name string
+ initiatorReserve btcutil.Amount
+
+ // acceptReserve overrides the package-level value for cases
+ // that need our reserve to sit above the initiator's.
+ acceptReserve btcutil.Amount
+
+ ourBalance btcutil.Amount
+ theirBalance btcutil.Amount
+ expectErr bool
+ }{
+ {
+ // The common case for a fundee: we start at zero with
+ // no push, but the initiator holds nearly the full
+ // capacity.
+ name: "only initiator above reserve",
+ initiatorReserve: initiatorReserve,
+ acceptReserve: acceptReserve,
+ ourBalance: 0,
+ theirBalance: 1000000,
+ },
+ {
+ // The mirror image, which is what a full push looks
+ // like.
+ name: "only fundee above reserve",
+ initiatorReserve: initiatorReserve,
+ acceptReserve: acceptReserve,
+ ourBalance: 1000000,
+ theirBalance: 0,
+ },
+ {
+ name: "both above reserve",
+ initiatorReserve: initiatorReserve,
+ acceptReserve: acceptReserve,
+ ourBalance: 500000,
+ theirBalance: 500000,
+ },
+ {
+ // The reporter's example: an absurd commitment fee rate
+ // burns the capacity before either party can use the
+ // channel.
+ name: "both below reserve",
+ initiatorReserve: initiatorReserve,
+ acceptReserve: acceptReserve,
+ ourBalance: 0,
+ theirBalance: 9000,
+ expectErr: true,
+ },
+ {
+ // Both balances sit above the reserve we name in
+ // accept_channel, so the usability check alone would
+ // accept. The spec check still fires, because both are
+ // at or below the initiator's reserve.
+ name: "both above accept reserve",
+ initiatorReserve: initiatorReserve,
+ acceptReserve: acceptReserve,
+ ourBalance: 9000,
+ theirBalance: 9000,
+ expectErr: true,
+ },
+ {
+ // The spec check rejects a USABLE channel
+ // here, and that is intentional: it is a MUST,
+ // not a heuristic. Our accept reserve is
+ // 5000 and the initiator's balance is 8000,
+ // so they can still spend, but both outputs
+ // are at or below the initiator's 10000
+ // reserve, so BOLT#02 requires us to fail the
+ // channel.
+ //
+ // This case exists to pin that behaviour. A
+ // future change that "fixes" the
+ // over-rejection by dropping the spec
+ // comparison must fail here.
+ name: "spec rejects one-sided",
+ initiatorReserve: initiatorReserve,
+ acceptReserve: acceptReserve,
+ ourBalance: 0,
+ theirBalance: 8000,
+ expectErr: true,
+ },
+ {
+ // Our balance is above the initiator's reserve, which
+ // clears the spec check, and the initiator's balance
+ // clears the reserve we named for them, so neither
+ // check fires.
+ name: "one side above initiator reserve",
+ initiatorReserve: initiatorReserve,
+ acceptReserve: acceptReserve,
+ ourBalance: 10001,
+ theirBalance: 0,
+ },
+ {
+ // The dead-channel case the spec check alone misses.
+ // The initiator names a reserve of us BELOW the reserve
+ // we name of them, so their balance sits above the
+ // initiator's reserve and the spec check does not fire.
+ // But it is at or below the reserve we
+ // require of them, and our own balance is
+ // at or below the initiator's, so neither
+ // side can spend.
+ name: "dead channel above reserve",
+ initiatorReserve: 1000,
+ acceptReserve: 5000,
+ ourBalance: 0,
+ theirBalance: 5000,
+ expectErr: true,
+ },
+ {
+ // The spec fails on "less than or equal to", so a
+ // balance sitting exactly at the reserve doesn't save
+ // the channel: no HTLC could be added without dipping
+ // below it.
+ name: "both exactly at reserve",
+ initiatorReserve: initiatorReserve,
+ acceptReserve: acceptReserve,
+ ourBalance: initiatorReserve,
+ theirBalance: initiatorReserve,
+ expectErr: true,
+ },
+ {
+ // A single satoshi above the reserve is enough for the
+ // channel to be considered usable.
+ name: "one satoshi above reserve",
+ initiatorReserve: initiatorReserve,
+ acceptReserve: acceptReserve,
+ ourBalance: initiatorReserve,
+ theirBalance: initiatorReserve + 1,
+ },
+ {
+ // A zero reserve is legitimate, in which case a
+ // channel with any balance at all is fine.
+ name: "zero reserve with balance",
+ initiatorReserve: 0,
+ acceptReserve: 0,
+ ourBalance: 0,
+ theirBalance: 1,
+ },
+ {
+ // A zero reserve does not help a channel with no funds
+ // anywhere: both balances are still at or below it.
+ name: "zero reserve without balance",
+ initiatorReserve: 0,
+ acceptReserve: 0,
+ ourBalance: 0,
+ theirBalance: 0,
+ expectErr: true,
+ },
+ }
+
+ for _, test := range tests {
+ t.Run(test.name, func(t *testing.T) {
+ t.Parallel()
+
+ commit := channeldb.ChannelCommitment{
+ LocalBalance: lnwire.NewMSatFromSatoshis(
+ test.ourBalance,
+ ),
+ RemoteBalance: lnwire.NewMSatFromSatoshis(
+ test.theirBalance,
+ ),
+ }
+
+ res := &ChannelReservation{
+ ourContribution: &ChannelContribution{
+ ChannelConfig: chanCfg(
+ test.initiatorReserve,
+ ),
+ },
+ theirContribution: &ChannelContribution{
+ ChannelConfig: chanCfg(
+ test.acceptReserve,
+ ),
+ },
+ partialState: &chanstate.OpenChannel{
+ LocalCommitment: commit,
+ },
+ }
+
+ err := res.validateInitialBalances()
+ if !test.expectErr {
+ require.NoError(t, err)
+ return
+ }
+
+ // The rejection is identified by the sentinel rather
+ // than by its message text, so the assertion does not
+ // depend on the wording we send the remote peer.
+ require.ErrorIs(t, err, ErrBalancesBelowReserveBase)
+ })
+ }
+}
+
+// TestValidateInitialBalancesUnionIsAdditive drives the real check across a
+// sweep of reserves and balances and asserts the property that makes the
+// usability comparison safe to layer onto the spec one: every channel it
+// rejects beyond what the spec comparison alone would reject must be one where
+// NEITHER side can spend. Adding it therefore costs us no usable channel.
+//
+// The predicate the spec comparison would apply is computed here independently,
+// and the rejection itself comes from validateInitialBalances, so this test
+// would fail if the implementation drifted from the property.
+func TestValidateInitialBalancesUnionIsAdditive(t *testing.T) {
+ t.Parallel()
+
+ // msat is a shorthand for the long constructor below, so the
+ // reservation builder stays within the column limit.
+ msat := lnwire.NewMSatFromSatoshis
+
+ chanCfg := func(reserve btcutil.Amount) *channeldb.ChannelConfig {
+ return &channeldb.ChannelConfig{
+ ChannelStateBounds: channeldb.ChannelStateBounds{
+ ChanReserve: reserve,
+ },
+ }
+ }
+
+ amounts := []btcutil.Amount{
+ 0, 1, 4999, 5000, 5001, 9999, 10000, 10001, 20000,
+ }
+
+ // The reserve the initiator names for us, and the reserve we name for
+ // them in accept_channel. Both directions of their relationship are
+ // exercised, since that is what decides which comparison bites.
+ reserves := []btcutil.Amount{1000, 5000, 10000, 20000}
+
+ addedRejections := 0
+
+ reservation := func(
+ ourBalance, theirBalance btcutil.Amount,
+ ourReserve, theirReserve btcutil.Amount,
+ ) *ChannelReservation {
+
+ return &ChannelReservation{
+ ourContribution: &ChannelContribution{
+ ChannelConfig: chanCfg(ourReserve),
+ },
+ theirContribution: &ChannelContribution{
+ ChannelConfig: chanCfg(theirReserve),
+ },
+ partialState: &chanstate.OpenChannel{
+ LocalCommitment: channeldb.ChannelCommitment{
+ LocalBalance: msat(ourBalance),
+ RemoteBalance: msat(theirBalance),
+ },
+ },
+ }
+ }
+
+ for _, ourReserve := range reserves {
+ for _, theirReserve := range reserves {
+ for _, ourBalance := range amounts {
+ for _, theirBalance := range amounts {
+ res := reservation(
+ ourBalance, theirBalance,
+ ourReserve, theirReserve,
+ )
+
+ err := res.validateInitialBalances()
+
+ // What the BOLT-02 comparison on its
+ // own would have done, computed here
+ // rather than read from the code under
+ // test.
+ specAlone := ourBalance <= ourReserve &&
+ theirBalance <= ourReserve
+
+ // A channel is usable if either side
+ // can add an HTLC without dipping below
+ // the reserve that side must maintain.
+ usable := ourBalance > ourReserve ||
+ theirBalance > theirReserve
+
+ rejected := err != nil
+
+ // The spec comparison must never be
+ // bypassed: whenever it fires, so must
+ // the check.
+ if specAlone && !rejected {
+ t.Fatalf("spec comparison did "+
+ "not reject: our=%v "+
+ "their=%v "+
+ "ourReserve=%v "+
+ "theirReserve=%v",
+ ourBalance,
+ theirBalance,
+ ourReserve,
+ theirReserve,
+ )
+ }
+
+ // Any rejection beyond the spec's must
+ // be a channel neither side can spend
+ // on.
+ if rejected && !specAlone {
+ addedRejections++
+
+ if usable {
+ t.Fatalf("rejected a "+
+ "usable "+
+ "channel the "+
+ "spec allows: "+
+ "our=%v "+
+ "their=%v "+
+ "ourRes=%v "+
+ "theirRes=%v",
+ ourBalance,
+ theirBalance,
+ ourReserve,
+ theirReserve,
+ )
+ }
+ }
+
+ // And the converse: a channel where
+ // neither side can spend must not be
+ // accepted.
+ if !usable && !rejected {
+ t.Fatalf("accepted a dead "+
+ "channel: our=%v "+
+ "their=%v "+
+ "ourReserve=%v "+
+ "theirReserve=%v",
+ ourBalance,
+ theirBalance,
+ ourReserve,
+ theirReserve,
+ )
+ }
+ }
+ }
+ }
+ }
+
+ // The sweep has to actually reach the added-rejection band, or the
+ // assertions above would vacuously hold.
+ require.Positive(t, addedRejections,
+ "the sweep never hit a channel the "+
+ "usability check adds, so it did "+
+ "not exercise the property")
+}
### lnwallet/wallet.go
@@ -2126,6 +2126,14 @@ func (l *LightningWallet) handleSingleContribution(req *addSingleContributionMsg
return
}
+ // Now that both reserves are known, make sure the channel the initiator
+ // is proposing could actually be used: at least one side must start out
+ // above its reserve.
+ if err := pendingReservation.validateInitialBalances(); err != nil {
+ req.err <- err
+ return
+ }
+
// Initialize an empty sha-chain for them, tracking the current pending
// revocation hash (we don't yet know the preimage so we can't add it
// to the chain).Why this scored 47/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.