Module postage 

Postage batch CRUD + stamp metadata. Mirrors pkg/postage in bee-go.

The endpoint methods live on PostageApi (get one from crate::Client::postage). Pure stamp math — get_stamp_cost, get_stamp_effective_bytes, etc. — is exposed as free functions since it has no I/O.

Batch-usability delay

A batch is not usable for uploads immediately after PostageApi::create_postage_batch returns. Bee waits for N confirmations of the purchase transaction (typically 8) before flipping PostageBatch::usable to true. On Gnosis (5-second blocks) this is ~40 s; on Sepolia (12-second blocks) it can be 2-3 minutes and occasionally longer.

Poll PostageApi::get_postage_batch in a loop until usable is true, or supply the batch via an environment variable so tests can reuse a known-good batch. Uploading against a not-yet-usable batch returns HTTP 422 “stamp not usable”, surfaced as crate::Error::Response with status = 422.

Dilute is one-way

PostageApi::dilute_batch only allows depth to grow. Once a batch’s depth is increased its previously-issued stamps remain valid; there is no way to shrink depth and reclaim funds.

Structs

BatchBucket

Per-bucket collision count from GET /stamps/{id}/buckets.

Envelope

Per-chunk postage envelope returned by Stamper::stamp.

GlobalPostageBatch

Postage batch as returned by GET /batches (chain-wide view; drops owner-only fields).

PostageApi

Handle exposing the postage endpoints. Cheap to clone.

PostageBatch

Postage batch as returned by GET /stamps / GET /stamps/{id} (owner-only view; includes utilization, label, blockNumber).

PostageBatchBuckets

Aggregated bucket fill stats for one batch.

Stamper

Client-side stamper that tracks per-bucket utilisation and signs envelopes for individual chunks.

Constants

EFFECTIVE_SIZE_BREAKPOINTS

Effective-utilisation breakpoints for encrypted, medium-erasure batches at each depth. Values mirror bee-js stamps.ts exactly.

MARSHALED_STAMP_LENGTH

Wire-format length of a marshaled postage stamp: batchID(32) || index(8) || timestamp(8) || signature(65).

MIN_DEPTH

Bucket-depth floor: stamper depth must be strictly greater than this value (matches bee-go and bee-js, which require depth > 16).

NUM_BUCKETS

Number of buckets in a postage batch (2^16).

Functions

convert_envelope_to_marshaled_stamp

Marshal an Envelope into the 113-byte stamp wire format. Thin wrapper over marshal_stamp for callers that already hold a structured envelope (typically from Stamper::stamp). Mirrors bee-go ConvertEnvelopeToMarshaledStamp / bee-js convertEnvelopeToMarshaledStamp.

get_depth_for_size

Smallest depth whose effective capacity covers bytes. Falls back to 35 for sizes the table doesn’t cover.

get_stamp_cost

Cost of buying a batch: 2^depth * amount PLUR.

get_stamp_effective_bytes

Practical capacity for the given depth using the encrypted-medium erasure breakpoints (17..=34). Outside that range falls back to 0.9 * theoretical.

get_stamp_theoretical_bytes

Theoretical capacity of a batch: 4096 * 2^depth bytes.

get_stamp_usage

Fractional usage [0, 1] of a postage batch.

marshal_stamp

Concatenate the components of a postage stamp into the wire format Bee expects when a stamp travels alongside a chunk: batchID(32) || index(8) || timestamp(8) || signature(65) — 113 bytes total. Mirrors bee-go postage.MarshalStamp and bee-js marshalStamp.