postage

package
v2.7.1 Latest Latest
Warning

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

 Go to latest Published: Mar 18, 2026 License: BSD-3-Clause Imports: 18 Imported by: 4

Documentation

Index

Constants

View Source 
const (
	StampSize   = 113
	IndexSize   = 8
	BucketDepth = 16
)

StampSize is the number of bytes in the serialisation of a stamp

Variables

View Source 
var (
	// ErrNotFound is the error returned when issuer with given batch ID does not exist.
	ErrNotFound = errors.New("not found")
	// ErrNotUsable is the error returned when issuer with given batch ID is not usable.
	ErrNotUsable = errors.New("not usable")
)
View Source 
var (
	// ErrOwnerMismatch is the error given for invalid signatures.
	ErrOwnerMismatch = errors.New("owner mismatch")
	// ErrInvalidIndex the error given for invalid stamp index.
	ErrInvalidIndex = errors.New("invalid index")
	// ErrStampInvalid is the error given if stamp cannot deserialise.
	ErrStampInvalid = errors.New("invalid stamp")
	// ErrBucketMismatch is the error given if stamp index bucket verification fails.
	ErrBucketMismatch = errors.New("bucket mismatch")
	// ErrInvalidBatchID is the error returned if the batch ID is incorrect
	ErrInvalidBatchID = errors.New("invalid batch ID")
	// ErrInvalidBatchIndex is the error returned if the batch index is incorrect
	ErrInvalidBatchIndex = errors.New("invalid batch index")
	// ErrInvalidBatchTimestamp is the error returned if the batch timestamp is incorrect
	ErrInvalidBatchTimestamp = errors.New("invalid batch timestamp")
	// ErrInvalidBatchSignature is the error returned if the batch signature is incorrect
	ErrInvalidBatchSignature = errors.New("invalid batch signature")
)
View Source 
var (
	// ErrBucketFull is the error when a collision bucket is full.
	ErrBucketFull = errors.New("bucket full")
)
View Source 
var ErrChainDisabled = errors.New("chain disabled")

Functions

func BucketIndexFromBytes 

func BucketIndexFromBytes(buf []byte) (bucket, index uint32)

BucketIndexFromBytes returns bucket index and within-bucket index from supplied bytes.

func IndexFromBytes 

func IndexFromBytes(buf []byte) uint64

IndexFromBytes returns uint64 value from supplied bytes

func RecoverBatchOwner 

func RecoverBatchOwner(chunkAddr swarm.Address, stamp swarm.Stamp) ([]byte, error)

RecoverBatchOwner returns ethereum address that signed postage batch of supplied stamp.

func TimestampFromBytes 

func TimestampFromBytes(buf []byte) uint64

TimestampFromBytes returns uint64 value from supplied bytes

func ToSignDigest 

func ToSignDigest(addr, batchId, index, timestamp []byte) ([]byte, error)

ToSignDigest creates a digest to represent the stamp which is to be signed by the owner.

Types

type Batch 

type Batch struct {
	ID          []byte   // batch ID
	Value       *big.Int // normalised balance of the batch
	Start       uint64   // block number the batch was created
	Owner       []byte   // owner's ethereum address
	Depth       uint8    // batch depth, i.e., size = 2^{depth}
	BucketDepth uint8    // the depth of neighbourhoods t
	Immutable   bool     // if the batch allows adding new capacity (dilution)
}

Batch represents a postage batch, a payment on the blockchain.

func (*Batch) MarshalBinary 

func (b *Batch) MarshalBinary() ([]byte, error)

MarshalBinary implements BinaryMarshaller. It will attempt to serialize the postage batch to a byte slice. serialised as ID(32)|big endian value(32)|start block(8)|owner addr(20)|BucketDepth(1)|depth(1)|immutable(1)

func (*Batch) UnmarshalBinary 

func (b *Batch) UnmarshalBinary(buf []byte) error

UnmarshalBinary implements BinaryUnmarshaller. It will attempt deserialize the given byte slice into the batch.

type BatchEventListener 

type BatchEventListener interface {
	HandleCreate(*Batch, *big.Int) error
	HandleTopUp(id []byte, newBalance *big.Int)
	HandleDepthIncrease(id []byte, newDepth uint8)
}

