store

Documentation

Overview

Package store implements KVStore getters and setters for various types.

Numerical getters and setters have a minimum value of zero, which will be interpreted as follows:

• Setters clear a KVStore entry when setting to exactly zero.
• Getters panic on unmarshal error, and interpret empty data as zero.

All functions which can fail require an errField parameter which is used when creating error messages. For example, the errField "balance" could appear in errors like "-12: cannot set negative balance". These errFields are cosmetic and do not affect the stored data (key or value) in any way.

Index

• func DeleteByPrefixStore(store sdk.KVStore)
• func GetAddress(store sdk.KVStore, key []byte) sdk.AccAddress
• func GetBinValue[TPtr PtrBinMarshalable[T], T any](store sdk.KVStore, key []byte, errField string) (TPtr, error)
• func GetDec(store sdk.KVStore, key []byte, errField string) (sdk.Dec, bool)
• func GetInt(store sdk.KVStore, key []byte, errField string) (sdkmath.Int, bool)
• func GetInteger[T Integer](store sdk.KVStore, key []byte) (T, bool)
• func GetTimeMs(store sdk.KVStore, key []byte) (time.Time, bool)
• func GetValue[TPtr PtrMarshalable[T], T any](store sdk.KVStore, key []byte, errField string) TPtr
• func GetValueCdc(store sdk.KVStore, cdc codec.Codec, key []byte, object codec.ProtoMarshaler, ...) bool
• func Int(bz []byte, errField string) sdkmath.Int
• func Iterate(store sdk.KVStore, prefix []byte, cb func(key, val []byte) error) error
• func IteratePaginated(store sdk.KVStore, prefix []byte, page, limit uint, ...) error
• func LoadAll[TPtr PtrMarshalable[T], T any](s storetypes.KVStore, prefix []byte) ([]T, error)
• func LoadAllDecCoins(iter db.Iterator, prefixLen int) (sdk.DecCoins, error)
• func MustLoadAll[TPtr PtrMarshalable[T], T any](s storetypes.KVStore, prefix []byte) []T
• func SetAddress(store sdk.KVStore, key []byte, val sdk.AccAddress)
• func SetBinValue[T BinMarshalable](store sdk.KVStore, key []byte, value T, errField string) error
• func SetDec(store sdk.KVStore, key []byte, val sdk.Dec, errField string) error
• func SetInt(store sdk.KVStore, key []byte, val sdkmath.Int, errField string) error
• func SetInteger[T Integer](store sdk.KVStore, key []byte, v T)
• func SetTimeMs(store sdk.KVStore, key []byte, t time.Time)
• func SetValue[T Marshalable](store sdk.KVStore, key []byte, value T, errField string) error
• func SetValueCdc(store sdk.KVStore, cdc codec.Codec, key []byte, object codec.ProtoMarshaler, ...) error
• func SumCoins(s storetypes.KVStore, f StrExtractor) sdk.Coins
• type BinMarshalable
• type Integer
• type Marshalable
• type PtrBinMarshalable
• type PtrMarshalable
• type StrExtractor

Functions

func DeleteByPrefixStore

func DeleteByPrefixStore(store sdk.KVStore)

DeleteByPrefixStore will delete all keys stored in prefix store

func GetAddress

func GetAddress(store sdk.KVStore, key []byte) sdk.AccAddress

GetAddress retrieves an sdk.AccAddress from a KVStore, or an empty address if no value is stored. Accepts an additional string which should describe the field being retrieved in custom error messages.

func GetBinValue

func GetBinValue[TPtr PtrBinMarshalable[T], T any](store sdk.KVStore, key []byte, errField string) (TPtr, error)

GetBinValue is similar to GetValue (loads value in the store), but uses UnmarshalBinary interface instead of protobuf

func GetDec

func GetDec(store sdk.KVStore, key []byte, errField string) (sdk.Dec, bool)

GetDec retrieves an sdk.Dec from a KVStore, or returns (0, false) if no value is stored. Accepts an additional string which should describe the field being retrieved in custom error messages.

func GetInt

func GetInt(store sdk.KVStore, key []byte, errField string) (sdkmath.Int, bool)

GetInt retrieves an sdkmath.Int from a KVStore, or returns (0, false) if no value is stored. It panics if a stored value fails to unmarshal or is negative. Accepts an additional string which should describe the field being retrieved in custom error messages.

func GetInteger

func GetInteger[T Integer](store sdk.KVStore, key []byte) (T, bool)

func GetTimeMs

func GetTimeMs(store sdk.KVStore, key []byte) (time.Time, bool)

GetTimeMs retrieves time saved as Unix time in Miliseconds. If the value is not in the store, returns (0 unix time, false).

func GetValue

func GetValue[TPtr PtrMarshalable[T], T any](store sdk.KVStore, key []byte, errField string) TPtr

GetValue loads value from the store using default Unmarshaler. Panics on failure to decode. Returns nil if the key is not found in the store. If the value contains codec.Any field, then SetObject MUST be used instead.

