channeldb: add custom blobs to RevocationLog+HTLCEntry

This'll be useful for custom channel types that want to store extra information that'll be useful to help handle channel revocation cases.

Author: Roasbeef

channeldb/revocation_log.go

@@ -172,22 +172,32 @@ type HTLCEntry struct {
 	//
 	// NOTE: this field is the memory representation of the field amtUint.
 	Amt tlv.RecordT[tlv.TlvType4, tlv.BigSizeT[btcutil.Amount]]
+
+	// CustomBlob is an optional blob that can be used to store information
+	// specific to revocation handling for a custom channel type.
+	CustomBlob tlv.OptionalRecordT[tlv.TlvType5, tlv.Blob]
 }
 
 // toTlvStream converts an HTLCEntry record into a tlv representation.
 func (h *HTLCEntry) toTlvStream() (*tlv.Stream, error) {
-	return tlv.NewStream(
+	records := []tlv.Record{
 		h.RHash.Record(),
 		h.RefundTimeout.Record(),
 		h.OutputIndex.Record(),
 		h.Incoming.Record(),
 		h.Amt.Record(),
-	)
+	}
+
+	h.CustomBlob.WhenSome(func(r tlv.RecordT[tlv.TlvType5, tlv.Blob]) {
+		records = append(records, r.Record())
+	})
+
+	return tlv.NewStream(records...)
 }
 
 // NewHTLCEntryFromHTLC creates a new HTLCEntry from an HTLC.
 func NewHTLCEntryFromHTLC(htlc HTLC) *HTLCEntry {
-	return &HTLCEntry{
+	h := &HTLCEntry{
 		RHash: tlv.NewRecordT[tlv.TlvType0](
 			NewSparsePayHash(htlc.RHash),
 		),
@@ -202,6 +212,16 @@ func NewHTLCEntryFromHTLC(htlc HTLC) *HTLCEntry {
 			tlv.NewBigSizeT(htlc.Amt.ToSatoshis()),
 		),
 	}
+
+	if len(htlc.ExtraData) != 0 {
+		h.CustomBlob = tlv.SomeRecordT(
+			tlv.NewPrimitiveRecord[tlv.TlvType5, tlv.Blob](
+				htlc.ExtraData,
+			),
+		)
+	}
+
+	return h
 }
 
 // RevocationLog stores the info needed to construct a breach retribution. Its
@@ -244,13 +264,19 @@ type RevocationLog struct {
 	// this field, it could be the case that the field is not present for
 	// all revocation logs.
 	TheirBalance tlv.OptionalRecordT[tlv.TlvType4, BigSizeMilliSatoshi]
+
+	// CustomBlob is an optional blob that can be used to store information
+	// specific to a custom channel type. This information is only created
+	// at channel funding time, and after wards is to be considered
+	// immutable.
+	CustomBlob tlv.OptionalRecordT[tlv.TlvType5, tlv.Blob]
 }
 
 // NewRevocationLog creates a new RevocationLog from the given parameters.
 func NewRevocationLog(ourOutputIndex uint16, theirOutputIndex uint16,
 	commitHash [32]byte, ourBalance,
-	theirBalance fn.Option[lnwire.MilliSatoshi],
-	htlcs []*HTLCEntry) RevocationLog {
+	theirBalance fn.Option[lnwire.MilliSatoshi], htlcs []*HTLCEntry,
+	customBlob fn.Option[tlv.Blob]) RevocationLog {
 
 	rl := RevocationLog{
 		OurOutputIndex: tlv.NewPrimitiveRecord[tlv.TlvType0](
@@ -275,6 +301,12 @@ func NewRevocationLog(ourOutputIndex uint16, theirOutputIndex uint16,
 		))
 	})
 
+	customBlob.WhenSome(func(blob tlv.Blob) {
+		rl.CustomBlob = tlv.SomeRecordT(
+			tlv.NewPrimitiveRecord[tlv.TlvType5, tlv.Blob](blob),
+		)
+	})
+
 	return rl
 }
 
@@ -306,6 +338,12 @@ func putRevocationLog(bucket kvdb.RwBucket, commit *ChannelCommitment,
 		HTLCEntries: make([]*HTLCEntry, 0, len(commit.Htlcs)),
 	}
 
