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
• Swarm docs — Mantaray (specification)
• Bee API — GET /chunks/{addr}
• Bee API — GET /bytes/{ref}