feat(tbtc): covenant signer final project branch

.github/workflows/client.yml

@@ -65,6 +65,25 @@ jobs:
               - './config/_electrum_urls/**'
               - './pkg/bitcoin/electrum/**'
 
+  client-risk-detect-changes:
+    runs-on: ubuntu-latest
+    outputs:
+      path-filter: ${{ steps.filter.outputs.path-filter }}
+    steps:
+      - uses: actions/checkout@v4
+        if: github.event_name == 'pull_request'
+
+      - uses: dorny/paths-filter@v2
+        if: github.event_name == 'pull_request'
+        id: filter
+        with:
+          filters: |
+            path-filter:
+              - './pkg/covenantsigner/**'
+              - './pkg/tbtc/**'
+              - './pkg/chain/ethereum/**'
+              - './cmd/start.go'
+
   client-build-test-publish:
     needs: client-detect-changes
     if: |
@@ -301,6 +320,29 @@ jobs:
           install-go: false
           checks: "-SA1019"
 
+  client-race:
+    needs: client-risk-detect-changes
+    if: |
+      github.event_name == 'push'
+        || needs.client-risk-detect-changes.outputs.path-filter == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: "go.mod"
+      - name: Race detector (high-risk packages)
+        run: |
+          go test -race -timeout 20m ./pkg/covenantsigner
+          go test -race -timeout 20m -v ./pkg/tbtc \
+            -run '^(TestSignerApprovalCertificateSignerSetHashBindsOnChainWalletIdentityAndThreshold|TestValidateMigrationOutputValues_RejectsValuesExceedingInt64)$' \
+            -count=1 2>&1 | tee /tmp/race-output.txt
+          # Fail if the -run filter matched no tests (silent pass).
+          if ! grep -q '=== RUN' /tmp/race-output.txt; then
+            echo "ERROR: race detector -run filter matched no tests" >&2
+            exit 1
+          fi
+
   client-integration-test:
     needs: [electrum-integration-detect-changes, client-build-test-publish]
     if: |

cmd/flags.go

