lnwallet+chanstate: keep persisted HTLC data readable
What changed, and why it matters
This commit fixes two bugs in how Lightning Network channel data is saved to disk. First, it stops extra 'aux' signatures meant only for advanced taproot channels from being saved on ordinary channels, where they don't belong. Second, it prevents a channel from being saved with an HTLC (a routed payment slot) whose attached data is too large to be read back later, which would previously have made the whole channel unrecoverable on restart.
Treat this as a hardening fix with availability impact. Review whether any existing channel databases contain plain-channel HTLCs with unexpected aux custom records, and consider backporting to supported release branches because the unreadable-state bug can lock user funds on restart.
Security signals we found
Persisted state could become unreadable due to writer/reader size mismatch
Auxiliary signatures for taproot overlay channels were persisted on plain channel HTLCs
Fix adds explicit serialization bound to prevent unreadable channel records
Fix gates aux-signature attachment on tapscript root channel type
Evidence from the diff
The patch enforces two invariants in LND’s persisted channel state. (1) In lnwallet/channel.go, genHtlcSigValidationJobs now only attaches auxHtlcSigs[i] to an HTLC when chanType.HasTapscriptRoot() is true, preventing aux data from being copied into HTLC custom records and persisted for plain channels. (2) In chanstate/codec.go, the existing 66,000-byte reader limit for variable-length byte slices is exposed as maxVarBytesLen, and SerializeHtlcs in chanstate/kv_commitment.go now rejects any HTLC whose combined onion blob plus extra data exceeds that limit. Previously, the writer was unbounded while the reader was capped, so an oversized HTLC could be written successfully but render the entire channel unreadable on the next load. Tests are added for both bounds.
Changed components
chanstate/codec.gochanstate/kv_commitment.golnwallet/channel.gochannel state persistence / HTLC serializationaux signature handling for taproot overlay channelsInspect captured patch +101 / −2
### chanstate/codec.go
@@ -18,6 +18,11 @@ import (
"github.com/lightningnetwork/lnd/tlv"
)
+// maxVarBytesLen is the largest variable length byte slice ReadElement will
+// decode. Writers of persisted state must stay within it, or the record they
+// write can never be read back.
+const maxVarBytesLen = 66000
+
var byteOrder = binary.BigEndian
// UnknownElementType is an error returned when the codec is unable to encode or
@@ -380,7 +385,7 @@ func ReadElement(r io.Reader, element interface{}) error { //nolint:funlen
}
case *[]byte:
- bytes, err := wire.ReadVarBytes(r, 0, 66000, "[]byte")
+ bytes, err := wire.ReadVarBytes(r, 0, maxVarBytesLen, "[]byte")
if err != nil {
return err
}
### chanstate/kv_commitment.go
@@ -108,6 +108,14 @@ func SerializeHtlcs(b io.Writer, htlcs ...HTLC) error {
copy(onionAndExtraData, htlc.OnionBlob[:])
copy(onionAndExtraData[lnwire.OnionPacketSize:], htlc.ExtraData)
+ // Refuse to write an HTLC that the reader would reject, as a
+ // single unreadable HTLC makes the whole channel unreadable.
+ if len(onionAndExtraData) > maxVarBytesLen {
+ return fmt.Errorf("htlc onion and extra data too "+
+ "large: %d > max %d", len(onionAndExtraData),
+ maxVarBytesLen)
+ }
+
if err := WriteElements(b,
//nolint:ll
htlc.Signature, htlc.RHash, htlc.Amt, htlc.RefundTimeout,
### chanstate/kv_commitment_test.go
@@ -0,0 +1,52 @@
+package chanstate
+
+import (
+ "bytes"
+ "testing"
+
+ "github.com/lightningnetwork/lnd/lnwire"
+ "github.com/stretchr/testify/require"
+)
+
+// TestSerializeHtlcsReadableBound checks that an HTLC is only written while
+// its combined onion and extra data stays within what the reader accepts, so
+// every HTLC that is written can be read back.
+func TestSerializeHtlcsReadableBound(t *testing.T) {
+ t.Parallel()
+
+ const customType = uint64(lnwire.MinCustomRecordsTlvType + 7)
+
+ // newHtlc returns an HTLC with one custom record holding a value of
+ // the given size.
+ newHtlc := func(valueLen int) HTLC {
+ return HTLC{
+ CustomRecords: lnwire.CustomRecords{
+ customType: bytes.Repeat([]byte{1}, valueLen),
+ },
+ }
+ }
+
+ // Measure the TLV overhead of the custom record, which is the same
+ // for every value length between 253 and 65535 bytes.
+ const probeLen = 1_000
+ probe := newHtlc(probeLen)
+ require.NoError(t, serializeHtlcExtraData(&probe))
+ overhead := len(probe.ExtraData) - probeLen
+
+ // The largest value that keeps the HTLC within the reader's limit.
+ maxValueLen := maxVarBytesLen - lnwire.OnionPacketSize - overhead
+
+ // An HTLC exactly at the limit is written and reads back intact.
+ var b bytes.Buffer
+ require.NoError(t, SerializeHtlcs(&b, newHtlc(maxValueLen)))
+
+ htlcs, err := DeserializeHtlcs(&b)
+ require.NoError(t, err)
+ require.Len(t, htlcs, 1)
+ require.Len(t, htlcs[0].CustomRecords[customType], maxValueLen)
+
+ // One more byte would make the record unreadable, so it is refused.
+ b.Reset()
+ err = SerializeHtlcs(&b, newHtlc(maxValueLen+1))
+ require.ErrorContains(t, err, "too large")
+}
### lnwallet/channel.go
@@ -5277,7 +5277,10 @@ func genHtlcSigValidationJobs(chanState *chanstate.OpenChannel,
SigHash: sigHash,
})
- if len(auxHtlcSigs) > i {
+ // Only taproot overlay channels carry aux signatures, so we
+ // don't attach or persist aux data a peer sends for any other
+ // channel type. This matches the per-HTLC count check below.
+ if chanType.HasTapscriptRoot() && len(auxHtlcSigs) > i {
auxSig := auxHtlcSigs[i]
auxVerifyJob := NewAuxVerifyJob(
auxSig, *keyRing, incoming,
### lnwallet/channel_test.go
@@ -12622,6 +12622,37 @@ func TestAuxSigNotRequiredOnPlainChannel(t *testing.T) {
))
}
+// TestAuxSigIgnoredOnPlainChannel tests that aux signatures sent for a channel
+// without the tapscript root bit are neither attached to the HTLC nor stored
+// with it. Only overlay channels use aux signatures, so the HTLC records of a
+// plain channel must not carry any.
+func TestAuxSigIgnoredOnPlainChannel(t *testing.T) {
+ t.Parallel()
+
+ plainChanType := taprootOverlayChanType &^ channeldb.TapscriptRootBit
+ aliceChannel, bobChannel := createAuxHtlcChannels(t, plainChanType, 1)
+
+ mockAuxSignerWithSigs(bobChannel, 1)
+
+ aliceNewCommit, err := aliceChannel.SignNextCommitment(ctxb)
+ require.NoError(t, err, "unable to sign commitment")
+
+ require.NoError(t, bobChannel.ReceiveNewCommitment(
+ aliceNewCommit.CommitSigs,
+ ))
+
+ // Revoking persists the new local commitment, whose HTLC must not
+ // carry the aux signature.
+ _, _, _, err = bobChannel.RevokeCurrentCommitment()
+ require.NoError(t, err, "unable to revoke commitment")
+
+ htlcs := bobChannel.channelState.LocalCommitment.Htlcs
+ require.Len(t, htlcs, 1)
+
+ sigType := uint64(htlcCustomSigType.TypeVal())
+ require.NotContains(t, htlcs[0].CustomRecords, sigType)
+}
+
// 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, soWhy this scored 58/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.