draft: UTXO reservation wallet-side foundations

pkg/chain/ethereum/tbtc.go

@@ -2408,3 +2408,96 @@ func (tc *TbtcChain) GetRedemptionDelay(
 func (tc *TbtcChain) GetDepositMinAge() (uint32, error) {
 	return tc.walletProposalValidator.DEPOSITMINAGE()
 }
+
+// GetReservation is not yet supported by the Ethereum chain implementation:
+// the reservation contract bindings will be regenerated once the reservation
+// Bridge API is published with the @keep-network/tbtc-v2 package.
+func (tc *TbtcChain) GetReservation(
+	reservationKey *big.Int,
+) (*tbtc.Reservation, error) {
+	return nil, fmt.Errorf(
+		"reservations not supported yet by the Ethereum chain implementation",
+	)
+}
+
+// GetReservationAction is not yet supported by the Ethereum chain
+// implementation: the reservation contract bindings will be regenerated once
+// the reservation Bridge API is published with the @keep-network/tbtc-v2
+// package.
+func (tc *TbtcChain) GetReservationAction(
+	reservationKey *big.Int,
+	requestNonce uint64,
+) (*tbtc.ReservationAction, error) {
+	return nil, fmt.Errorf(
+		"reservations not supported yet by the Ethereum chain implementation",
+	)
+}
+
+// ReservationParameters is not yet supported by the Ethereum chain
+// implementation: the reservation contract bindings will be regenerated once
+// the reservation Bridge API is published with the @keep-network/tbtc-v2
+// package.
+func (tc *TbtcChain) ReservationParameters() (
+	*tbtc.ReservationParameters,
+	error,
+) {
+	return nil, fmt.Errorf(
+		"reservations not supported yet by the Ethereum chain implementation",
+	)
+}
+
+// ValidateReservationAnchorProposal is not yet supported by the Ethereum
+// chain implementation: the reservation contract bindings will be
+// regenerated once the reservation Bridge API is published with the
+// @keep-network/tbtc-v2 package.
+func (tc *TbtcChain) ValidateReservationAnchorProposal(
+	walletPublicKeyHash [20]byte,
+	proposal *tbtc.ReservationAnchorProposal,
+	depositExtraInfo struct {
+		*tbtc.Deposit
+		FundingTx *bitcoin.Transaction
+	},
+) error {
+	return fmt.Errorf(
+		"reservations not supported yet by the Ethereum chain implementation",
+	)
+}
+
+// ValidateReservedRedemptionProposal is not yet supported by the Ethereum
+// chain implementation: the reservation contract bindings will be
+// regenerated once the reservation Bridge API is published with the
+// @keep-network/tbtc-v2 package.
+func (tc *TbtcChain) ValidateReservedRedemptionProposal(
+	walletPublicKeyHash [20]byte,
+	proposal *tbtc.ReservedRedemptionProposal,
+) error {
+	return fmt.Errorf(
+		"reservations not supported yet by the Ethereum chain implementation",
+	)
+}
+
+// ValidateReservationReanchorProposal is not yet supported by the Ethereum
+// chain implementation: the reservation contract bindings will be
+// regenerated once the reservation Bridge API is published with the
+// @keep-network/tbtc-v2 package.
+func (tc *TbtcChain) ValidateReservationReanchorProposal(
+	sourceWalletPublicKeyHash [20]byte,
+	proposal *tbtc.ReservationReanchorProposal,
+) error {
+	return fmt.Errorf(
+		"reservations not supported yet by the Ethereum chain implementation",
+	)
+}
+
+// ValidateReservationDissolutionProposal is not yet supported by the
+// Ethereum chain implementation: the reservation contract bindings will be
+// regenerated once the reservation Bridge API is published with the
+// @keep-network/tbtc-v2 package.
+func (tc *TbtcChain) ValidateReservationDissolutionProposal(
+	walletPublicKeyHash [20]byte,
+	proposal *tbtc.ReservationDissolutionProposal,
+) error {
+	return fmt.Errorf(
+		"reservations not supported yet by the Ethereum chain implementation",
+	)
+}

pkg/clientinfo/performance.go

@@ -751,5 +751,9 @@ func GetAllWalletActionTypes() []string {
 		"redemption",
 		"moving_funds",
 		"moved_funds_sweep",
+		"reservation_anchor",
+		"reserved_redemption",
+		"reservation_reanchor",
+		"reservation_dissolution",
 	}
 }

pkg/clientinfo/performance_test.go

@@ -430,3 +430,54 @@ func TestJoinFailureAndOnChainCountersRegistered(t *testing.T) {
 		}
 	}
 }
+
+func TestWalletActionMetricsRegistered(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	registry := &Registry{keepclientinfo.NewRegistry(), ctx}
+	pm := NewPerformanceMetrics(ctx, registry)
+
+	expectedActionTypes := []string{
+		"heartbeat",
+		"deposit_sweep",
+		"redemption",
+		"moving_funds",
+		"moved_funds_sweep",
+		"reservation_anchor",
+		"reserved_redemption",
+		"reservation_reanchor",
+		"reservation_dissolution",
+	}
+
+	for _, actionType := range expectedActionTypes {
+		for _, metricType := range []string{
+			"total",
+			"success_total",
+			"failed_total",
+		} {
+			metricName := WalletActionMetricName(actionType, metricType)
+
+			pm.countersMutex.RLock()
+			_, exists := pm.counters[metricName]
+			pm.countersMutex.RUnlock()
+			if !exists {
+				t.Errorf("counter %s should be registered upfront", metricName)
+			}
+		}
+
+		durationMetricName := WalletActionMetricName(
+			actionType,
+			"duration_seconds",
+		)
+		pm.histogramsMutex.RLock()
+		_, exists := pm.histograms[durationMetricName]
+		pm.histogramsMutex.RUnlock()
+		if !exists {
+			t.Errorf(
+				"histogram %s should be registered upfront",
+				durationMetricName,
+			)
+		}
+	}
+}

