feat(tbtc): wire reservation executors and watchers

.github/workflows/client.yml

@@ -135,6 +135,45 @@ jobs:
         with:
           environment: ${{ github.event.inputs.environment }}
 
+      # TODO(https://github.com/threshold-network/tbtc-v2/pull/1112): remove once
+      # @keep-network/tbtc-v2 publishes the reservation-router surface (Bridge,
+      # WalletProposalValidator, RedemptionWatchtower, ReservationRouter, and the
+      # rest of the tbtc module's required_contracts) under the `development` npm
+      # tag. Until then, PRs targeting `reservations-epic` compile tbtc-v2 PR #1112
+      # (pinned SHA, not a moving branch ref) locally to produce the artifacts
+      # `make get_artifacts` can't fetch from npm yet. `environment=development`
+      # only ever reads the `.abi` field off these files (the gen Makefile writes
+      # a hardcoded zero address rather than reading one - see
+      # pkg/chain/ethereum/common/gen/Makefile's `_address/%` rule), so a plain
+      # `hardhat compile` artifact is sufficient; no local deployment needed. See
+      # ./ci-shims/tbtc-artifacts and the matching Dockerfile step.
+      - name: Prepare tbtc-v2 artifact shim directory
+        run: mkdir -p ci-shims/tbtc-artifacts
+
+      - name: Set up Node.js for tbtc-v2 shim build
+        if: github.base_ref == 'reservations-epic'
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22.23.1"
+
+      - name: Build tbtc-v2 module artifacts from PR #1112 (temporary shim)
+        if: github.base_ref == 'reservations-epic'
+        run: |
+          set -euo pipefail
+          git clone --quiet https://github.com/threshold-network/tbtc-v2.git /tmp/tbtc-v2-shim
+          cd /tmp/tbtc-v2-shim
+          git checkout --quiet 1c8c1cd1437c077700b372544677aa0f9b08ef87
+          cd solidity
+          corepack enable
+          git config --global url."https://".insteadOf git://
+          yarn install --immutable
+          yarn build
+          for contract in Bridge MaintainerProxy LightRelay LightRelayMaintainerProxy \
+            WalletProposalValidator RedemptionWatchtower ReservationRouter; do
+            artifact="$(find build/contracts -iname "$contract.json" -path "*/$contract.sol/*")"
+            cp "$artifact" "$GITHUB_WORKSPACE/ci-shims/tbtc-artifacts/$contract.json"
+          done
+
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 

.gitignore

@@ -4,6 +4,10 @@
 # Executables
 /keep-client
 
+# Temporary CI-only artifact injected before the Docker build; see Dockerfile
+# and .github/workflows/client.yml (ReservationRouter tbtc-v2 PR #1112 shim).
+/ci-shims/
+
 # IDEs
 .vscode/
 .idea/

Dockerfile

@@ -62,11 +62,31 @@ COPY ./pkg/protocol/inactivity/gen $APP_DIR/pkg/protocol/inactivity/gen
 RUN go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.32.0
 
 # Environment is to download published and tagged NPM packages versions.
-ARG ENVIRONMENT
+# Defaults to `development` to mirror the root Makefile's `ifndef environment`
+# fallback (the "Build Docker Build Image" CI step never passes this build-arg).
+ARG ENVIRONMENT=development
 
 COPY ./Makefile $APP_DIR/Makefile
 RUN make get_artifacts environment=$ENVIRONMENT
 
+# TODO(https://github.com/threshold-network/tbtc-v2/pull/1112): remove once
+# @keep-network/tbtc-v2 publishes Bridge/WalletProposalValidator/RedemptionWatchtower/
+# ReservationRouter (and the rest of the tbtc module's required_contracts) under the
+# `development` npm tag. Until then, `get_artifacts` fetches a tbtc-v2 package whose
+# Bridge/WalletProposalValidator/RedemptionWatchtower don't yet expose the reservation
+# methods this PR binds against, and has no ReservationRouter artifact at all. The
+# `client.yml` workflow locally compiles tbtc-v2 PR #1112 (pinned SHA) and drops its
+# compiled ABI artifacts for the tbtc module's required_contracts at
+# ./ci-shims/tbtc-artifacts/*.json when it runs; this only overrides the tbtc module's
+# artifacts, and only for `environment=development` (PR CI) builds - sepolia/mainnet
+# builds and the beacon/ecdsa/threshold modules are untouched.
+COPY ./ci-shims/tbtc-artifacts /tmp/tbtc-artifacts
+RUN if { [ -z "$ENVIRONMENT" ] || [ "$ENVIRONMENT" = "development" ]; } && [ -n "$(ls -A /tmp/tbtc-artifacts 2>/dev/null)" ]; then \
+	echo "Using tbtc-v2 module artifacts built from tbtc-v2 PR #1112 (temporary shim)"; \
+	cp /tmp/tbtc-artifacts/*.json \
+		$APP_DIR/tmp/contracts/development/@keep-network/tbtc-v2/artifacts/; \
+fi
+
 # Need this to resolve imports in generated Ethereum commands.
 COPY ./config $APP_DIR/config
 RUN make generate environment=$ENVIRONMENT

cmd/start.go

@@ -8,6 +8,7 @@ import (
 	"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/electrum"
 	"github.com/keep-network/keep-core/pkg/operator"
@@ -22,6 +23,7 @@ import (
 	"github.com/keep-network/keep-core/pkg/clientinfo"
 	"github.com/keep-network/keep-core/pkg/firewall"
 	"github.com/keep-network/keep-core/pkg/generator"
+	"github.com/keep-network/keep-core/pkg/maintainer/spv"
 	"github.com/keep-network/keep-core/pkg/net"
 	"github.com/keep-network/keep-core/pkg/net/libp2p"
 	"github.com/keep-network/keep-core/pkg/net/retransmission"
@@ -92,7 +94,11 @@ func start(cmd *cobra.Command) error {
 	// Wire performance metrics into network provider if available
 	var perfMetrics *clientinfo.PerformanceMetrics
 	if clientInfoRegistry != nil {
-		perfMetrics = clientinfo.NewPerformanceMetrics(ctx, clientInfoRegistry)
+		perfMetrics = clientinfo.NewPerformanceMetrics(
+			ctx,
+			clientInfoRegistry,
+			clientConfig.Tbtc.Reservations.Enabled,
+		)
 		// Type assert to libp2p provider to set metrics recorder
 		// The provider struct is not exported, so we use interface assertion
 		if setter, ok := netProvider.(interface {
@@ -160,9 +166,10 @@ func start(cmd *cobra.Command) error {
 		proposalGenerator := tbtcpg.NewProposalGenerator(
 			tbtcChain,
 			btcChain,
+			clientConfig.Tbtc.Reservations.Enabled,
 		)
 
-		err = tbtc.Initialize(
+		resolver, err := tbtc.Initialize(
 			ctx,
 			tbtcChain,
 			btcChain,
@@ -177,7 +184,29 @@ func start(cmd *cobra.Command) error {
 			clientConfig.Ethereum.Network,
 		)
 		if err != nil {
-			return fmt.Errorf("error initializing TBTC: [%v]", err)
+			return fmt.Errorf("cannot initialize TBTC: [%v]", err)
+		}
+
+		// Wire the reservation watchers (stranding, stale-deposit,
+		// action-timeout) directly against the same tbtcChain handle:
+		// cmd/start.go already imports both tbtc and spv, so there is no
+		// import-cycle reason to thread this through tbtc.Initialize via a
+		// callback type. Gated on the same flag that gates the reservation
+		// proposal generator tasks above. Failing to wire the watchers is
+		// fatal: the operator opted into reservations, so a missing
+		// watcher would silently strand anchors.
+		if clientConfig.Tbtc.Reservations.Enabled {
+			if err := spv.WireReservationWatchers(
+				ctx,
+				tbtcChain,
+				tbtcChain,
+				resolver,
+			); err != nil {
+				return fmt.Errorf(
+					"failed to wire reservation watchers: [%v]",
+					err,
+				)
+			}
 		}
 	}
 

config/config_test.go

@@ -233,6 +233,14 @@ func TestReadConfigFromFile(t *testing.T) {
 			readValueFunc: func(c *Config) interface{} { return c.Maintainer.Spv.IdleBackoffTime },
 			expectedValue: 15 * time.Minute,
 		},
+		"Maintainer.Spv.Reservations.Enabled": {
+			readValueFunc: func(c *Config) interface{} { return c.Maintainer.Spv.Reservations.Enabled },
+			expectedValue: true,
+		},
+		"Tbtc.Reservations.Enabled": {
+			readValueFunc: func(c *Config) interface{} { return c.Tbtc.Reservations.Enabled },
+			expectedValue: true,
+		},
 	}
 
 	for _, filePath := range filePaths {