kvstore

package
v0.0.0-...-be384fd Latest Latest
Warning

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

Go to latest
Published: Feb 8, 2024 License: Apache-2.0 Imports: 30 Imported by: 0

README

KVStore

There are two app's here: the KVStoreApplication and the PersistentKVStoreApplication.

KVStoreApplication

The KVStoreApplication is a simple merkle key-value store. Transactions of the form key=value are stored as key-value pairs in the tree. Transactions without an = sign set the value to the key. The app has no replay protection (other than what the mempool provides).

PersistentKVStoreApplication

The PersistentKVStoreApplication wraps the KVStoreApplication and provides three additional features:

  1. persistence of state across app restarts (using Tendermint's ABCI-Handshake mechanism)
  2. validator set changes

The state is persisted in leveldb along with the last block committed, and the Handshake allows any necessary blocks to be replayed. Validator set changes are effected using the following transaction format:

"val:proTxHash1!pubkey1!power1,proTxHash2!pubkey2!power2,proTxHash3!pubkey3!power3"

where proTxHashN is a base64-encoded 32 byte reference for the validator, pubkeyN is a base64-encoded 48-byte bls12381 key and powerN is a new voting power for the validator with pubkeyN (possibly a new one). To remove a validator from the validator set, set power to 0. There is no sybil protection against new validators joining.

Documentation

Index

Constants

View Source
const PreparePrefix = "prepare"
View Source
const ProtocolVersion uint64 = 0x12345678

Variables

This section is empty.

Functions

This section is empty.

Types

type Application

type Application struct {
	abci.BaseApplication

	// LastCommittedState is last state that was committed by Tenderhellar and finalized with abci.FinalizeBlock()
	LastCommittedState State

	RetainBlocks int64 // blocks to retain after commit (via ResponseCommit.RetainHeight)
	// contains filtered or unexported fields
}

Application is an example implementation of abci.Application.

func NewMemoryApp

func NewMemoryApp(opts ...OptFunc) (*Application, error)

NewMemoryApp creates new Key/value store application that stores data to memory. Data is lost when the app stops. The application can be used for testing or as an example of ABCI implementation. It is possible to alter initial application configs with option functions.

func NewPersistentApp

func NewPersistentApp(cfg Config, opts ...OptFunc) (*Application, error)

NewPersistentApp creates a new kvstore application that uses json file as persistent storage to store state.

func (*Application) AddConsensusParamsUpdate

func (app *Application) AddConsensusParamsUpdate(params types1.ConsensusParams, height int64)

AddConsensusParamsUpdate schedules new consensus params update to be returned at `height` and used at `height+1`. `params` must be a final struct that should be passed to Tenderhellar in ResponsePrepare/ProcessProposal at `height`.

func (*Application) AddValidatorSetUpdate

func (app *Application) AddValidatorSetUpdate(vsu abci.ValidatorSetUpdate, height int64)

AddValidatorSetUpdate schedules new valiudator set update at some height

func (*Application) ApplySnapshotChunk

ApplySnapshotChunk implements ABCI.

func (*Application) CheckTx

CheckTx implements ABCI

func (*Application) Close

func (app *Application) Close() error

Close closes the app gracefully

func (*Application) FinalizeBlock

FinalizeBlock implements ABCI

func (*Application) Info

Info implements ABCI

func (*Application) InitChain

InitChain implements ABCI

func (*Application) ListSnapshots

ListSnapshots implements ABCI.

func (*Application) LoadSnapshotChunk

LoadSnapshotChunk implements ABCI.

func (*Application) OfferSnapshot

OfferSnapshot implements ABCI.

func (*Application) PrepareProposal

PrepareProposal implements ABCI

func (*Application) ProcessProposal

func (*Application) Query

func (app *Application) Query(_ context.Context, reqQuery *abci.RequestQuery) (*abci.ResponseQuery, error)

Query returns an associated value or nil if missing.

func (*Application) SetLastCommittedState

func (app *Application) SetLastCommittedState(state State)

SetLastCommittedState updates a last committed state

type Config

type Config struct {
	// The directory with which state will be persisted in. Usually $HOME/.tendermint/data
	Dir string `toml:"dir"`

	// SnapshotInterval specifies the height interval at which the application
	// will take state sync snapshots. Defaults to 0 (disabled).
	SnapshotInterval uint64 `toml:"snapshot_interval"`

	// RetainBlocks specifies the number of recent blocks to retain. Defaults to
	// 0, which retains all blocks. Must be greater that PersistInterval,
	// SnapshotInterval and EvidenceAgeHeight.
	RetainBlocks int64 `toml:"retain_blocks"`

	// KeyType sets the curve that will be used by validators.
	// Options are ed25519 & secp256k1
	KeyType string `toml:"key_type"`

	// PersistInterval specifies the height interval at which the application
	// will persist state to disk. Defaults to 1 (every height), setting this to
	// 0 disables state persistence.
	PersistInterval uint64 `toml:"persist_interval"`

	// ValidatorUpdates is a map of heights to validator names and their power,
	// and will be returned by the ABCI application. For example, the following
	// changes the power of validator01 and validator02 at height 1000:
	//
	// [validator_update.1000]
	// validator01 = 20
	// validator02 = 10
	//
	// Specifying height 0 returns the validator update during InitChain. The
	// application returns the validator updates as-is, i.e. removing a
	// validator must be done by returning it with power 0, and any validators
	// not specified are not changed.
	//
	// height <-> pubkey <-> voting power
	ValidatorUpdates map[string]map[string]string `toml:"validator_update"`

	// Add artificial delays to each of the main ABCI calls to mimic computation time
	// of the application
	PrepareProposalDelayMS uint64 `toml:"prepare_proposal_delay_ms"`
	ProcessProposalDelayMS uint64 `toml:"process_proposal_delay_ms"`
	CheckTxDelayMS         uint64 `toml:"check_tx_delay_ms"`
	VoteExtensionDelayMS   uint64 `toml:"vote_extension_delay_ms"`
	FinalizeBlockDelayMS   uint64 `toml:"finalize_block_delay_ms"`

	// hellar parameters
	ThesholdPublicKeyUpdate  map[string]string `toml:"threshold_public_key_update"`
	QuorumHashUpdate         map[string]string `toml:"quorum_hash_update"`
	ChainLockUpdates         map[string]string `toml:"chainlock_updates"`
	PrivValServerType        string            `toml:"privval_server_type"`
	InitAppInitialCoreHeight uint32            `toml:"init_app_core_chain_locked_height"`
}

Config allows for the setting of high level parameters for running the e2e Application KeyType and ValidatorUpdates must be the same for all nodes running the same application.

func DefaultConfig

func DefaultConfig(dir string) Config

type ExecTxFunc

type ExecTxFunc func(tx types.Tx, roundState State) (abci.ExecTxResult, error)

ExecTxFunc executes the transaction against some state

type OptFunc

type OptFunc func(app *Application) error

OptFunc is a function that can modify application configuration. Used when creating new application.

func WithCommitVerification

func WithCommitVerification() OptFunc

WithCommitVerification enables commit verification

func WithConfig

func WithConfig(config Config) OptFunc

WithConfig provides Config to new Application

func WithDuplicateRequestDetection

func WithDuplicateRequestDetection(enabled bool) OptFunc

WithDuplicateRequestDetection makes it possible to disable duplicate request detection. (enabled by default)

func WithExecTx

func WithExecTx(execTx ExecTxFunc) OptFunc

WithExecTx provides custom transaction executing function to the Application

func WithLogger

func WithLogger(logger log.Logger) OptFunc

WithLogger sets logger when creating Application

func WithPrepareTxsFunc

func WithPrepareTxsFunc(prepareTxs PrepareTxsFunc) OptFunc

WithPrepareTxsFunc provides custom transaction modification function to the Application

func WithState

func WithState(height int64, appHash []byte) OptFunc

WithState defines last committed state height and apphash of the Application

func WithValidatorSetUpdates

func WithValidatorSetUpdates(validatorSetUpdates map[int64]abci.ValidatorSetUpdate) OptFunc

WithValidatorSetUpdates defines initial validator set when creating Application

func WithVerifyTxFunc

func WithVerifyTxFunc(verifyTx VerifyTxFunc) OptFunc

WithVerifyTxFunc provides custom transaction verification function to the Application

type PrepareTxsFunc

type PrepareTxsFunc func(req abci.RequestPrepareProposal) ([]*abci.TxRecord, error)

PrepareTxsFunc prepares transactions, possibly adding and/or removing some of them

type SnapshotStore

type SnapshotStore struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

SnapshotStore stores state sync snapshots. Snapshots are stored simply as JSON files, and chunks are generated on-the-fly by splitting the JSON data into fixed-size chunks.

func NewSnapshotStore

func NewSnapshotStore(dir string) (*SnapshotStore, error)

NewSnapshotStore creates a new snapshot store.

func (*SnapshotStore) Create

func (s *SnapshotStore) Create(state State) (abci.Snapshot, error)

Create creates a snapshot of the given application state's key/value pairs.

func (*SnapshotStore) List

func (s *SnapshotStore) List() ([]*abci.Snapshot, error)

List lists available snapshots.

func (*SnapshotStore) LoadChunk

func (s *SnapshotStore) LoadChunk(height uint64, version uint32, chunkID []byte) ([]byte, error)

LoadChunk loads a snapshot chunk.

func (*SnapshotStore) Prune

func (s *SnapshotStore) Prune(n int) error

Prune removes old snapshots ensuring only the most recent n snapshots remain

type State

type State interface {
	dbm.DB
	json.Marshaler
	json.Unmarshaler

	// Save writes full content of this state to some output
	Save(output io.Writer) error
	// Load loads state from some input
	Load(from io.Reader) error
	// Copy copies the state to dst
	Copy(dst State) error
	// Close closes the state and frees up resources
	Close() error

	// GetHeight returns height of the state
	GetHeight() int64
	// IncrementHeight increments height by 1, but not lower than initial height.
	IncrementHeight()

	// SetRound sets consensus round for the state
	SetRound(int32)
	// GetRound returns consensus round defined for the state
	GetRound() int32

	// GetAppHash returns app hash for the state. You need to call UpdateAppHash() beforehand.
	GetAppHash() tmbytes.HexBytes

	// UpdateAppHash regenerates apphash for the state. It accepts transactions and tx results from current round.
	// It is deterministic for a given state, txs and txResults.
	UpdateAppHash(lastCommittedState State, txs types1.Txs, txResults []*types.ExecTxResult) error
}

State represents kvstore app state at some height. State can be committed or uncommitted. Caller of State methods should do proper concurrency locking (eg. mutexes)

func NewKvState

func NewKvState(db dbm.DB, initialHeight int64) State

NewKvState creates new, empty, uninitialized kvstore State. Use Copy() to populate.

type StateExport

type StateExport struct {
	Height        *int64            `json:"height,omitempty"`
	InitialHeight *int64            `json:"initial_height,omitempty"`
	AppHash       tmbytes.HexBytes  `json:"app_hash,omitempty"`
	Items         map[string]string `json:"items,omitempty"` // we store items as string-encoded values
}

type StoreFactory

type StoreFactory interface {
	// Reader returns new io.ReadCloser to be used to read data from
	Reader() (io.ReadCloser, error)
	// Writer returns new io.WriteCloser to be used to write data to
	Writer() (io.WriteCloser, error)
}

StoreFactory is a factory that offers a reader to read data from, or writer to write data to it. Not thread-safe - the caller should control concurrency.

func NewFileStore

func NewFileStore(path string) StoreFactory

func NewMemStateStore

func NewMemStateStore() StoreFactory

type TxRecords

type TxRecords struct {
	Size  int64
	Limit int64
	Txs   []*abci.TxRecord
}

Helper struct that controls size of added transactions

func (*TxRecords) Add

Add new transaction if it fits the limit.

Returns action that was taken, as some transactions may be delayed despite provided `tx.Action`. Errors when newly added transaction does not fit the limit.

type VerifyTxFunc

type VerifyTxFunc func(tx types.Tx, typ abci.CheckTxType) (abci.ResponseCheckTx, error)

VerifyTxFunc checks if transaction is correct

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL