refactor: replace full-node flag with explicit node-mode config by martinconic · Pull Request #5431 · ethersphere/bee

martinconic · 2026-04-09T10:00:51Z

Checklist

I have read the coding guide.
My change requires a documentation update, and I have done it.
I have added tests to cover my changes.
I have filled out the description and linked the related issues.

Description

Fixes #5172. The previous approach to node mode was implicit and
inconsistent: the mode was inferred from a combination of --full-node
(bool) and whether blockchain-rpc-endpoint was non-empty, which
diverged from the documented definition of modes and allowed silent
misconfigurations.

This PR introduces a single explicit --node-mode option with three
valid values: full, light, and ultra-light.

Key changes:

NodeMode string type added to pkg/node with constants FullMode,
LightMode, UltraLightMode; replaces FullNodeMode bool in Options
--node-mode flag added; --full-node deprecated with a warning
pointing to --node-mode=full (see Backward compatibility below)

resolveNodeMode() in start.go enforces mode requirements at startup:

Mode	Requires
`full`	`blockchain-rpc-endpoint` + `swap-enable: true` + `chequebook-enable: true` + `storage-incentives-enable: true`
`light`	`blockchain-rpc-endpoint` (`swap-enable` optional; `chequebook-enable` requires `swap-enable`)
`ultra-light`	`swap-enable` must be false (`blockchain-rpc-endpoint` ignored if set)

isChainEnabled rewritten: no longer infers chain state from the RPC
endpoint string — now reads directly from NodeMode
storage-incentives-enable default corrected to false (full node only)
chequebook-enable default corrected to false (requires swap-enable)
All packaging yamls (bee.yaml, scoop, homebrew-amd64, homebrew-arm64)
restructured into labelled mode-based sections

Backward compatibility

chequebook-enable and storage-incentives-enable previously defaulted to
true, and --full-node implied them. With the corrected false defaults, an
existing --full-node config that relied on those implicit values would now
fail strict full-mode validation and the node would not start after upgrade.

To keep upgrades smooth, a legacy --full-node: true config (when node-mode
is not set) still starts: swap-enable, chequebook-enable and
storage-incentives-enable are auto-enabled for any the operator did not set
explicitly, a deprecation warning is logged for each, and the node comes up as a
fully-functional full node. This is a restoration of the previous implied
behavior — not silent degradation: the node runs full with chequebook and
incentives on, exactly as before.

The compatibility default only fills in values left unset. It does not mask
genuine misconfigurations:

explicitly setting any of those options to false while requesting a full
node still fails validation;
a full node still requires blockchain-rpc-endpoint — that cannot be
inferred;
the explicit --node-mode=full path is unaffected and remains strict (no
auto-enable), since it is the new, intentional model.

Test plan

AI Disclosure

This PR contains code that has been generated by an LLM.
I have reviewed the AI generated code thoroughly.
I possess the technical expertise to responsibly review the code generated in this PR.

martinconic · 2026-04-09T12:59:18Z

Beekeeper changes are also needed

acud · 2026-04-16T04:53:08Z

needs a rebase

akrem-chabchoub

Thanks @martinconic, Glad to see this change, It will simplify and enhance the UX 🚀

Cafe137 · 2026-04-23T09:57:26Z

What's the actual difference between swap-enable and chequebook-enable? Do we really need both?

martinconic · 2026-05-04T09:54:17Z

What's the actual difference between swap-enable and chequebook-enable? Do we really need both?

The actual semantics are:

swap-enable = "participate in the swap settlement protocol at all" (peer cheque protocol + factory + cashout).
chequebook-enable = "I have funded my own chequebook and want to pay peers with cheques."

Functionally yes, we need them both, because swap=on, chequebook=off (receive-only / cash-out-only) is a genuine state. It's useful for: a node booting before its chequebook is funded, an operator who wants to earn from serving content without depositing collateral yet, and any deferred-funding workflow.

