Merge pull request #10684 from ziggie1984/postgres-network-separation

sqldb: add network-mismatch safeguard for native-SQL backends

Author: ziggie1984

chainparams/store.go

@@ -0,0 +1,114 @@
+package chainparams
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+
+	"github.com/btcsuite/btcd/chaincfg"
+	"github.com/lightningnetwork/lnd/lncfg"
+	"github.com/lightningnetwork/lnd/sqldb"
+	"github.com/lightningnetwork/lnd/sqldb/sqlc"
+)
+
+// ErrNetworkMismatch is returned by ValidateNetwork when the network stored in
+// the database does not match the network lnd is configured to use.
+var ErrNetworkMismatch = errors.New("database network mismatch")
+
+// SQLChainParamQueries defines the SQL queries required by Store.
+type SQLChainParamQueries interface {
+	InsertChainNetwork(ctx context.Context, network string) error
+	GetChainNetwork(ctx context.Context) (string, error)
+}
+
+// BatchedChainParamQueries is a version of SQLChainParamQueries that is
+// capable of batched database operations.
+type BatchedChainParamQueries interface {
+	SQLChainParamQueries
+
+	sqldb.BatchedTx[SQLChainParamQueries]
+}
+
+// Store is a database-backed store that persists and retrieves chain-level
+// parameters such as the network the database was initialised for.
+type Store struct {
+	db BatchedChainParamQueries
+}
+
+// NewStore creates a new chain params Store backed by the given BaseDB.
+func NewStore(db *sqldb.BaseDB) *Store {
+	executor := sqldb.NewTransactionExecutor(
+		db, func(tx *sql.Tx) SQLChainParamQueries {
+			return db.WithTx(tx)
+		},
+	)
+
+	return &Store{db: executor}
+}
+
+// ValidateNetwork checks that the network stored in the chain_params table
+// matches the provided network. On the first call the network is persisted so
+// that subsequent restarts can detect an accidental network switch.
+func (s *Store) ValidateNetwork(ctx context.Context,
+	net *chaincfg.Params) error {
+
+	network, err := normalizeNetworkName(net)
+	if err != nil {
+		return err
+	}
+
+	return s.db.ExecTx(
+		ctx, sqldb.WriteTxOpt(),
+		func(tx SQLChainParamQueries) error {
+			// Insert the network only if the chain_params table is
+			// still empty. This is a no-op on every startup after
+			// the first.
+			err := tx.InsertChainNetwork(ctx, network)
+			if err != nil {
+				return fmt.Errorf("unable to set network in "+
+					"chain_params: %w", err)
+			}
+
+			// Read back whatever is stored. This is either the
+			// value we just inserted (first startup) or a value
+			// from a previous run.
+			storedNetwork, err := tx.GetChainNetwork(ctx)
+			if err != nil {
+				return fmt.Errorf("unable to read network "+
+					"from chain_params: %w", err)
+			}
+
+			if storedNetwork != network {
+				return fmt.Errorf("%w: the database was "+
+					"previously used with network '%s', "+
+					"but lnd is now configured for "+
+					"network '%s'. To fix this, either "+
+					"point lnd at a different database "+
+					"or reconfigure lnd to use "+
+					"network '%s'", ErrNetworkMismatch,
+					storedNetwork, network, storedNetwork)
+			}
+
+			return nil
+		}, sqldb.NoOpReset,
+	)
+}
+
+// normalizeNetworkName returns the stable network identifier persisted in the
+// chain_params table.
+func normalizeNetworkName(net *chaincfg.Params) (string, error) {
+	if net == nil {
+		return "", fmt.Errorf("chain parameters must not be nil")
+	}
+
+	network := lncfg.NormalizeNetwork(net.Name)
+	if network == "" {
+		return "", fmt.Errorf("chain parameters must define a network")
+	}
+
+	return network, nil
+}
+
+// Compile-time check that *sqlc.Queries implements SQLChainParamQueries.
+var _ SQLChainParamQueries = (*sqlc.Queries)(nil)

chainparams/store_test.go

@@ -0,0 +1,87 @@
+//go:build test_db_postgres || test_db_sqlite
+
+package chainparams
+
+import (
+	"testing"
+
+	"github.com/btcsuite/btcd/chaincfg"
+	"github.com/stretchr/testify/require"
+)
+
+// TestValidateNetworkMismatch verifies that ValidateNetwork persists the first
+// network and fails when a different network is used later.
+func TestValidateNetworkMismatch(t *testing.T) {
+	t.Parallel()
+
+	store := NewStore(newTestDB(t))
+
+	// First call: persists regtest into the store.
+	err := store.ValidateNetwork(t.Context(), &chaincfg.RegressionNetParams)
+	require.NoError(t, err)
+
+	// Second call: a different network — must fail with ErrNetworkMismatch.
+	err = store.ValidateNetwork(t.Context(), &chaincfg.SimNetParams)
+	require.ErrorIs(t, err, ErrNetworkMismatch)
+}
+
+// TestValidateNetworkSameNetwork verifies that ValidateNetwork succeeds when
+// called repeatedly with the same network (idempotent-match path).
+func TestValidateNetworkSameNetwork(t *testing.T) {
+	t.Parallel()
+
+	store := NewStore(newTestDB(t))
+
+	// First call: persists the network.
+	err := store.ValidateNetwork(t.Context(), &chaincfg.RegressionNetParams)
+	require.NoError(t, err)
+
+	// Second call: same network again — reads the stored value and must
+	// succeed (idempotent match).
+	err = store.ValidateNetwork(t.Context(), &chaincfg.RegressionNetParams)
+	require.NoError(t, err)
+}
+
+// TestValidateNetworkNormalizesTestnet verifies that network aliases collapse
+// to the same persisted value.
+func TestValidateNetworkNormalizesTestnet(t *testing.T) {
+	t.Parallel()
+
+	store := NewStore(newTestDB(t))
+
+	// First call: persists canonical testnet3 parameters.
+	err := store.ValidateNetwork(t.Context(), &chaincfg.TestNet3Params)
+	require.NoError(t, err)
+
+	// Second call: same logical network, different Name field — still
+	// matches after normalization (not ErrNetworkMismatch).
+	testnetAlias := chaincfg.TestNet3Params
+	testnetAlias.Name = "testnet"
+
+	err = store.ValidateNetwork(t.Context(), &testnetAlias)
+	require.NoError(t, err)
+}
+
+// TestValidateNetworkRejectsEmptyName verifies that malformed network params
+// are rejected before touching the database.
+func TestValidateNetworkRejectsEmptyName(t *testing.T) {
+	t.Parallel()
+
+	store := NewStore(newTestDB(t))
+
+	// Empty Params.Name — rejected before any database read or write.
+	err := store.ValidateNetwork(t.Context(), &chaincfg.Params{})
+	require.ErrorContains(t, err, "must define a network")
+}
+
+// TestValidateNetworkRejectsNilParams verifies that callers provide network
+// parameters.
+func TestValidateNetworkRejectsNilParams(t *testing.T) {
+	t.Parallel()
+
+	store := NewStore(newTestDB(t))
+
+	// Nil params — rejected before any database read or write.
+	err := store.ValidateNetwork(t.Context(), nil)
+	require.ErrorContains(t, err, "must not be nil")
+}

chainparams/test_postgres.go

@@ -0,0 +1,21 @@
+//go:build test_db_postgres && !test_db_sqlite
+
+package chainparams
+
+import (
+	"testing"
+
+	"github.com/lightningnetwork/lnd/sqldb"
+)
+
+// newTestDB creates a Postgres-backed BaseDB for use in unit tests.
+func newTestDB(t testing.TB) *sqldb.BaseDB {
+	pgFixture := sqldb.NewTestPgFixture(
+		t, sqldb.DefaultPostgresFixtureLifetime,
+	)
+	t.Cleanup(func() {
+		pgFixture.TearDown(t)
+	})
+
+	return sqldb.NewTestPostgresDB(t, pgFixture).GetBaseDB()
+}

chainparams/test_sqlite.go

@@ -0,0 +1,14 @@
+//go:build !test_db_postgres && test_db_sqlite
+
+package chainparams
+
+import (
+	"testing"
+
+	"github.com/lightningnetwork/lnd/sqldb"
+)
+
+// newTestDB creates a SQLite-backed BaseDB for use in unit tests.
+func newTestDB(t testing.TB) *sqldb.BaseDB {
+	return sqldb.NewTestSqliteDB(t).GetBaseDB()
+}

config_builder.go

