fix(staking): report minimum deposit when commitment would decrease

Pre-check manageStake against the non-decreasing commitment rule so
small deposits fail with HTTP 400 and the required amount instead of a
misleading gas error. Expose the minimum on GET /stake.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: sbackend123

openapi/Swarm.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 
 info:
-  version: 8.1.0
+  version: 8.2.0
   title: Bee API
   description: "API endpoints for interacting with the Swarm network, supporting file operations, messaging, and node management"
 
@@ -2567,7 +2567,7 @@ paths:
   "/stake":
     get:
       summary: Get the staked amount.
-      description: This endpoint fetches the total staked amount from the blockchain.
+      description: This endpoint fetches the total staked amount and the minimum additional deposit from the blockchain. The first deposit is at least 0.1 BZZ times 2^height. Subsequent deposits are at least 1 PLUR, or more if the price oracle has increased since the last deposit.
       tags:
         - Staking
       responses:

openapi/SwarmCommon.yaml

@@ -681,6 +681,8 @@ components:
       properties:
         stakedAmount:
           $ref: "#/components/schemas/BigInt"
+        minimumDeposit:
+          $ref: "#/components/schemas/BigInt"
 
     GetWithdrawableResponse:
       type: object

pkg/api/staking.go

@@ -6,14 +6,15 @@ package api
 
 import (
 	"errors"
+	"fmt"
 	"math/big"
 	"net/http"
 
-	"github.com/ethersphere/bee/v2/pkg/bigint"
+	"github.com/gorilla/mux"
 
+	"github.com/ethersphere/bee/v2/pkg/bigint"
 	"github.com/ethersphere/bee/v2/pkg/jsonhttp"
 	"github.com/ethersphere/bee/v2/pkg/storageincentives/staking"
-	"github.com/gorilla/mux"
 )
 
 func (s *Service) stakingAccessHandler(h http.Handler) http.Handler {
@@ -31,7 +32,8 @@ func (s *Service) stakingAccessHandler(h http.Handler) http.Handler {
 }
 
 type getStakeResponse struct {
-	StakedAmount *bigint.BigInt `json:"stakedAmount"`
+	StakedAmount   *bigint.BigInt `json:"stakedAmount"`
+	MinimumDeposit *bigint.BigInt `json:"minimumDeposit"`
 }
 
 type getWithdrawableResponse struct {
@@ -55,9 +57,15 @@ func (s *Service) stakingDepositHandler(w http.ResponseWriter, r *http.Request)
 	txHash, err := s.stakingContract.DepositStake(r.Context(), paths.Amount)
 	if err != nil {
 		if errors.Is(err, staking.ErrInsufficientStakeAmount) {
-			logger.Debug("insufficient stake amount", "minimum_stake", staking.MinimumStakeAmount, "error", err)
+			minDeposit := staking.MinimumStakeAmount
+			var minErr *staking.MinDepositError
+			if errors.As(err, &minErr) && minErr.Minimum != nil {
+				minDeposit = minErr.Minimum
+			}
+			msg := fmt.Sprintf("insufficient stake amount, minimum is %s", minDeposit)
+			logger.Debug("insufficient stake amount", "minimum_stake", minDeposit, "error", err)
 			logger.Error(nil, "insufficient stake amount")
-			jsonhttp.BadRequest(w, "insufficient stake amount")
+			jsonhttp.BadRequest(w, msg)
 			return
 		}
 		if errors.Is(err, staking.ErrNotImplemented) {
@@ -105,7 +113,18 @@ func (s *Service) getPotentialStake(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	jsonhttp.OK(w, getStakeResponse{StakedAmount: bigint.Wrap(stakedAmount)})
+	minDeposit, err := s.stakingContract.GetMinDeposit(r.Context())
+	if err != nil {
+		logger.Debug("get minimum deposit failed", "overlayAddr", s.overlay, "error", err)
+		logger.Error(nil, "get minimum deposit failed")
+		jsonhttp.InternalServerError(w, "get minimum deposit failed")
+		return
+	}
+
+	jsonhttp.OK(w, getStakeResponse{
+		StakedAmount:   bigint.Wrap(stakedAmount),
+		MinimumDeposit: bigint.Wrap(minDeposit),
+	})
 }
 
 func (s *Service) getWithdrawableStakeHandler(w http.ResponseWriter, r *http.Request) {

pkg/api/staking_test.go

@@ -12,9 +12,9 @@ import (
 	"testing"
 
 	"github.com/ethereum/go-ethereum/common"
-	"github.com/ethersphere/bee/v2/pkg/bigint"
 
 	"github.com/ethersphere/bee/v2/pkg/api"
+	"github.com/ethersphere/bee/v2/pkg/bigint"
 	"github.com/ethersphere/bee/v2/pkg/jsonhttp"
 	"github.com/ethersphere/bee/v2/pkg/jsonhttp/jsonhttptest"
 	"github.com/ethersphere/bee/v2/pkg/sctx"
@@ -54,7 +54,21 @@ func TestDepositStake(t *testing.T) {
 		)
 		ts, _, _, _ := newTestServer(t, testServerOptions{StakingContract: contract})
 		jsonhttptest.Request(t, ts, http.MethodPost, depositStake(invalidMinStake), http.StatusBadRequest,
-			jsonhttptest.WithExpectedJSONResponse(&jsonhttp.StatusResponse{Code: http.StatusBadRequest, Message: "insufficient stake amount"}))
+			jsonhttptest.WithExpectedJSONResponse(&jsonhttp.StatusResponse{Code: http.StatusBadRequest, Message: "insufficient stake amount, minimum is 100000000000000000"}))
+	})
+
+	t.Run("with insufficient amount reports minimum", func(t *testing.T) {
+		t.Parallel()
+
+		minDeposit := big.NewInt(123)
+		contract := stakingContractMock.New(
+			stakingContractMock.WithDepositStake(func(ctx context.Context, stakedAmount *big.Int) (common.Hash, error) {
+				return common.Hash{}, &staking.MinDepositError{Minimum: minDeposit}
+			}),
+		)
+		ts, _, _, _ := newTestServer(t, testServerOptions{StakingContract: contract})
+		jsonhttptest.Request(t, ts, http.MethodPost, depositStake("1"), http.StatusBadRequest,
+			jsonhttptest.WithExpectedJSONResponse(&jsonhttp.StatusResponse{Code: http.StatusBadRequest, Message: "insufficient stake amount, minimum is 123"}))
 	})
 
 	t.Run("out of funds", func(t *testing.T) {
@@ -134,7 +148,10 @@ func TestGetStakeCommitted(t *testing.T) {
 		)
 		ts, _, _, _ := newTestServer(t, testServerOptions{StakingContract: contract})
 		jsonhttptest.Request(t, ts, http.MethodGet, "/stake", http.StatusOK,
-			jsonhttptest.WithExpectedJSONResponse(&api.GetStakeResponse{StakedAmount: bigint.Wrap(big.NewInt(1))}))
+			jsonhttptest.WithExpectedJSONResponse(&api.GetStakeResponse{
+				StakedAmount:   bigint.Wrap(big.NewInt(1)),
+				MinimumDeposit: bigint.Wrap(big.NewInt(1)),
+			}))
 	})
 
 	t.Run("with error", func(t *testing.T) {
@@ -149,6 +166,22 @@ func TestGetStakeCommitted(t *testing.T) {
 		jsonhttptest.Request(t, ts, http.MethodGet, "/stake", http.StatusInternalServerError,
 			jsonhttptest.WithExpectedJSONResponse(&jsonhttp.StatusResponse{Code: http.StatusInternalServerError, Message: "get staked amount failed"}))
 	})
+
+	t.Run("minimum deposit error", func(t *testing.T) {
+		t.Parallel()
+
+		contractWithError := stakingContractMock.New(
+			stakingContractMock.WithGetStake(func(ctx context.Context) (*big.Int, error) {
+				return big.NewInt(1), nil
+			}),
+			stakingContractMock.WithGetMinDeposit(func(ctx context.Context) (*big.Int, error) {
+				return nil, fmt.Errorf("get minimum deposit failed")
+			}),
+		)
+		ts, _, _, _ := newTestServer(t, testServerOptions{StakingContract: contractWithError})
+		jsonhttptest.Request(t, ts, http.MethodGet, "/stake", http.StatusInternalServerError,
+			jsonhttptest.WithExpectedJSONResponse(&jsonhttp.StatusResponse{Code: http.StatusInternalServerError, Message: "get minimum deposit failed"}))
+	})
 }
 
 func TestGetStakeWithdrawable(t *testing.T) {

pkg/storageincentives/staking/contract.go

@@ -13,16 +13,18 @@ import (
 	"github.com/ethereum/go-ethereum/accounts/abi"
 	"github.com/ethereum/go-ethereum/common"
 	"github.com/ethereum/go-ethereum/core/types"
+	"github.com/ethersphere/go-sw3-abi/sw3abi"
+
 	"github.com/ethersphere/bee/v2/pkg/sctx"
 	"github.com/ethersphere/bee/v2/pkg/transaction"
 	"github.com/ethersphere/bee/v2/pkg/util/abiutil"
-	"github.com/ethersphere/go-sw3-abi/sw3abi"
 )
 
 var (
 	MinimumStakeAmount = big.NewInt(100000000000000000)
 
-	erc20ABI = abiutil.MustParseABI(sw3abi.ERC20ABIv0_6_9)
+	erc20ABI       = abiutil.MustParseABI(sw3abi.ERC20ABIv0_6_9)
+	priceOracleABI = abiutil.MustParseABI(`[{"inputs":[],"name":"currentPrice","outputs":[{"internalType":"uint32","name":"","type":"uint32"}],"stateMutability":"view","type":"function"}]`)
 
 	ErrInsufficientStakeAmount = errors.New("insufficient stake amount")
 	ErrInsufficientFunds       = errors.New("insufficient token balance")
@@ -37,10 +39,25 @@ var (
 	migrateStakeDescription  = "Migrate stake"
 )
 
+// MinDepositError is returned when a deposit is below the amount required by the
+// staking contract, including the non-decreasing commitment rule.
+type MinDepositError struct {
+	Minimum *big.Int
+}
+
+func (e *MinDepositError) Error() string {
+	return fmt.Sprintf("insufficient stake amount: minimum %s", e.Minimum)
+}
+
+func (e *MinDepositError) Unwrap() error {
+	return ErrInsufficientStakeAmount
+}
+
 type Contract interface {
 	DepositStake(ctx context.Context, stakedAmount *big.Int) (common.Hash, error)
 	ChangeStakeOverlay(ctx context.Context, nonce common.Hash) (common.Hash, error)
 	GetPotentialStake(ctx context.Context) (*big.Int, error)
+	GetMinDeposit(ctx context.Context) (*big.Int, error)
 	GetWithdrawableStake(ctx context.Context) (*big.Int, error)
 	WithdrawStake(ctx context.Context) (common.Hash, error)
 	MigrateStake(ctx context.Context) (common.Hash, error)
@@ -86,19 +103,13 @@ func New(
 }
 
 func (c *contract) DepositStake(ctx context.Context, stakedAmount *big.Int) (common.Hash, error) {
-	prevStakedAmount, err := c.GetPotentialStake(ctx)
+	minDeposit, err := c.GetMinDeposit(ctx)
 	if err != nil {
 		return common.Hash{}, err
 	}
 
-	if len(prevStakedAmount.Bits()) == 0 {
-		if stakedAmount.Cmp(MinimumStakeAmount) == -1 {
-			return common.Hash{}, ErrInsufficientStakeAmount
-		}
-	}
-
-	if big.NewInt(0).Add(prevStakedAmount, stakedAmount).Cmp(big.NewInt(0).Mul(big.NewInt(1<<c.height), MinimumStakeAmount)) < 0 {
-		return common.Hash{}, fmt.Errorf("stake amount does not sufficiently cover the additional reserve capacity: %w", ErrInsufficientStakeAmount)
+	if stakedAmount.Cmp(minDeposit) < 0 {
+		return common.Hash{}, &MinDepositError{Minimum: minDeposit}
 	}
 
 	balance, err := c.getBalance(ctx)
@@ -154,11 +165,59 @@ func (c *contract) UpdateHeight(ctx context.Context) (common.Hash, bool, error)
 }
 
 func (c *contract) GetPotentialStake(ctx context.Context) (*big.Int, error) {
-	stakedAmount, err := c.getPotentialStake(ctx)
+	_, potential, err := c.getStake(ctx)
 	if err != nil {
 		return nil, fmt.Errorf("staking contract: failed to get stake: %w", err)
 	}
-	return stakedAmount, nil
+	return potential, nil
+}
+
+func (c *contract) GetMinDeposit(ctx context.Context) (*big.Int, error) {
+	committed, potential, err := c.getStake(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("staking contract: failed to get stake: %w", err)
+	}
+
+	var price uint32
+	if committed.Sign() > 0 {
+		price, err = c.getCurrentPrice(ctx)
+		if err != nil {
+			return nil, fmt.Errorf("staking contract: failed to get oracle price: %w", err)
+		}
+	}
+
+	return calculateMinDeposit(potential, committed, price, c.height), nil
+}
+
+// calculateMinDeposit returns the minimum additional deposit in PLUR that
+// manageStake will accept. The first deposit must cover 2^height * MIN_STAKE.
+// Later deposits must keep committed stake from decreasing after a price
+// increase; if that constraint is already satisfied the minimum is 1 PLUR.
+func calculateMinDeposit(potential, committed *big.Int, price uint32, height uint8) *big.Int {
+	minAdd := new(big.Int)
+
+	minTotal := new(big.Int).Lsh(new(big.Int).Set(MinimumStakeAmount), uint(height))
+	if gap := new(big.Int).Sub(minTotal, potential); gap.Sign() > 0 {
+		minAdd.Set(gap)
+	}
+
+	if price != 0 && committed.Sign() > 0 {
+		required := new(big.Int).SetUint64(uint64(price))
+		required.Lsh(required, uint(height))
+		required.Mul(required, committed)
+		if gap := new(big.Int).Sub(required, potential); gap.Cmp(minAdd) > 0 {
+			minAdd.Set(gap)
+		}
+	}
+
+	if minAdd.Sign() == 0 {
+		if potential.Sign() > 0 {
+			return big.NewInt(1)
+		}
+		return new(big.Int).Set(MinimumStakeAmount)
+	}
+
+	return minAdd
 }
 
 func (c *contract) GetWithdrawableStake(ctx context.Context) (*big.Int, error) {
@@ -327,17 +386,17 @@ func (c *contract) sendManageStakeTransaction(ctx context.Context, stakedAmount
 	return receipt, nil
 }
 
-func (c *contract) getPotentialStake(ctx context.Context) (*big.Int, error) {
+func (c *contract) getStake(ctx context.Context) (committed, potential *big.Int, err error) {
 	callData, err := c.stakingContractABI.Pack("stakes", c.owner)
 	if err != nil {
-		return nil, err
+		return nil, nil, err
 	}
 	result, err := c.transactionService.Call(ctx, &transaction.TxRequest{
 		To:   &c.stakingContractAddress,
 		Data: callData,
 	})
 	if err != nil {
-		return nil, fmt.Errorf("get potential stake: %w", err)
+		return nil, nil, fmt.Errorf("get potential stake: %w", err)
 	}
 
 	// overlay bytes32,
@@ -346,14 +405,71 @@ func (c *contract) getPotentialStake(ctx context.Context) (*big.Int, error) {
 	// lastUpdatedBlockNumber uint256,
 	results, err := c.stakingContractABI.Unpack("stakes", result)
 	if err != nil {
-		return nil, err
+		return nil, nil, err
 	}
 
 	if len(results) < 4 {
-		return nil, ErrUnexpectedLength
+		return nil, nil, ErrUnexpectedLength
+	}
+
+	committed = abi.ConvertType(results[1], new(big.Int)).(*big.Int)
+	potential = abi.ConvertType(results[2], new(big.Int)).(*big.Int)
+	return committed, potential, nil
+}
+
+func (c *contract) getCurrentPrice(ctx context.Context) (uint32, error) {
+	callData, err := c.stakingContractABI.Pack("OracleContract")
+	if err != nil {
+		return 0, err
+	}
+
+	result, err := c.transactionService.Call(ctx, &transaction.TxRequest{
+		To:   &c.stakingContractAddress,
+		Data: callData,
+	})
+	if err != nil {
+		return 0, fmt.Errorf("get oracle address: %w", err)
+	}
+
+	results, err := c.stakingContractABI.Unpack("OracleContract", result)
+	if err != nil {
+		return 0, err
+	}
+
+	if len(results) == 0 {
+		return 0, errors.New("unexpected empty results")
+	}
+
+	oracleAddr := *abi.ConvertType(results[0], new(common.Address)).(*common.Address)
+
+	callData, err = priceOracleABI.Pack("currentPrice")
+	if err != nil {
+		return 0, err
+	}
+
+	result, err = c.transactionService.Call(ctx, &transaction.TxRequest{
+		To:   &oracleAddr,
+		Data: callData,
+	})
+	if err != nil {
+		return 0, fmt.Errorf("get current price: %w", err)
+	}
+
+	results, err = priceOracleABI.Unpack("currentPrice", result)
+	if err != nil {
+		return 0, err
+	}
+
+	if len(results) == 0 {
+		return 0, errors.New("unexpected empty results")
+	}
+
+	price, ok := results[0].(uint32)
+	if !ok {
+		return 0, fmt.Errorf("unexpected oracle price type %T", results[0])
 	}
 
-	return abi.ConvertType(results[2], new(big.Int)).(*big.Int), nil
+	return price, nil
 }
 
 func (c *contract) getWithdrawableStake(ctx context.Context) (*big.Int, error) {