API: which of this node's batches stamp a chunk, or the chunks under a reference

Aperta
  • Qualcosa non va?
#5,682 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 3 giorni

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
22/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
go
Ambito
api, backend

Direzione di ricerca

Start from the stamp issuer records: postage.StampItem in pkg/postage/stampissuer.go, and how stamper.go reads an existing item so a re-stamped chunk keeps its slot. The first endpoint needs one lookup of that item by batchID/chunkAddress, returning index, timestamp, or 404. The second reuses the traversal behind GET /stewardship/{reference} and counts per-batch hits. The issue's privacy limits are part of the design, so settle who may call these routes before writing code. Done means both routes return correct answers in tests, with the existing stewardship tests still passing.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Summary

Two read-only endpoints through which a node reports, from its own stamp
issuer's records, which of its batches stamp a chunk:

  1. GET /stamps/{batch_id}/chunks/{address}: whether this node stamped the
    chunk with this batch, with the stamp's index and timestamp; 404 when
    it did not.
  2. GET /stewardship/{reference}/stamps: walk the tree as
    GET /stewardship/{reference} does and report, for each of the node's
    own batches, how many of the tree's chunks it stamps, and how many
    chunks none of them stamp.

They answer only from the node's own records, about its own batches. Nothing
is asked of other nodes, and the protocol does not change.

Motivation

Whoever keeps content alive has to know which of their batches stamp it.
After moving it onto a new batch with PUT /stewardship/{reference}, they
also need to know whether all of it moved. Today the node can say only
whether content is retrievable (GET /stewardship/{reference}), and that
can't tell the batches apart: while the old batch lasts, a chunk the move
skipped is still retrievable. It shows only when the old batch expires,
which is too late.

So tools keep their own records of what went where, with no way to check
them against the node. Examples are swarm-keep's
keep-lists (it checks and moves content onto a new batch before the old one
runs out), Freedom's publish history and the Swarm Desktop File Manager's
drives.

swarm-keep's first real rotation, on 2026-10-31, moved six keep-lists onto a
new batch about nine days before the old one ran out: 47,003 addresses
(sites, apps, feeds and the blobs of record stores), none failed.
GET /stewardship then answered retrievable for a sample of each list. It
could not show that any of them is on the new batch.

How long a batch lasts stays with the caller. The node already serves what
the estimate needs: the batch's value from GET /batches/{id}, and
totalAmount and currentPrice from GET /chainstate. So these answers
name batches and nothing about time.

Implementation

The node already keeps the record. A stamp issuer stores a
postage.StampItem
(batch ID, chunk address, index, timestamp) for every chunk it stamps,
keyed batchID/chunkAddress. stamper.Stamp reads it so that a chunk
stamped again on the same batch keeps its slot
(stamper.go L42–L65).

  • (1) is one Get of that item.
  • (2) is the traversal GET /stewardship already does, with one such
    Get per chunk for each of the node's usable batches (/stamps).
Drawbacks
  • Privacy. A stamp links a chunk to a batch, through the batch to its
    owner's address on chain, and to every other chunk the same batch
    stamped, encrypted ones included.
    • These endpoints answer only the batch's owner, about chunks it stamped
      itself, through its own API, like /stamps and /wallet. They tell
      no one anything they did not already know.
    • A gateway that stamps uploads for others should keep them closed, as
      it keeps /stamps closed.
    • Deliberately not asked:
      • Stamps in retrieval. Delivery.Stamp has been empty since
        1.17.0. Filling it again would let anyone who downloads content link
        it to its uploader.
      • Storers telling anyone a chunk's batch or expiry. An expiry
        alone nearly identifies the batch, and a storer could answer falsely.
  • Cost. (2) walks the whole tree, as GET /stewardship does, so it is
    as slow on a large tree: it fetches every chunk it does not hold. The
    stamp lookups themselves are local.
AI Disclosure
  • This issue contains suggestions and text generated by an LLM.
  • I have reviewed the AI generated content thoroughly.
  • I possess the technical expertise to responsibly review the AI generated content mentioned in this issue.
Lingua principale
Go
Stelle
1.5k
Fork
390
Merge medio
2g 22h
PR unite (30g)
24

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di ethersphere/bee

Tutte le issue di ethersphere/bee

Issue simili

Altre issue su Go

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.