feat(p2p): support inbound-only peers without underlay addresses by gacevicljubisa · Pull Request #5326 · ethersphere/bee

gacevicljubisa · 2026-01-22T15:35:55Z

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

Allow peers without dialable underlay addresses (e.g., browsers, WebRTC
clients, NAT-restricted nodes) to establish connections and use protocols
over existing streams.

Changes:

Remove empty underlay validation in bzz.ParseAddress and MarshalJSON
Skip addressbook persistence for peers with empty underlays
Add nil check in notifyReacherConnected to prevent reacher crashes
Rename peerRegistry.underlays to overlayToPeerID for clarity

Inbound-only peers can participate in protocols (pricing, retrieval, pss)
but are excluded from Kademlia topology and hive gossip since they cannot
be dialed back.

Open API Spec Version Changes (if applicable)

Motivation and Context (Optional)

Related Issue (Optional)

Screenshots (if appropriate):

janos

Very nice, maybe just to add some tests for behaviour changes.

janos · 2026-01-22T20:40:16Z

Also, do not add peer without underlays to the addressbook in hive here https://github.com/ethersphere/bee/blob/master/pkg/hive/hive.go#L314.

gacevicljubisa · 2026-01-23T08:35:48Z

Also, do not add peer without underlays to the addressbook in hive here https://github.com/ethersphere/bee/blob/master/pkg/hive/hive.go#L314.

They are skipped here

bee/pkg/hive/hive.go

Lines 288 to 291 in 706fe4c

    
           if len(multiUnderlays) == 0 { 
        
           	s.logger.Debug("check and add peers, no underlays", "overlay", swarm.NewAddress(p.Overlay).String()) 
        
           	continue // no underlays sent 
        
           }

akrem-chabchoub · 2026-01-23T14:15:08Z

pkg/p2p/libp2p/libp2p_test.go

