refactor: replace full-node flag with explicit node-mode config

.github/workflows/beekeeper.yml

@@ -19,7 +19,7 @@ env:
   SETUP_CONTRACT_IMAGE: "ethersphere/bee-localchain"
   SETUP_CONTRACT_IMAGE_TAG: "0.9.4"
   BEELOCAL_BRANCH: "main"
-  BEEKEEPER_BRANCH: "master"
+  BEEKEEPER_BRANCH: "refactor/node-mode-config"
   BEEKEEPER_METRICS_ENABLED: false
   REACHABILITY_OVERRIDE_PUBLIC: true
   BATCHFACTOR_OVERRIDE_PUBLIC: 2

cmd/bee/cmd/cmd.go

@@ -52,9 +52,10 @@ const (
 	optionNameBootnodeMode                 = "bootnode-mode"
 	optionNameSwapFactoryAddress           = "swap-factory-address"
 	optionNameSwapInitialDeposit           = "swap-initial-deposit"
+	optionNameNodeMode                     = "node-mode"
 	optionNameSwapEnable                   = "swap-enable"
 	optionNameChequebookEnable             = "chequebook-enable"
-	optionNameFullNode                     = "full-node"
+	optionNameFullNode                     = "full-node" // Deprecated: use node-mode instead.
 	optionNamePostageContractAddress       = "postage-stamp-address"
 	optionNamePostageContractStartBlock    = "postage-stamp-start-block"
 	optionNamePriceOracleAddress           = "price-oracle-address"
@@ -304,9 +305,13 @@ func (c *command) setAllFlags(cmd *cobra.Command) {
 	cmd.Flags().Duration(optionNameBlockchainRpcKeepalive, 30*time.Second, "blockchain rpc TCP keepalive interval")
 	cmd.Flags().String(optionNameSwapFactoryAddress, "", "swap factory addresses")
 	cmd.Flags().String(optionNameSwapInitialDeposit, "0", "initial deposit if deploying a new chequebook")
+	cmd.Flags().String(optionNameNodeMode, string(node.UltraLightMode), "node operational mode: full, light, or ultra-light")
 	cmd.Flags().Bool(optionNameSwapEnable, false, "enable swap")
-	cmd.Flags().Bool(optionNameChequebookEnable, true, "enable chequebook")
-	cmd.Flags().Bool(optionNameFullNode, false, "cause the node to start in full mode")
+	cmd.Flags().Bool(optionNameChequebookEnable, false, "enable chequebook (requires swap-enable)")
+	cmd.Flags().Bool(optionNameFullNode, false, "cause the node to start in full mode (deprecated: use --node-mode=full)")
+	if err := cmd.Flags().MarkDeprecated(optionNameFullNode, "use --node-mode=full instead"); err != nil {
+		panic(err)
+	}
 	cmd.Flags().String(optionNamePostageContractAddress, "", "postage stamp contract address")
 	cmd.Flags().Uint64(optionNamePostageContractStartBlock, 0, "postage stamp contract start block number")
 	cmd.Flags().String(optionNamePriceOracleAddress, "", "price oracle contract address")
@@ -322,7 +327,7 @@ func (c *command) setAllFlags(cmd *cobra.Command) {
 	cmd.Flags().Bool(optionNamePProfMutex, false, "enable pprof mutex profile")
 	cmd.Flags().StringSlice(optionNameStaticNodes, []string{}, "protect nodes from getting kicked out on bootnode")
 	cmd.Flags().Bool(optionNameAllowPrivateCIDRs, false, "allow to advertise private CIDRs to the public network")
-	cmd.Flags().Bool(optionNameStorageIncentivesEnable, true, "enable storage incentives feature")
+	cmd.Flags().Bool(optionNameStorageIncentivesEnable, false, "enable storage incentives feature (full node only)")
 	cmd.Flags().Uint64(optionNameStateStoreCacheCapacity, 100_000, "lru memory caching capacity in number of statestore entries")
 	cmd.Flags().String(optionNameTargetNeighborhood, "", "neighborhood to target in binary format (ex: 111111001) for mining the initial overlay")
 	cmd.Flags().String(optionNameNeighborhoodSuggester, "https://api.swarmscan.io/v1/network/neighborhoods/suggestion", "suggester for target neighborhood")

cmd/bee/cmd/start.go

@@ -204,9 +204,13 @@ func buildBeeNode(ctx context.Context, c *command, cmd *cobra.Command, logger lo
 	}
 
 	bootNode := c.config.GetBool(optionNameBootnodeMode)
-	fullNode := c.config.GetBool(optionNameFullNode)
 
-	if bootNode && !fullNode {
+	nodeMode, err := c.resolveNodeMode(logger)
+	if err != nil {
+		return nil, err
+	}
+
+	if bootNode && nodeMode != node.FullMode {
 		return nil, errors.New("boot node must be started as a full node")
 	}
 
@@ -297,7 +301,7 @@ func buildBeeNode(ctx context.Context, c *command, cmd *cobra.Command, logger lo
 		EnableWS:                      c.config.GetBool(optionNameP2PWSEnable),
 		AutoTLSDomain:                 c.config.GetString(optionAutoTLSDomain),
 		AutoTLSRegistrationEndpoint:   c.config.GetString(optionAutoTLSRegistrationEndpoint),
-		FullNodeMode:                  fullNode,
+		NodeMode:                      nodeMode,
 		Logger:                        logger,
 		MinimumGasTipCap:              c.config.GetUint64(optionNameMinimumGasTipCap),
 		GasLimitFallback:              c.config.GetUint64(optionNameGasLimitFallback),
@@ -337,6 +341,54 @@ func buildBeeNode(ctx context.Context, c *command, cmd *cobra.Command, logger lo
 	return b, err
 }
 
+// resolveNodeMode determines the effective node mode from config.
+// --node-mode takes precedence and triggers strict per-mode validation.
+// The deprecated --full-node flag is honoured as a fallback.
+// When neither is set, mode is inferred from blockchain-rpc-endpoint presence
+// (legacy behaviour) without strict validation, for backward compatibility.
+func (c *command) resolveNodeMode(logger log.Logger) (node.NodeMode, error) {
+	rpcEndpoint := c.config.GetString(configKeyBlockchainRpcEndpoint)
+	swapEnable := c.config.GetBool(optionNameSwapEnable)
+
+	if c.config.IsSet(optionNameNodeMode) {
+		// Explicit node-mode: validate strictly.
+		mode := node.NodeMode(c.config.GetString(optionNameNodeMode))
+		if !mode.IsValid() {
+			return "", fmt.Errorf("invalid node-mode %q: must be one of full, light, ultra-light", mode)
+		}
+		switch mode {
+		case node.FullMode:
+			if rpcEndpoint == "" {
+				return "", errors.New("full node requires blockchain-rpc-endpoint to be set")
+			}
+			if !swapEnable {
+				return "", errors.New("full node requires swap-enable to be true")
+			}
+		case node.LightMode:
+			if rpcEndpoint == "" {
+				return "", errors.New("light node requires blockchain-rpc-endpoint to be set")
+			}
+		case node.UltraLightMode:
+			if swapEnable {
+				return "", errors.New("ultra-light node cannot have swap-enable set to true")
+			}
+		}
+		return mode, nil
+	}
+
+	// Legacy path: node-mode not set, fall back to deprecated flags / old detection.
+	if c.config.GetBool(optionNameFullNode) {
+		logger.Warning("--full-node is deprecated, use --node-mode=full instead")
+		return node.FullMode, nil
+	}
+
+	// Infer light vs ultra-light from RPC endpoint presence (original behaviour).
+	if rpcEndpoint != "" {
+		return node.LightMode, nil
+	}
+	return node.UltraLightMode, nil
+}
+
 type program struct {
 	start func()
 	stop  func()

packaging/bee.yaml

@@ -1,36 +1,110 @@
 ## Bee configuration - https://docs.ethswarm.org/docs/working-with-bee/configuration
 
-## allow to advertise private CIDRs to the public network
-# allow-private-cidrs: false
-## HTTP API listen address
-# api-addr: 127.0.0.1:1633
-## chain block time
-# block-time: "5"
-## block number cache sync interval in blocks
-# block-sync-interval: 10
+## ── Node mode ────────────────────────────────────────────────────────────────
+## Selects the operational mode of this node.
+##   full        - participates in storage and incentives; requires swap-enable and blockchain-rpc
+##   light       - uploads and downloads only; requires blockchain-rpc
+##   ultra-light - free-tier downloads only; no blockchain connection needed (default)
+# node-mode: ultra-light
+
+## ── Blockchain / RPC (required for full and light nodes) ─────────────────────
 ## blockchain rpc configuration
 # blockchain-rpc:
 #   endpoint: ""
 #   dial-timeout: 30s
 #   tls-timeout: 10s
 #   idle-timeout: 90s
 #   keepalive: 30s
+## chain block time
+# block-time: "5"
+## block number cache sync interval in blocks
+# block-sync-interval: 10
+
+## ── Swap / chequebook (full and light nodes only) ────────────────────────────
+## enable swap
+# swap-enable: false
+## enable chequebook
+# chequebook-enable: false
+## swap factory addresses
+# swap-factory-address: ""
+## initial deposit if deploying a new chequebook
+# swap-initial-deposit: "0"
+
+## ── Full node only ────────────────────────────────────────────────────────────
+## enable storage incentives feature
+# storage-incentives-enable: false
+## reserve capacity doubling
+# reserve-capacity-doubling: 0
+## minimum radius storage threshold
+# minimum-storage-radius: "0"
+## neighborhood to target in binary format (ex: 111111001) for mining the initial overlay
+# target-neighborhood: ""
+## suggester for target neighborhood
+# neighborhood-suggester: https://api.swarmscan.io/v1/network/neighborhoods/suggestion
+## redistribution contract address
+# redistribution-address: ""
+## staking contract address
+# staking-address: ""
+
+## ── Network ───────────────────────────────────────────────────────────────────
+## triggers connect to main net bootnodes
+# mainnet: true
+## ID of the Swarm network
+# network-id: "1"
 ## initial nodes to connect to
 # bootnode: ["/dnsaddr/mainnet.ethswarm.org"]
 ## cause the node to always accept incoming connections
 # bootnode-mode: false
-## cache capacity in chunks, multiply by 4096 to get approximate capacity in bytes
-# cache-capacity: "1000000"
-## enable forwarded content caching
-# cache-retrieval: true
-## enable chequebook
-# chequebook-enable: true
-## config file (default is $HOME/.bee.yaml)
-config: "/etc/bee/bee.yaml"
+## protect nodes from getting kicked out on bootnode
+# static-nodes: []
+## P2P listen address
+# p2p-addr: :1634
+## enable P2P WebSocket transport
+# p2p-ws-enable: false
+## enable wss p2p connections
+# p2p-wss-enable: false
+## wss address
+# p2p-wss-addr: :1635
+## NAT exposed address
+# nat-addr: ""
+## WSS NAT exposed address
+# nat-wss-addr: ""
+## autotls domain
+# autotls-domain: ""
+## autotls registration endpoint
+# autotls-registration-endpoint: ""
+## autotls ca endpoint
+# autotls-ca-endpoint: ""
+## allow to advertise private CIDRs to the public network
+# allow-private-cidrs: false
+
+## ── HTTP API ──────────────────────────────────────────────────────────────────
+## HTTP API listen address
+# api-addr: 127.0.0.1:1633
 ## origins with CORS headers enabled
 # cors-allowed-origins: []
+
+## ── Storage ───────────────────────────────────────────────────────────────────
 ## data directory
 data-dir: "/var/lib/bee"
+## cache capacity in chunks, multiply by 4096 to get approximate capacity in bytes
+# cache-capacity: "1000000"
+## enable forwarded content caching
+# cache-retrieval: true
+## postage stamp contract address
+# postage-stamp-address: ""
+## postage stamp contract start block number
+# postage-stamp-start-block: "0"
+## skip postage snapshot
+# skip-postage-snapshot: false
+## forces the node to resync postage contract data
+# resync: false
+## ENS compatible API endpoint for a TLD and with contract address, can be repeated, format [tld:][contract-addr@]url
+# resolver-options: []
+## price oracle contract address
+# price-oracle-address: ""
+
+## ── Database ──────────────────────────────────────────────────────────────────
 ## size of block cache of the database in bytes
 # db-block-cache-capacity: "33554432"
 ## disables db compactions triggered by seeks
@@ -39,72 +113,36 @@ data-dir: "/var/lib/bee"
 # db-open-files-limit: "200"
 ## size of the database write buffer in bytes
 # db-write-buffer-size: "33554432"
-## cause the node to start in full mode
-# full-node: false
-## help for printconfig
-# help: false
-## triggers connect to main net bootnodes.
-# mainnet: true
+## lru memory caching capacity in number of statestore entries
+# statestore-cache-capacity: "100000"
+
+## ── Payments ──────────────────────────────────────────────────────────────────
+## threshold in BZZ where you expect to get paid from your peers
+# payment-threshold: "13500000"
+## percentage below the peers payment threshold when we initiate settlement
+# payment-early-percent: 50
+## excess debt above payment threshold in percentages where you disconnect from your peer
+# payment-tolerance-percent: 25
 ## minimum gas tip cap in wei for transactions, 0 means use suggested gas tip cap
 # minimum-gas-tip-cap: 0
-## minimum radius storage threshold
-# minimum-storage-radius: "0"
-## NAT exposed address
-# nat-addr: ""
-## suggester for target neighborhood
-# neighborhood-suggester: https://api.swarmscan.io/v1/network/neighborhoods/suggestion
-## ID of the Swarm network
-# network-id: "1"
-## P2P listen address
-# p2p-addr: :1634
-## enable P2P WebSocket transport
-# p2p-ws-enable: false
+## gas limit fallback when estimation fails for contract transactions (default 500000)
+# gas-limit-fallback: 500000
+## skips the gas estimate step for contract transactions
+# transaction-debug-mode: false
+## withdrawal target addresses
+# withdrawal-addresses-whitelist: []
+
+## ── Keys / identity ───────────────────────────────────────────────────────────
+## config file (default is $HOME/.bee.yaml)
+config: "/etc/bee/bee.yaml"
 ## password for decrypting keys
 # password: ""
 ## path to a file that contains password for decrypting keys
 password-file: "/var/lib/bee/password"
-## percentage below the peers payment threshold when we initiate settlement
-# payment-early-percent: 50
-## threshold in BZZ where you expect to get paid from your peers
-# payment-threshold: "13500000"
-## excess debt above payment threshold in percentages where you disconnect from your peer
-# payment-tolerance-percent: 25
-## postage stamp contract address
-# postage-stamp-address: ""
-## postage stamp contract start block number
-# postage-stamp-start-block: "0"
-## enable pprof mutex profile
-# pprof-mutex: false
-## enable pprof block profile
-# pprof-profile: false
-## price oracle contract address
-# price-oracle-address: ""
-## redistribution contract address
-# redistribution-address: ""
-## reserve capacity doubling
-# reserve-capacity-doubling: 0
-## ENS compatible API endpoint for a TLD and with contract address, can be repeated, format [tld:][contract-addr@]url
-# resolver-options: []
-## forces the node to resync postage contract data
-# resync: false
-## skip postage snapshot
-# skip-postage-snapshot: false
-## staking contract address
-# staking-address: ""
-## lru memory caching capacity in number of statestore entries
-# statestore-cache-capacity: "100000"
-## protect nodes from getting kicked out on bootnode
-# static-nodes: []
-## enable storage incentives feature
-# storage-incentives-enable: true
-## enable swap
-# swap-enable: false
-## swap factory addresses
-# swap-factory-address: ""
-## initial deposit if deploying a new chequebook
-# swap-initial-deposit: "0"
-## neighborhood to target in binary format (ex: 111111001) for mining the initial overlay
-# target-neighborhood: ""
+
+## ── Logging / tracing ─────────────────────────────────────────────────────────
+## log verbosity level 0=silent, 1=error, 2=warn, 3=info, 4=debug, 5=trace
+# verbosity: info
 ## enable tracing
 # tracing-enable: false
 ## endpoint to send tracing data
@@ -115,27 +153,13 @@ password-file: "/var/lib/bee/password"
 # tracing-port: ""
 ## service name identifier for tracing
 # tracing-service-name: bee
-## gas limit fallback when estimation fails for contract transactions (default 500000)
-# gas-limit-fallback: 500000
-## skips the gas estimate step for contract transactions
-# transaction-debug-mode: false
-## log verbosity level 0=silent, 1=error, 2=warn, 3=info, 4=debug, 5=trace
-# verbosity: info
+## enable pprof mutex profile
+# pprof-mutex: false
+## enable pprof block profile
+# pprof-profile: false
+
+## ── Miscellaneous ─────────────────────────────────────────────────────────────
 ## maximum node warmup duration; proceeds when stable or after this time
 # warmup-time: 5m0s
 ## send a welcome message string during handshakes
 # welcome-message: ""
-## withdrawal target addresses
-# withdrawal-addresses-whitelist: []
-## enable wss p2p connections (default: false)
-# p2p-wss-enable: false
-## wss address (default: :1635)
-# p2p-wss-addr: :1635
-## WSS NAT exposed address
-# nat-wss-addr: ""
-## autotls domain (default: libp2p.direct)
-# autotls-domain: ""
-## autotls registration endpoint (default: https://registration.libp2p.direct)
-# autotls-registration-endpoint: ""
-## autotls ca endpoint (default: https://acme-v02.api.letsencrypt.org/directory)
-# autotls-ca-endpoint: ""