postage

package
v0.0.0-...-c9321c3 Latest Latest
Warning

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

Go to latest
Published: Mar 7, 2022 License: BSD-3-Clause Imports: 10 Imported by: 0

Documentation

Index

Constants

View Source
const StampSize = 97

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

Variables

View Source
var (
	// ErrOwnerMismatch is the error given for invalid signatures.
	ErrOwnerMismatch = errors.New("owner mismatch")
	// ErrStampInvalid is the error given if stamp cannot deserialise.
	ErrStampInvalid = errors.New("invalid stamp")
)
View Source
var (
	// ErrBucketFull is the error when a collision bucket is full.
	ErrBucketFull = errors.New("bucket full")
)
View Source
var (
	// ErrNotFound is the error returned when issuer with given batch ID does not exist.
	ErrNotFound = errors.New("not found")
)

Functions

func ValidStamp

func ValidStamp(batchStore Storer) func(chunk penguin.Chunk, stampBytes []byte) (penguin.Chunk, error)

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

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}
	Radius uint8    // reserve radius, non-serialised
}

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)|depth(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 ChainState

type ChainState struct {
	Block        uint64   `json:"block"`        // The block number of the last postage event.
	TotalAmount  *big.Int `json:"totalAmount"`  // Cumulative amount paid per stamp.
	CurrentPrice *big.Int `json:"currentPrice"` // 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, normalisedBalance *big.Int, depth uint8) error
	TopUp(id []byte, normalisedBalance *big.Int) error
	UpdateDepth(id []byte, depth uint8, normalisedBalance *big.Int) error
	UpdatePrice(price *big.Int) error
	UpdateBlockNumber(blockNumber uint64) error
	Start(startBlock uint64) (<-chan struct{}, 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(from uint64, updater EventUpdater) <-chan struct{}
}

Listener provides a blockchain event iterator.

type RadiusSetter

type RadiusSetter interface {
	SetRadius(uint8)
}

type ReserveState

type ReserveState struct {
	Radius    uint8    `json:"radius"`
	Available int64    `json:"available"`
	Outer     *big.Int `json:"outer"` // lower value limit for outer layer = the further half of chunks
	Inner     *big.Int `json:"inner"`
}

type Service

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

Service is the postage service interface.

func NewService

func NewService(store storage.StateStorer, 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, sig []byte) *Stamp

NewStamp constructs a new stamp from a given batch ID and signature.

func (*Stamp) BatchID

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

BatchID returns the batch ID of the stamp.

func (*Stamp) MarshalBinary

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

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

func (*Stamp) Sig

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

Sig returns the signature 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 penguin.Address, ownerAddr []byte) 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, batchDepth, bucketDepth uint8) *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) ID

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

ID returns the BatchID for this batch.

func (*StampIssuer) Label

func (st *StampIssuer) Label() string

Label returns the label of the issuer.

func (*StampIssuer) MarshalBinary

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

MarshalBinary gives the byte slice serialisation of a StampIssuer: = label[32]|keyID[32]|batchID[32]|batchDepth[1]|bucketDepth[1]|size_0[4]|size_1[4]|....

func (*StampIssuer) UnmarshalBinary

func (st *StampIssuer) UnmarshalBinary(buf []byte) error

UnmarshalBinary parses a serialised StampIssuer into the receiver struct.

func (*StampIssuer) Utilization

func (st *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(penguin.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 Storer

type Storer interface {
	Get(id []byte) (*Batch, error)
	Put(*Batch, *big.Int, uint8) error
	PutChainState(*ChainState) error
	GetChainState() *ChainState
	GetReserveState() *ReserveState
	SetRadiusSetter(RadiusSetter)

	Reset() error
}

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

Directories

Path Synopsis
Package batchstore implements the reserve the reserve serves to maintain chunks in the area of responsibility it has two components - the batchstore reserve which maintains information about batches, their values, priorities and synchronises with the blockchain - the localstore which stores chunks and manages garbage collection when a new chunk arrives in the localstore, the batchstore reserve is asked to check the batch used in the postage stamp attached to the chunk.
Package batchstore implements the reserve the reserve serves to maintain chunks in the area of responsibility it has two components - the batchstore reserve which maintains information about batches, their values, priorities and synchronises with the blockchain - the localstore which stores chunks and manages garbage collection when a new chunk arrives in the localstore, the batchstore reserve is asked to check the batch used in the postage stamp attached to the chunk.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL