chore: remove backwards compatibility with 2.6.0 by sbackend123 · Pull Request #5415 · ethersphere/bee

sbackend123 · 2026-03-30T08:56:33Z

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

Breaking changes

Removes Bee 2.6.0 backward-compatibility code and the legacy single-multiaddr underlay wire encoding. Minimum supported Bee version on the network is 2.7.0; nodes on 2.6.0 or earlier will fail to complete a handshake with this build.

Underlay wire format
The 0x99 list prefix (underlayListPrefix) is kept. The only supported encoding is now always the prefixed list format, including for a single address or an empty list:

[0x99][varint_len_1][addr_1_bytes][varint_len_2][addr_2_bytes]...

Changes in detail:

Removed the legacy path where a single underlay was serialized as raw multiaddr bytes (without the 0x99 prefix).
Even a peer with one underlay is encoded as a one-entry prefixed list.
An empty underlay list serializes to [0x99] and deserializes to an empty slice.
DeserializeUnderlays rejects payloads that do not start with 0x99 (including legacy raw single-multiaddr bytes from Bee 2.6.0).
ParseAddress still rejects addresses with zero underlays after deserialization.

Removed 2.6.0 compatibility shims

WithBee260Compatibility handshake option
FilterBee260CompatibleUnderlays / Bee260CompatibilityStreamer / IsBee260
User-agent–based Bee 2.6.0 detection in libp2p peer registry

Database migrations

Legacy migration step implementations are removed; version indices are retained as NOOPs so existing data directories can still migrate safely (ValidateVersions requires contiguous version numbers). Comments document why these slots must not be removed or renumbered.

Also removes unused legacy helpers (olditems, oldstampindex, obsolete storer migration step files, etc.).

Open API Spec Version Changes (if applicable)

Motivation and Context (Optional)

Related Issue (Optional)

#5340

Screenshots (if appropriate):

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.

acud · 2026-03-31T07:32:00Z

@sbackend123 I think that removing all migration code might be a bit too eager - can you make sure that the migration code covers the currently active bee node version still showing up in swarmscan?

janos · 2026-03-31T09:32:33Z

@sbackend123 I think that removing all migration code might be a bit too eager - can you make sure that the migration code covers the currently active bee node version still showing up in swarmscan?

I agree, as there are still 2.6 nodes (not many, but still ~6%), it is early to release bee without compatibility.

This code is intended to be temporary. It is a good effort, but I would suggest to hold on merging, for some time.

sbackend123 · 2026-03-31T22:31:00Z

@sbackend123 I think that removing all migration code might be a bit too eager - can you make sure that the migration code covers the currently active bee node version still showing up in swarmscan?

I ran the previous bee version (v2.6.0) locally, let it sync to current block height on maiinet and build a real data directory. Then I started this build on the same data directory without clearing it. The node started successfully with no migration errors.

I also ran earlier versions trying to sync with mainnet, but get error connect new stream: incompatible stream: failed to negotiate protocol: protocols not supported.

acud · 2026-04-01T04:30:53Z

@sbackend123 I think that removing all migration code might be a bit too eager - can you make sure that the migration code covers the currently active bee node version still showing up in swarmscan?

I ran the previous bee version (v2.6.0) locally, let it sync to current block height on maiinet and build a real data directory. Then I started this build on the same data directory without clearing it. The node started successfully with no migration errors.

I also ran earlier versions trying to sync with mainnet, but get error connect new stream: incompatible stream: failed to negotiate protocol: protocols not supported.

I suppose it does not error the migrations because there's nothing to do in the migrations in the current build. I am not 100% sure about the reasoning behind the necessity of those migrations. But we should definitely leave in place the migration code to support the migration path from the node version still running on the network (2.6.0 definitely). The older ones we can mark as nops.

…h 2.7.0 version

mfw78 · 2026-04-02T08:23:14Z

I agree, as there are still 2.6 nodes (not many, but still ~6%), it is early to release bee without compatibility.

Those 2.6.0 nodes are on some dirty tag mostly, so it's on them. They are running custom code - we shouldn't be persisting with cruft in the protocol because someone doesn't update their modifications.

acud · 2026-04-06T11:26:45Z

@sbackend123 this needs a rebase

acud

there's a whole chunk of changes that are in pkg/storer/migration/all_steps.go that is completely not touched but the code can probably also be removed. as for the individual migration steps which are not in use already - there's no need of keeping the files with empty functions that do nothing - those can be removed.

acud · 2026-04-15T05:50:33Z