Resolves a conflict in pkg/node/node.go where master (#5460) added a startup block-height verification guard for the postage listener, while this branch replaced the o.FullNodeMode bool with o.NodeMode == FullMode. Resolution keeps master's new guard and applies the NodeMode predicate to the subsequent batch-service start branch.

akrem-chabchoub

Just there are some git conflicts

martinconic · 2026-05-21T11:51:58Z

Just there are some git conflicts

New things were merged until my last commit, so yes, will address the merge conflicts.

Resolved packaging yaml conflicts (bee, scoop, homebrew-amd64, homebrew-arm64): kept the mode-based section layout from this branch and added the new 'use-simd-hashing' option from master. The p2p-wss, nat-wss, autotls, and withdrawal-addresses-whitelist options master appended already exist in the reorganized Network/Payments sections, so master's duplicates were dropped.

Resolve conflicts from v2.8.0 (#5477): - cmd.go: keep node-mode flag and deprecated full-node path while adding master's chequebook-verification and chequebook-min-balance flags; keep chequebook-enable default of false. - node.go: take master's chain-enabled chequebook factory init (wallet ERC20 resolution); adapt new chequebook-verification check to use NodeMode == FullMode instead of the removed FullNodeMode field. - packaging/*.yaml: keep the section-organized layout and add the new chequebook-verification option.

…config

akrem-chabchoub · 2026-08-31T12:20:31Z

+		} {
+			if !c.config.IsSet(key) {
+				logger.Warning("enabling option implied by legacy --full-node; set it explicitly or use --node-mode=full", "option", key)
+				c.config.Set(key, true)


For old users who ran a full node with swap-enable left at its default (false, never explicitly set), upgrading while still using the deprecated --full-node flag causes swap-enable,chequebook-enable and storage-incentives-enable to be silently forced to change on startup. This is only surfaced via a log, which is easy to miss maybe ?

Does this not risk misbehavior or misunderstanding for node operators ?

Prior to this PR, chequebook-enable and storage-incentives-enable actually defaulted to true. So an existing full node was already running with chequebook and incentives active.

When we corrected those defaults to false in this PR to make the new configuration explicit, an existing --full-node config that relied on the old defaults would suddenly fail startup validation after an upgrade.

The auto-enable logic in the legacy fallback doesn't introduce unexpected behavior—it restores the previous implicit full-node stack so existing nodes don't crash on upgrade, while logging clear warnings advising operators to migrate to --node-mode=full. Crucially, it only applies to options left unset; an explicit false is never overridden and still fails validation as expected.

gacevicljubisa

Requesting changes on the upgrade path. The legacy branch currently gets some of the new semantics (strict validation, swap forced on) but not all (no defaults restored for light nodes), so existing configs break in both directions:

light node with swap-enable: true, no chequebook-enable → chequebook-enable default flipped (cmd.go:363), nothing restores it, SetPayFunc never installed (node.go:1115) — starts clean, silently loses cheque settlement
any config still carrying chequebook-enable: true without swap (the old shipped default, still in packaging/docker/env) → exits at start.go:417; master silently gated this under swap (node.go:595)
bootnode with storage-incentives-enable: false → exits at start.go:472, though node.go:1295 never starts the agent for bootnodes anyway
BEE_NODE_MODE missing from the compose passthrough (docker-compose.yml:33)

None of these are in the test plan, and the tests go through a bare viper.New() so the pflag default of ultra-light (which must not count as set) is never exercised.

Proposal: two regimes, one switch.

node-mode unset → master's behavior verbatim: old defaults, old inference, no new validation. Log a deprecation warning with the equivalent node-mode: line and the release it will be removed in.
node-mode set → the mode owns the config, no sub-flags: ultra-light = no chain/swap/incentives, light = chain + swap, full = chain + swap + incentives. full-node, swap-enable, chequebook-enable, storage-incentives-enable become deprecated and warn; explicit contradictions error. The cost is a chequebook deploy on light nodes, which only needs gas (swap-initial-deposit is 0) — and a light node that buys stamps needs gas anyway.

That removes the restore loop and validateFullMode entirely (only "chain required for light/full" remains), gives a clean cutover date, and makes node-mode: full sufficient on its own — today it's rejected without three more flags.

martinconic added this to the 2026 milestone Apr 9, 2026

martinconic added enhancement enhancement of existing functionality user-experience issue affecting user experience labels Apr 9, 2026

martinconic self-assigned this Apr 9, 2026

acud approved these changes Apr 14, 2026

View reviewed changes

martinconic marked this pull request as ready for review April 14, 2026 08:02

martinconic mentioned this pull request Apr 14, 2026

refactor: replace full-node flag with explicit node-mode config ethersphere/beekeeper#580

Open

sbackend123 reviewed Apr 15, 2026

View reviewed changes

Comment thread .github/workflows/beekeeper.yml

martinconic added 2 commits April 16, 2026 12:11

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

e386677

fix: restore legacy mode detection in resolveNodeMode

b58c43a

martinconic force-pushed the refactor/node-mode-config branch from b374fd7 to b58c43a Compare April 16, 2026 09:12

akrem-chabchoub reviewed Apr 17, 2026

View reviewed changes

Comment thread cmd/bee/cmd/cmd.go

test: add table-driven tests for resolveNodeMode

9d736a0

fix: tighten node-mode validation to prevent silent upgrade regressions

7e68799

martinconic mentioned this pull request May 11, 2026

Suggest to switch bee config files with more readable versions #5219

Open

akrem-chabchoub reviewed May 21, 2026

View reviewed changes

martinconic requested review from akrem-chabchoub and sbackend123 May 26, 2026 18:56

martinconic added 2 commits May 28, 2026 13:11

fix(node-mode): keep legacy --full-node configs starting after upgrade

479c759

martinconic mentioned this pull request Jun 3, 2026

ci: disable golangci-lint cache to avoid stale-cache lint failures #5488

Merged

martinconic added 2 commits July 13, 2026 16:05

Merge remote-tracking branch 'origin/master' into refactor/node-mode-…

6a0c78e

…config

Merge remote-tracking branch 'origin/master' into refactor/node-mode-…

98be0b4

…config

test(cmd): add edge-case and precedence tests for resolveNodeMode

ebc5f4a

martinconic requested review from aloknerurkar, gacevicljubisa and janos August 27, 2026 19:44

aloknerurkar approved these changes Aug 30, 2026

View reviewed changes

Comment thread cmd/bee/cmd/start.go

akrem-chabchoub approved these changes Aug 31, 2026

View reviewed changes

fix(cmd): reject storage incentives in light and ultra-light modes

8b061de

gacevicljubisa requested changes Sep 2, 2026

View reviewed changes

martinconic mentioned this pull request Sep 3, 2026

refactor: node mode two regimes #5596

Open

12 tasks

Navigation Menu

Uh oh!

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

refactor: replace full-node flag with explicit node-mode config#5431
martinconic wants to merge 12 commits into
masterfrom
refactor/node-mode-config

martinconic commented Apr 9, 2026 •

edited

Loading

Uh oh!

martinconic commented Apr 9, 2026

Uh oh!

Uh oh!

acud commented Apr 16, 2026

Uh oh!

akrem-chabchoub left a comment

Uh oh!

Uh oh!

Cafe137 commented Apr 23, 2026

Uh oh!

martinconic commented May 4, 2026

Uh oh!

akrem-chabchoub left a comment

Uh oh!

martinconic commented May 21, 2026

Uh oh!

Uh oh!

akrem-chabchoub Aug 31, 2026

Uh oh!

martinconic Sep 2, 2026

Uh oh!

gacevicljubisa left a comment •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

Uh oh!

Conversation

martinconic commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Description

Backward compatibility

Test plan

AI Disclosure

Uh oh!

martinconic commented Apr 9, 2026

Uh oh!

Uh oh!

acud commented Apr 16, 2026

Uh oh!

akrem-chabchoub left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Cafe137 commented Apr 23, 2026

Uh oh!

martinconic commented May 4, 2026

Uh oh!

akrem-chabchoub left a comment

Choose a reason for hiding this comment

Uh oh!

martinconic commented May 21, 2026

Uh oh!

Uh oh!

akrem-chabchoub Aug 31, 2026

Choose a reason for hiding this comment

Uh oh!

martinconic Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

gacevicljubisa left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

martinconic commented Apr 9, 2026 •

edited

Loading

gacevicljubisa left a comment •

edited

Loading