# Manifests and per-chunk drill-down

A Swarm reference can point at:

1. A **raw chunk** — up to 4 KiB of arbitrary bytes.
2. A **manifest** — a Mantaray-encoded trie that maps paths to other
   references. A manifest's tree can be many chunks deep.

When you `GET /bzz/{ref}/`, Bee walks the manifest from `ref`,
descends to the leaf for the requested path, then fetches the
content reference stored there. The user sees one "file" — the
network does many chunk retrievals under the hood.

## Why per-chunk matters

A `GET /stewardship/{ref}` either says yes or no for the whole tree.
That's useful for a top-level signal but it hides a lot:

- A 50 MB upload is roughly 12,500 chunks. If 50 of them are missing
  from one neighborhood, stewardship says **no** with no further
  detail.
- A manifest with one slow neighborhood will return *slow yes* and
  you won't know which chunks were the bottleneck.

`--per-chunk` walks the manifest with `GET /chunks/{addr}` on every
vantage and records:

- which chunks were found,
- how long each fetch took,
- the chunk's neighborhood (first byte of its address),
- per-vantage proximity to that chunk.

The result is a matrix: rows = chunks, columns = vantages, cells =
found/missing + elapsed_ms. Plus two roll-up tables in the report:

- **per_vantage** — how each vantage performed across all chunks
  (found ratio, p50/p95/max latency).
- **per_neighborhood** — how each chunk neighborhood performed
  across all vantages (reveals "neighborhood 0x4a is slow everywhere"
  patterns).

## How the walk works

Starting from the root reference:

1. Fetch the chunk via `GET /chunks/{addr}`.
2. Try to parse it as a Mantaray node.
3. If parsing succeeds:
   - Record the node's `target_address` (the content reference at
     this node, if any).
   - Enqueue every fork's child manifest chunk.
4. If parsing fails: it's a leaf or raw content — stop walking from
   here.

The walk is breadth-first and capped at **1000 chunks** to bound
work for pathological trees. If your manifest is larger than that
you'll get a representative sample but not the full picture; in
practice 1000 chunks ≈ 4 MB of structure which is more than enough
for typical sites and archives.

## Chunk addresses are not file paths

A chunk's address is its content hash, not its path in the manifest.
So a chunk whose address starts with `0x4a` is in neighborhood `4a`
regardless of where it appears in the directory tree. Patterns
across "slow neighborhoods" rarely correlate with which file the
chunks belong to — that's expected.

## See also

- [Swarm docs — Manifests](https://docs.ethswarm.org/docs/concepts/data/manifest)
- [Swarm docs — Mantaray (specification)](https://github.com/ethersphere/swarm-specs/blob/master/mantaray.md)
- [Bee API — `GET /chunks/{addr}`](https://docs.ethswarm.org/api/#tag/Chunk)
- [Bee API — `GET /bytes/{ref}`](https://docs.ethswarm.org/api/#tag/Bytes)
