postage

package
v1.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 8, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package postage covers the Swarm postage-batch lifecycle plus the pure stamp math used to translate (size, duration) into (depth, amount) and back.

Get a *Service handle from github.com/ethswarm-tools/bee-go.Client.Postage for batch CRUD:

  • CreatePostageBatch / CreatePostageBatchWithOptions
  • TopUpBatch, DiluteBatch
  • GetPostageBatch (one), GetPostageBatches (owned, hits /stamps)
  • GetGlobalPostageBatches (chain-wide, hits /batches; alias GetAllGlobalPostageBatch is deprecated)
  • GetPostageBatchBuckets

Stamp math is exposed as free functions because it has no I/O: GetStampCost, GetStampDuration, GetAmountForDuration, GetDepthForSize, GetStampEffectiveBytes.

Stamper is an offline postage stamper for callers that need to sign stamps client-side (e.g. when uploading via /chunks or /soc with a pre-issued envelope). MarshalStamp / ConvertEnvelopeToMarshaledStamp produce the 113-byte on-wire stamp layout (batchID || index || timestamp || signature).

Mirrors bee-js's createPostageBatch / topUpBatch / diluteBatch / getPostageBatch / getGlobalPostageBatches / Stamper / marshalStamp / convertEnvelopeToMarshaledStamp surface.

Batch-usability delay

A postage batch is not usable for uploads immediately after CreatePostageBatch returns. Bee waits for N confirmations of the purchase transaction (configurable on the node, typically 8) before flipping the batch's usable bit. On Gnosis (5-second blocks) this is ~40 seconds; on Sepolia (12-second blocks) it can be 2-3 minutes and occasionally longer.

Use the returned [PostageBatch.Usable] field — poll Service.GetPostageBatch 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".

Dilute is one-way

Service.DiluteBatch 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.

Index

Constants

View Source 
const MarshaledStampLength = 32 + 8 + 8 + 65

MarshaledStampLength is the byte length of a marshaled stamp: 32 (batchID) + 8 (index) + 8 (timestamp) + 65 (signature).

Variables

This section is empty.

Functions

func ConvertEnvelopeToMarshaledStamp 

func ConvertEnvelopeToMarshaledStamp(env Envelope) ([]byte, error)

ConvertEnvelopeToMarshaledStamp marshals a stamper Envelope into the wire format. Convenience wrapper around MarshalStamp for callers that already hold a structured Envelope (typically the return value of Stamper.Stamp).

Mirrors bee-js convertEnvelopeToMarshaledStamp (stamps.ts:177).

func GetAmountForDuration 

func GetAmountForDuration(duration swarm.Duration, pricePerBlock uint64, blockTime uint64) *big.Int

GetAmountForDuration computes the `amount` (PLUR per chunk) needed to fund a batch for the given duration: 

amount = (duration / blockTime) * pricePerBlock + 1

The `+ 1` matches bee-js to compensate for integer division and avoid short funding.

func GetDepthForSize 

func GetDepthForSize(size swarm.Size) int

GetDepthForSize returns the smallest depth whose effective capacity covers the given size. Falls back to 35 for sizes larger than the table covers.

func GetStampCost 

func GetStampCost(depth int, amount *big.Int) *big.Int

GetStampCost returns 2^depth × amount, the BZZ-PLUR cost of buying a batch of the given depth and amount.

func GetStampDuration 

func GetStampDuration(amount *big.Int, pricePerBlock uint64, blockTime uint64) swarm.Duration

GetStampDuration estimates the TTL of a batch given its `amount`, `pricePerBlock` (PLUR/block) and `blockTime` (seconds/block): 

seconds = amount * blockTime / pricePerBlock

pricePerBlock and blockTime should come from the Bee node where possible (chainstate). Mirrors bee-js getStampDuration.

func GetStampEffectiveBytes 

func GetStampEffectiveBytes(depth int) int64

GetStampEffectiveBytes returns the practical capacity for the given depth, using the Swarm effective-utilisation table for depths 17–34 and the 0.9 max-utilization approximation outside that range.

func GetStampTheoreticalBytes 

func GetStampTheoreticalBytes(depth int) int64

GetStampTheoreticalBytes is the upper bound for a batch of the given depth: 4096 bytes per chunk × 2^depth chunks.

func GetStampUsage 

func GetStampUsage(utilization uint32, depth uint8, bucketDepth uint8) float64

GetStampUsage calculates the fractional usage [0,1] of a postage batch.

func MarshalStamp 

func MarshalStamp(batchID swarm.BatchID, index, timestamp []byte, signature swarm.Signature) ([]byte, error)

MarshalStamp concatenates the stamp components into the wire format Bee expects when a stamp travels alongside a chunk: batchID || index || timestamp || signature (113 bytes).

Mirrors bee-js marshalStamp (stamps.ts:181). Returns a typed argument error if any input has the wrong length, so callers can route the failure through the BeeArgumentError surface.

Types

type BatchBucket 

type BatchBucket struct {
	BucketID   uint32 `json:"bucketID"`
	Collisions uint32 `json:"collisions"`
}

BatchBucket is one entry in PostageBatchBuckets.Buckets — the collision count for one of the 2^bucketDepth buckets in a batch.

type Envelope 

type Envelope struct {
	BatchID   swarm.BatchID
	Index     []byte // 8 bytes: bucket (BE u32) || height (BE u32)
	Issuer    swarm.EthAddress
	Signature swarm.Signature
	Timestamp []byte // 8 bytes: Unix milliseconds (BE u64), matching bee-js Date.now()
}

Envelope is the per-chunk postage envelope returned by Stamp. Mirrors bee-js EnvelopeWithBatchId.

