multi: log additional information for local force closures

channeldb/channel.go

@@ -3252,6 +3252,96 @@ const (
 	Abandoned ClosureType = 5
 )
 
+// LocalForceCloseInitiator is a type that gives information about what led to a
+// channel being force closed locally.
+type LocalForceCloseInitiator string
+
+const (
+	// UserInitiated indicates that the force close was specifically
+	// initiated by the user.
+	UserInitiated LocalForceCloseInitiator = "user initiated"
+
+	// ChainActionsInitiated indicates that the force close was
+	// automatically initiated by an on-chain trigger such as HTLC timeout.
+	ChainActionsInitiated LocalForceCloseInitiator = "chain action" +
+		" initiated"
+
+	// localForceCloseInitiatorType is used to serialize/deserialize
+	// localForceCloseInitiator.
+	localForceCloseInitiatorType tlv.Type = 0
+)
+
+// String returns the human-readable format of the LocalForceCloseInitiator.
+func (l *LocalForceCloseInitiator) String() string {
+	return string(*l)
+}
+
+// SerializeLocalForceCloseInitiator writes out the passed set of
+// LocalForceCloseInitiator to the passed writer.
+func SerializeLocalForceCloseInitiator(w io.Writer,
+	lc *LocalForceCloseInitiator) error {
+
+	localForceCloseReasonByte := []byte(*lc)
+
+	tlvStream, err := tlv.NewStream(
+		tlv.MakePrimitiveRecord(localForceCloseInitiatorType,
+			&localForceCloseReasonByte),
+	)
+
+	if err != nil {
+		return err
+	}
+	var b bytes.Buffer
+	err = tlvStream.Encode(&b)
+	if err != nil {
+		return err
+	}
+
+	err = binary.Write(w, byteOrder, uint64(b.Len()))
+	if err != nil {
+		return err
+	}
+
+	if _, err = w.Write(b.Bytes()); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+// DeserializeLocalForceCloseInitiator reads out the ForceCloseInitiator from
+// the reader.
+func DeserializeLocalForceCloseInitiator(r io.Reader) (LocalForceCloseInitiator,
+	error) {
+
+	var (
+		lc []byte
+	)
+
+	tlvStream, err := tlv.NewStream(
+		tlv.MakePrimitiveRecord(
+			localForceCloseInitiatorType, &lc,
+		),
+	)
+
+	if err != nil {
+		return LocalForceCloseInitiator(lc), err
+	}
+
+	var bodyLen int64
+	err = binary.Read(r, byteOrder, &bodyLen)
+	if err != nil {
+		return LocalForceCloseInitiator(lc), err
+	}
+
+	lr := io.LimitReader(r, bodyLen)
+	if err = tlvStream.Decode(lr); err != nil {
+		return LocalForceCloseInitiator(lc), err
+	}
+
+	return LocalForceCloseInitiator(lc), nil
+}
+
 // ChannelCloseSummary contains the final state of a channel at the point it
 // was closed. Once a channel is closed, all the information pertaining to that
 // channel within the openChannelBucket is deleted, and a compact summary is

channeldb/channel_test.go

@@ -1633,3 +1633,45 @@ func TestOnionBlobIncorrectLength(t *testing.T) {
 	_, err := DeserializeHtlcs(&b)
 	require.ErrorIs(t, err, ErrOnionBlobLength)
 }
+
+// TestLocalForceCloseInitiatorEncoding tests serializing and deserializing
+// LocalForceCloseInitiator.
+func TestLocalForceCloseInitiatorEncoding(t *testing.T) {
+	t.Parallel()
+
+	testCases := []struct {
+		name string
+		data LocalForceCloseInitiator
+	}{
+		{
+			name: "chain action initiated",
+			data: ChainActionsInitiated,
+		},
+		{
+			name: "user initiated",
+			data: ChainActionsInitiated,
+		},
+		{
+			name: "custom initiator",
+			data: LocalForceCloseInitiator("invalid update"),
+		},
+	}
+
+	for _, testCase := range testCases {
+		testCase := testCase
+
+		t.Run(testCase.name, func(t *testing.T) {
+			t.Parallel()
+
+			var b bytes.Buffer
+			err := SerializeLocalForceCloseInitiator(&b,
+				&testCase.data)
+			require.NoError(t, err)
+
+			r := bytes.NewReader(b.Bytes())
+			data, err := DeserializeLocalForceCloseInitiator(r)
+			require.NoError(t, err)
+			require.Equal(t, testCase.data, data)
+		})
+	}
+}

contractcourt/briefcase.go

@@ -118,6 +118,20 @@ type ArbitratorLog interface {
 	// introduced.
 	FetchChainActions() (ChainActionMap, error)
 
+	// LogLocalForceCloseInitiator records the passed-in
+	// localForceCloseInitiator object within the ArbitratorLog for deferred
+	// consumption. This is typically invoked when the channel force closure
+	// is first initiated either by the user or automatically (
+	// link error, HTLC actions, etc.).
+	LogLocalForceCloseInitiator(
+		initiator channeldb.LocalForceCloseInitiator) error
+
+	// FetchLocalForceCloseInitiator attempts to fetch the
+	// localForceCloseInitiator object that was previously logged in the
+	// ArbitratorLog.
+	FetchLocalForceCloseInitiator() (channeldb.LocalForceCloseInitiator,
+		error)
+
 	// WipeHistory is to be called ONLY once *all* contracts have been
 	// fully resolved, and the channel closure if finalized. This method
 	// will delete all on-disk state within the persistent log.
@@ -366,6 +380,10 @@ var (
 	// taprootDataKey is the key we'll use to store taproot specific data
 	// for the set of channels we'll need to sweep/claim.
 	taprootDataKey = []byte("taproot-data")
+
+	// localForceCloseInitiatorKey is the key that we use to store the
+	// localForceCloseInitiator object within the log, if any.
+	localForceCloseInitiatorKey = []byte("local-force-close-info")
 )
 
 var (
@@ -1047,6 +1065,65 @@ func (b *boltArbitratorLog) FetchChainActions() (ChainActionMap, error) {
 	return actionsMap, nil
 }
 
+// LogLocalForceCloseInitiator records the passed-in localForceCloseInitiator
+// object within the ArbitratorLog for deferred consumption. This is
+// typically invoked when the channel force closure is first initiated
+// either by the user or automatically (link error, HTLC actions, etc.).
+func (b *boltArbitratorLog) LogLocalForceCloseInitiator(
+	info channeldb.LocalForceCloseInitiator) error {
+
+	return kvdb.Update(b.db, func(tx kvdb.RwTx) error {
+		scopeBucket, err := tx.CreateTopLevelBucket(b.scopeKey[:])
+		if err != nil {
+			return err
+		}
+		var buf bytes.Buffer
+		if err := channeldb.SerializeLocalForceCloseInitiator(&buf,
+			&info); err != nil {
+			return err
+		}
+
+		return scopeBucket.Put(localForceCloseInitiatorKey, buf.Bytes())
+	}, func() {})
+}
+
+// FetchLocalForceCloseInitiator attempts to fetch the localForceCloseInitiator
+// object that was previously logged in the ArbitratorLog.
+func (b *boltArbitratorLog) FetchLocalForceCloseInitiator() (
+	channeldb.LocalForceCloseInitiator,
+	error) {
+
+	var init channeldb.LocalForceCloseInitiator
+	err := kvdb.View(b.db, func(tx kvdb.RTx) error {
+		scopeBucket := tx.ReadBucket(b.scopeKey[:])
+		if scopeBucket == nil {
+			return errScopeBucketNoExist
+		}
+
+		infoBytes := scopeBucket.Get(localForceCloseInitiatorKey)
+		if infoBytes == nil {
+			return nil
+		}
+
+		infoReader := bytes.NewReader(infoBytes)
+		lcInfo, err := channeldb.DeserializeLocalForceCloseInitiator(
+			infoReader)
+		if err != nil {
+			return err
+		}
+
+		init = lcInfo
+
+		return nil
+	}, func() {})
+
+	if err != nil {
+		return "", err
+	}
+
+	return init, nil
+}
+
 // InsertConfirmedCommitSet stores the known set of active HTLCs at the time
 // channel closure. We'll use this to reconstruct our set of chain actions anew
 // based on the confirmed and pending commitment state.

contractcourt/channel_arbitrator_test.go

@@ -40,6 +40,7 @@ type mockArbitratorLog struct {
 	failCommitState ArbitratorState
 	resolutions     *ContractResolutions
 	resolvers       map[ContractResolver]struct{}
+	localFCInfo     channeldb.LocalForceCloseInitiator
 
 	commitSet *CommitSet
 
@@ -134,6 +135,20 @@ func (b *mockArbitratorLog) FetchChainActions() (ChainActionMap, error) {
 	return nil, nil
 }
 
+func (b *mockArbitratorLog) LogLocalForceCloseInitiator(
+	init channeldb.LocalForceCloseInitiator) error {
+
+	b.localFCInfo = init
+	return nil
+}
+
+func (b *mockArbitratorLog) FetchLocalForceCloseInitiator() (
+	channeldb.LocalForceCloseInitiator,
+	error) {
+
+	return b.localFCInfo, nil
+}
+
 func (b *mockArbitratorLog) InsertConfirmedCommitSet(c *CommitSet) error {
 	b.commitSet = c
 	return nil