+	commit.CustomBlob.WhenSome(func(blob tlv.Blob) {
+		rl.CustomBlob = tlv.SomeRecordT(
+			tlv.NewPrimitiveRecord[tlv.TlvType5, tlv.Blob](blob),
+		)
+	})
+
 	if !noAmtData {
 		rl.OurBalance = tlv.SomeRecordT(tlv.NewRecordT[tlv.TlvType3](
 			tlv.NewBigSizeT(commit.LocalBalance),
@@ -381,6 +419,10 @@ func serializeRevocationLog(w io.Writer, rl *RevocationLog) error {
 		},
 	)
 
+	rl.CustomBlob.WhenSome(func(r tlv.RecordT[tlv.TlvType5, tlv.Blob]) {
+		records = append(records, r.Record())
+	})
+
 	// Create the tlv stream.
 	tlvStream, err := tlv.NewStream(records...)
 	if err != nil {
@@ -421,6 +463,7 @@ func deserializeRevocationLog(r io.Reader) (RevocationLog, error) {
 
 	ourBalance := rl.OurBalance.Zero()
 	theirBalance := rl.TheirBalance.Zero()
+	customBlob := rl.CustomBlob.Zero()
 
 	// Create the tlv stream.
 	tlvStream, err := tlv.NewStream(
@@ -429,6 +472,7 @@ func deserializeRevocationLog(r io.Reader) (RevocationLog, error) {
 		rl.CommitTxHash.Record(),
 		ourBalance.Record(),
 		theirBalance.Record(),
+		customBlob.Record(),
 	)
 	if err != nil {
 		return rl, err
@@ -448,6 +492,10 @@ func deserializeRevocationLog(r io.Reader) (RevocationLog, error) {
 		rl.TheirBalance = tlv.SomeRecordT(theirBalance)
 	}
 
+	if t, ok := parsedTypes[customBlob.TlvType()]; ok && t == nil {
+		rl.CustomBlob = tlv.SomeRecordT(customBlob)
+	}
+
 	// Read the HTLC entries.
 	rl.HTLCEntries, err = deserializeHTLCEntries(r)
 
@@ -462,21 +510,37 @@ func deserializeHTLCEntries(r io.Reader) ([]*HTLCEntry, error) {
 	for {
 		var htlc HTLCEntry
 
+		customBlob := htlc.CustomBlob.Zero()
+
 		// Create the tlv stream.
-		tlvStream, err := htlc.toTlvStream()
+		records := []tlv.Record{
+			htlc.RHash.Record(),
+			htlc.RefundTimeout.Record(),
+			htlc.OutputIndex.Record(),
+			htlc.Incoming.Record(),
+			htlc.Amt.Record(),
+			customBlob.Record(),
+		}
+
+		tlvStream, err := tlv.NewStream(records...)
 		if err != nil {
 			return nil, err
 		}
 
 		// Read the HTLC entry.
-		if _, err := readTlvStream(r, tlvStream); err != nil {
+		parsedTypes, err := readTlvStream(r, tlvStream)
+		if err != nil {
 			// We've reached the end when hitting an EOF.
 			if err == io.ErrUnexpectedEOF {
 				break
 			}
 			return nil, err
 		}
 
+		if t, ok := parsedTypes[customBlob.TlvType()]; ok && t == nil {
+			htlc.CustomBlob = tlv.SomeRecordT(customBlob)
+		}
+
 		// Append the entry.
 		htlcs = append(htlcs, &htlc)
 	}

channeldb/revocation_log_test.go

@@ -34,6 +34,10 @@ var (
 		0xff, // value = 255
 	}
 
+	blobBytes = tlv.Blob{
+		0x01, 0x02, 0x03, 0x04,
+	}
+
 	testHTLCEntry = HTLCEntry{
 		RefundTimeout: tlv.NewPrimitiveRecord[tlv.TlvType1, uint32](
 			740_000,
@@ -45,10 +49,13 @@ var (
 		Amt: tlv.NewRecordT[tlv.TlvType4](
 			tlv.NewBigSizeT(btcutil.Amount(1_000_000)),
 		),
+		CustomBlob: tlv.SomeRecordT(
+			tlv.NewPrimitiveRecord[tlv.TlvType5](blobBytes),
+		),
 	}
 	testHTLCEntryBytes = []byte{
-		// Body length 23.
-		0x16,
+		// Body length 28.
+		0x1c,
 		// Rhash tlv.
 		0x0, 0x0,
 		// RefundTimeout tlv.
@@ -59,6 +66,8 @@ var (
 		0x3, 0x1, 0x1,
 		// Amt tlv.
 		0x4, 0x5, 0xfe, 0x0, 0xf, 0x42, 0x40,
+		// Custom blob tlv.
+		0x5, 0x4, 0x1, 0x2, 0x3, 0x4,
 	}
 
 	localBalance  = lnwire.MilliSatoshi(9000)
@@ -79,17 +88,19 @@ var (
 			Amt: lnwire.NewMSatFromSatoshis(
 				testHTLCEntry.Amt.Val.Int(),
 			),
+			ExtraData: blobBytes,
 		}},
+		CustomBlob: fn.Some(blobBytes),
 	}
 
 	testRevocationLogNoAmts = NewRevocationLog(
 		0, 1, testChannelCommit.CommitTx.TxHash(),
 		fn.None[lnwire.MilliSatoshi](), fn.None[lnwire.MilliSatoshi](),
-		[]*HTLCEntry{&testHTLCEntry},
+		[]*HTLCEntry{&testHTLCEntry}, fn.Some(blobBytes),
 	)
 	testRevocationLogNoAmtsBytes = []byte{
-		// Body length 42.
-		0x2a,
+		// Body length 48.
+		0x30,
 		// OurOutputIndex tlv.
 		0x0, 0x2, 0x0, 0x0,
 		// TheirOutputIndex tlv.
@@ -100,16 +111,18 @@ var (
 		0x6e, 0x60, 0x29, 0x23, 0x1d, 0x5e, 0xc5, 0xe6,
 		0xbd, 0xf7, 0xd3, 0x9b, 0x16, 0x7d, 0x0, 0xff,
 		0xc8, 0x22, 0x51, 0xb1, 0x5b, 0xa0, 0xbf, 0xd,
+		// Custom blob tlv.
+		0x5, 0x4, 0x1, 0x2, 0x3, 0x4,
 	}
 
 	testRevocationLogWithAmts = NewRevocationLog(
 		0, 1, testChannelCommit.CommitTx.TxHash(),
 		fn.Some(localBalance), fn.Some(remoteBalance),
-		[]*HTLCEntry{&testHTLCEntry},
+		[]*HTLCEntry{&testHTLCEntry}, fn.Some(blobBytes),
 	)
 	testRevocationLogWithAmtsBytes = []byte{
-		// Body length 52.
-		0x34,
+		// Body length 58.
+		0x3a,
 		// OurOutputIndex tlv.
 		0x0, 0x2, 0x0, 0x0,
 		// TheirOutputIndex tlv.
@@ -124,6 +137,8 @@ var (
 		0x3, 0x3, 0xfd, 0x23, 0x28,
 		// Remote Balance.
 		0x4, 0x3, 0xfd, 0x0b, 0xb8,
+		// Custom blob tlv.
+		0x5, 0x4, 0x1, 0x2, 0x3, 0x4,
 	}
 )
 
@@ -220,7 +235,7 @@ func TestSerializeHTLCEntries(t *testing.T) {
 	partialBytes := testHTLCEntryBytes[3:]
 
 	// Write the total length and RHash tlv.
-	expectedBytes := []byte{0x36, 0x0, 0x20}
+	expectedBytes := []byte{0x3c, 0x0, 0x20}
 	expectedBytes = append(expectedBytes, rHashBytes...)
 
 	// Append the rest.
@@ -335,7 +350,7 @@ func TestDerializeHTLCEntries(t *testing.T) {
 	partialBytes := testHTLCEntryBytes[3:]
 
 	// Write the total length and RHash tlv.
-	testBytes := append([]byte{0x36, 0x0, 0x20}, rHashBytes...)
+	testBytes := append([]byte{0x3c, 0x0, 0x20}, rHashBytes...)
 
 	// Append the rest.
 	testBytes = append(testBytes, partialBytes...)

lnwallet/channel_test.go

@@ -10025,7 +10025,7 @@ func TestCreateBreachRetribution(t *testing.T) {
 	revokedLog := channeldb.NewRevocationLog(
 		uint16(localIndex), uint16(remoteIndex), commitHash,
 		fn.Some(ourAmtMsat), fn.Some(theirAmtMsat),
-		[]*channeldb.HTLCEntry{htlc},
+		[]*channeldb.HTLCEntry{htlc}, fn.None[tlv.Blob](),
 	)
 
 	// Create a log with an empty local output index.