What changed, and why it matters
This commit is a straightforward internal code reorganization. It moves the definitions of CommitDiff, AddRef, and SettleFailRef from the channeldb package to a new chanstate package, and creates type aliases in channeldb so existing code keeps working. There is no change to how data is stored, parsed, or validated, and no security fix or vulnerability is introduced.
No security action required. Review as normal refactoring during routine code review.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The patch relocates CommitDiff and forwarding reference types (AddRef, SettleFailRef) into the chanstate package to avoid import cycles for an upcoming commitment store subinterface. channeldb now uses type aliases (e.g., CommitDiff = cstate.CommitDiff) to preserve existing call sites. Serialization logic and persistence remain in channeldb. The moved types retain identical fields and methods; no behavioral, validation, or wire-format changes are present.
Changed components
channeldb/channel.gochanneldb/forwarding_package.gochanstate/commitment.gochanstate/forwarding.goInspect captured patch +127 / −104
diff --git a/channeldb/channel.go b/channeldb/channel.go
index 7ded835..f509d50 100644
--- a/channeldb/channel.go
+++ b/channeldb/channel.go
@@ -238,6 +238,10 @@ type (
// LogUpdate represents a pending update to the remote commitment
// chain.
LogUpdate = cstate.LogUpdate
+
+ // CommitDiff represents the delta needed to apply the state
+ // transition between two subsequent commitment states.
+ CommitDiff = cstate.CommitDiff
)
// openChannelTlvData houses the new data fields that are stored for each
@@ -2757,61 +2761,6 @@ func deserializeLogUpdate(r io.Reader) (*LogUpdate, error) {
return l, nil
}
-// CommitDiff represents the delta needed to apply the state transition between
-// two subsequent commitment states. Given state N and state N+1, one is able
-// to apply the set of messages contained within the CommitDiff to N to arrive
-// at state N+1. Each time a new commitment is extended, we'll write a new
-// commitment (along with the full commitment state) to disk so we can
-// re-transmit the state in the case of a connection loss or message drop.
-type CommitDiff struct {
- // ChannelCommitment is the full commitment state that one would arrive
- // at by applying the set of messages contained in the UpdateDiff to
- // the prior accepted commitment.
- Commitment ChannelCommitment
-
- // LogUpdates is the set of messages sent prior to the commitment state
- // transition in question. Upon reconnection, if we detect that they
- // don't have the commitment, then we re-send this along with the
- // proper signature.
- LogUpdates []LogUpdate
-
- // CommitSig is the exact CommitSig message that should be sent after
- // the set of LogUpdates above has been retransmitted. The signatures
- // within this message should properly cover the new commitment state
- // and also the HTLC's within the new commitment state.
- CommitSig *lnwire.CommitSig
-
- // OpenedCircuitKeys is a set of unique identifiers for any downstream
- // Add packets included in this commitment txn. After a restart, this
- // set of htlcs is acked from the link's incoming mailbox to ensure
- // there isn't an attempt to re-add them to this commitment txn.
- OpenedCircuitKeys []models.CircuitKey
-
- // ClosedCircuitKeys records the unique identifiers for any settle/fail
- // packets that were resolved by this commitment txn. After a restart,
- // this is used to ensure those circuits are removed from the circuit
- // map, and the downstream packets in the link's mailbox are removed.
- ClosedCircuitKeys []models.CircuitKey
-
- // AddAcks specifies the locations (commit height, pkg index) of any
- // Adds that were failed/settled in this commit diff. This will ack
- // entries in *this* channel's forwarding packages.
- //
- // NOTE: This value is not serialized, it is used to atomically mark the
- // resolution of adds, such that they will not be reprocessed after a
- // restart.
- AddAcks []AddRef
-
- // SettleFailAcks specifies the locations (chan id, commit height, pkg
- // index) of any Settles or Fails that were locked into this commit
- // diff, and originate from *another* channel, i.e. the outgoing link.
- //
- // NOTE: This value is not serialized, it is used to atomically acks
- // settles and fails from the forwarding packages of other channels,
- // such that they will not be reforwarded internally after a restart.
- SettleFailAcks []SettleFailRef
-}
-
// serializeLogUpdates serializes provided list of updates to a stream.
func serializeLogUpdates(w io.Writer, logUpdates []LogUpdate) error {
numUpdates := uint16(len(logUpdates))
diff --git a/channeldb/forwarding_package.go b/channeldb/forwarding_package.go
index c393a53..8ba2c95 100644
--- a/channeldb/forwarding_package.go
+++ b/channeldb/forwarding_package.go
@@ -7,10 +7,20 @@ import (
"fmt"
"io"
+ cstate "github.com/lightningnetwork/lnd/chanstate"
"github.com/lightningnetwork/lnd/kvdb"
"github.com/lightningnetwork/lnd/lnwire"
)
+type (
+ // AddRef is used to identify a particular Add in a FwdPkg.
+ AddRef = cstate.AddRef
+
+ // SettleFailRef is used to locate a Settle/Fail in another channel's
+ // FwdPkg.
+ SettleFailRef = cstate.SettleFailRef
+)
+
// ErrCorruptedFwdPkg signals that the on-disk structure of the forwarding
// package has potentially been mangled.
var ErrCorruptedFwdPkg = errors.New("fwding package db has been corrupted")
@@ -327,55 +337,6 @@ func (f *FwdPkg) String() string {
f, f.Source, f.Height, len(f.Adds), len(f.SettleFails))
}
-// AddRef is used to identify a particular Add in a FwdPkg. The short channel ID
-// is assumed to be that of the packager.
-type AddRef struct {
- // Height is the remote commitment height that locked in the Add.
- Height uint64
-
- // Index is the index of the Add within the fwd pkg's Adds.
- //
- // NOTE: This index is static over the lifetime of a forwarding package.
- Index uint16
-}
-
-// Encode serializes the AddRef to the given io.Writer.
-func (a *AddRef) Encode(w io.Writer) error {
- if err := binary.Write(w, binary.BigEndian, a.Height); err != nil {
- return err
- }
-
- return binary.Write(w, binary.BigEndian, a.Index)
-}
-
-// Decode deserializes the AddRef from the given io.Reader.
-func (a *AddRef) Decode(r io.Reader) error {
- if err := binary.Read(r, binary.BigEndian, &a.Height); err != nil {
- return err
- }
-
- return binary.Read(r, binary.BigEndian, &a.Index)
-}
-
-// SettleFailRef is used to locate a Settle/Fail in another channel's FwdPkg. A
-// channel does not remove its own Settle/Fail htlcs, so the source is provided
-// to locate a db bucket belonging to another channel.
-type SettleFailRef struct {
- // Source identifies the outgoing link that locked in the settle or
- // fail. This is then used by the *incoming* link to find the settle
- // fail in another link's forwarding packages.
- Source lnwire.ShortChannelID
-
- // Height is the remote commitment height that locked in this
- // Settle/Fail.
- Height uint64
-
- // Index is the index of the Add with the fwd pkg's SettleFails.
- //
- // NOTE: This index is static over the lifetime of a forwarding package.
- Index uint16
-}
-
// SettleFailAcker is a generic interface providing the ability to acknowledge
// settle/fail HTLCs stored in forwarding packages.
type SettleFailAcker interface {
diff --git a/chanstate/commitment.go b/chanstate/commitment.go
index 6f7bc77..db8d102 100644
--- a/chanstate/commitment.go
+++ b/chanstate/commitment.go
@@ -4,6 +4,7 @@ import (
"github.com/btcsuite/btcd/btcutil/v2"
"github.com/btcsuite/btcd/wire/v2"
"github.com/lightningnetwork/lnd/fn/v2"
+ "github.com/lightningnetwork/lnd/graph/db/models"
"github.com/lightningnetwork/lnd/lnwire"
"github.com/lightningnetwork/lnd/tlv"
)
@@ -229,3 +230,58 @@ type LogUpdate struct {
// we're left with a dangling update on restart.
UpdateMsg lnwire.Message
}
+
+// CommitDiff represents the delta needed to apply the state transition between
+// two subsequent commitment states. Given state N and state N+1, one is able
+// to apply the set of messages contained within the CommitDiff to N to arrive
+// at state N+1. Each time a new commitment is extended, we'll write a new
+// commitment (along with the full commitment state) to disk so we can
+// re-transmit the state in the case of a connection loss or message drop.
+type CommitDiff struct {
+ // ChannelCommitment is the full commitment state that one would arrive
+ // at by applying the set of messages contained in the UpdateDiff to
+ // the prior accepted commitment.
+ Commitment ChannelCommitment
+
+ // LogUpdates is the set of messages sent prior to the commitment state
+ // transition in question. Upon reconnection, if we detect that they
+ // don't have the commitment, then we re-send this along with the
+ // proper signature.
+ LogUpdates []LogUpdate
+
+ // CommitSig is the exact CommitSig message that should be sent after
+ // the set of LogUpdates above has been retransmitted. The signatures
+ // within this message should properly cover the new commitment state
+ // and also the HTLC's within the new commitment state.
+ CommitSig *lnwire.CommitSig
+
+ // OpenedCircuitKeys is a set of unique identifiers for any downstream
+ // Add packets included in this commitment txn. After a restart, this
+ // set of htlcs is acked from the link's incoming mailbox to ensure
+ // there isn't an attempt to re-add them to this commitment txn.
+ OpenedCircuitKeys []models.CircuitKey
+
+ // ClosedCircuitKeys records the unique identifiers for any settle/fail
+ // packets that were resolved by this commitment txn. After a restart,
+ // this is used to ensure those circuits are removed from the circuit
+ // map, and the downstream packets in the link's mailbox are removed.
+ ClosedCircuitKeys []models.CircuitKey
+
+ // AddAcks specifies the locations (commit height, pkg index) of any
+ // Adds that were failed/settled in this commit diff. This will ack
+ // entries in *this* channel's forwarding packages.
+ //
+ // NOTE: This value is not serialized, it is used to atomically mark the
+ // resolution of adds, such that they will not be reprocessed after a
+ // restart.
+ AddAcks []AddRef
+
+ // SettleFailAcks specifies the locations (chan id, commit height, pkg
+ // index) of any Settles or Fails that were locked into this commit
+ // diff, and originate from *another* channel, i.e. the outgoing link.
+ //
+ // NOTE: This value is not serialized, it is used to atomically acks
+ // settles and fails from the forwarding packages of other channels,
+ // such that they will not be reforwarded internally after a restart.
+ SettleFailAcks []SettleFailRef
+}
diff --git a/chanstate/forwarding.go b/chanstate/forwarding.go
new file mode 100644
index 0000000..9cc830f
--- /dev/null
+++ b/chanstate/forwarding.go
@@ -0,0 +1,57 @@
+package chanstate
+
+import (
+ "encoding/binary"
+ "io"
+
+ "github.com/lightningnetwork/lnd/lnwire"
+)
+
+// AddRef is used to identify a particular Add in a FwdPkg. The short channel ID
+// is assumed to be that of the packager.
+type AddRef struct {
+ // Height is the remote commitment height that locked in the Add.
+ Height uint64
+
+ // Index is the index of the Add within the fwd pkg's Adds.
+ //
+ // NOTE: This index is static over the lifetime of a forwarding package.
+ Index uint16
+}
+
+// Encode serializes the AddRef to the given io.Writer.
+func (a *AddRef) Encode(w io.Writer) error {
+ if err := binary.Write(w, binary.BigEndian, a.Height); err != nil {
+ return err
+ }
+
+ return binary.Write(w, binary.BigEndian, a.Index)
+}
+
+// Decode deserializes the AddRef from the given io.Reader.
+func (a *AddRef) Decode(r io.Reader) error {
+ if err := binary.Read(r, binary.BigEndian, &a.Height); err != nil {
+ return err
+ }
+
+ return binary.Read(r, binary.BigEndian, &a.Index)
+}
+
+// SettleFailRef is used to locate a Settle/Fail in another channel's FwdPkg. A
+// channel does not remove its own Settle/Fail htlcs, so the source is provided
+// to locate a db bucket belonging to another channel.
+type SettleFailRef struct {
+ // Source identifies the outgoing link that locked in the settle or
+ // fail. This is then used by the *incoming* link to find the settle
+ // fail in another link's forwarding packages.
+ Source lnwire.ShortChannelID
+
+ // Height is the remote commitment height that locked in this
+ // Settle/Fail.
+ Height uint64
+
+ // Index is the index of the Add with the fwd pkg's SettleFails.
+ //
+ // NOTE: This index is static over the lifetime of a forwarding package.
+ Index uint16
+}
Why this scored 15/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.