type BatchExist added in v2.5.0 

type BatchExist interface {
	// Exists reports whether batch referenced by the give id exists.
	Exists([]byte) (bool, error)
}

type BatchExpiryHandler 

type BatchExpiryHandler interface {
	HandleStampExpiry(context.Context, []byte) error
}

type ChainState 

type ChainState struct {
	Block        uint64   // The block number of the last postage event.
	TotalAmount  *big.Int // Cumulative amount paid per stamp.
	CurrentPrice *big.Int // Bzz/chunk/block normalised price.
}

ChainState contains data the batch service reads from the chain.

type ChainStateGetter 

type ChainStateGetter interface {
	CommitmentGetter
	// GetChainState returns the stored chain state from the store.
	GetChainState() *ChainState
}

type CommitmentGetter 

type CommitmentGetter interface {
	Commitment() (uint64, error)
}

CommitmentGetter is used to calculate total batch commitment of the network.

type EventUpdater 

type EventUpdater interface {
	Create(id []byte, owner []byte, totalAmount, normalisedBalance *big.Int, depth, bucketDepth uint8, immutable bool, txHash common.Hash) error
	TopUp(id []byte, topUpAmount, normalisedBalance *big.Int, txHash common.Hash) error
	UpdateDepth(id []byte, depth uint8, normalisedBalance *big.Int, txHash common.Hash) error
	UpdatePrice(price *big.Int, txHash common.Hash) error
	UpdateBlockNumber(blockNumber uint64) error
	Start(ctx context.Context, startBlock uint64) error

	TransactionStart() error
	TransactionEnd() error
}

EventUpdater interface definitions reflect the updates triggered by events emitted by the postage contract on the blockchain.

type Listener 

type Listener interface {
	io.Closer
	Listen(ctx context.Context, from uint64, updater EventUpdater) <-chan error
}

Listener provides a blockchain event iterator.

type NoOpBatchStore 

type NoOpBatchStore struct{}

NoOpBatchStore is a placeholder implementation for postage.Storer

func (*NoOpBatchStore) Commitment 

func (b *NoOpBatchStore) Commitment() (uint64, error)

func (*NoOpBatchStore) Exists 

func (b *NoOpBatchStore) Exists([]byte) (bool, error)

func (*NoOpBatchStore) Get 

func (b *NoOpBatchStore) Get([]byte) (*Batch, error)

func (*NoOpBatchStore) GetChainState 

func (b *NoOpBatchStore) GetChainState() *ChainState

func (*NoOpBatchStore) IsWithinStorageRadius 

func (b *NoOpBatchStore) IsWithinStorageRadius(swarm.Address) bool

func (*NoOpBatchStore) Iterate 

func (b *NoOpBatchStore) Iterate(func(*Batch) (bool, error)) error

func (*NoOpBatchStore) PutChainState 

func (b *NoOpBatchStore) PutChainState(*ChainState) error

func (*NoOpBatchStore) Radius 

func (b *NoOpBatchStore) Radius() uint8

func (*NoOpBatchStore) Reset 

func (b *NoOpBatchStore) Reset() error

func (*NoOpBatchStore) Save 

func (b *NoOpBatchStore) Save(*Batch) error

func (*NoOpBatchStore) SetBatchExpiryHandler 

func (b *NoOpBatchStore) SetBatchExpiryHandler(BatchExpiryHandler)

func (*NoOpBatchStore) SetStorageRadius 

func (b *NoOpBatchStore) SetStorageRadius(func(uint8) uint8) error

func (*NoOpBatchStore) StorageRadius 

func (b *NoOpBatchStore) StorageRadius() uint8

func (*NoOpBatchStore) Update 

func (b *NoOpBatchStore) Update(*Batch, *big.Int, uint8) error

type Service 

type Service interface {
	Add(*StampIssuer) error
	StampIssuers() []*StampIssuer
	GetStampIssuer([]byte) (*StampIssuer, func() error, error)
	IssuerUsable(*StampIssuer) bool
	BatchEventListener
	BatchExpiryHandler
	io.Closer
}

Service is the postage service interface.

func NewService 

func NewService(logger log.Logger, store storage.Store, postageStore Storer, chainID int64) (Service, error)