@@ -15,6 +15,7 @@ import (
 	"github.com/keep-network/keep-core/pkg/bitcoin/electrum"
 	chainEthereum "github.com/keep-network/keep-core/pkg/chain/ethereum"
 	"github.com/keep-network/keep-core/pkg/clientinfo"
+	"github.com/keep-network/keep-core/pkg/covenantsigner"
 	"github.com/keep-network/keep-core/pkg/maintainer/spv"
 	"github.com/keep-network/keep-core/pkg/net/libp2p"
 	"github.com/keep-network/keep-core/pkg/tbtc"
@@ -46,6 +47,8 @@ func initFlags(
 			initStorageFlags(cmd, cfg)
 		case config.ClientInfo:
 			initClientInfoFlags(cmd, cfg)
+		case config.CovenantSigner:
+			initCovenantSignerFlags(cmd, cfg)
 		case config.Tbtc:
 			initTbtcFlags(cmd, cfg)
 		case config.Maintainer:
@@ -310,6 +313,39 @@ func initTbtcFlags(cmd *cobra.Command, cfg *config.Config) {
 	)
 }
 
+func initCovenantSignerFlags(cmd *cobra.Command, cfg *config.Config) {
+	cmd.Flags().IntVar(
+		&cfg.CovenantSigner.Port,
+		"covenantSigner.port",
+		covenantsigner.Config{}.Port,
+		"Covenant signer provider HTTP server listening port. Zero disables the service.",
+	)
+	cmd.Flags().StringVar(
+		&cfg.CovenantSigner.ListenAddress,
+		"covenantSigner.listenAddress",
+		covenantsigner.DefaultListenAddress,
+		"Covenant signer provider HTTP listen address. Defaults to loopback-only.",
+	)
+	cmd.Flags().StringVar(
+		&cfg.CovenantSigner.AuthToken,
+		"covenantSigner.authToken",
+		covenantsigner.Config{}.AuthToken,
+		"Covenant signer provider static Bearer auth token. Required for non-loopback binds; prefer config file or env var over CLI in production.",
+	)
+	cmd.Flags().BoolVar(
+		&cfg.CovenantSigner.EnableSelfV1,
+		"covenantSigner.enableSelfV1",
+		false,
+		"Expose self_v1 covenant signer HTTP routes. Keep disabled for a qc_v1-first launch unless self_v1 is explicitly approved.",
+	)
+	cmd.Flags().BoolVar(
+		&cfg.CovenantSigner.RequireApprovalTrustRoots,
+		"covenantSigner.requireApprovalTrustRoots",
+		false,
+		"Fail startup when enabled covenant routes are missing route-level approval trust roots. Request-time validation still enforces exact reserve/network trust-root matches.",
+	)
+}
+
 // Initialize flags for Maintainer configuration.
 func initMaintainerFlags(command *cobra.Command, cfg *config.Config) {
 	command.Flags().BoolVar(

cmd/flags_test.go

@@ -22,6 +22,7 @@ import (
 	ethereumEcdsa "github.com/keep-network/keep-core/pkg/chain/ethereum/ecdsa/gen"
 	ethereumTbtc "github.com/keep-network/keep-core/pkg/chain/ethereum/tbtc/gen"
 	ethereumThreshold "github.com/keep-network/keep-core/pkg/chain/ethereum/threshold/gen"
+	"github.com/keep-network/keep-core/pkg/covenantsigner"
 )
 
 var cmdFlagsTests = map[string]struct {
@@ -190,6 +191,41 @@ var cmdFlagsTests = map[string]struct {
 		expectedValueFromFlag: 76 * time.Second,
 		defaultValue:          10 * time.Minute,
 	},
+	"covenantSigner.port": {
+		readValueFunc:         func(c *config.Config) interface{} { return c.CovenantSigner.Port },
+		flagName:              "--covenantSigner.port",
+		flagValue:             "9711",
+		expectedValueFromFlag: 9711,
+		defaultValue:          0,
+	},
+	"covenantSigner.listenAddress": {
+		readValueFunc:         func(c *config.Config) interface{} { return c.CovenantSigner.ListenAddress },
+		flagName:              "--covenantSigner.listenAddress",
+		flagValue:             "0.0.0.0",
+		expectedValueFromFlag: "0.0.0.0",
+		defaultValue:          covenantsigner.DefaultListenAddress,
+	},
+	"covenantSigner.authToken": {
+		readValueFunc:         func(c *config.Config) interface{} { return c.CovenantSigner.AuthToken },
+		flagName:              "--covenantSigner.authToken",
+		flagValue:             "secret-token",
+		expectedValueFromFlag: "secret-token",
+		defaultValue:          "",
+	},
+	"covenantSigner.enableSelfV1": {
+		readValueFunc:         func(c *config.Config) interface{} { return c.CovenantSigner.EnableSelfV1 },
+		flagName:              "--covenantSigner.enableSelfV1",
+		flagValue:             "",
+		expectedValueFromFlag: true,
+		defaultValue:          false,
+	},
+	"covenantSigner.requireApprovalTrustRoots": {
+		readValueFunc:         func(c *config.Config) interface{} { return c.CovenantSigner.RequireApprovalTrustRoots },
+		flagName:              "--covenantSigner.requireApprovalTrustRoots",
+		flagValue:             "",
+		expectedValueFromFlag: true,
+		defaultValue:          false,
+	},
 	"tbtc.preParamsPoolSize": {
 		readValueFunc:         func(c *config.Config) interface{} { return c.Tbtc.PreParamsPoolSize },
 		flagName:              "--tbtc.preParamsPoolSize",

cmd/start.go

@@ -3,12 +3,17 @@ package cmd
 import (
 	"context"
 	"fmt"
+	"os/signal"
+	"path/filepath"
+	"syscall"
 	"time"
 
+	commonEthereum "github.com/keep-network/keep-common/pkg/chain/ethereum"
 	"github.com/keep-network/keep-core/pkg/tbtcpg"
 
 	"github.com/keep-network/keep-common/pkg/persistence"
 	"github.com/keep-network/keep-core/build"
+	"github.com/keep-network/keep-core/pkg/bitcoin"
 	"github.com/keep-network/keep-core/pkg/bitcoin/electrum"
 	"github.com/keep-network/keep-core/pkg/operator"
 	"github.com/keep-network/keep-core/pkg/storage"
@@ -17,9 +22,11 @@ import (
 
 	"github.com/keep-network/keep-core/config"
 	"github.com/keep-network/keep-core/pkg/beacon"
+	beaconchain "github.com/keep-network/keep-core/pkg/beacon/chain"
 	"github.com/keep-network/keep-core/pkg/chain"
 	"github.com/keep-network/keep-core/pkg/chain/ethereum"
 	"github.com/keep-network/keep-core/pkg/clientinfo"
+	"github.com/keep-network/keep-core/pkg/covenantsigner"
 	"github.com/keep-network/keep-core/pkg/firewall"
 	"github.com/keep-network/keep-core/pkg/generator"
 	"github.com/keep-network/keep-core/pkg/net"
@@ -45,6 +52,77 @@ var StartCommand = &cobra.Command{
 	},
 }
 
+type startDeps struct {
+	connectEthereum func(
+		ctx context.Context,
+		config commonEthereum.Config,
+	) (
+		*ethereum.BeaconChain,
+		*ethereum.TbtcChain,
+		chain.BlockCounter,
+		chain.Signing,
+		*operator.PrivateKey,
+		error,
+	)
+	connectElectrum func(
+		ctx context.Context,
+		config electrum.Config,
+	) (bitcoin.Chain, error)
+	initializeNetwork func(
+		ctx context.Context,
+		applications []firewall.Application,
+		operatorPrivateKey *operator.PrivateKey,
+		blockCounter chain.BlockCounter,
+	) (net.Provider, error)
+	initializePersistence func() (
+		beaconKeyStorePersistence persistence.ProtectedHandle,
+		tbtcKeyStorePersistence persistence.ProtectedHandle,
+		tbtcDataPersistence persistence.BasicHandle,
+		err error,
+	)
+	initializeBeacon func(
+		ctx context.Context,
+		chain beaconchain.Interface,
+		netProvider net.Provider,
+		keyStorePersistence persistence.ProtectedHandle,
+		scheduler *generator.Scheduler,
+	) error
+	initializeTbtc func(
+		ctx context.Context,
+		chain tbtc.Chain,
+		btcChain bitcoin.Chain,
+		netProvider net.Provider,
+		keyStorePersistence persistence.ProtectedHandle,
+		workPersistence persistence.BasicHandle,
+		scheduler *generator.Scheduler,
+		proposalGenerator tbtc.CoordinationProposalGenerator,
+		config tbtc.Config,
+		clientInfoRegistry *clientinfo.Registry,
+		perfMetrics *clientinfo.PerformanceMetrics,
+		minActiveOutpointConfirmations uint,
+	) (covenantsigner.Engine, error)
+	initializeSigner func(
+		ctx context.Context,
+		config covenantsigner.Config,
+		handle persistence.BasicHandle,
+		engine covenantsigner.Engine,
+	) (*covenantsigner.Server, bool, error)
+	startScheduler func() *generator.Scheduler
+}
+
+func defaultStartDeps() startDeps {
+	return startDeps{
+		connectEthereum:       ethereum.Connect,
+		connectElectrum:       electrum.Connect,
+		initializeNetwork:     initializeNetwork,
+		initializePersistence: initializePersistence,
+		initializeBeacon:      beacon.Initialize,
+		initializeTbtc:        tbtc.Initialize,
+		initializeSigner:      covenantsigner.Initialize,
+		startScheduler:        generator.StartScheduler,
+	}
+}
+
 func init() {
 	initFlags(StartCommand, &configFilePath, clientConfig, config.StartCmdCategories...)
 
@@ -63,15 +141,20 @@ Environment variables:
 
 // start starts a node
 func start(cmd *cobra.Command) error {
-	ctx := context.Background()
+	return startWithDeps(cmd, defaultStartDeps())
+}
+
+func startWithDeps(cmd *cobra.Command, deps startDeps) error {
+	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+	defer stop()
 
 	beaconChain, tbtcChain, blockCounter, signing, operatorPrivateKey, err :=
-		ethereum.Connect(ctx, clientConfig.Ethereum)
+		deps.connectEthereum(ctx, clientConfig.Ethereum)
 	if err != nil {
 		return fmt.Errorf("error connecting to Ethereum node: [%v]", err)
 	}
 
-	netProvider, err := initializeNetwork(
+	netProvider, err := deps.initializeNetwork(
 		ctx,
 		[]firewall.Application{beaconChain, tbtcChain},
 		operatorPrivateKey,
@@ -110,20 +193,20 @@ func start(cmd *cobra.Command) error {
 	// Skip initialization for bootstrap nodes as they are only used for network
 	// discovery.
 	if !isBootstrap() {
-		btcChain, err := electrum.Connect(ctx, clientConfig.Bitcoin.Electrum)
+		btcChain, err := deps.connectElectrum(ctx, clientConfig.Bitcoin.Electrum)
 		if err != nil {
 			return fmt.Errorf("could not connect to Electrum chain: [%v]", err)
 		}
 
 		beaconKeyStorePersistence,
 			tbtcKeyStorePersistence,
 			tbtcDataPersistence,
-			err := initializePersistence()
+			err := deps.initializePersistence()
 		if err != nil {
 			return fmt.Errorf("cannot initialize persistence: [%w]", err)
 		}
 
-		scheduler := generator.StartScheduler()
+		scheduler := deps.startScheduler()
 
 		if clientInfoRegistry != nil {
 			clientInfoRegistry.ObserveBtcConnectivity(
@@ -142,7 +225,7 @@ func start(cmd *cobra.Command) error {
 			rpcHealthChecker.Start(ctx)
 		}
 
-		err = beacon.Initialize(
+		err = deps.initializeBeacon(
 			ctx,
 			beaconChain,
 			netProvider,
@@ -158,7 +241,7 @@ func start(cmd *cobra.Command) error {
 			btcChain,
 		)
 
-		err = tbtc.Initialize(
+		covenantSignerEngine, err := deps.initializeTbtc(
 			ctx,
 			tbtcChain,
 			btcChain,
@@ -170,10 +253,28 @@ func start(cmd *cobra.Command) error {
 			clientConfig.Tbtc,
 			clientInfoRegistry,
 			perfMetrics, // Pass the existing performance metrics instance to avoid duplicate registrations
+			clientConfig.CovenantSigner.MinActiveOutpointConfirmations,
 		)
 		if err != nil {
 			return fmt.Errorf("error initializing TBTC: [%v]", err)
 		}
+
+		signerConfig := clientConfig.CovenantSigner
+		if signerConfig.DataDir == "" && signerConfig.Port != 0 {
+			signerConfig.DataDir = filepath.Join(
+				filepath.Clean(clientConfig.Storage.Dir), "work", "tbtc",
+			)
+		}
+
+		_, _, err = deps.initializeSigner(
+			ctx,
+			signerConfig,
+			tbtcDataPersistence,
+			covenantSignerEngine,
+		)
+		if err != nil {
+			return fmt.Errorf("error initializing covenant signer: [%v]", err)
+		}
 	}
 
 	nodeHeader(