Postage batches and re-seeding

Uploads to Swarm are paid for with postage batches — pre-funded allowances of chunk-storage capacity bought on-chain. Every chunk stored in the network carries a stamp linking it to a batch; if the batch expires, the chunks become unstamped and storer nodes eventually drop them.

This matters for retrievability because:

• a reference that was fine yesterday can become unretrievable if the batch it was uploaded with expired and storers garbage- collected the chunks;
• re-uploading the same content (re-seeding) refreshes the stamp but does not automatically use the original batch — you supply a current batch.

What bee-check --reseed does

bee-check <ref> --reseed --stamp <batch-id> --bee https://my-bee.example

Two API calls, in order:

1. GET /stamps/{batch-id} on the target Bee — pre-flight check. Verifies that the batch:

   • is known to this Bee (exists)
   • is usable (chain has confirmed enough blocks)
   • has a TTL ≥ 24h (warns otherwise — re-seeding from a batch that’s about to expire would be wasted effort)

2. PUT /stewardship/{ref} with the swarm-postage-batch-id header — instructs Bee to re-upload all chunks reachable from ref, stamped with this batch. Bee fetches anything it doesn’t have locally, hashes everything, and pushes it back into the network with fresh stamps.

The pre-flight step is what makes --reseed safe to wire into a script: it refuses to fire the re-upload if the batch is unhealthy, so you don’t burn API time on a doomed operation.

What you need before you can re-seed

• A postage batch you control on the target Bee, currently usable, with enough TTL left to be worth using.
• The reference you want to re-seed — and the chunks must be reachable from somewhere in the network or locally pinned. Bee re-fetches chunks during reupload; if no peer has them and the local store doesn’t either, the chunks can’t be re-stamped and the upload will be incomplete.

When to re-seed

• Approaching batch expiration of an important upload.
• After a stewardship partial or unretrievable and you suspect garbage collection.
• After moving content between Bee nodes (“transferred” content needs to be re-stamped from the new node’s perspective).

When not to re-seed: if stewardship says false because the content was never pushed (deferred upload, network split). Re- seeding requires retrievability of the source chunks — see the lost-upload cookbook entry for that case.

See also

• Swarm docs — Postage stamps
• Swarm docs — Buying a stamp
• Bee API — GET /stamps/{id}