@@ -30,6 +30,7 @@ import (
 	"github.com/lightninglabs/neutrino/pushtx"
 	"github.com/lightningnetwork/lnd/blockcache"
 	"github.com/lightningnetwork/lnd/chainntnfs"
+	"github.com/lightningnetwork/lnd/chainparams"
 	"github.com/lightningnetwork/lnd/chainreg"
 	"github.com/lightningnetwork/lnd/channeldb"
 	"github.com/lightningnetwork/lnd/clock"
@@ -1237,8 +1238,48 @@ func (d *DefaultDatabaseBuilder) BuildDatabase(
 
 		// With the DB ready and migrations applied, we can now create
 		// the base DB and transaction executor for the native SQL
-		// invoice store.
+		// stores.
 		baseDB := dbs.NativeSQLStore.GetBaseDB()
+
+		// Validate that the database was initialised for the same
+		// network as the currently active network. This catches cases
+		// where a user accidentally reuses a database (e.g. via a
+		// postgres DSN or by copying a file) across different networks
+		// (e.g. mainnet → testnet), which would otherwise lead to
+		// silent data corruption. This check applies to all native SQL
+		// backends.
+		//
+		// If migrations are explicitly skipped, we also skip this check
+		// because the chain_params table may not exist yet. We check
+		// only the active backend's flag since only one backend is
+		// used at a time.
+		var skipMigrations bool
+		switch d.cfg.DB.Backend {
+		case lncfg.SqliteBackend:
+			skipMigrations = d.cfg.DB.Sqlite.SkipMigrations
+		case lncfg.PostgresBackend:
+			skipMigrations = d.cfg.DB.Postgres.SkipMigrations
+		}
+
+		if !skipMigrations {
+			chainParamsStore := chainparams.NewStore(baseDB)
+			err = chainParamsStore.ValidateNetwork(
+				ctx, d.cfg.ActiveNetParams.Params,
+			)
+			if err != nil {
+				cleanUp()
+				d.logger.Error(err)
+
+				return nil, nil, err
+			}
+		} else {
+			d.logger.Warnf("Database network validation skipped " +
+				"because SkipMigrations is enabled; " +
+				"cross-network database reuse would not be " +
+				"detected.")
+		}
+
+		// Create the invoice store.
 		invoiceExecutor := sqldb.NewTransactionExecutor(
 			baseDB, func(tx *sql.Tx) invoices.SQLInvoiceQueries {
 				return baseDB.WithTx(tx)
@@ -1251,6 +1292,7 @@ func (d *DefaultDatabaseBuilder) BuildDatabase(
 
 		dbs.InvoiceDB = sqlInvoiceDB
 
+		// Create the graph store.
 		graphExecutor := sqldb.NewTransactionExecutor(
 			baseDB, func(tx *sql.Tx) graphdb.SQLQueries {
 				return baseDB.WithTx(tx)
@@ -1272,6 +1314,7 @@ func (d *DefaultDatabaseBuilder) BuildDatabase(
 			return nil, nil, err
 		}
 
+		// Create the payments store.
 		paymentsExecutor := sqldb.NewTransactionExecutor(
 			baseDB, func(tx *sql.Tx) paymentsdb.SQLQueries {
 				return baseDB.WithTx(tx)

docs/release-notes/release-notes-0.21.0.md

@@ -307,7 +307,15 @@
 
 ## Database
 
-* Freeze the [graph SQL migration 
+* [Prevent silent data corruption](https://github.com/lightningnetwork/lnd/pull/10684)
+  when reusing the same database across different Bitcoin networks. On first
+  startup the active network is persisted in a new `chain_params` table; on
+  every subsequent restart lnd compares the stored value against the configured
+  network and refuses to start if they differ, printing a clear error message
+  with remediation steps. This safeguard applies to both the PostgreSQL and
+  SQLite native-SQL backends when running with `--db.use-native-sql`.
+
+* Freeze the [graph SQL migration
   code](https://github.com/lightningnetwork/lnd/pull/10338) to prevent the 
   need for maintenance as the sqlc code evolves. 
 * Prepare the graph DB for handling gossip V2

itest/list_on_test.go

@@ -791,6 +791,10 @@ var allTestCases = []*lntest.TestCase{
 		Name:     "estimate on chain fee auto selected inputs",
 		TestFunc: testEstimateOnChainFeeAutoSelectedInputs,
 	},
+	{
+		Name:     "postgres network separation",
+		TestFunc: testPostgresNetworkSeparation,
+	},
 }
 
 // appendPrefixed is used to add a prefix to each test name in the subtests