voucher

package
v0.9.3 Latest Latest
Warning

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

 Go to latest Published: Apr 10, 2023 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 (b *NoOpBatchStore) Unreserve(UnreserveIteratorFn) error

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

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.