Documentation ¶
Index ¶
- Constants
- Variables
- type Batch
- type BatchEventListener
- type BatchExpiryHandler
- type ChainSnapshot
- type ChainState
- type EventUpdater
- type Listener
- type NoOpBatchStore
- func (b *NoOpBatchStore) Exists([]byte) (bool, error)
- func (b *NoOpBatchStore) Get([]byte) (*Batch, error)
- func (b *NoOpBatchStore) GetChainState() *ChainState
- func (b *NoOpBatchStore) GetReserveState() *ReserveState
- func (b *NoOpBatchStore) Iterate(func(*Batch) (bool, error)) error
- func (b *NoOpBatchStore) PutChainState(*ChainState) error
- func (b *NoOpBatchStore) Reset() error
- func (b *NoOpBatchStore) Save(*Batch) error
- func (b *NoOpBatchStore) SetBatchExpiryHandler(BatchExpiryHandler)
- func (b *NoOpBatchStore) SetStorageRadius(func(uint8) uint8) error
- func (b *NoOpBatchStore) SetStorageRadiusSetter(StorageRadiusSetter)
- func (b *NoOpBatchStore) Unreserve(UnreserveIteratorFn) error
- func (b *NoOpBatchStore) Update(*Batch, *big.Int, uint8) error
- type ReserveState
- type ReserveStateGetter
- type Service
- type Stamp
- func (s *Stamp) BatchID() []byte
- func (s *Stamp) Index() []byte
- func (s *Stamp) MarshalBinary() ([]byte, error)
- func (s *Stamp) Sig() []byte
- func (s *Stamp) Timestamp() []byte
- func (s *Stamp) UnmarshalBinary(buf []byte) error
- func (s *Stamp) Valid(chunkAddr cluster.Address, ownerAddr []byte, depth, bucketDepth uint8, ...) error
- type StampIssuer
- func (si *StampIssuer) Amount() *big.Int
- func (si *StampIssuer) BlockNumber() uint64
- func (si *StampIssuer) BucketDepth() uint8
- func (si *StampIssuer) BucketUpperBound() uint32
- func (si *StampIssuer) Buckets() []uint32
- func (si *StampIssuer) Depth() uint8
- func (si *StampIssuer) Expired() bool
- func (si *StampIssuer) ID() []byte
- func (si *StampIssuer) ImmutableFlag() bool
- func (si *StampIssuer) Label() string
- func (si *StampIssuer) MarshalBinary() ([]byte, error)
- func (si *StampIssuer) SetExpired()
- func (si *StampIssuer) UnmarshalBinary(data []byte) error
- func (si *StampIssuer) Utilization() uint32
- type Stamper
- type StorageRadiusSetter
- type Storer
- type UnreserveIteratorFn
- type ValidStampFn
Constants ¶
const ( StampSize = 113 IndexSize = 8 BucketDepth = 16 )
StampSize is the number of bytes in the serialisation of a stamp
Variables ¶
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") )
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") )
var ( // ErrBucketFull is the error when a collision bucket is full. ErrBucketFull = errors.New("bucket full") )
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 ¶
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 ¶
UnmarshalBinary implements BinaryUnmarshaller. It will attempt deserialize the given byte slice into the batch.
type BatchEventListener ¶
type BatchExpiryHandler ¶
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) GetChainState ¶
func (b *NoOpBatchStore) GetChainState() *ChainState
func (*NoOpBatchStore) GetReserveState ¶
func (b *NoOpBatchStore) GetReserveState() *ReserveState
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
type ReserveState ¶
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 ¶
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 (*Stamp) MarshalBinary ¶
MarshalBinary gives the byte slice serialisation of a stamp: batchID[32]|index[8]|timestamp[8]|Signature[65].
func (*Stamp) UnmarshalBinary ¶
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) 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 ¶
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 ¶
UnreserveIteratorFn is used as a callback on Storer.Unreserve method calls.
type ValidStampFn ¶
func ValidStamp ¶
func ValidStamp(batchStore Storer) ValidStampFn
ValidStamp returns a stampvalidator function passed to protocols with chunk entrypoints.