+	// If emptyUnderlays is set, use a custom host factory that creates a host with no listen addresses
+	// This simulates an inbound-only peer (browser, WebRTC connection, strict NAT)
+	if o.emptyUnderlays {
+		opts = libp2p.WithHostFactory(


This overwrites opts, losing any previously set fields like FullNode from o.libp2pOpts.
I think we should append to previous opts ?

Yes, this makes emptyUnderlays option coupled with libp2pOpts in a not transparent way.

It is a problem with WithHostFactory function that, just returns the new libp2p.Options instead just to set the unexported field internally. This is just not practical, or composable.

I suggest to add in export_test.go:

func SetHostFactory(o *Options, factory func(...libp2pm.Option) (host.Host, error)) { o.hostFactory = factory }

as more flexible alternative. WithHostFactory is not even named clearly, its name does not suggest that it is (one of) a constructor of the Options type.

akrem-chabchoub · 2026-01-23T17:35:10Z

pkg/p2p/libp2p/connections_test.go

+		expectPeers(t, s2, overlay1)
+		expectPeersEventually(t, s1, overlay2)
+
+		// Verify s1 (has underlays) is persisted in s2's addressbook


I think we should add this test case:
s2 should not be saved in s1's addressbook

…ests

lat-murmeldjur · 2026-01-27T16:11:17Z

I'm not sure this is necessary. From browser connecting to testnet wss addresses is already possible. The browser node also has an (ephemeral) underlay.

v1rtl · 2026-01-27T22:14:46Z

Without this Bee in browser fails to maintain connections. It is really necessary. I dont see any drawback to not support inbound-only peers

gacevicljubisa · 2026-01-28T08:24:22Z

I'm not sure this is necessary. From browser connecting to testnet wss addresses is already possible. The browser node also has an (ephemeral) underlay.

@lat-murmeldjur Can you provide more details about ephemeral underlay?

lat-murmeldjur · 2026-01-28T11:17:37Z

I'm not sure this is necessary. From browser connecting to testnet wss addresses is already possible. The browser node also has an (ephemeral) underlay.

@lat-murmeldjur Can you provide more details about ephemeral underlay?

Yes.
If you go to the weeb-3 client here: https://lat-murmeldjur.github.io/weeb-3/
In the logs at the bottom of the page you can see lines like
Observed address /ip4/37.76.0.186/tcp/28943/wss for peer QmfSx1ujzboapD5h2CiqTJqUy46FeTDwXBszB3XUCfKEEj stored/overwritten

This is our ephemeral underlay in the browser, observed by the bee node, and sent back to the browser in the libp2p-identify protocol.

The reason why getting it through this libp2p-protocol was necessary, is because connecting to a tls/ws address broke 1 thing:
In the handshake, we no longer get back our observed underlay field filled out by the bee node. I suspect that could have been the reason for v1rtl requiring this PR as well. So without observed underlay being signed after handshake i got disconnected immediately. Now that i read it from the libp2p-identify, wait for it (after dial, before handshake) and then use it for the handshake it completes and I can upload and download after that.

gacevicljubisa · 2026-01-29T11:03:56Z

Without this Bee in browser fails to maintain connections. It is really necessary. I dont see any drawback to not support inbound-only peers

As I understand, with this PR, the browser client doesn't need the workaround of reading the observed underlay from libp2p-identify before the handshake. The handshake now accepts empty underlays, so the browser can complete the handshake immediately without waiting for the observed address.

lat-murmeldjur · 2026-01-29T14:15:46Z

Without this Bee in browser fails to maintain connections. It is really necessary. I dont see any drawback to not support inbound-only peers

As I understand, with this PR, the browser client doesn't need the workaround of reading the observed underlay from libp2p-identify before the handshake. The handshake now accepts empty underlays, so the browser can complete the handshake immediately without waiting for the observed address.

It's okay I'm not objecting to this change just wanted to make it clear that strictly speaking you don't need this to make connections work.

…-support

gacevicljubisa · 2026-02-04T14:25:21Z

With introducing the RemoteMultiaddr this PR is no longer required.

mfw78 · 2026-02-18T12:31:56Z

@gacevicljubisa I'll comment here, so that we don't pollute the other PR.

The problem IMO that needs to be resolved is that a solution should not require some multiaddr. Sure, it's nice to send an observed multiaddr from the connectee back to the connector, however for NAT-bound peers connecting out, it has no relevance (it does let them know that they are connected to a globally routable network, albeit via NAT, but the success of a connection is enough in and of itself to satisfy this). Subsequently, the address was being added to the peer store, which is suitable for the connectee, but pointless from a hive perspective.

It seems odd to be signing a multiaddr, simply just trusting it, in order to satisfy the handshake, and actual fact, why can't the ack have a bzz address with no signed multiaddr in it (ie. the signature is over an empty Vec). Examples of where this is particularly painful is that with the introduction of the peer store waiting, this essentially causes all light clients behind NAT to get blocked for 10s on connection.

bcsorvasi · 2026-02-24T10:48:38Z

Hi @mfw78,

Thanks for taking the time to lay this out and explain your concerns.

To make sure this gets the proper visibility and structured discussion it deserves, could you please open a dedicated issue in the repository outlining:

The core problem as you see it
The specific pain points (e.g. NAT-bound peers, light client blocking, etc.)
The proposed alternative approach

We’d like our research team to review this in more depth and evaluate whether this requirement should exist in its current form, as well as the protocol-level implications of changing it.

Opening an issue will help us track the discussion properly without losing context in the PR thread.

Appreciate the thoughtful feedback!

feat(p2p): support inbound-only peers without underlay addresses

706fe4c

janos reviewed Jan 22, 2026

View reviewed changes

test(p2p): add tests for empty underlays

7c3bc02

gacevicljubisa marked this pull request as ready for review January 23, 2026 10:29

gacevicljubisa requested review from acud, akrem-chabchoub, janos and martinconic January 23, 2026 13:03

test(p2p): fix addressbook persistence test

b39629d

akrem-chabchoub reviewed Jan 23, 2026

View reviewed changes

test(p2p): fix host factory option handling and enhance addressbook t…

62e5c1c

…ests

gacevicljubisa requested a review from akrem-chabchoub January 23, 2026 18:22

janos approved these changes Jan 23, 2026

View reviewed changes

akrem-chabchoub approved these changes Jan 23, 2026

View reviewed changes

fix(p2p): revert changes not related to PR

26e563a

gacevicljubisa closed this Jan 30, 2026

gacevicljubisa reopened this Jan 30, 2026

gacevicljubisa added 2 commits January 30, 2026 17:10

fix(p2p): prevent race condition in unit tests

fa87414

Merge remote-tracking branch 'origin/master' into feat/empty-underlay…

953ec44

…-support

gacevicljubisa closed this Feb 4, 2026

gacevicljubisa deleted the feat/empty-underlay-support branch February 17, 2026 20:46

gacevicljubisa mentioned this pull request Feb 18, 2026

fix(p2p): skip addressbook and reacher for unreachable addresses #5370

Merged

4 tasks

gacevicljubisa restored the feat/empty-underlay-support branch February 18, 2026 11:24

Conversation

gacevicljubisa commented Jan 22, 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):

Uh oh!

janos left a comment

Choose a reason for hiding this comment

Uh oh!

janos commented Jan 22, 2026

Uh oh!

gacevicljubisa commented Jan 23, 2026

Uh oh!

akrem-chabchoub Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

janos Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

akrem-chabchoub Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

lat-murmeldjur commented Jan 27, 2026

Uh oh!

v1rtl commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

lat-murmeldjur commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gacevicljubisa commented Jan 29, 2026

Uh oh!

lat-murmeldjur commented Jan 29, 2026

Uh oh!

gacevicljubisa commented Feb 4, 2026

Uh oh!

mfw78 commented Feb 18, 2026

Uh oh!

bcsorvasi commented Feb 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

gacevicljubisa commented Jan 22, 2026 •

edited

Loading

v1rtl commented Jan 27, 2026 •

edited

Loading

gacevicljubisa commented Jan 28, 2026 •

edited

Loading

lat-murmeldjur commented Jan 28, 2026 •

edited

Loading