state

Documentation

Index

• Constants
• func MarshalUnitData(u types.UnitData) ([]byte, error)
• func NewStateNodeCounter() *stateNodeCounter
• type Action
  • func AddUnit(id types.UnitID, data types.UnitData) Action
  • func AddUnitWithLock(id types.UnitID, data types.UnitData, l []byte) Action
  • func DeleteUnit(id types.UnitID) Action
  • func SetStateLock(id types.UnitID, stateLockTx []byte) Action
  • func UpdateUnitData(id types.UnitID, f UpdateFunction) Action
• type CRC32Reader
  • func NewCRC32Reader(reader io.Reader, checksumLength int) *CRC32Reader
  • func (c *CRC32Reader) Read(p []byte) (n int, err error)
  • func (c *CRC32Reader) Sum() uint32
• type CRC32Writer
  • func NewCRC32Writer(writer io.Writer) *CRC32Writer
  • func (c *CRC32Writer) Sum() uint32
  • func (c *CRC32Writer) Write(p []byte) (n int, err error)
• type Index
  • func CreateIndex[T comparable](s *State, ke KeyExtractor[T]) (Index[T], error)
• type KeyExtractor
• type Log
  • func (l *Log) Clone() *Log
  • func (l *Log) Hash(algorithm crypto.Hash) ([]byte, error)
• type Option
  • func WithHashAlgorithm(hashAlgorithm crypto.Hash) Option
• type Options
• type ShardState
• type State
  • func NewEmptyState(opts ...Option) *State
  • func NewRecoveredState(stateData io.Reader, udc UnitDataConstructor, opts ...Option) (*State, error)
  • func (s *State) AddUnitLog(id types.UnitID, transactionRecordHash []byte) error
  • func (s *State) Apply(actions ...Action) error
  • func (s *State) CalculateRoot() (uint64, []byte, error)
  • func (s *State) Clone() *State
  • func (s *State) Commit(uc *types.UnicityCertificate) error
  • func (s *State) CommittedUC() *types.UnicityCertificate
  • func (s *State) CreateIndex(ke KeyExtractor[string]) (Index[string], error)
  • func (s *State) CreateUnitStateProof(id types.UnitID, logIndex int) (*types.UnitStateProof, error)
  • func (s *State) GetUnit(id types.UnitID, committed bool) (*Unit, error)
  • func (s *State) HashAlgorithm() crypto.Hash
  • func (s *State) IsCommitted() bool
  • func (s *State) Prune() error
  • func (s *State) ReleaseToSavepoint(id int)
  • func (s *State) Revert()
  • func (s *State) RollbackToSavepoint(id int)
  • func (s *State) Savepoint() int
  • func (s *State) Serialize(writer io.Writer, committed bool) error
  • func (s *State) Size() (uint64, error)
  • func (s *State) Traverse(traverser avl.Traverser[types.UnitID, *Unit]) error
• type Unit
  • func NewUnit(data types.UnitData) *Unit
  • func (u *Unit) Clone() *Unit
  • func (u *Unit) Data() types.UnitData
  • func (u *Unit) IsStateLocked() bool
  • func (u *Unit) LastLogIndex() int
  • func (u *Unit) Logs() []*Log
  • func (u *Unit) StateLockTx() []byte
  • func (u *Unit) String() string
• type UnitDataConstructor
• type UpdateFunction

Constants

const CBORChecksumLength = 5

Functions

func MarshalUnitData

func MarshalUnitData(u types.UnitData) ([]byte, error)

func NewStateNodeCounter

func NewStateNodeCounter() *stateNodeCounter

Types

type Action

type Action func(s ShardState, hashAlgorithm crypto.Hash) error

func AddUnit

func AddUnit(id types.UnitID, data types.UnitData) Action

AddUnit adds a new unit with given identifier, owner predicate, unit data.

func AddUnitWithLock

func AddUnitWithLock(id types.UnitID, data types.UnitData, l []byte) Action

AddUnitWithLock adds a new unit with given identifier, owner predicate, unit data and lock.

func DeleteUnit

func DeleteUnit(id types.UnitID) Action

DeleteUnit removes the unit from the state with given identifier.

func SetStateLock

func SetStateLock(id types.UnitID, stateLockTx []byte) Action

SetStateLock sets new state lock or removes the existing one and increments counter

func UpdateUnitData

func UpdateUnitData(id types.UnitID, f UpdateFunction) Action

UpdateUnitData changes the data of the item, leaves owner as is.

type CRC32Reader

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

func NewCRC32Reader

func NewCRC32Reader(reader io.Reader, checksumLength int) *CRC32Reader

func (*CRC32Reader) Read

func (c *CRC32Reader) Read(p []byte) (n int, err error)

A hacky way to calculate the checksum of a data stream that has checksum appended to the end. Makes sure that the last checksumLength bytes are not included in the checksum calculation.

func (*CRC32Reader) Sum

func (c *CRC32Reader) Sum() uint32

type CRC32Writer

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

func NewCRC32Writer

func NewCRC32Writer(writer io.Writer) *CRC32Writer

func (*CRC32Writer) Sum

func (c *CRC32Writer) Sum() uint32

func (*CRC32Writer) Write

func (c *CRC32Writer) Write(p []byte) (n int, err error)

type Index

type Index[T comparable] map[T][]types.UnitID

stateIndexer traverses the state tree and constructs an index using the keyExtractor

func CreateIndex

func CreateIndex[T comparable](s *State, ke KeyExtractor[T]) (Index[T], error)

type KeyExtractor

type KeyExtractor[T comparable] func(unit *Unit) (T, error)

stateIndexer traverses the state tree and constructs an index using the keyExtractor

type Log

type Log struct {
	TxRecordHash       []byte // the hash of the transaction record that brought the unit to the state described by given log entry.
	UnitLedgerHeadHash []byte // the new head hash of the unit ledger
	NewUnitData        types.UnitData
	NewStateLockTx     []byte
}

Log contains a state changes of the unit during the transaction execution.

func (*Log) Clone

func (l *Log) Clone() *Log

func (*Log) Hash

func (l *Log) Hash(algorithm crypto.Hash) ([]byte, error)

type Option

type Option func(o *Options)

func WithHashAlgorithm

func WithHashAlgorithm(hashAlgorithm crypto.Hash) Option

type Options

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

type ShardState

type ShardState interface {
	Add(id types.UnitID, u *Unit) error
	Get(id types.UnitID) (*Unit, error)
	Update(id types.UnitID, unit *Unit) error
	Delete(id types.UnitID) error
}

type State

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

State is a data structure that keeps track of units, unit ledgers, and calculates global state tree root hash.

State can be changed by calling Apply function with one or more Action function. Savepoint method can be used to add a special marker to the state that allows all actions that are executed after savepoint was established to be rolled back. In the other words, savepoint lets you roll back part of the state changes instead of the entire state. Releasing a savepoint does NOT trigger a state root hash calculation. To calculate the root hash of the state use method CalculateRoot. Calling a Commit method commits and releases all savepoints.

func NewEmptyState

func NewEmptyState(opts ...Option) *State

func NewRecoveredState

func NewRecoveredState(stateData io.Reader, udc UnitDataConstructor, opts ...Option) (*State, error)

func (*State) AddUnitLog

func (s *State) AddUnitLog(id types.UnitID, transactionRecordHash []byte) error

func (*State) Apply

func (s *State) Apply(actions ...Action) error

Apply applies given actions to the state. All Action functions are executed together as a single atomic operation. If any of the Action functions returns an error all previous state changes made by any of the action function will be reverted.

func (*State) CalculateRoot

func (s *State) CalculateRoot() (uint64, []byte, error)

func (*State) Clone

func (s *State) Clone() *State

Clone returns a clone of the state. The original state and the cloned state can be used by different goroutines but can never be merged. The cloned state is usually used by read only operations (e.g. unit proof generation).

func (*State) Commit

func (s *State) Commit(uc *types.UnicityCertificate) error

Commit makes the changes in the latest savepoint permanent.

func (*State) CommittedUC

func (s *State) CommittedUC() *types.UnicityCertificate

CommittedUC returns the Unicity Certificate of the committed state.

func (*State) CreateIndex

func (s *State) CreateIndex(ke KeyExtractor[string]) (Index[string], error)

func (*State) CreateUnitStateProof

func (s *State) CreateUnitStateProof(id types.UnitID, logIndex int) (*types.UnitStateProof, error)

func (*State) GetUnit

func (s *State) GetUnit(id types.UnitID, committed bool) (*Unit, error)

func (*State) HashAlgorithm

func (s *State) HashAlgorithm() crypto.Hash

func (*State) IsCommitted

func (s *State) IsCommitted() bool

func (*State) Prune

func (s *State) Prune() error

func (*State) ReleaseToSavepoint

func (s *State) ReleaseToSavepoint(id int)

ReleaseToSavepoint destroys all savepoints, keeping all state changes after it was created. If a savepoint with given id does not exist then this method does nothing.

Releasing savepoints does NOT trigger a state root hash calculation. To calculate the root hash of the state a Commit method must be called.

func (*State) Revert

func (s *State) Revert()

Revert rolls back all changes made to the state.

func (*State) RollbackToSavepoint

func (s *State) RollbackToSavepoint(id int)

RollbackToSavepoint destroys savepoints without keeping the changes in the state tree. All actions that were executed after the savepoint was established are rolled back, restoring the state to what it was at the time of the savepoint.

func (*State) Savepoint

func (s *State) Savepoint() int

Savepoint creates a new savepoint and returns an id of the savepoint. Use RollbackToSavepoint to roll back all changes made after calling Savepoint method. Use ReleaseToSavepoint to save all changes made to the state.

func (*State) Serialize

func (s *State) Serialize(writer io.Writer, committed bool) error

Serialize writes the current committed state to the given writer. Not concurrency safe. Should clone the state before calling this.

func (*State) Size

func (s *State) Size() (uint64, error)

func (*State) Traverse

func (s *State) Traverse(traverser avl.Traverser[types.UnitID, *Unit]) error

type Unit

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

Unit is a node in the state tree. It is used to build state tree and unit ledgers.

func NewUnit

func NewUnit(data types.UnitData) *Unit

func (*Unit) Clone

func (u *Unit) Clone() *Unit

func (*Unit) Data

func (u *Unit) Data() types.UnitData

func (*Unit) IsStateLocked

func (u *Unit) IsStateLocked() bool

func (*Unit) LastLogIndex

func (u *Unit) LastLogIndex() int

func (*Unit) Logs

func (u *Unit) Logs() []*Log

func (*Unit) StateLockTx

func (u *Unit) StateLockTx() []byte

func (*Unit) String

func (u *Unit) String() string

type UnitDataConstructor

type UnitDataConstructor func(types.UnitID) (types.UnitData, error)

UnitDataConstructor is a function that constructs an empty UnitData structure based on UnitID

type UpdateFunction

type UpdateFunction func(data types.UnitData) (newData types.UnitData, err error)

UpdateFunction is a function for updating the data of an item. Taken in previous UnitData and returns new UnitData.