Reservations epic -> dev tracking

.github/workflows/client.yml

@@ -136,6 +136,20 @@ 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, `make get_artifacts` can't fetch these from npm; the gen
+      # Makefile's vendored fallback artifacts (see
+      # pkg/chain/ethereum/tbtc/gen/Makefile's ReservationRouter.fallback-artifact.json
+      # rule and the Bridge/WalletProposalValidator reservation-methods-fallback.json
+      # patch rules) supply the missing methods for `environment=development` builds
+      # instead. This directory only exists so the Dockerfile's COPY step (guarded by
+      # `-n "$(ls -A ...)"`, a no-op when empty) always has a source to copy from; 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 Docker Buildx
         uses: docker/setup-buildx-action@v3
 

.gitignore

@@ -4,6 +4,12 @@
 # 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/*
+!/ci-shims/tbtc-artifacts/
+!/ci-shims/tbtc-artifacts/**
+
 # 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" ]; } && ls /tmp/tbtc-artifacts/*.json >/dev/null 2>&1; 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,34 @@ 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 !clientConfig.Maintainer.Spv.Reservations.Enabled {
+				logger.Warnf("Client reservation proposal generation is enabled; " +
+					"ensure the paired Maintainer.Spv.Reservations.Enabled flag is also " +
+					"enabled in the maintainer config for end-to-end operation")
+			}
+			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 {

pkg/chain/ethereum/tbtc.go

@@ -1,6 +1,7 @@
 // tbtc.go: TbtcChain adapter construction and shared state. See tbtc_*.go for
 // per-concern implementations (tbtc_deposit.go, tbtc_dkg.go, tbtc_moving_funds.go,
-// tbtc_redemption.go, tbtc_wallet.go, tbtc_sortition.go, tbtc_inactivity.go).
+// tbtc_redemption.go, tbtc_reservation.go, tbtc_wallet.go, tbtc_sortition.go,
+// tbtc_inactivity.go).
 //
 // These files were split out of a single monolithic tbtc.go with no rename
 // markers git can detect (each file is a fresh addition, not a tracked move),
@@ -61,6 +62,10 @@ type TbtcChain struct {
 	sortitionPool           *ecdsacontract.EcdsaSortitionPool
 	walletProposalValidator *tbtccontract.WalletProposalValidator
 	redemptionWatchtower    *tbtccontract.RedemptionWatchtower
+	// reservationRouter is the abigen binding for ReservationRouter.sol's ABI
+	// constructed against the Bridge address (see tbtc_reservation.go for the
+	// address invariant explanation).
+	reservationRouter *tbtccontract.ReservationRouter
 	// ecdsaDkgValidatorAddress optional; when zero, TBTC uses defaultGroupParameters(network).
 	ecdsaDkgValidatorAddress common.Address
 
@@ -263,6 +268,14 @@ func newTbtcChain(
 		)
 	}
 
+	reservationRouter, err := reservationRouterBinding(bridgeAddress, baseChain)
+	if err != nil {
+		return nil, fmt.Errorf(
+			"failed to attach to ReservationRouter binding: [%v]",
+			err,
+		)
+	}
+
 	return &TbtcChain{
 		baseChain:                baseChain,
 		bridge:                   bridge,
@@ -271,6 +284,7 @@ func newTbtcChain(
 		sortitionPool:            sortitionPool,
 		walletProposalValidator:  walletProposalValidator,
 		redemptionWatchtower:     redemptionWatchtower,
+		reservationRouter:        reservationRouter,
 		ecdsaDkgValidatorAddress: ecdsaDkgValidatorAddress,
 		sweptDepositsCache:       cache.NewGenericTimeCache[*tbtc.DepositChainRequest](sweptDepositsCachePeriod),
 	}, nil

pkg/chain/ethereum/tbtc/gen/Bridge.reservation-methods-fallback.json

@@ -0,0 +1,21 @@
+[
+  {
+    "inputs": [
+      {
+        "internalType": "uint256",
+        "name": "depositKey",
+        "type": "uint256"
+      }
+    ],
+    "name": "isReservedDeposit",
+    "outputs": [
+      {
+        "internalType": "bool",
+        "name": "",
+        "type": "bool"
+      }
+    ],
+    "stateMutability": "view",
+    "type": "function"
+  }
+]

pkg/chain/ethereum/tbtc/gen/Makefile

@@ -1,7 +1,7 @@
 npm_package_name=@keep-network/tbtc-v2
 
 # Contracts for which the bindings should be generated.
-required_contracts := Bridge MaintainerProxy LightRelay LightRelayMaintainerProxy WalletProposalValidator RedemptionWatchtower
+required_contracts := Bridge MaintainerProxy LightRelay LightRelayMaintainerProxy WalletProposalValidator RedemptionWatchtower ReservationRouter
 
 # There is a bug in the currently used abigen version (v1.10.19) that makes it
 # re-declaring structs used by multiple contracts
@@ -22,6 +22,7 @@ define after_abi_hook
 	$(eval type := $(1))
 	$(if $(filter $(type),WalletProposalValidator),$(call fix_wallet_proposal_validator_collision))
 	$(if $(filter $(type),MaintainerProxy),$(call fix_maintainer_proxy_collision))
+	$(if $(filter $(type),ReservationRouter),$(call fix_reservation_router_collision))
 endef
 define fix_wallet_proposal_validator_collision
 	@perl -pi -e s,BitcoinTxInfo,BitcoinTxInfo2,g ./abi/WalletProposalValidator.go
@@ -32,12 +33,26 @@ define fix_maintainer_proxy_collision
 	@perl -pi -e s,BitcoinTxProof,BitcoinTxProof2,g ./abi/MaintainerProxy.go
 	@perl -pi -e s,BitcoinTxInfo,BitcoinTxInfo3,g ./abi/MaintainerProxy.go
 endef
+# ReservationRouter introduces its own copies of the BitcoinTx.* structs
+# (BitcoinTxInfo, BitcoinTxProof, BitcoinTxUTXO) used by submitReservationProof.
+# These names already collide with Bridge's (BitcoinTxInfo/BitcoinTxProof/BitcoinTxUTXO),
+# WalletProposalValidator's (BitcoinTxInfo2/BitcoinTxUTXO3), and MaintainerProxy's
+# (BitcoinTxInfo3/BitcoinTxProof2/BitcoinTxUTXO2). Renumber ReservationRouter's
+# copies to the next free suffix in each family. The router code only ever runs
+# via Bridge.fallback delegatecall, so its storage pointer is unused; this is
+# a purely textual rename to keep the abi package compiling.
+define fix_reservation_router_collision
+	@perl -pi -e s,BitcoinTxInfo,BitcoinTxInfo4,g ./abi/ReservationRouter.go
+	@perl -pi -e s,BitcoinTxProof,BitcoinTxProof3,g ./abi/ReservationRouter.go
+	@perl -pi -e s,BitcoinTxUTXO,BitcoinTxUTXO4,g ./abi/ReservationRouter.go
+endef
 
 # See explanation in https://github.com/keep-network/keep-common/issues/117.
 define after_contract_hook
 	$(eval type := $(1))
 	$(if $(filter $(type),WalletProposalValidator),$(call fix_wallet_proposal_validator_contract_collision))
 	$(if $(filter $(type),MaintainerProxy),$(call fix_maintainer_proxy_contract_collision))
+	$(if $(filter $(type),ReservationRouter),$(call fix_reservation_router_contract_collision))
 endef
 define fix_wallet_proposal_validator_contract_collision
 	@perl -pi -e s,BitcoinTxUTXO,BitcoinTxUTXO3,g ./contract/WalletProposalValidator.go
@@ -51,5 +66,76 @@ define fix_maintainer_proxy_contract_collision
 	@perl -pi -e s,BitcoinTxProof,BitcoinTxProof2,g ./cmd/MaintainerProxy.go
 	@perl -pi -e s,BitcoinTxInfo,BitcoinTxInfo3,g ./cmd/MaintainerProxy.go
 endef
+# keep-common's generator emits BitcoinTx* references inside the generated
+# contract/cmd binding code paths too (e.g. method wrappers). Apply the same
+# renames there so the contract and cmd packages compile.
+define fix_reservation_router_contract_collision
+	@perl -pi -e s,BitcoinTxInfo,BitcoinTxInfo4,g ./contract/ReservationRouter.go
+	@perl -pi -e s,BitcoinTxProof,BitcoinTxProof3,g ./contract/ReservationRouter.go
+	@perl -pi -e s,BitcoinTxUTXO,BitcoinTxUTXO4,g ./contract/ReservationRouter.go
+	@perl -pi -e s,BitcoinTxInfo,BitcoinTxInfo4,g ./cmd/ReservationRouter.go
+	@perl -pi -e s,BitcoinTxProof,BitcoinTxProof3,g ./cmd/ReservationRouter.go
+	@perl -pi -e s,BitcoinTxUTXO,BitcoinTxUTXO4,g ./cmd/ReservationRouter.go
+endef
 
 include ../../common/gen/Makefile
+
+# @keep-network/tbtc-v2@development on npm does not yet publish
+# ReservationRouter.json (threshold-network/keep-core#4281), which makes
+# `make generate` fail outright since nothing else can produce that
+# prerequisite. Fall back to a vendored copy - its ABI is byte-for-byte
+# the ABI already embedded in the committed bindings (re-derived from
+# ReservationRouterMetaData.ABI, with the "struct"/"enum"/"contract"
+# internalType prefix space abigen's metadata packer strips put back;
+# verified by round-tripping through the same abigen + keep-common
+# generator invocation and diffing byte-identical against
+# abi/ReservationRouter.go, contract/ReservationRouter.go, and
+# cmd/ReservationRouter.go) - only when the real artifact is missing,
+# and only in the `development` environment, which already tolerates
+# placeholder addresses (see the _address/% rule above). Non-development
+# builds still hard-fail if the real artifact is ever missing there,
+# since a real deployed address must never be substituted silently.
+# Remove this rule once tbtc-v2 publishes the real artifact upstream.
+${artifacts_dir}/ReservationRouter.json:
+ifeq ($(environment), development)
+	@[ -f "$@" ] || { \
+		echo "ReservationRouter - artifact missing from ${npm_package_name}@${environment}, using vendored fallback (see threshold-network/keep-core#4281)"; \
+		cp ReservationRouter.fallback-artifact.json "$@"; \
+	}
+else
+	@[ -f "$@" ] || { echo "$@ does not exist!"; exit 1; }
+endif
+
+# @keep-network/tbtc-v2@development on npm publishes Bridge.json and
+# WalletProposalValidator.json, but both are stale relative to the
+# reservation feature: they're missing isReservedDeposit (Bridge) and
+# validateReservationAnchorProposal/validateReservationReanchorProposal
+# (WalletProposalValidator), which the committed bindings already call
+# (threshold-network/keep-core#4281). Unlike ReservationRouter.json,
+# these files exist, so an only-if-missing artifact rule can't apply -
+# patch the fetched artifact in place instead, merging in vendored
+# fragments (extracted from the committed BridgeMetaData.ABI /
+# WalletProposalValidatorMetaData.ABI, internalType prefix space
+# restored the same way as ReservationRouter's; verified by
+# round-tripping through the same abigen + keep-common generator
+# invocation, producing a clean `go build ./...`) before anything reads
+# the artifact. Only in `development`; only when the methods are
+# actually missing, so a real future npm publish makes this a no-op
+# without needing to be removed first. Non-development builds are
+# untouched. Remove this whole block once tbtc-v2 publishes the real
+# methods upstream.
+.PHONY: patch-artifacts
+check_artifacts: patch-artifacts
+patch-artifacts:
+ifeq ($(environment), development)
+	@jq -e '.abi[] | select(.name == "isReservedDeposit")' ${artifacts_dir}/Bridge.json >/dev/null 2>&1 || { \
+		echo "Bridge - artifact missing reservation methods, patching in vendored fallback (see threshold-network/keep-core#4281)"; \
+		jq --slurpfile extra Bridge.reservation-methods-fallback.json '.abi += $$extra[0]' ${artifacts_dir}/Bridge.json > ${artifacts_dir}/Bridge.json.patched && \
+		mv ${artifacts_dir}/Bridge.json.patched ${artifacts_dir}/Bridge.json; \
+	}
+	@jq -e '.abi[] | select(.name == "validateReservationAnchorProposal")' ${artifacts_dir}/WalletProposalValidator.json >/dev/null 2>&1 || { \
+		echo "WalletProposalValidator - artifact missing reservation methods, patching in vendored fallback (see threshold-network/keep-core#4281)"; \
+		jq --slurpfile extra WalletProposalValidator.reservation-methods-fallback.json '.abi += $$extra[0]' ${artifacts_dir}/WalletProposalValidator.json > ${artifacts_dir}/WalletProposalValidator.json.patched && \
+		mv ${artifacts_dir}/WalletProposalValidator.json.patched ${artifacts_dir}/WalletProposalValidator.json; \
+	}
+endif