voucher

package
v0.9.0 Latest Latest
Warning

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

Go to latest
Published: Nov 4, 2022 License: BSD-3-Clause Imports: 13 Imported by: 0

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 BNB Smart Chain
	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 voucher batch, a payment on the blockchain.

func (*Batch) MarshalBinary

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

MarshalBinary implements BinaryMarshaller. It will attempt to serialize the voucher 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

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

type BatchExpiryHandler

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

type ChainSnapshot

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 voucher events between the FirstBlockNumber and LastBlockNumber. The timestamp stores the time at which the snapshot was generated. This snapshot can be used to chainsync the voucher package to prevent large no. of chain backend calls.

type ChainState

type ChainState struct {
	Block        uint64   // The block number of the last voucher event.
	TotalAmount  *big.Int // Cumulative amount paid per stamp.
	CurrentPrice *big.Int // Mop/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 []byte) error
	TopUp(id []byte, topUpAmount, normalisedBalance *big.Int, txHash []byte) error
	UpdateDepth(id []byte, depth uint8, normalisedBalance *big.Int, txHash []byte) error
	UpdatePrice(price *big.Int, txHash []byte) error
	UpdateBlockNumber(blockNumber uint64) error
	Start(startBlock uint64, initState *ChainSnapshot, interrupt chan struct{}) error

	TransactionStart() error
	TransactionEnd() error
}

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

type Listener

type Listener interface {
	io.Closer
	Listen(from uint64, updater EventUpdater, initState *ChainSnapshot) <-chan error
}

Listener provides a blockchain event iterator.

type NoOpBatchStore

type NoOpBatchStore struct{}

NoOpBatchStore is a placeholder implementation for voucher.Storer

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

func (b *NoOpBatchStore) GetReserveState() *ReserveState

func (*NoOpBatchStore) Iterate

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

func (*NoOpBatchStore) PutChainState

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

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

func (b *NoOpBatchStore) SetStorageRadiusSetter(StorageRadiusSetter)

func (*NoOpBatchStore) Unreserve

func (*NoOpBatchStore) Update

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

type ReserveState

type ReserveState struct {
	Radius        uint8
	StorageRadius uint8
}

type ReserveStateGetter

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, error)
	IssuerUsable(*StampIssuer) bool
	BatchEventListener
	BatchExpiryHandler
	io.Closer
}

Service is the voucher service interface.

func NewService

func NewService(store storage.StateStorer, voucherStore Storer, chainID int64) (Service, error)

NewService constructs a new Service.

type Stamp

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

Stamp represents a voucher 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

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

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 cluster.Address, ownerAddr []byte, depth, bucketDepth uint8, immutable bool) error

Valid checks the validity of the voucher 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

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

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

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

func (si *StampIssuer) SetExpired()

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(cluster.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

type StorageRadiusSetter interface {
	SetStorageRadius(uint8)
}

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

type Storer

type Storer interface {
	ReserveStateGetter

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

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

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

type ValidStampFn

type ValidStampFn func(chunk cluster.Chunk, stampBytes []byte) (cluster.Chunk, error)

func ValidStamp

func ValidStamp(batchStore Storer) ValidStampFn

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

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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