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

Abierto
  • ¿Algo no está bien?
#5,682 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 3 días

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
22/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
go
Área
api, backend

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.
Lenguaje dominante
Go
Estrellas
1.5k
Forks
390
Merge medio
2 d 22 h
PR fusionados (30 d)
24

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de ethersphere/bee

Todos los issues de ethersphere/bee

Issues similares

Más issues de Go

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.