Documentation ¶
Index ¶
- Constants
- Variables
- type Batch
- type BatchEventListener
- 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) SetRadiusSetter(RadiusSetter)
- func (b *NoOpBatchStore) Unreserve(UnreserveIteratorFn) error
- func (b *NoOpBatchStore) Update(*Batch, *big.Int, uint8) error
- type RadiusSetter
- type ReserveState
- 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 swarm.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) ID() []byte
- func (si *StampIssuer) ImmutableFlag() bool
- func (si *StampIssuer) Label() string
- func (si *StampIssuer) MarshalBinary() ([]byte, error)
- func (si *StampIssuer) UnmarshalBinary(data []byte) error
- func (si *StampIssuer) Utilization() uint32
- type Stamper
- 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 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) StorageRadius uint8 // storage radius }
Batch represents a postage batch, a payment on the blockchain.
func (*Batch) MarshalBinary ¶
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)|StorageRadius(1)
func (*Batch) UnmarshalBinary ¶
UnmarshalBinary implements BinaryUnmarshaller. It will attempt deserialize the given byte slice into the batch.
type BatchEventListener ¶ added in v1.2.0
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 EventUpdater ¶
type EventUpdater interface { Create(id []byte, owner []byte, normalisedBalance *big.Int, depth, bucketDepth uint8, immutable bool, txHash []byte) error TopUp(id []byte, 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) (<-chan error, 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, 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) Exists ¶ added in v1.6.2
func (b *NoOpBatchStore) Exists([]byte) (bool, error)
func (*NoOpBatchStore) GetChainState ¶ added in v1.6.2
func (b *NoOpBatchStore) GetChainState() *ChainState
func (*NoOpBatchStore) GetReserveState ¶ added in v1.6.2
func (b *NoOpBatchStore) GetReserveState() *ReserveState
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) 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) SetRadiusSetter ¶ added in v1.6.2
func (b *NoOpBatchStore) SetRadiusSetter(RadiusSetter)
func (*NoOpBatchStore) Unreserve ¶ added in v1.6.2
func (b *NoOpBatchStore) Unreserve(UnreserveIteratorFn) error
type RadiusSetter ¶
type RadiusSetter interface {
SetRadius(uint8)
}
RadiusSetter is used as a callback when the radius of a node changes.
type ReserveState ¶
type Service ¶
type Service interface { Add(*StampIssuer) error StampIssuers() []*StampIssuer GetStampIssuer([]byte) (*StampIssuer, error) IssuerUsable(*StampIssuer) bool BatchEventListener io.Closer }
Service is the postage service interface.
func NewService ¶
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 (*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 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 inc() 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) 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) 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 Storer ¶
type Storer interface { // 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 // GetReserveState returns a copy of stored reserve state. GetReserveState() *ReserveState // SetRadiusSetter sets the RadiusSetter to the given value. // The given RadiusSetter will be called when radius changes. SetRadiusSetter(RadiusSetter) // 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 }
Storer represents the persistence layer for batches on the current (highest available) block.
type UnreserveIteratorFn ¶ added in v1.0.0
UnreserveIteratorFn is used as a callback on Storer.Unreserve method calls.
type ValidStampFn ¶ added in v1.1.0
func ValidStamp ¶
func ValidStamp(batchStore Storer) ValidStampFn
ValidStamp returns a stampvalidator function passed to protocols with chunk entrypoints.