Overlay, neighborhood, proximity order

A Swarm node has an overlay address — a 32-byte identifier in the same address space as chunk references. This overlay determines where in the network the node sits, and therefore which chunks it’s responsible for storing and serving.

bee-check calls GET /addresses on every vantage and surfaces:

• overlay — the node’s full 32-byte overlay (rendered as 64 hex chars).
• neighborhood — the first byte of the overlay, by convention the unit used when discussing where a chunk “lives”.
• proximity_to_root — how close the node sits to the reference being probed (defined below).

Proximity order (PO)

Given two 32-byte values A and B, the proximity order is the number of leading bits they share. Higher = closer.

In Swarm, chunks with address X are pushed toward (and stored by) peers with high proximity to X. So a vantage with PO 8+ to the reference is in the chunk’s neighborhood; a vantage with PO 0 or PO 1 is on the other side of the network and is sampling retrieval through the network, not local storage.

Reading the per-vantage row

nb 71 PO 3

means: this node’s overlay starts with byte 0x71 (neighborhood 71), and its overlay shares 3 leading bits with the reference being probed. PO 3 is far — the node is not in the chunk’s neighborhood, so a “yes” here genuinely means the network retrieved the content for this node from elsewhere.

Per-chunk proximity

With --per-chunk, each chunk also reports per-vantage proximity to that specific chunk’s address. So a --per-chunk report can say:

chunk 1a2b… (neighborhood 1a) was missing on http://b.example (overlay c4…, PO 0 to this chunk) but found on http://a.example (overlay 1a…, PO 8 to this chunk)

That’s diagnostic gold: the chunk is only answerable by a node in its own neighborhood; the rest of the network either doesn’t know about it or can’t route to a storer.

See also

• Swarm docs — Address space and Kademlia (the Book of Swarm chapter on overlay topology)
• Bee API — GET /addresses

--target-overlay: framing the question

bee-check --target-overlay HEX re-sorts the vantages closest-first to a hypothetical target overlay and tags each with target_proximity. Use this when you’re asking “from a node near neighborhood X, is this retrievable?” — useful when you’re debugging a specific user’s experience and you know their overlay.