func GetValueCdc

func GetValueCdc(store sdk.KVStore, cdc codec.Codec, key []byte, object codec.ProtoMarshaler, errField string) bool

GetValueCdc is similar to GetValue, but uses codec for marshaling. For Protobuf objects the result is the same, unless codec.Any is used. In the latter case this function MUST be used, instead of GetValue. Returns a boolean indicating whether any data was found. If the return is false, the object is not changed by this function.

func Int

func Int(bz []byte, errField string) sdkmath.Int

Int converts bytes to sdk.Int, and panics on failure or negative value with a message which includes the name of the value being retrieved

func Iterate

func Iterate(store sdk.KVStore, prefix []byte, cb func(key, val []byte) error) error

Iterate through all keys in a kvStore that start with a given prefix using a provided function. If the provided function returns an error, iteration stops and the error is returned.

func IteratePaginated

func IteratePaginated(store sdk.KVStore, prefix []byte, page, limit uint, cb func(key, val []byte) error) error

IteratePaginated through keys in a kvStore that start with a given prefix using a provided function. If the provided function returns an error, iteration stops and the error is returned. Accepts pagination parameters: limit defines a number of keys per page, and page indicates what page to skip to when iterating. For example, page = 3 and limit = 10 will iterate over the 21st - 30th keys that would be found by a non-paginated iterator.

func LoadAll

func LoadAll[TPtr PtrMarshalable[T], T any](s storetypes.KVStore, prefix []byte) ([]T, error)

LoadAll iterates over all records in the prefix store and unmarshals value into the list.

func LoadAllDecCoins

func LoadAllDecCoins(iter db.Iterator, prefixLen int) (sdk.DecCoins, error)

LoadAllDecCoins iterates over all records in the prefix store and unmarshals value into the dec coin list.

func MustLoadAll

func MustLoadAll[TPtr PtrMarshalable[T], T any](s storetypes.KVStore, prefix []byte) []T

MustLoadAll executes LoadAll and panics on error

func SetAddress

func SetAddress(store sdk.KVStore, key []byte, val sdk.AccAddress)

SetAddress stores an sdk.AccAddress in a KVStore, or clears if setting to an empty or nil address. Accepts an additional string which should describe the field being set in custom error messages.

func SetBinValue

func SetBinValue[T BinMarshalable](store sdk.KVStore, key []byte, value T, errField string) error

SetBinValue is similar to SetValue (stores value in the store), but uses UnmarshalBinary interface instead of protobuf

func SetDec

func SetDec(store sdk.KVStore, key []byte, val sdk.Dec, errField string) error

SetDec stores an sdk.Dec in a KVStore, or clears if setting to zero or nil. Returns an error serialization failure. Accepts an additional string which should describe the field being set in custom error messages.

func SetInt

func SetInt(store sdk.KVStore, key []byte, val sdkmath.Int, errField string) error

SetInt stores an sdkmath.Int in a KVStore, or clears if setting to zero or nil. Returns an error on serialization error. Accepts an additional string which should describe the field being set in custom error messages.

func SetInteger

func SetInteger[T Integer](store sdk.KVStore, key []byte, v T)

func SetTimeMs

func SetTimeMs(store sdk.KVStore, key []byte, t time.Time)

SetTimeMs saves time as Unix time in Miliseconds.

func SetValue

func SetValue[T Marshalable](store sdk.KVStore, key []byte, value T, errField string) error

SetValue saves value in the store using default Marshaler. Returns error in case of marshaling failure. If the value contains codec.Any field, then SetObject MUST be used instead.

func SetValueCdc

func SetValueCdc(store sdk.KVStore, cdc codec.Codec, key []byte, object codec.ProtoMarshaler, errField string) error

SetValueCdc is similar to the SetValue, but uses codec for marshaling. For Protobuf objects the result is the same, unless codec.Any is used. In the latter case this function MUST be used, instead of SetValue.

func SumCoins

func SumCoins(s storetypes.KVStore, f StrExtractor) sdk.Coins

SumCoins aggregates all coins saved as (denom: Int) pairs in store. Use store/prefix.NewStore to create a prefix store which will automatically look only at the given prefix.

Types

type BinMarshalable

type BinMarshalable interface {
	MarshalBinary() ([]byte, error)
	UnmarshalBinary(data []byte) error
}

type Integer

type Integer interface {
	~int32 | ~int64 | ~uint32 | ~uint64 | byte
}

type Marshalable

type Marshalable interface {
	Marshal() ([]byte, error)
	MarshalTo(data []byte) (n int, err error)
	Unmarshal(data []byte) error
}

type PtrBinMarshalable

type PtrBinMarshalable[T any] interface {
	BinMarshalable
	*T
}

type PtrMarshalable

type PtrMarshalable[T any] interface {
	Marshalable
	*T
}

type StrExtractor

type StrExtractor func([]byte) string

StrExtractor is a function type which will take a bytes string value and extracts string out of it.