# 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)

![Proximity order diagram](./images/proximity.svg)

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

| PO | Leading bits matching |
|----|-----------------------|
| 0  | none — they differ at the very first bit |
| 4  | first 4 bits (i.e. first hex nibble) match |
| 8  | first byte matches — same neighborhood |
| 16 | first two bytes match |
| 32 | first 4 bytes match — very close |
| 256 | identical |

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](https://docs.ethswarm.org/docs/concepts/the-book-of-swarm) (the Book of Swarm chapter on overlay topology)
- [Bee API — `GET /addresses`](https://docs.ethswarm.org/api/#tag/Connectivity/operation/getAddresses)

## `--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.