+
+func firstByteString(data []byte) string {
+	if len(data) == 0 {
+		return "none"


maybe just ""?

acud · 2026-04-15T05:55:32Z

+// step_02 was a migration step that migrated the cache to a new format.
+// It is now a NOOP since all nodes have already run this migration,
+// and new nodes start with an empty database.
+func step_02(_ transaction.Storage) func() error {


if this is not used anywhere - why do we need to keep the file?

…2.6.0 # Conflicts: # pkg/p2p/libp2p/version_test.go # pkg/statestore/storeadapter/migration.go # pkg/storer/internal/reserve/olditems.go # pkg/storer/migration/refCntSize.go # pkg/storer/migration/step_02.go # pkg/storer/migration/step_04_test.go # pkg/storer/migration/step_05.go # pkg/storer/migration/step_05_test.go # pkg/storer/migration/step_06.go # pkg/storer/migration/step_06_test.go

…ility-with-2.6.0

Add test. Move db repair tool.

sbackend123 · 2026-04-22T13:24:47Z

there's a whole chunk of changes that are in pkg/storer/migration/all_steps.go that is completely not touched but the code can probably also be removed. as for the individual migration steps which are not in use already - there's no need of keeping the files with empty functions that do nothing - those can be removed.

If I understand everything correctly, we can't remove it completely because of our migration mechanism.
Existing upgraded nodes may appear fine, but new installations would be broken, because ValidateVersions checks versions are without gaps (added unit test for that) and when we have currentVersion=0 and then next one 8 -> fail.

akrem-chabchoub · 2026-04-28T11:43:55Z


 func (a *Address) UnmarshalJSON(b []byte) error {
 	v := &addressJSON{}
 	err := json.Unmarshal(b, v)


Nice work @sbackend123.

I just have a concern here, what will happen for the 2.6.0 nodes here ? because I see you removed Underlay field from addressJSON, I know this is not needed anymore, but in the Unmarshal the node will have the Underlays filed empty.

Maybe we can keep it in addressJSON (just to for the Unmarshal) and we get that Underlay addr and set it to Underlays slice
Right or maybe I'm missing some parts ?

This is main point, we remove compatibility with 2.6.0 so minimal supported version would be 2.7.0. So we force everybody update their versions

Yes, I know.
I’m just thinking out loud, if I were a node operator on 2.6.0 or earlier, I might suddenly get disconnected without really understanding why. That could be a bit confusing.
But as @janos mentioned, those nodes are only around 6%, so the impact seems pretty small.

acud · 2026-04-28T13:59:01Z

+		5: noop,
+		6: noop,
+		7: noop,
+		8: noop,


like in the other migrations comment - the sequence and indexes of these migrations should be commented such that they aren't removed in the future

acud

LGTM but will need a squash + rebase after the upcoming release

…2.6.0 # Conflicts: # pkg/bzz/address.go # pkg/bzz/address_test.go # pkg/bzz/export_test.go # pkg/bzz/underlay.go # pkg/bzz/underlay_test.go # pkg/hive/hive.go # pkg/p2p/libp2p/internal/handshake/handshake.go # pkg/p2p/libp2p/libp2p.go # pkg/statestore/storeadapter/migration.go

acud · 2026-06-01T16:03:55Z

@sbackend123 linter failing

gacevicljubisa · 2026-06-05T07:12:53Z

@sbackend123 can you update the PR description?

acud · 2026-06-05T17:00:54Z

-
-	// For 0 or 2+ addresses, the custom list format with the prefix is used.
-	// The format is: [prefix_byte][varint_len_1][addr_1_bytes]...
+	// The format is: [varint_len_1][addr_1_bytes]...


missing the prefix byte here. see comment on the left

acud · 2026-06-05T17:02:54Z

-	}
-	// The result is returned as a single-element slice for a consistent return type.
-	return []multiaddr.Multiaddr{addr}, nil
+	return deserializeList(data)


this doesn't seem right. with this change, the underlay should always start with the prefix byte. the if block above should check whether the first byte is not a prefix byte and throw if that is the case, then just deserialize like in the current if statement below (happy path not nested).
also some input length validation is needed since the deserialize call can panic on a short buffer (pass just 0x99 as the underlay)

Fixed: in case if array of underlays contains only 0x99 prefix, decerialize will not panic, it just returns prefix (behavior unchanged)

acud · 2026-06-05T17:05:57Z


 	observedUnderlays, err := bzz.DeserializeUnderlays(resp.Syn.ObservedUnderlay)
 	if err != nil {
+		s.logger.Debug("handshake invalid synack observed underlay payload", "payload_len", len(resp.Syn.ObservedUnderlay), "first_byte", firstByteString(resp.Syn.ObservedUnderlay), "payload_prefix", payloadPrefix(resp.Syn.ObservedUnderlay), "error", err)


lots of stuff in this log line... not sure if it will be just swallowed in the rest of the logs. maybe just better to instrument the error with a tiny bit of information of what went wrong (not all the fields here). the same for the other logline

acud · 2026-06-05T17:07:07Z

+	return fmt.Sprintf("0x%02x", data[0])
+}
+
+func payloadPrefix(data []byte) string {


not sure i understand why this is needed... maybe some info about why and how to use this... also why is n=16?

acud · 2026-06-05T17:08:42Z

+	if len(data) < n {
+		n = len(data)
+	}
+	return fmt.Sprintf("%x", data[:n])


you can just fmt.Sprintf("%x",data[:min(16,len(data))])

acud

last one...

acud · 2026-06-08T13:06:50Z

+	if len(payload) == 0 {
+		return fmt.Errorf("%w: observed underlay (len=0): %w", ErrInvalidSyn, err)
+	}
+	return fmt.Errorf("%w: observed underlay (len=%d, first=0x%02x): %w", ErrInvalidSyn, len(payload), payload[0], err)


why do we need conditional error formatting? this appears to be needed just so you have a sneak peek into the first byte (not sure what is the added value of this in production). i would suggest to get rid of this helper and just stringify the payload in the error formatting (one format). the 0x99 ascii character is the trademark sign so you would be able to see it in the logs correctly (if ever needed)

sbackend123 added 3 commits March 26, 2026 00:09

chore: remove legacy code

eebec22

chore: remove legacy code for underlay addresses

af6c38e

chore: noop old migrations and remove legacy underlay test

71d07fd

chore: remove underlayListPrefix prefix

2ee43af

sbackend123 requested review from akrem-chabchoub, gacevicljubisa and janos and removed request for akrem-chabchoub, gacevicljubisa and janos March 31, 2026 09:15

fix: restore underlay prefix and tests for backward compatibility wit…

68613ec

…h 2.7.0 version

gacevicljubisa linked an issue Apr 9, 2026 that may be closed by this pull request

Remove backwards compatibility code to clean up codebase #5340

Open

9 tasks

acud requested changes Apr 15, 2026

View reviewed changes

sbackend123 added 4 commits April 22, 2026 12:42

Merge branch 'refs/heads/master' into chore/remove-backwards-compatib…

fff123b

…ility-with-2.6.0

fix: remove empty files

8a068fc

Add test. Move db repair tool.

fix: remove legacy migrations files

70022f4

sbackend123 added 4 commits April 22, 2026 16:57

fix: fix broken merge

5ac22ee

fix: remove unnecessary changes

1e92169

fix: revert unnecessary changes

c9674df

fix: revert unnecessary changes 3

4758020

fix: clean up

e0ce20d

sbackend123 requested a review from acud April 28, 2026 09:08

sbackend123 marked this pull request as ready for review April 28, 2026 09:08

sbackend123 requested review from akrem-chabchoub and janos April 28, 2026 09:09

akrem-chabchoub reviewed Apr 28, 2026

View reviewed changes

acud reviewed Apr 28, 2026

View reviewed changes

sbackend123 added 2 commits April 30, 2026 12:39

fix: remove single underlay address complitely

7adc040

fix: added comment

90459ba

sbackend123 requested review from acud and akrem-chabchoub April 30, 2026 11:20

fix: cleanup

2a663ab

akrem-chabchoub approved these changes May 25, 2026

View reviewed changes

acud approved these changes May 26, 2026

View reviewed changes

sbackend123 added 3 commits June 1, 2026 12:42

fix: merge with master and fix merge

5480ccf

fix: fix unit tests

e5995f7

sbackend123 added 2 commits June 2, 2026 22:22

fix: linter error, tests, bump handshake

1efe078

fix: revert removing underlayPrefix

0a76467

acud requested changes Jun 5, 2026

View reviewed changes

sbackend123 added 2 commits June 8, 2026 01:35

fix: review fixes

75003bb

fix: linter

503921c

acud requested changes Jun 8, 2026

View reviewed changes

fix: error fix

154bbeb

sbackend123 requested a review from acud June 8, 2026 15:50

acud approved these changes Jun 8, 2026

View reviewed changes

sbackend123 merged commit 680e893 into master Jun 8, 2026
20 of 21 checks passed

sbackend123 deleted the chore/remove-backwards-compatibility-with-2.6.0 branch June 8, 2026 20:40

+: noop,
+: noop,
+: noop,
+: noop,

Conversation

sbackend123 commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Description

Open API Spec Version Changes (if applicable)

Motivation and Context (Optional)

Related Issue (Optional)

Screenshots (if appropriate):

AI Disclosure

Uh oh!

acud commented Mar 31, 2026

Uh oh!

janos commented Mar 31, 2026

Uh oh!

sbackend123 commented Mar 31, 2026

Uh oh!

acud commented Apr 1, 2026

Uh oh!

mfw78 commented Apr 2, 2026

Uh oh!

acud commented Apr 6, 2026

Uh oh!

acud left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sbackend123 commented Apr 22, 2026

Uh oh!

akrem-chabchoub Apr 28, 2026 • 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!

sbackend123 Apr 28, 2026 • 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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

acud left a comment

Choose a reason for hiding this comment

Uh oh!

acud commented Jun 1, 2026

Uh oh!

gacevicljubisa commented Jun 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

acud left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

sbackend123 commented Mar 30, 2026 •

edited

Loading

akrem-chabchoub Apr 28, 2026 •

edited

Loading

sbackend123 Apr 28, 2026 •

edited

Loading

gacevicljubisa commented Jun 5, 2026 •

edited

Loading