NewService constructs a new Service.

type Stamp 

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

Stamp represents a postage stamp as attached to a chunk.

func NewStamp 

func NewStamp(batchID, index, timestamp, sig []byte) *Stamp

NewStamp constructs a new stamp from a given batch ID, index and signatures.

func (*Stamp) BatchID 

func (s *Stamp) BatchID() []byte

BatchID returns the batch ID of the stamp.

func (*Stamp) Clone 

func (s *Stamp) Clone() swarm.Stamp

func (*Stamp) Hash added in v2.2.0 

func (s *Stamp) Hash() ([]byte, error)

Hash returns the hash of the stamp.

func (*Stamp) Index 

func (s *Stamp) Index() []byte

Index returns the within-batch index of the stamp.

func (*Stamp) MarshalBinary 

func (s *Stamp) MarshalBinary() ([]byte, error)

MarshalBinary gives the byte slice serialisation of a stamp: batchID[32]|index[8]|timestamp[8]|Signature[65].

func (*Stamp) MarshalJSON 

func (s *Stamp) MarshalJSON() ([]byte, error)

func (*Stamp) Sig 

func (s *Stamp) Sig() []byte

Sig returns the signature of the stamp by the user

func (*Stamp) Timestamp 

func (s *Stamp) Timestamp() []byte

Timestamp returns the timestamp of the stamp

func (*Stamp) UnmarshalBinary 

func (s *Stamp) UnmarshalBinary(buf []byte) error

UnmarshalBinary parses a serialised stamp into id and signature.

func (*Stamp) UnmarshalJSON 

func (a *Stamp) UnmarshalJSON(b []byte) error

func (*Stamp) Valid 

func (s *Stamp) Valid(chunkAddr swarm.Address, ownerAddr []byte, depth, bucketDepth uint8, immutable bool) error

Valid checks the validity of the postage stamp; in particular: - authenticity - check batch is valid on the blockchain - authorisation - the batch owner is the stamp signer the validity check is only meaningful in its association of a chunk this chunk address needs to be given as argument

type StampIssuer 

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

StampIssuer is a local extension of a batch issuing stamps for uploads. A StampIssuer instance extends a batch with bucket collision tracking embedded in multiple Stampers, can be used concurrently.

func NewStampIssuer 

func NewStampIssuer(label, keyID string, batchID []byte, batchAmount *big.Int, batchDepth, bucketDepth uint8, blockNumber uint64, immutableFlag bool) *StampIssuer

NewStampIssuer constructs a StampIssuer as an extension of a batch for local upload.

BucketDepth must always be smaller than batchDepth otherwise increment() panics.

func (*StampIssuer) Amount 

func (si *StampIssuer) Amount() *big.Int

Amount represent issued batch amount paid.

func (*StampIssuer) BlockNumber 

func (si *StampIssuer) BlockNumber() uint64

BlockNumber when this batch was created.

func (*StampIssuer) BucketDepth 

func (si *StampIssuer) BucketDepth() uint8

BucketDepth the depth of collision Buckets uniformity.

func (*StampIssuer) BucketUpperBound 

func (si *StampIssuer) BucketUpperBound() uint32

BucketUpperBound returns the maximum number of collisions possible in a bucket given the batch's depth and bucket depth.

func (*StampIssuer) Buckets 

func (si *StampIssuer) Buckets() []uint32

func (*StampIssuer) Depth 

func (si *StampIssuer) Depth() uint8

Depth represent issued batch depth.

func (*StampIssuer) ID 

func (si *StampIssuer) ID() []byte

ID returns the BatchID for this batch.

func (*StampIssuer) ImmutableFlag 

func (si *StampIssuer) ImmutableFlag() bool

ImmutableFlag immutability of the created batch.

func (*StampIssuer) Label 

func (si *StampIssuer) Label() string

Label returns the label of the issuer.

func (*StampIssuer) MarshalBinary 

func (si *StampIssuer) MarshalBinary() ([]byte, error)

MarshalBinary implements the encoding.BinaryMarshaler interface.

func (*StampIssuer) UnmarshalBinary 

func (si *StampIssuer) UnmarshalBinary(data []byte) error

UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.

func (*StampIssuer) Utilization 

