refactor: node mode two regimes - #5596
Open
martinconic wants to merge 15 commits into
Open
Conversation
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.
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.
Split resolveNodeMode into a legacy regime (node-mode unset) that reproduces the behaviour of releases before node-mode existed, and a mode-owned regime (node-mode set) where the mode supplies defaults for swap-enable, chequebook-enable and storage-incentives-enable. Legacy regime: restore the former true defaults of chequebook-enable and storage-incentives-enable when unset, infer the mode from full-node and blockchain-rpc-endpoint as before, apply no new validation, and log a deprecation warning naming the inferred mode and the removal release. This fixes upgraded configs that were broken in both directions: a light node with swap-enable only silently lost cheque settlement, and a config carrying the old chequebook-enable default without swap, or a bootnode with storage-incentives-enable false, refused to start. Mode-owned regime: full implies swap, chequebook and incentives unless explicitly disabled (bootnodes exempt, NewBee never starts them there), light and full require blockchain-rpc-endpoint, and options a mode cannot support are rejected only when explicitly enabled. node-mode=full is now sufficient on its own; validateFullMode and the full-node restore loop are removed. The node-mode flag default becomes empty so an unset value selects the legacy regime without relying on viper's IsSet semantics for pflag defaults. Tests cover both regimes, including a run against the real bound start flags.
… defaults Add BEE_NODE_MODE to the docker-compose environment passthrough and the env template, mark BEE_FULL_NODE deprecated, and correct the stale true defaults documented for BEE_CHEQUEBOOK_ENABLE and BEE_STORAGE_INCENTIVES_ENABLE. Document in the bee.yaml variants that full mode implies the swap, chequebook and incentives options and that an unset node-mode falls back to deprecated inference.
martinconic
changed the title
martinconic
marked this pull request as ready for review
September 3, 2026 13:02
sbackend123
approved these changes
Sep 3, 2026
| } | ||
| } | ||
| modeStr := c.config.GetString(optionNameNodeMode) | ||
| if modeStr == "" { |
Contributor
There was a problem hiding this comment.
Seems, this differs from the documented distinction based on whether node-mode is set. Should we use IsSet to distinguish an omitted value from an explicitly empty one?
| # BEE_CACHE_RETRIEVAL=true | ||
| ## enable chequebook (default true) | ||
| # BEE_CHEQUEBOOK_ENABLE=true | ||
| ## enable chequebook; requires swap; implied by BEE_NODE_MODE=full (default false) |
Contributor
There was a problem hiding this comment.
When BEE_NODE_MODE is unset, the legacy resolver restores chequebook-enable to true. Could we clarify that false applies only when BEE_NODE_MODE is explicitly set?
martinconic
changed the base branch from
refactor/node-mode-config
to
master
September 4, 2026 12:11
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Checklist
Description
Follow-up to #5431, addressing the upgrade-path review from @gacevicljubisa. Stacked on
refactor/node-mode-config.The legacy branch in
resolveNodeModeapplied some of the new semantics (strict validation, swap forced on) but not all (no defaults restored for light nodes), so existing configs broke in both directions. This PR replaces it with two regimes selected by one switch: whethernode-modeis set.node-modeunset (legacy): behaves exactly as releases beforenode-modeexisted.chequebook-enableandstorage-incentives-enablefall back to their former default oftruewhen not set. Both remain gated inNewBee(chequebook on swap, incentives on full mode), so nothing starts that the previous release would not have started.full-node: truegives full, otherwise an RPC endpoint gives light, otherwise ultra-light.v2.11.0, a constant instart.go).node-modeset: the mode owns the config.fullrequires an RPC endpoint and impliesswap-enable,chequebook-enableandstorage-incentives-enableunless explicitly disabled. An explicit opt-out is honoured and logged as a warning. Bootnodes are exempt from the implied options becauseNewBeenever starts swap, push-sync or the incentives agent for them.lightrequires an RPC endpoint. Swap and chequebook stay off unless set.storage-incentives-enable: trueis rejected.ultra-lightrejectsswap-enable: trueandstorage-incentives-enable: true. An RPC endpoint is ignored.chequebook-enable: truewithswap-enable: falseis rejected in every mode. Implied values never produce this combination, so it is always an explicit contradiction.node-mode: fullis now sufficient on its own.validateFullModeand the--full-noderestore loop are gone.The
node-modeflag default is now empty instead ofultra-light, so an unset value selects the legacy regime without relying on viper'sIsSetsemantics for pflag defaults, and--helpno longer shows a default that does not describe what happens.Packaging:
BEE_NODE_MODEadded to the docker-compose passthrough and the env template,BEE_FULL_NODEmarked deprecated, staletruedefaults forBEE_CHEQUEBOOK_ENABLEandBEE_STORAGE_INCENTIVES_ENABLEcorrected, bee.yaml variants document the implied options and the deprecated inference.Behaviour matrix
swap-enable: true, nothing elsechequebook-enable: true, swap unsetfull-node: true+bootnode-mode: true+ incentives falsefull-node: true+ RPC onlyfull-node: true, no RPCnode-mode: full+ RPC onlynode-mode: full+storage-incentives-enable: falsenode-mode: full+swap-enable: falsenode-mode: full+bootnode-mode: true+ RPCnode-mode: light+ RPCnode-mode: light+chequebook-enable: true, swap unsetnode-mode: ultra-light+swap-enable: truenode-mode: full, no RPCTest plan
TestResolveNodeModecovers every row above throughviper.New().TestResolveNodeModeWithBoundFlagsruns the resolver against the real boundstartflags, so the emptynode-modedefault selects the legacy regime and the sub-option flag defaults do not count as set.make lint(0 issues),go vet, fullgo test ./...pass.dist/bee startagainst an unreachable RPC endpoint (reaching chain init proves resolution passed):v2.11.0chequebook-enable: truewithout swap: starts as ultra-light (was a hard exit)swap-enable: true: light, chequebook restored, reaches chain initfull-node+bootnode-mode+storage-incentives-enable: false: full, reaches chain init (was a hard exit)full-nodewithout RPC: clear errornode-mode: full+ RPC only: swap, chequebook, incentives implied (debug log), reaches chain initnode-mode: full+storage-incentives-enable: false: opt-out honoured with a warningnode-mode: fullwithout RPC,light+ chequebook without swap,ultra-light+ swap: rejected with clear errorslocal.yamlstill usesfull-node; it keeps working via the legacy regime and migrates tonode-modein a follow-up beekeeper PR.AI Disclosure