postage

package
v1.13.0-rc3 Latest Latest
Warning

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

 Go to latest Published: Mar 2, 2023 License: BSD-3-Clause Imports: 15 Imported by: 22

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")
)
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

This section is empty.

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)
	StorageRadius uint8    // storage radius
}

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)|StorageRadius(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 added in v1.2.0 

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

type BatchExpiryHandler added in v1.8.0 

type BatchExpiryHandler interface {
	HandleStampExpiry([]byte)
	SetExpired() error
}

type ChainSnapshot added in v1.6.0 

type ChainSnapshot struct {
	Events           []types.Log `json:"events"`
	LastBlockNumber  uint64      `json:"lastBlockNumber"`
	FirstBlockNumber uint64      `json:"firstBlockNumber"`
	Timestamp        int64       `json:"timestamp"`
}

ChainSnapshot represents the snapshot of all the postage events between the FirstBlockNumber and LastBlockNumber. The timestamp stores the time at which the snapshot was generated. This snapshot can be used to sync the postage package to prevent large no. of chain backend calls.

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 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, initState *ChainSnapshot) 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, initState *ChainSnapshot) <-chan error
}

Listener provides a blockchain event iterator.

type NoOpBatchStore added in v1.6.2 

type NoOpBatchStore struct{}

NoOpBatchStore is a placeholder implementation for postage.Storer

func (*NoOpBatchStore) Exists added in v1.6.2 

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

func (*NoOpBatchStore) Get added in v1.6.2 

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

func (*NoOpBatchStore) GetChainState added in v1.6.2 

func (b *NoOpBatchStore) GetChainState() *ChainState

func (*NoOpBatchStore) GetReserveState added in v1.6.2 

func (b *NoOpBatchStore) GetReserveState() *ReserveState

func (*NoOpBatchStore) IsWithinStorageRadius added in v1.12.0 

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

func (*NoOpBatchStore) Iterate added in v1.6.2 

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

func (*NoOpBatchStore) PutChainState added in v1.6.2 

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

func (*NoOpBatchStore) Reset added in v1.6.2 

func (b *NoOpBatchStore) Reset() error

func (*NoOpBatchStore) Save added in v1.6.2 

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

func (*NoOpBatchStore) SetBatchExpiryHandler added in v1.8.0 

func (b *NoOpBatchStore) SetBatchExpiryHandler(BatchExpiryHandler)

func (*NoOpBatchStore) SetStorageRadius added in v1.8.0 

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

func (*NoOpBatchStore) SetStorageRadiusSetter added in v1.8.0 

func (b *NoOpBatchStore) SetStorageRadiusSetter(StorageRadiusSetter)

func (*NoOpBatchStore) StorageRadius added in v1.12.0 

func (b *NoOpBatchStore) StorageRadius() uint8

func (*NoOpBatchStore) Unreserve added in v1.6.2 

func (b *NoOpBatchStore) Unreserve(UnreserveIteratorFn) error

func (*NoOpBatchStore) Update added in v1.6.2 

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

type RadiusChecker added in v1.12.0 

type RadiusChecker interface {
	IsWithinStorageRadius(addr swarm.Address) bool
	StorageRadius() uint8
}

type ReserveState 

type ReserveState struct {
	Radius        uint8
	StorageRadius uint8
}

type ReserveStateGetter added in v1.8.0 

type ReserveStateGetter interface {
	// GetReserveState returns a copy of stored reserve state.
	GetReserveState() *ReserveState
}

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(store storage.StateStorer, 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) Index added in v1.0.0 

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) Sig 

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

Sig returns the signature of the stamp by the user

func (*Stamp) Timestamp added in v1.0.0 

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) 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 inc() panics.

func (*StampIssuer) Amount added in v1.0.0 

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

Amount represent issued batch amount paid.

func (*StampIssuer) BlockNumber added in v1.0.0 

func (si *StampIssuer) BlockNumber() uint64

BlockNumber when this batch was created.

func (*StampIssuer) BucketDepth added in v1.0.0 

func (si *StampIssuer) BucketDepth() uint8

BucketDepth the depth of collision Buckets uniformity.

func (*StampIssuer) BucketUpperBound added in v1.1.0 

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 added in v1.1.0 

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

func (*StampIssuer) Depth added in v1.0.0 

func (si *StampIssuer) Depth() uint8

Depth represent issued batch depth.

func (*StampIssuer) Expired added in v1.8.0 

func (si *StampIssuer) Expired() bool

Expired returns the expired property of stamp

func (*StampIssuer) ID 

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

ID returns the BatchID for this batch.

func (*StampIssuer) ImmutableFlag added in v1.0.0 

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) SetExpired added in v1.8.0 

func (si *StampIssuer) SetExpired(e bool)

SetExpired is setter for Expired property

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 Stamper 

type Stamper interface {
	Stamp(swarm.Address) (*Stamp, error)
}

Stamper can issue stamps from the given address.

func NewStamper 

func NewStamper(st *StampIssuer, signer crypto.Signer) Stamper

NewStamper constructs a Stamper.

type StorageRadiusSetter added in v1.8.0 

type StorageRadiusSetter interface {
	SetStorageRadius(uint8)
}

StorageRadiusSetter is used as a callback when the radius of a node changes.

type Storer 

type Storer interface {
	ReserveStateGetter
	RadiusChecker

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

	// Exists reports whether batch referenced by the give id exists.
	Exists([]byte) (bool, 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

	// GetChainState returns the stored chain state from the store.
	GetChainState() *ChainState

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

	// SetStorageRadius updates the value of the storage radius atomically.
	SetStorageRadius(func(uint8) uint8) error

	// SetStorageRadiusSetter sets the RadiusSetter to the given value.
	// The given RadiusSetter will be called when radius changes.
	SetStorageRadiusSetter(StorageRadiusSetter)

	// Unreserve evict batches from the unreserve queue of the storage.
	// During the eviction process, the given UnreserveIteratorFn is called.
	Unreserve(UnreserveIteratorFn) 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 UnreserveIteratorFn added in v1.0.0 

type UnreserveIteratorFn func(id []byte, radius uint8) (bool, error)

UnreserveIteratorFn is used as a callback on Storer.Unreserve method calls.

type ValidStampFn added in v1.1.0 

type ValidStampFn func(chunk swarm.Chunk, stampBytes []byte) (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.