lnwallet: require an aux sig per HTLC on taproot overlay channels
What changed, and why it matters
This commit fixes a bug in LND's taproot overlay Lightning channels where a peer could deliberately leave out an extra signature (aux sig) for one or more HTLCs. Because the code only checked the main Bitcoin signatures, the missing aux signature went unnoticed. Later, if the channel was force-closed, the affected HTLC could not be swept on-chain, potentially locking up funds. The fix adds a count check so that every non-dust HTLC must have a matching aux signature on taproot overlay channels.
Upgrade LND nodes running taproot overlay channels to a release containing this commit. Nodes not using taproot overlay channels or not configuring an aux signer are not affected. Monitor channels for force-close scenarios and verify that all HTLCs can be swept.
Security signals we found
Missing input validation on peer-supplied aux signature blob length
State acceptance despite incomplete signature set
On-chain fund recovery failure (second-level HTLC unsweepable) after force close
Peer-triggered omission could strand HTLC value
Fix is narrowly scoped to taproot overlay channels with active aux signer
Evidence from the diff
In lnwallet/channel.go’s genHtlcSigValidationJobs, the existing code validated that the number of BTC-level htlcSigs matched the expected count i, but did not enforce the same for auxHtlcSigs on custom channels. The aux signature blob is peer-supplied and carries no count, so a peer could omit an entry and no verification job would be created for that HTLC. The commitment would still be accepted as the local state, and at force-close the resolver would read an empty signature from the HTLC’s custom records, preventing the second-level HTLC from being swept. The patch adds a length check gated on auxSigner.IsSome() && chanType.HasTapscriptRoot(), ensuring aux signatures are required only for taproot overlay channels and only when an aux signer is configured. Tests cover honest, withheld, extra, dust-HTLC, plain-channel, no-signer, and signer-rejection cases.
Changed components
lnwallet/channel.golnwallet/channel_test.gotaproot overlay Lightning channelsaux signer / custom channel signature verificationHTLC second-level sweep resolverInspect captured patch +323 / −0
### lnwallet/channel.go
@@ -5292,6 +5292,28 @@ func genHtlcSigValidationJobs(chanState *chanstate.OpenChannel,
"Expected %v sigs, got %v", i, len(htlcSigs))
}
+ // The same has to hold for the aux signatures on a custom channel. An
+ // aux signer emits one entry per non-dust HTLC, in lockstep with the
+ // BTC level signatures, so a peer sending fewer has withheld a
+ // signature we need to resolve that HTLC on chain later. The blob
+ // carries no count of its own, and a missing entry produces no
+ // verification job, so this is the only place the omission is visible.
+ //
+ // This is gated on the channel being a taproot overlay one, and not
+ // merely on an aux signer being present: the signer is configured node
+ // wide, so it is also attached to plain channels, whose peers
+ // correctly send no aux signatures at all. The tapscript root bit is
+ // set at funding time if and only if the commitment type is a taproot
+ // overlay, so it identifies precisely the channels whose peers owe us
+ // aux signatures. It is still also gated on the aux signer, since
+ // without one there is nothing that could consume those signatures.
+ if auxSigner.IsSome() && chanType.HasTapscriptRoot() &&
+ len(auxHtlcSigs) != i {
+
+ return nil, nil, fmt.Errorf("number of aux htlc sig mismatch. "+
+ "Expected %v sigs, got %v", i, len(auxHtlcSigs))
+ }
+
return verifyJobs, auxVerifyJobs, nil
}
### lnwallet/channel_test.go
@@ -12057,3 +12057,304 @@ func TestEvaluateNoOpHtlc(t *testing.T) {
require.Equal(t, tc.expectedDeltas, tc.balanceDeltas)
}
}
+
+// taprootOverlayChanType is the channel type of a taproot overlay channel. The
+// tapscript root bit is what marks it as one, and therefore as a channel whose
+// peer owes us an aux signature for every HTLC.
+var taprootOverlayChanType = channeldb.SingleFunderTweaklessBit |
+ channeldb.AnchorOutputsBit | channeldb.SimpleTaprootFeatureBit |
+ channeldb.TapscriptRootBit
+
+// auxHtlcAmt is the amount of the HTLCs added by createAuxHtlcChannels. It is
+// well above both channels' dust limit, so each such HTLC gets its own
+// commitment output and therefore its own signature.
+const auxHtlcAmt = btcutil.Amount(20000)
+
+// auxDustHtlcAmt is an amount below Bob's dust limit, so an HTLC of this size
+// gets no output on the commitment Alice signs for Bob, and therefore no
+// signature of either kind.
+const auxDustHtlcAmt = btcutil.Amount(1000)
+
+// addAuxHtlc adds a single HTLC of the given amount, offered by Alice and
+// received by Bob. The index seeds the payment preimage, so callers must pass a
+// distinct index for each HTLC added to the same pair of channels.
+func addAuxHtlc(t *testing.T, aliceChannel, bobChannel *LightningChannel,
+ idx int, amt btcutil.Amount) {
+
+ var fakeOnionBlob [lnwire.OnionPacketSize]byte
+ copy(
+ fakeOnionBlob[:],
+ bytes.Repeat([]byte{0x05}, lnwire.OnionPacketSize),
+ )
+
+ var preimage [32]byte
+ copy(preimage[:], bytes.Repeat([]byte{byte(idx)}, 32))
+
+ htlc := &lnwire.UpdateAddHTLC{
+ PaymentHash: sha256.Sum256(preimage[:]),
+ Amount: lnwire.NewMSatFromSatoshis(amt),
+ Expiry: uint32(10),
+ OnionBlob: fakeOnionBlob,
+ }
+
+ htlcIndex, err := aliceChannel.AddHTLC(htlc, nil)
+ require.NoError(t, err, "unable to add htlc")
+
+ htlc.ID = htlcIndex
+ _, err = bobChannel.ReceiveHTLC(htlc)
+ require.NoError(t, err, "unable to recv htlc")
+}
+
+// createAuxHtlcChannels creates a pair of channels of the given type, with the
+// given number of HTLCs offered by Alice and received by Bob. The HTLCs are
+// well above the dust limit, so each of them gets its own commitment output
+// and therefore its own signature.
+func createAuxHtlcChannels(t *testing.T, chanType channeldb.ChannelType,
+ numHtlcs int) (*LightningChannel, *LightningChannel) {
+
+ aliceChannel, bobChannel, err := CreateTestChannels(t, chanType)
+ require.NoError(t, err, "unable to create test channels")
+
+ for idx := range numHtlcs {
+ addAuxHtlc(t, aliceChannel, bobChannel, idx, auxHtlcAmt)
+ }
+
+ return aliceChannel, bobChannel
+}
+
+// mockAuxSignerWithSigs installs an aux signer on the given channel that
+// reports the given number of unpacked signature slots, regardless of what the
+// remote party actually sent. That stands in for a peer whose commit_sig
+// carried that many aux signatures.
+func mockAuxSignerWithSigs(channel *LightningChannel,
+ numSigs int) *MockAuxSigner {
+
+ auxSigner := NewAuxSignerMock(EmptyMockJobHandler)
+ channel.auxSigner = fn.Some[AuxSigner](auxSigner)
+
+ slots := make([]fn.Option[tlv.Blob], numSigs)
+ for idx := range slots {
+ slots[idx] = fn.Some(tlv.Blob{0x01})
+ }
+
+ auxSigner.On("UnpackSigs", mock.Anything).Return(fn.Ok(slots))
+ auxSigner.On(
+ "VerifySecondLevelSigs", mock.Anything, mock.Anything,
+ mock.Anything,
+ ).Return(nil)
+
+ return auxSigner
+}
+
+// TestAuxSigCount tests that a taproot overlay commitment is accepted only
+// when the remote party supplied exactly one aux signature per HTLC.
+//
+// A peer can otherwise withhold the aux signature for an HTLC: no verification
+// job is produced for it, nothing reports the omission, and the commitment
+// becomes our state carrying a signature we never received. At force close the
+// resolver then reads an empty signature out of that HTLC's custom records and
+// the second level HTLC cannot be swept.
+func TestAuxSigCount(t *testing.T) {
+ t.Parallel()
+
+ testCases := []struct {
+ name string
+ numHtlcs int
+ numDustHtlcs int
+ numSigs int
+ expectErr bool
+ }{{
+ // The honest case: an aux signer emits one signature per
+ // non-dust HTLC, so the counts line up.
+ name: "one signature per htlc",
+ numHtlcs: 2,
+ numSigs: 2,
+ }, {
+ name: "all signatures withheld",
+ numHtlcs: 1,
+ numSigs: 0,
+ expectErr: true,
+ }, {
+ // The subtler withholding: enough signatures to look
+ // plausible, but one HTLC left unsigned.
+ name: "one signature withheld",
+ numHtlcs: 2,
+ numSigs: 1,
+ expectErr: true,
+ }, {
+ name: "more signatures than htlcs",
+ numHtlcs: 1,
+ numSigs: 2,
+ expectErr: true,
+ }, {
+ // A dust HTLC has no output on the commitment, so it gets
+ // neither a BTC level nor an aux signature. This pins the
+ // invariant the count check relies on: the aux signatures are
+ // emitted on the same non-dust basis as the BTC level ones.
+ name: "dust htlc gets no signature",
+ numHtlcs: 1,
+ numDustHtlcs: 1,
+ numSigs: 1,
+ }, {
+ // Signing the dust HTLC as well is exactly the divergence that
+ // the count check is there to catch.
+ name: "dust htlc signed anyway",
+ numHtlcs: 1,
+ numDustHtlcs: 1,
+ numSigs: 2,
+ expectErr: true,
+ }}
+
+ for _, tc := range testCases {
+ t.Run(tc.name, func(t *testing.T) {
+ t.Parallel()
+
+ aliceChannel, bobChannel := createAuxHtlcChannels(
+ t, taprootOverlayChanType, tc.numHtlcs,
+ )
+ for idx := range tc.numDustHtlcs {
+ addAuxHtlc(
+ t, aliceChannel, bobChannel,
+ tc.numHtlcs+idx, auxDustHtlcAmt,
+ )
+ }
+
+ mockAuxSignerWithSigs(bobChannel, tc.numSigs)
+
+ aliceNewCommit, err := aliceChannel.SignNextCommitment(
+ ctxb,
+ )
+ require.NoError(t, err, "unable to sign commitment")
+
+ err = bobChannel.ReceiveNewCommitment(
+ aliceNewCommit.CommitSigs,
+ )
+ if !tc.expectErr {
+ require.NoError(t, err)
+
+ return
+ }
+
+ require.ErrorContains(
+ t, err, "number of aux htlc sig mismatch",
+ )
+ })
+ }
+}
+
+// TestAuxSigBlobOmittedFailsCommitment tests the same rejection, but driven by
+// the field a remote party actually controls: a commit_sig that carries no aux
+// signature custom record at all. ReceiveNewCommitment turns a nil AuxSigBlob
+// into fn.None, and a real aux signer unpacks that into no signatures.
+func TestAuxSigBlobOmittedFailsCommitment(t *testing.T) {
+ t.Parallel()
+
+ aliceChannel, bobChannel := createAuxHtlcChannels(
+ t, taprootOverlayChanType, 1,
+ )
+
+ // Bob's aux signer mirrors the real one: an absent blob unpacks to no
+ // signatures at all. We record what it was handed, so the test can
+ // show it exercised the absent blob branch rather than assuming it.
+ auxSigner := NewAuxSignerMock(EmptyMockJobHandler)
+ bobChannel.auxSigner = fn.Some[AuxSigner](auxSigner)
+
+ var unpackedBlob fn.Option[tlv.Blob]
+ auxSigner.On("UnpackSigs", mock.Anything).Run(func(a mock.Arguments) {
+ blob, ok := a.Get(0).(fn.Option[tlv.Blob])
+ require.True(t, ok)
+ unpackedBlob = blob
+ }).Return(fn.Ok[[]fn.Option[tlv.Blob]](nil))
+
+ aliceNewCommit, err := aliceChannel.SignNextCommitment(ctxb)
+ require.NoError(t, err, "unable to sign commitment")
+
+ // Alice's commit_sig does carry an aux signature blob. Stripping it is
+ // precisely what a peer omitting the custom record looks like here.
+ require.NotNil(t, aliceNewCommit.AuxSigBlob)
+ aliceNewCommit.AuxSigBlob = nil
+
+ err = bobChannel.ReceiveNewCommitment(aliceNewCommit.CommitSigs)
+ require.ErrorContains(t, err, "number of aux htlc sig mismatch")
+
+ // The blob really was absent by the time lnd asked the aux signer to
+ // unpack it, so this was the wire level case.
+ require.True(t, unpackedBlob.IsNone())
+}
+
+// TestAuxSigNotRequiredOnPlainChannel tests that a channel without the
+// tapscript root bit still accepts commitments carrying no aux signatures. The
+// aux signer is configured node wide, so a node running one also attaches it to
+// its plain channels, whose peers correctly send none. Requiring them there
+// would force close those channels.
+func TestAuxSigNotRequiredOnPlainChannel(t *testing.T) {
+ t.Parallel()
+
+ // The same channel type as the overlay one, minus the tapscript root
+ // bit, which is the only thing that marks a channel as an overlay.
+ plainChanType := taprootOverlayChanType &^ channeldb.TapscriptRootBit
+ aliceChannel, bobChannel := createAuxHtlcChannels(t, plainChanType, 1)
+
+ mockAuxSignerWithSigs(bobChannel, 0)
+
+ aliceNewCommit, err := aliceChannel.SignNextCommitment(ctxb)
+ require.NoError(t, err, "unable to sign commitment")
+
+ require.NoError(t, bobChannel.ReceiveNewCommitment(
+ aliceNewCommit.CommitSigs,
+ ))
+}
+
+// TestAuxSigNotRequiredWithoutAuxSigner tests that an overlay channel on a node
+// with no aux signer configured still accepts commitments carrying no aux
+// signatures. Without a signer there is nothing that could consume them, so
+// demanding them would only strand the channel.
+func TestAuxSigNotRequiredWithoutAuxSigner(t *testing.T) {
+ t.Parallel()
+
+ aliceChannel, bobChannel := createAuxHtlcChannels(
+ t, taprootOverlayChanType, 1,
+ )
+
+ bobChannel.auxSigner = fn.None[AuxSigner]()
+
+ aliceNewCommit, err := aliceChannel.SignNextCommitment(ctxb)
+ require.NoError(t, err, "unable to sign commitment")
+
+ require.NoError(t, bobChannel.ReceiveNewCommitment(
+ aliceNewCommit.CommitSigs,
+ ))
+}
+
+// TestAuxSigRejectionFailsCommitment tests that when the aux signer rejects a
+// verification job, the new commitment is rejected as a whole. The count check
+// only establishes that a signature arrived for every HTLC; this is what makes
+// the aux signer's verdict on those signatures binding.
+func TestAuxSigRejectionFailsCommitment(t *testing.T) {
+ t.Parallel()
+
+ aliceChannel, bobChannel := createAuxHtlcChannels(
+ t, taprootOverlayChanType, 1,
+ )
+
+ auxSigner := NewAuxSignerMock(EmptyMockJobHandler)
+ bobChannel.auxSigner = fn.Some[AuxSigner](auxSigner)
+
+ // The peer sends a well formed blob with one entry for the single
+ // HTLC, so the count check passes and the aux signer gets to weigh in
+ // on the signature itself. It rejects.
+ auxSigner.On("UnpackSigs", mock.Anything).Return(
+ fn.Ok([]fn.Option[tlv.Blob]{fn.Some(tlv.Blob{0x01})}),
+ )
+ auxSigner.On(
+ "VerifySecondLevelSigs", mock.Anything, mock.Anything,
+ mock.Anything,
+ ).Return(fmt.Errorf("second level sig verification failed"))
+
+ aliceNewCommit, err := aliceChannel.SignNextCommitment(ctxb)
+ require.NoError(t, err, "unable to sign commitment")
+
+ err = bobChannel.ReceiveNewCommitment(aliceNewCommit.CommitSigs)
+ require.ErrorContains(t, err, "unable to validate aux sigs")
+ require.ErrorContains(t, err, "second level sig verification failed")
+}Why this scored 74/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.