postage

package
v1.18.0-rc2 Latest Latest
Warning

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

 Go to latest Published: Sep 29, 2023 License: BSD-3-Clause Imports: 17 Imported by: 21

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")
	ErrOverwriteImmutableIndex = errors.New("immutable batch old index overwrite due to previous faulty save")
)
View Source 
var ErrChainDisabled = errors.New("chain disabled")

Functions

func BucketIndexFromBytes added in v1.17.0 

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

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

func IndexFromBytes added in v1.17.0 

func IndexFromBytes(buf []byte) uint64

IndexFromBytes returns uint64 value from supplied bytes

func RecoverBatchOwner added in v1.17.0 

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

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

func TimestampFromBytes added in v1.17.0 

func TimestampFromBytes(buf []byte) uint64

TimestampFromBytes returns uint64 value from supplied bytes

func ToSignDigest added in v1.17.0 

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

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

type CommitmentGetter added in v1.16.0 

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

StorageRadiusSetter 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, 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) Commitment added in v1.16.0 

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

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) 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) Radius added in v1.17.0 

func (b *NoOpBatchStore) Radius() uint8

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

func (b *NoOpBatchStore) StorageRadius() uint8

func (*NoOpBatchStore) Update added in v1.6.2 

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

func (s *Stamp) Clone() swarm.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 increment() 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 StampIssuerItem added in v1.17.0 

type StampIssuerItem struct {
	Issuer *StampIssuer
}

StampIssuerItem is a storage.Item implementation for StampIssuer.

func NewStampIssuerItem added in v1.17.0 

func NewStampIssuerItem(ID []byte) *StampIssuerItem

NewStampIssuerItem creates a new StampIssuerItem.

func (*StampIssuerItem) Clone added in v1.17.0 

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

Clone returns a clone of StampIssuerItem.

func (*StampIssuerItem) ID added in v1.17.0 

func (s *StampIssuerItem) ID() string

ID is the batch ID.

func (*StampIssuerItem) Marshal added in v1.17.0 

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

Marshal marshals the StampIssuerItem into a byte slice.

func (*StampIssuerItem) Namespace added in v1.17.0 

func (s *StampIssuerItem) Namespace() string

Namespace returns the storage namespace for a stampIssuer.

func (StampIssuerItem) String added in v1.17.0 

func (s StampIssuerItem) String() string

String returns the string representation of a StampIssuerItem.

func (*StampIssuerItem) Unmarshal added in v1.17.0 

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

Unmarshal unmarshals a byte slice into a StampIssuerItem.

type Stamper 

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

Stamper can issue stamps from the given address of chunk.

func NewStamper 

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

NewStamper constructs a Stamper.

type Storer 

type Storer interface {
	ChainStateGetter
	CommitmentGetter

	Radius() uint8

	// 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

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

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.