common

package
v0.0.0-...-9a6e996 Latest Latest
Warning

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

 Go to latest Published: Oct 31, 2024 License: MIT Imports: 18 Imported by: 28

Documentation

Index

Constants

View Source 
const (
	PathArity256 = PathArity(255)
	PathArity16  = PathArity(15)
	PathArity2   = PathArity(1)
)
View Source 
const (
	EndingNone = PathEndingCode(iota)
	EndingTerminal
	EndingSplit
	EndingExtend
)

Variables

View Source 
var (
	ErrWrongNibble      = errors.New("key16 byte must be less than 0x0F")
	ErrEmpty            = errors.New("encoded key16 can't be empty")
	ErrWrongFormat      = errors.New("encoded key16 wrong format")
	ErrWrongBinaryValue = errors.New("key2 byte must be 1 or 0")
	ErrWrongArity       = errors.New("arity value must be 1, 15 or 255")
)
View Source 
var (
	ErrNotAllBytesConsumed = errors.New("serialization error: not all bytes were consumed")

	// ErrDBUnavailable implementations of KV storage may choose to panic with this error in case the
	// underlying storage is closed or unavailable
	ErrDBUnavailable = errors.New("database is closed or unavailable")
)
View Source 
var AllPathArity = []PathArity{PathArity256, PathArity16, PathArity2}

Functions

func AsKey 

func AsKey(c Serializable) []byte

func Assert 

func Assert(cond bool, format string, args ...any)

func AssertNoError 

func AssertNoError(err error, prefix ...string)

func Blake2b160 

func Blake2b160(data []byte) (ret [20]byte)

func ByteSize 

func ByteSize(s KVIterator) int

ByteSize computes byte size of the serialized key/value iterator assumes 2 bytes per key length and 4 bytes per value length

func CatchPanicOrError 

func CatchPanicOrError(f func() error) error

func CheckNils 

func CheckNils(i1, i2 interface{}) (bool, bool)

CheckNils returns (conclusive comparison result, true) if at least one is nil return (false, false) if both are not nil and can both be safely dereferenced

func CloneBytes 

func CloneBytes(data []byte) []byte

func CommitmentToString 

func CommitmentToString(c Serializable) string

func Concat 

func Concat(par ...interface{}) []byte

Concat concatenates bytes of byte-able objects

func ConcatBytes 

func ConcatBytes(data ...[]byte) []byte

ConcatBytes allocates exact size array

func CopyAll 

func CopyAll(dst KVWriter, src KVIterator)

CopyAll flushes KVIterator to KVWriter. It is up to the iterator correctly stop iterating

func DangerouslyDumpToConsole 

func DangerouslyDumpToConsole(title string, r KVIterator)

func DecodeToUnpackedBytes 

func DecodeToUnpackedBytes(encoded []byte, arity PathArity) ([]byte, error)

func DumpToFile 

func DumpToFile(r KVIterator, fname string) (int, error)

DumpToFile serializes iterator to the file in binary form. The content of the file in general is non-deterministic due to the random order of iteration

func EncodeUnpackedBytes 

func EncodeUnpackedBytes(unpacked []byte, arity PathArity) ([]byte, error)

func ExtractValue 

func ExtractValue(c TCommitment) ([]byte, bool)

func HasWithPrefix 

func HasWithPrefix(r Traversable, prefix []byte) bool

func IsNil 

func IsNil(p interface{}) bool

func KVStreamIteratorToChan 

func KVStreamIteratorToChan(iter KVStreamIterator, ctx context.Context) chan KVPairOrError

KVStreamIteratorToChan makes channel out of KVStreamIterator

func MustBytes 

func MustBytes(o interface{ Write(w io.Writer) error }) []byte

MustBytes most common way of serialization

func MustEncodeUnpackedBytes 

func MustEncodeUnpackedBytes(unpacked []byte, arity PathArity) []byte

func MustSize 

func MustSize(o interface{ Write(w io.Writer) error }) int

MustSize calculates byte size of the serializable object

func MustUint32From4Bytes 

func MustUint32From4Bytes(b []byte) uint32

func NumEntries 

func NumEntries(s KVIterator) int

NumEntries calculates number of key/value pair in the iterator

func PackUnpackedBytes 

func PackUnpackedBytes(unpacked []byte, arity PathArity) ([]byte, error)

func ReadByte 

func ReadByte(r io.Reader) (byte, error)

func ReadBytes16 

func ReadBytes16(r io.Reader) ([]byte, error)

func ReadBytes32 

func ReadBytes32(r io.Reader) ([]byte, error)

func ReadBytes8 

func ReadBytes8(r io.Reader) ([]byte, error)

func ReadUint16 

func ReadUint16(r io.Reader, pval *uint16) error

func ReadUint32 

func ReadUint32(r io.Reader, pval *uint32) error

func RequireErrorWith 

func RequireErrorWith(t *testing.T, err error, fragments ...string)

func RequirePanicOrErrorWith 

func RequirePanicOrErrorWith(t *testing.T, f func() error, fragments ...string)

func Size 

func Size(o interface{ Write(w io.Writer) error }) (int, error)

Size calculates byte size of the serializable object

func Uint16From2Bytes 

func Uint16From2Bytes(b []byte) (uint16, error)

func Uint16To2Bytes 

func Uint16To2Bytes(val uint16) []byte

func Uint32From4Bytes 

func Uint32From4Bytes(b []byte) (uint32, error)

func Uint32To4Bytes 

func Uint32To4Bytes(val uint32) []byte

func UnDumpFromFile 

func UnDumpFromFile(w KVWriter, fname string) (int, error)

UnDumpFromFile restores dumped set of key/value pairs into the key/value writer

func UnpackBytes 

func UnpackBytes(src []byte, arity PathArity) []byte

func WriteByte 

func WriteByte(w io.Writer, val byte) error

func WriteBytes16 

func WriteBytes16(w io.Writer, data []byte) error

func WriteBytes32 

func WriteBytes32(w io.Writer, data []byte) error

func WriteBytes8 

func WriteBytes8(w io.Writer, data []byte) error

func WriteUint16 

func WriteUint16(w io.Writer, val uint16) error

func WriteUint32 

func WriteUint32(w io.Writer, val uint32) error

Types

type BatchedUpdatable 

type BatchedUpdatable interface {
	BatchedWriter() KVBatchedWriter
}

BatchedUpdatable is a KVStore equipped with the batched update capability. You can only update BatchedUpdatable in atomic batches

type BinaryStreamFileIterator 

type BinaryStreamFileIterator struct {
	*BinaryStreamIterator
	// contains filtered or unexported fields
}

func BinaryStreamIteratorFromFile 

func BinaryStreamIteratorFromFile(file *os.File) *BinaryStreamFileIterator

func OpenKVStreamFile 

func OpenKVStreamFile(fname string) (*BinaryStreamFileIterator, error)

OpenKVStreamFile opens existing file with key/value stream for reading

func (*BinaryStreamFileIterator) Close 

func (fs *BinaryStreamFileIterator) Close() error

type BinaryStreamFileWriter 

type BinaryStreamFileWriter struct {
	*BinaryStreamWriter
	// contains filtered or unexported fields
}

func BinaryStreamWriterFromFile 

func BinaryStreamWriterFromFile(file *os.File) *BinaryStreamFileWriter

func CreateKVStreamFile 

func CreateKVStreamFile(fname string) (*BinaryStreamFileWriter, error)

CreateKVStreamFile create a new BinaryStreamFileWriter

func (*BinaryStreamFileWriter) Close 

func (fw *BinaryStreamFileWriter) Close() error

type BinaryStreamIterator 

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

func NewBinaryStreamIterator 

func NewBinaryStreamIterator(r io.Reader) *BinaryStreamIterator

func (BinaryStreamIterator) Iterate 

func (b BinaryStreamIterator) Iterate(fun func(k []byte, v []byte) bool) error

type BinaryStreamWriter 

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

func NewBinaryStreamWriter 

func NewBinaryStreamWriter(w io.Writer) *BinaryStreamWriter

func (*BinaryStreamWriter) Stats 

func (b *BinaryStreamWriter) Stats() (int, int)

func (*BinaryStreamWriter) Write 

func (b *BinaryStreamWriter) Write(key, value []byte) error

type CommitmentModel 

type CommitmentModel interface {
	// PathArity is used by implementations to optimize operations
	PathArity() PathArity
	// EqualCommitments compares two commitments
	EqualCommitments(c1, c2 Serializable) bool
	// NewVectorCommitment creates empty trie_go.VCommitment
	NewVectorCommitment() VCommitment
	// NewTerminalCommitment creates empty trie_go.TCommitment
	NewTerminalCommitment() TCommitment
	// CommitToData calculates terminal commitment to an arbitrary data
	CommitToData([]byte) TCommitment
	// CalcNodeCommitment calculates commitment of the node data
	CalcNodeCommitment(n *NodeData, nodePath []byte) VCommitment
	// UpdateNodeCommitment updates mutable NodeData with the update information.
	// The node commitment value is part of the mutable NodeData.
	// Parameter 'calcDelta' specifies if commitment is calculated
	// from scratch using CalcNodeCommitment, or it can be calculated by applying additive delta
	// I can be used by implementation to optimize the computation of update. For example KZG implementation
	// can be made dramatically faster this way than strictly computing each time whole expensive vector commitment
	// This interface takes into account different ways how updates are propagated in the trie
	UpdateNodeCommitment(mutate *NodeData, childUpdates map[byte]VCommitment, terminal TCommitment, pathFragment, nodePath []byte, calcDelta bool)
	// ForceStoreTerminalWithNode if == true, terminal commitment will always be serialized with the node,
	// otherwise it may be skipped to optimize storage, depending on the trie setting
	ForceStoreTerminalWithNode(c TCommitment) bool
	// AlwaysStoreTerminalWithNode by returning true model signals that it does not optimize value commitments
	AlwaysStoreTerminalWithNode() bool
	// Description return description of the implementation
	Description() string
	// ShortName short name
	ShortName() string
}

CommitmentModel abstracts 256+ Trie logic from the commitment logic/cryptography

type InMemoryKVStore 

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

InMemoryKVStore is thread-safe

func NewInMemoryKVStore 

func NewInMemoryKVStore() *InMemoryKVStore

func (*InMemoryKVStore) BatchedWriter 

func (im *InMemoryKVStore) BatchedWriter() KVBatchedWriter

func (*InMemoryKVStore) Get 

func (im *InMemoryKVStore) Get(k []byte) []byte

func (*InMemoryKVStore) Has 

func (im *InMemoryKVStore) Has(k []byte) bool

func (*InMemoryKVStore) IsClosed 

func (im *InMemoryKVStore) IsClosed() bool

func (*InMemoryKVStore) Iterate 

func (im *InMemoryKVStore) Iterate(f func(k []byte, v []byte) bool)

func (*InMemoryKVStore) IterateKeys 

func (im *InMemoryKVStore) IterateKeys(f func(k []byte) bool)

func (*InMemoryKVStore) Iterator 

func (im *InMemoryKVStore) Iterator(prefix []byte) KVIterator

func (*InMemoryKVStore) Len 

func (im *InMemoryKVStore) Len() int

func (*InMemoryKVStore) Set 

func (im *InMemoryKVStore) Set(k, v []byte)

type KVBatchedWriter 

type KVBatchedWriter interface {
	KVWriter
	Commit() error
}

KVBatchedWriter collects Mutations in the buffer via Set-s to KVWriter and then flushes (applies) it atomically to DB with Commit KVBatchedWriter implementation should be deterministic: the sequence of Set-s to KWWriter exactly determines the sequence, how key/value pairs in the database are updated or deleted (with value == nil)

type KVIterator 

type KVIterator interface {
	KVIteratorBase
	IterateKeys(func(k []byte) bool)
}

KVIterator normally implements iteration over k/v collection with unique keys

type KVIteratorBase 

type KVIteratorBase interface {
	Iterate(func(k, v []byte) bool)
}

KVIteratorBase is an interface to iterate through the collection of key/value pairs, probably with duplicate keys. Order of iteration is NON-DETERMINISTIC in general

type KVPairOrError 

type KVPairOrError struct {
	Key   []byte
	Value []byte
	Err   error
}

func (*KVPairOrError) IsNil 

func (p *KVPairOrError) IsNil() bool

type KVReader 

type KVReader interface {
	// Get retrieves value by key. Returned nil means absence of the key
	Get(key []byte) []byte
	// Has checks presence of the key in the key/value store
	Has(key []byte) bool // for performance
}

KVReader is a key/value reader

func MakeReaderPartition 

func MakeReaderPartition(r KVReader, prefix byte) KVReader

type KVStore 

type KVStore interface {
	KVReader
	KVWriter
}

KVStore is a compound interface for reading and writing

type KVStreamIterator 

type KVStreamIterator interface {
	Iterate(func(k, v []byte) bool) error
}

KVStreamIterator is an interface to iterate stream In general, order is non-deterministic

type KVStreamWriter 

type KVStreamWriter interface {
	// Write writes key/value pair
	Write(key, value []byte) error
	// Stats return num k/v pairs and num bytes so far
	Stats() (int, int)
}

KVStreamWriter represents an interface to write a sequence of key/value pairs

type KVTraversableReader 

type KVTraversableReader interface {
	KVReader
	Traversable
}

func MakeTraversableReaderPartition 

func MakeTraversableReaderPartition(r KVTraversableReader, p byte) KVTraversableReader

type KVWriter 

type KVWriter interface {
	// Set writes new or updates existing key with the value.
	// value == nil means deletion of the key from the store
	Set(key, value []byte)
}

KVWriter is a key/value writer

func MakeWriterPartition 

func MakeWriterPartition(w KVWriter, prefix byte) KVWriter

type Mutations 

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

func NewMutations 

func NewMutations(doubleBookingCallback ...func(error)) *Mutations

func NewMutationsMustNoDoubleBooking 

func NewMutationsMustNoDoubleBooking() *Mutations

func (*Mutations) Apply 

func (m *Mutations) Apply(mut *Mutations)

func (*Mutations) Iterate 

func (m *Mutations) Iterate(fun func(k []byte, v []byte, wasSet bool) bool)

Iterate is special iteration for mutations. It first iterates SET mutations, then DEL mutations On SET mutation, k, v != nil and wasSet = true On DEL mutation, k != nil, v == nil. wasSet is true if value was set before delete, otherwise false The wasSet allows control deletion of keys which must exist in the original state, e.g. UTXO ledger state

func (*Mutations) LenDel 

func (m *Mutations) LenDel() int

func (*Mutations) LenSet 

func (m *Mutations) LenSet() int

func (*Mutations) Set 

func (m *Mutations) Set(k, v []byte)

func (*Mutations) String 

func (m *Mutations) String() string

func (*Mutations) WriteTo 

func (m *Mutations) WriteTo(w KVWriter)

type NodeData 

type NodeData struct {
	PathFragment     []byte
	ChildCommitments map[byte]VCommitment
	Terminal         TCommitment
	// used for immutable only
	// persisted in the key
	Commitment VCommitment
}

NodeData contains all data trie node needs to compute commitment

func NewNodeData 

func NewNodeData() *NodeData

func NodeDataFromBytes 

func NodeDataFromBytes(model CommitmentModel, data []byte, arity PathArity, getValueFunc func(pathFragment []byte) ([]byte, error)) (*NodeData, error)

func (*NodeData) Clone 

func (n *NodeData) Clone() *NodeData

Clone deep copy

func (*NodeData) IterateChildren 

func (n *NodeData) IterateChildren(f func(byte, VCommitment) bool) bool

func (*NodeData) Read 

func (n *NodeData) Read(r io.Reader, model CommitmentModel, arity PathArity, getValue func(pathFragment []byte) ([]byte, error)) error

Read deserialize node data

func (*NodeData) String 

func (n *NodeData) String() string

func (*NodeData) Write 

func (n *NodeData) Write(w io.Writer, arity PathArity, skipTerminal bool) error

Write serialized node data

type PathArity 

type PathArity byte

func (PathArity) IsValidChildIndex 

func (a PathArity) IsValidChildIndex(i int) bool

func (PathArity) NumChildren 

func (a PathArity) NumChildren() int

func (PathArity) PathCommitmentIndex 

func (a PathArity) PathCommitmentIndex() int

func (PathArity) String 

func (a PathArity) String() string

func (PathArity) TerminalCommitmentIndex 

func (a PathArity) TerminalCommitmentIndex() int

func (PathArity) VectorLength 

func (a PathArity) VectorLength() int

type PathEndingCode 

type PathEndingCode byte

PathEndingCode is a tag how trie path ends wrt the trieKey

func (PathEndingCode) String 

func (e PathEndingCode) String() string

type RandStreamIterator 

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

func NewRandStreamIterator 

func NewRandStreamIterator(p ...RandStreamParams) *RandStreamIterator

func (*RandStreamIterator) Iterate 

func (r *RandStreamIterator) Iterate(fun func(k []byte, v []byte) bool) error

type RandStreamParams 

type RandStreamParams struct {
	// Seed for deterministic randomization
	Seed int64
	// NumKVPairs maximum number of key value pairs to generate. 0 means infinite
	NumKVPairs int
	// MaxKey maximum length of key (randomly generated)
	MaxKey int
	// MaxValue maximum length of value (randomly generated)
	MaxValue int
}

RandStreamParams represents parameters of the RandStreamIterator

type Serializable 

type Serializable interface {
	Read(r io.Reader) error
	Write(w io.Writer) error
	Bytes() []byte
	String() string
	AsKey() []byte
}

Serializable is a common interface for serialization of commitment data

type TCommitment 

type TCommitment interface {
	Clone() TCommitment
	ExtractValue() ([]byte, bool)
	Serializable
}

TCommitment represents commitment to the terminal data. Usually it is a hash of the data of a scalar field element

func ReadTerminalCommitment 

func ReadTerminalCommitment(m CommitmentModel, r io.Reader) (TCommitment, error)

func TerminalCommitmentFromBytes 

func TerminalCommitmentFromBytes(m CommitmentModel, data []byte) (TCommitment, error)

type Traversable 

type Traversable interface {
	Iterator(prefix []byte) KVIterator
}

Traversable is an interface which provides with partial iterators

type VCommitment 

type VCommitment interface {
	Clone() VCommitment
	Serializable
}

VCommitment represents interface to the vector commitment. It can be hash, or it can be a curve element

func ReadVectorCommitment 

func ReadVectorCommitment(m CommitmentModel, r io.Reader) (VCommitment, error)

func VectorCommitmentFromBytes 

func VectorCommitmentFromBytes(m CommitmentModel, data []byte) (VCommitment, error)

Source Files

View all Source files

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.