type GlobalPostageBatch 

type GlobalPostageBatch struct {
	BatchID     swarm.BatchID `json:"batchID"`
	Value       *big.Int      `json:"-"`
	Start       uint64        `json:"start"`
	Owner       string        `json:"owner"`
	Depth       uint8         `json:"depth"`
	BucketDepth uint8         `json:"bucketDepth"`
	Immutable   bool          `json:"immutable"`
	BatchTTL    int64         `json:"batchTTL"`
}

GlobalPostageBatch is one entry in GET /batches. The chain-wide view drops owner-only fields (utilization, usable, label, blockNumber).

func (*GlobalPostageBatch) UnmarshalJSON 

func (g *GlobalPostageBatch) UnmarshalJSON(b []byte) error

type PostageBatch 

type PostageBatch struct {
	BatchID     swarm.BatchID `json:"batchID"`
	Amount      *big.Int      `json:"-"`
	Start       uint64        `json:"start"`
	Owner       string        `json:"owner"`
	Depth       uint8         `json:"depth"`
	BucketDepth uint8         `json:"bucketDepth"`
	Immutable   bool          `json:"immutableFlag"`
	BatchTTL    int64         `json:"batchTTL"`
	Utilization uint32        `json:"utilization"`
	Usable      bool          `json:"usable"`
	Exists      bool          `json:"exists"`
	Label       string        `json:"label"`
	BlockNumber uint64        `json:"blockNumber"`
}

PostageBatch represents a Swarm postage batch.

func (*PostageBatch) UnmarshalJSON 

func (pb *PostageBatch) UnmarshalJSON(b []byte) error

UnmarshalJSON implements custom unmarshalling for PostageBatch.

type PostageBatchBuckets 

type PostageBatchBuckets struct {
	Depth            uint8         `json:"depth"`
	BucketDepth      uint8         `json:"bucketDepth"`
	BucketUpperBound uint32        `json:"bucketUpperBound"`
	Buckets          []BatchBucket `json:"buckets"`
}

PostageBatchBuckets is the response from GET /stamps/{id}/buckets: per-bucket fill stats useful for spotting near-overcommit batches.

type Service 

type Service struct {
	// contains filtered or unexported fields
}

Service is the postage-batch endpoint group: create, top-up, dilute, list owned (/stamps) and chain-wide (/batches). Get one from the top-level Client.Postage field rather than constructing it directly.

Stamp math is exposed as free functions in this package (GetStampCost, GetAmountForDuration, GetDepthForSize, …) since it has no I/O.

func NewService 

func NewService(baseURL *url.URL, httpClient *http.Client) *Service

NewService wires up a postage.Service against a Bee base URL and HTTP client. The top-level bee.NewClient calls this for you.

func (*Service) CreatePostageBatch 

func (s *Service) CreatePostageBatch(ctx context.Context, amount *big.Int, depth uint8, label string) (swarm.BatchID, error)

CreatePostageBatch purchases a new postage batch. amount: initial balance per chunk (big.Int) depth: batch depth (uint8) 17 -> 2^17 chunks label: optional label for the batch

func (*Service) DiluteBatch 

func (s *Service) DiluteBatch(ctx context.Context, batchID swarm.BatchID, depth uint8) error

DiluteBatch increases the depth of an existing batch.

func (*Service) GetAllGlobalPostageBatch deprecated 

func (s *Service) GetAllGlobalPostageBatch(ctx context.Context) ([]GlobalPostageBatch, error)

GetAllGlobalPostageBatch is the bee-js name for GetGlobalPostageBatches.

Deprecated: bee-js scheduled the singular form for removal; prefer GetGlobalPostageBatches.

func (*Service) GetGlobalPostageBatches 

func (s *Service) GetGlobalPostageBatches(ctx context.Context) ([]GlobalPostageBatch, error)

GetGlobalPostageBatches returns every postage batch currently visible on-chain, regardless of owner. Mirrors bee-js getGlobalPostageBatches. Hits GET /batches.

func (*Service) GetPostageBatch 

func (s *Service) GetPostageBatch(ctx context.Context, batchID swarm.BatchID) (*PostageBatch, error)

GetPostageBatch retrieves a single postage batch by ID.

func (*Service) GetPostageBatchBuckets 

func (s *Service) GetPostageBatchBuckets(ctx context.Context, batchID swarm.BatchID) (PostageBatchBuckets, error)

GetPostageBatchBuckets returns per-bucket collision stats for an owned postage batch. Mirrors bee-js getPostageBatchBuckets.

func (*Service) GetPostageBatches 

func (s *Service) GetPostageBatches(ctx context.Context) ([]PostageBatch, error)

GetPostageBatches retrieves all postage batches owned by this node. Hits GET /stamps; the response includes utilization, label and other owner-only fields. For the chain-wide list of every batch (without owner-only fields) see GetGlobalPostageBatches.

func (*Service) TopUpBatch 

func (s *Service) TopUpBatch(ctx context.Context, batchID swarm.BatchID, amount *big.Int) error

TopUpBatch adds more value (amount) to an existing batch.

type Stamper 

type Stamper struct {
	// contains filtered or unexported fields
}

Stamper represents a client-side postage stamper.

func NewStamper 

func NewStamper(signer swarm.PrivateKey, batchID swarm.BatchID, depth int) (*Stamper, error)

NewStamper creates a new Stamper.

func (*Stamper) Stamp 

func (s *Stamper) Stamp(chunkAddr []byte) (Envelope, error)

Stamp signs a chunk and returns its postage envelope.

Signing input (per bee-js): chunkAddr || batchID || index || timestamp, signed via PrivateKey.Sign (Ethereum signed-message scheme).

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.