chanstate: introduce ChannelStore interface

Add a new chanstate package containing the ChannelStore interface plus a
package logger. The interface mirrors the public surface of
*channeldb.ChannelStateDB so the compile-time assertion

    var _ ChannelStore = (*channeldb.ChannelStateDB)(nil)

passes today. Subsequent consumer migration is a mechanical type swap
from *channeldb.ChannelStateDB to chanstate.ChannelStore with no further
interface design churn.

The interface deliberately excludes:

  - GetParentDB: documented as a test-only escape hatch.
  - LinkNodeDB: belongs to a separate peer/node-metadata domain that
    gets its own decomposition later.

No kvdb types appear in the interface, matching the precedent set by
invoices/, payments/db/, and graph/db/. The chanstate -> channeldb
import direction is one-way; channeldb does not import chanstate.

No consumer migrates in this commit.

Author: ziggie1984

chanstate/interface.go

@@ -0,0 +1,156 @@
+package chanstate
+
+import (
+	"github.com/btcsuite/btcd/btcec/v2"
+	"github.com/btcsuite/btcd/wire"
+	"github.com/lightningnetwork/lnd/channeldb"
+	"github.com/lightningnetwork/lnd/lnwire"
+)
+
+// ChannelStore is the persistence contract for the channel-state subsystem.
+// Consumers depend on this interface rather than the concrete
+// channeldb.ChannelStateDB so the underlying storage can be swapped without
+// touching call sites.
+type ChannelStore interface {
+	// FetchOpenChannels starts a new database transaction and returns
+	// all stored currently active/open channels associated with the
+	// target nodeID. In the case that no active channels are known to
+	// have been created with this node, then a zero-length slice is
+	// returned.
+	FetchOpenChannels(nodeID *btcec.PublicKey) (
+		[]*channeldb.OpenChannel, error)
+
+	// FetchChannel attempts to locate a channel specified by the passed
+	// channel point. If the channel cannot be found, then an error will
+	// be returned.
+	FetchChannel(chanPoint wire.OutPoint) (*channeldb.OpenChannel, error)
+
+	// FetchChannelByID attempts to locate a channel specified by the
+	// passed channel ID. If the channel cannot be found, then an error
+	// will be returned.
+	FetchChannelByID(id lnwire.ChannelID) (*channeldb.OpenChannel, error)
+
+	// FetchHistoricalChannel fetches open channel data from the
+	// historical channel bucket.
+	FetchHistoricalChannel(outPoint *wire.OutPoint) (
+		*channeldb.OpenChannel, error)
+
+	// FetchAllChannels attempts to retrieve all open channels currently
+	// stored within the database, including pending open, fully open and
+	// channels waiting for a closing transaction to confirm.
+	FetchAllChannels() ([]*channeldb.OpenChannel, error)
+
+	// FetchAllOpenChannels will return all channels that have the
+	// funding transaction confirmed, and is not waiting for a closing
+	// transaction to be confirmed.
+	FetchAllOpenChannels() ([]*channeldb.OpenChannel, error)
+
+	// FetchPendingChannels will return channels that have completed the
+	// process of generating and broadcasting funding transactions, but
+	// whose funding transactions have yet to be confirmed on the
+	// blockchain.
+	FetchPendingChannels() ([]*channeldb.OpenChannel, error)
+
+	// FetchWaitingCloseChannels will return all channels that have been
+	// opened, but are now waiting for a closing transaction to be
+	// confirmed.
+	//
+	// NOTE: This includes channels that are also pending to be opened.
+	FetchWaitingCloseChannels() ([]*channeldb.OpenChannel, error)
+
+	// FetchClosedChannels attempts to fetch all closed channels from the
+	// database. The pendingOnly bool toggles if channels that aren't yet
+	// fully closed should be returned in the response or not. When a
+	// channel was cooperatively closed, it becomes fully closed after a
+	// single confirmation. When a channel was forcibly closed, it will
+	// become fully closed after _all_ the pending funds (if any) have
+	// been swept.
+	FetchClosedChannels(pendingOnly bool) (
+		[]*channeldb.ChannelCloseSummary, error)
+
+	// FetchClosedChannel queries for a channel close summary using the
+	// channel point of the channel in question.
+	FetchClosedChannel(chanID *wire.OutPoint) (
+		*channeldb.ChannelCloseSummary, error)
+
+	// FetchClosedChannelForID queries for a channel close summary using
+	// the channel ID of the channel in question.
+	FetchClosedChannelForID(cid lnwire.ChannelID) (
+		*channeldb.ChannelCloseSummary, error)
+
+	// FetchPermAndTempPeers returns a map where the key is the remote
+	// node's public key and the value is a struct that has a tally of
+	// the pending-open channels and whether the peer has an open or
+	// closed channel with us.
+	FetchPermAndTempPeers(chainHash []byte) (
+		map[string]channeldb.ChanCount, error)
+
+	// MarkChanFullyClosed marks a channel as fully closed within the
+	// database. A channel should be marked as fully closed if the
+	// channel was initially cooperatively closed and it's reached a
+	// single confirmation, or after all the pending funds in a channel
+	// that has been forcibly closed have been swept.
+	MarkChanFullyClosed(chanPoint *wire.OutPoint) error
+
+	// CloseChannel marks the given channel as closed: the open-channel
+	// record is removed and the supplied ChannelCloseSummary is
+	// archived so the channel becomes retrievable via
+	// FetchClosedChannel and FetchClosedChannelForID. Any ChannelStatus
+	// values are merged into the archived summary. Returns
+	// ErrChannelCloseSummaryNil if summary is nil.
+	CloseChannel(channel *channeldb.OpenChannel,
+		summary *channeldb.ChannelCloseSummary,
+		statuses ...channeldb.ChannelStatus) error
+
+	// AbandonChannel attempts to remove the target channel from the open
+	// channel database. If the channel was already removed (has a closed
+	// channel entry), then we'll return a nil error. Otherwise, we'll
+	// insert a new close summary into the database.
+	AbandonChannel(chanPoint *wire.OutPoint, bestHeight uint32) error
+
+	// RestoreChannelShells reconstructs the state of an OpenChannel from
+	// the ChannelShell. We'll attempt to write the new channel to disk,
+	// create a LinkNode instance with the passed node addresses, and
+	// finally create an edge within the graph for the channel as well.
+	// This method is idempotent, so repeated calls with the same set of
+	// channel shells won't modify the database after the initial call.
+	RestoreChannelShells(channelShells ...*channeldb.ChannelShell) error
+
+	// SaveChannelOpeningState saves the serialized channel state for the
+	// provided chanPoint to the channelOpeningStateBucket.
+	SaveChannelOpeningState(outPoint, serializedState []byte) error
+
+	// GetChannelOpeningState fetches the serialized channel state for
+	// the provided outPoint from the database, or returns
+	// ErrChannelNotFound if the channel is not found.
+	GetChannelOpeningState(outPoint []byte) ([]byte, error)
+
+	// DeleteChannelOpeningState removes any state for outPoint from the
+	// database.
+	DeleteChannelOpeningState(outPoint []byte) error
+
+	// LookupFinalHtlc retrieves a final htlc resolution from the
+	// database. If the htlc has no final resolution yet, ErrHtlcUnknown
+	// is returned.
+	LookupFinalHtlc(chanID lnwire.ShortChannelID,
+		htlcIndex uint64) (*channeldb.FinalHtlcInfo, error)
+
+	// PutOnchainFinalHtlcOutcome stores the final on-chain outcome of an
+	// htlc in the database.
+	PutOnchainFinalHtlcOutcome(chanID lnwire.ShortChannelID,
+		htlcID uint64, settled bool) error
+
+	// PruneLinkNodes attempts to prune all link nodes found within the
+	// database with whom we no longer have any open channels with.
+	PruneLinkNodes() error
+
+	// RepairLinkNodes scans all channels in the database and ensures
+	// that a link node exists for each remote peer. This should be
+	// called on startup to ensure that our database is consistent.
+	RepairLinkNodes(network wire.BitcoinNet) error
+}
+
+// Compile-time assertion that channeldb.ChannelStateDB satisfies the
+// ChannelStore contract. If a method signature drifts on the concrete type,
+// this assertion will fail to build before any consumer migration.
+var _ ChannelStore = (*channeldb.ChannelStateDB)(nil)

chanstate/log.go

@@ -0,0 +1,28 @@
+package chanstate
+
+import (
+	"github.com/btcsuite/btclog/v2"
+	"github.com/lightningnetwork/lnd/build"
+)
+
+// log is a logger that is initialized with no output filters.  This means the
+// package will not perform any logging by default until the caller requests
+// it.
+var log btclog.Logger
+
+func init() {
+	UseLogger(build.NewSubLogger("CHST", nil))
+}
+
+// DisableLog disables all library log output.  Logging output is disabled by
+// default until UseLogger is called.
+func DisableLog() {
+	UseLogger(btclog.Disabled)
+}
+
+// UseLogger uses a specified Logger to output package logging info. This
+// should be used in preference to SetLogWriter if the caller is also using
+// btclog.
+func UseLogger(logger btclog.Logger) {
+	log = logger
+}