pkg/tbtc/chain.go

@@ -427,6 +427,58 @@ type WalletProposalValidatorChain interface {
 		},
 	) error
 
+	// GetReservation gets the on-chain reservation record for the given
+	// reservation key. Returns an error if the reservation was not found.
+	GetReservation(reservationKey *big.Int) (*Reservation, error)
+
+	// GetReservationAction gets the on-chain action record for the given
+	// reservation key and request nonce. Returns an error if the action
+	// generation was not found.
+	GetReservationAction(
+		reservationKey *big.Int,
+		requestNonce uint64,
+	) (*ReservationAction, error)
+
+	// ReservationParameters gets the current on-chain values of the Bridge
+	// reservation parameters.
+	ReservationParameters() (*ReservationParameters, error)
+
+	// ValidateReservationAnchorProposal validates the given reservation
+	// anchor proposal against the chain. Returns an error if the proposal
+	// is not valid or nil otherwise.
+	ValidateReservationAnchorProposal(
+		walletPublicKeyHash [20]byte,
+		proposal *ReservationAnchorProposal,
+		depositExtraInfo struct {
+			*Deposit
+			FundingTx *bitcoin.Transaction
+		},
+	) error
+
+	// ValidateReservedRedemptionProposal validates the given reserved
+	// redemption proposal against the chain. Returns an error if the
+	// proposal is not valid or nil otherwise.
+	ValidateReservedRedemptionProposal(
+		walletPublicKeyHash [20]byte,
+		proposal *ReservedRedemptionProposal,
+	) error
+
+	// ValidateReservationReanchorProposal validates the given reservation
+	// re-anchor proposal against the chain. Returns an error if the
+	// proposal is not valid or nil otherwise.
+	ValidateReservationReanchorProposal(
+		sourceWalletPublicKeyHash [20]byte,
+		proposal *ReservationReanchorProposal,
+	) error
+
+	// ValidateReservationDissolutionProposal validates the given reservation
+	// dissolution proposal against the chain. Returns an error if the
+	// proposal is not valid or nil otherwise.
+	ValidateReservationDissolutionProposal(
+		walletPublicKeyHash [20]byte,
+		proposal *ReservationDissolutionProposal,
+	) error
+
 	// ValidateRedemptionProposal validates the given redemption proposal
 	// against the chain. Returns an error if the proposal is not valid or
 	// nil otherwise.

pkg/tbtc/chain_test.go

@@ -1450,3 +1450,52 @@ func generateHandlerID() int {
 	// Local chain implementation doesn't require secure randomness.
 	return rand.Int()
 }
+
+func (lc *localChain) GetReservation(
+	reservationKey *big.Int,
+) (*Reservation, error) {
+	panic("unsupported")
+}
+
+func (lc *localChain) GetReservationAction(
+	reservationKey *big.Int,
+	requestNonce uint64,
+) (*ReservationAction, error) {
+	panic("unsupported")
+}
+
+func (lc *localChain) ReservationParameters() (*ReservationParameters, error) {
+	panic("unsupported")
+}
+
+func (lc *localChain) ValidateReservationAnchorProposal(
+	walletPublicKeyHash [20]byte,
+	proposal *ReservationAnchorProposal,
+	depositExtraInfo struct {
+		*Deposit
+		FundingTx *bitcoin.Transaction
+	},
+) error {
+	panic("unsupported")
+}
+
+func (lc *localChain) ValidateReservedRedemptionProposal(
+	walletPublicKeyHash [20]byte,
+	proposal *ReservedRedemptionProposal,
+) error {
+	panic("unsupported")
+}
+
+func (lc *localChain) ValidateReservationReanchorProposal(
+	sourceWalletPublicKeyHash [20]byte,
+	proposal *ReservationReanchorProposal,
+) error {
+	panic("unsupported")
+}
+
+func (lc *localChain) ValidateReservationDissolutionProposal(
+	walletPubKeyHash [20]byte,
+	proposal *ReservationDissolutionProposal,
+) error {
+	panic("unsupported")
+}

pkg/tbtc/marshaling.go

@@ -229,12 +229,16 @@ func unmarshalCoordinationProposal(actionType uint32, payload []byte) (
 	}
 
 	proposal, ok := map[WalletActionType]CoordinationProposal{
-		ActionNoop:            &NoopProposal{},
-		ActionHeartbeat:       &HeartbeatProposal{},
-		ActionDepositSweep:    &DepositSweepProposal{},
-		ActionRedemption:      &RedemptionProposal{},
-		ActionMovingFunds:     &MovingFundsProposal{},
-		ActionMovedFundsSweep: &MovedFundsSweepProposal{},
+		ActionNoop:                   &NoopProposal{},
+		ActionHeartbeat:              &HeartbeatProposal{},
+		ActionDepositSweep:           &DepositSweepProposal{},
+		ActionRedemption:             &RedemptionProposal{},
+		ActionMovingFunds:            &MovingFundsProposal{},
+		ActionMovedFundsSweep:        &MovedFundsSweepProposal{},
+		ActionReservationAnchor:      &ReservationAnchorProposal{},
+		ActionReservedRedemption:     &ReservedRedemptionProposal{},
+		ActionReservationReanchor:    &ReservationReanchorProposal{},
+		ActionReservationDissolution: &ReservationDissolutionProposal{},
 	}[parsedActionType]
 	if !ok {
 		return nil, fmt.Errorf(