bee-check

Retrievability checker for Ethereum Swarm references — like check.ipfs.network, but for Swarm and built on plain HTTP via bee-rs.

bee-check c79394...bdc36a \
    --bee https://my-bee.example.com \
    --bee http://localhost:1633 \
    --gateway https://api.gateway.ethswarm.org \
    --per-chunk

# Resolve a Swarm feed first, then probe the current reference:
bee-check feed:<40-hex-owner>:<64-hex-topic> --bee http://localhost:1633

For each Bee URL ("vantage") it calls GET /stewardship/{ref} in parallel and reports whether the reference is retrievable through that node. Each vantage also reports its overlay address, proximity order to the reference, and Bee version — so a miss tells you which neighborhood the probe was in, not just that the answer was no. With --per-chunk it walks the manifest, fetches every reachable chunk via GET /chunks/{addr}, and shows which chunks are missing on which vantage, tagged with the per-chunk proximity. With --reseed --stamp <id> it first calls GET /stamps/{id} to confirm the batch is usable, then issues PUT /stewardship/{ref} against the first vantage.

Install

cargo install bee-check

Or build from source: cargo build --release then take the binary at target/release/bee-check.

Quick examples

# Single-vantage check against the default node.
bee-check <ref>

# Multi-vantage; --bee may repeat.
bee-check <ref> --bee https://a.example --bee https://b.example

# Manifest drill-down: probe every chunk on every vantage.
bee-check <ref> --per-chunk

# Machine-readable output (see SPEC.md).
bee-check <ref> --output json

# Re-seed after probing (requires the postage batch you want to use).
bee-check <ref> --reseed --stamp <batch-id> --bee https://my-bee.example

Configuration

BEE_API_URL — used as the single default vantage when no --bee flag is provided. Falls back to http://localhost:1633.

Exit codes

code	meaning
`0`	At least one vantage returned `retrievable: true`.
`2`	No vantage returned `retrievable: true` (unretrievable, partial-with-no-success, or all-error).
other	Unexpected error (parse failure, invalid arg, etc.).

Multi-vantage semantics

Each vantage gets its own probe. The top-level status aggregates them:

retrievable — every vantage said yes
unretrievable — every vantage said no (or errored)
partial — mixed: some yes, some no
error — every vantage errored before producing an answer

This is the "from MY vantage" model, not "globally retrievable" — see the Limitations section.

Limitations

/stewardship/{ref} must be exposed. Most public Swarm gateways serve only /bzz and /bytes. For a meaningful check, point --bee at a Bee node whose API you can reach (your own, a private gateway, etc.).
The probe is "from this vantage", not "globally retrievable". Stewardship's IsRetrievable walks the manifest through the probed node's own retrieval path; another node in a different neighborhood might see different results.
Per-chunk drill-down is best-effort. When the root or a child manifest can't be fetched, the walker can't recurse past it; the top-level stewardship result is still authoritative.
Re-seed needs a usable stamp. --reseed calls PUT /stewardship/{ref}, which requires the postage batch ID to be known to the probing node.

License

MIT OR Apache-2.0.

bee-check 0.4.0