func (si *StampIssuer) Utilization() uint32

Utilization returns the batch utilization in the form of an integer between 0 and 4294967295. Batch fullness can be calculated with: max_bucket_value / 2 ^ (batch_depth - bucket_depth)

type StampIssuerItem 

type StampIssuerItem struct {
	Issuer *StampIssuer
}

StampIssuerItem is a storage.Item implementation for StampIssuer.

func NewStampIssuerItem 

func NewStampIssuerItem(ID []byte) *StampIssuerItem

NewStampIssuerItem creates a new StampIssuerItem.

func (*StampIssuerItem) Clone 

func (s *StampIssuerItem) Clone() storage.Item

Clone returns a clone of StampIssuerItem.

func (*StampIssuerItem) ID 

func (s *StampIssuerItem) ID() string

ID is the batch ID.

func (*StampIssuerItem) Marshal 

func (s *StampIssuerItem) Marshal() ([]byte, error)

Marshal marshals the StampIssuerItem into a byte slice.

func (*StampIssuerItem) Namespace 

func (s *StampIssuerItem) Namespace() string

Namespace returns the storage namespace for a stampIssuer.

func (StampIssuerItem) String 

func (s StampIssuerItem) String() string

String returns the string representation of a StampIssuerItem.

func (*StampIssuerItem) Unmarshal 

func (s *StampIssuerItem) Unmarshal(bytes []byte) error

Unmarshal unmarshals a byte slice into a StampIssuerItem.

type StampItem 

type StampItem struct {
	// Keys.
	BatchID []byte

	// Values.
	BatchIndex     []byte
	BatchTimestamp []byte
	// contains filtered or unexported fields
}

func (*StampItem) Clone 

func (si *StampItem) Clone() storage.Item

Clone implements the storage.Item interface.

func (StampItem) ID 

func (si StampItem) ID() string

ID implements the storage.Item interface.

func (StampItem) Marshal 

func (si StampItem) Marshal() ([]byte, error)

Marshal implements the storage.Item interface.

func (StampItem) Namespace 

func (si StampItem) Namespace() string

Namespace implements the storage.Item interface.

func (StampItem) String 

func (si StampItem) String() string

String implements the fmt.Stringer interface.

func (*StampItem) Unmarshal 

func (si *StampItem) Unmarshal(bytes []byte) error

Unmarshal implements the storage.Item interface.

type Stamper 

type Stamper interface {
	// addr is the request address of the chunk and idAddr is the identity address of the chunk.
	Stamp(addr, idAddr swarm.Address) (*Stamp, error)
	BatchId() []byte
}

Stamper can issue stamps from the given address of chunk.

func NewPresignedStamper added in v2.2.0 

func NewPresignedStamper(stamp *Stamp, owner []byte) Stamper

func NewStamper 

func NewStamper(store storage.Store, issuer *StampIssuer, signer crypto.Signer) Stamper

NewStamper constructs a Stamper.

type Storer 

type Storer interface {
	ChainStateGetter
	BatchExist

	Radius() uint8

	// Get returns a batch from the store with the given ID.
	Get([]byte) (*Batch, error)

	// Iterate iterates through stored batches.
	Iterate(func(*Batch) (bool, error)) error

	// Save stores given batch in the store. The call is idempotent, so
	// a subsequent call would not create new batches if a batch with
	// such ID already exists.
	Save(*Batch) error

	// Update updates a given batch in the store by first deleting the
	// existing batch and then creating a new one. It's an error to update
	// non-existing batch.
	Update(*Batch, *big.Int, uint8) error

	// PutChainState puts given chain state into the store.
	PutChainState(*ChainState) error

	// Reset resets chain state and reserve state of the storage.
	Reset() error

	SetBatchExpiryHandler(BatchExpiryHandler)
}

Storer represents the persistence layer for batches on the current (highest available) block.

type ValidStampFn 

type ValidStampFn func(chunk swarm.Chunk) (swarm.Chunk, error)

func ValidStamp 

func ValidStamp(batchStore Storer) ValidStampFn

ValidStamp returns a stampvalidator function passed to protocols with chunk entrypoints.

Source Files

View all Source files

Directories

Path Synopsis
mock
mock

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.