kvstore

README

KVStore

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).

Validator set changes are effected using the following transaction format:

"val:pubkeytype1!pubkey1!power1,pubkeytype2!pubkey2!power2,pubkeytype3!pubkey3!power3"

where pubkeyN is a base64-encoded 32-byte key, pubkeytypeN is a string representing the key type, 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
• func InitKVStore(ctx context.Context, app *Application) error
• func MakeValSetChangeTx(v types.ValidatorUpdate) []byte
• func NewRandomTx(size int) []byte
• func NewRandomTxs(n int) [][]byte
• func NewTx(key, value string) []byte
• func NewTxFromID(i int) []byte
• func RandVal() types.ValidatorUpdate
• func RandVals(cnt int) []types.ValidatorUpdate
• type Application
  • func NewApplication(db dbm.DB) *Application
  • func NewInMemoryApplication() *Application
  • func NewPersistentApplication(dbDir string) *Application
  • func (*Application) CheckTx(_ context.Context, req *types.CheckTxRequest) (*types.CheckTxResponse, error)
  • func (app *Application) Close() error
  • func (app *Application) Commit(context.Context, *types.CommitRequest) (*types.CommitResponse, error)
  • func (app *Application) FinalizeBlock(_ context.Context, req *types.FinalizeBlockRequest) (*types.FinalizeBlockResponse, error)
  • func (app *Application) Info(context.Context, *types.InfoRequest) (*types.InfoResponse, error)
  • func (app *Application) InitChain(_ context.Context, req *types.InitChainRequest) (*types.InitChainResponse, error)
  • func (app *Application) PrepareProposal(ctx context.Context, req *types.PrepareProposalRequest) (*types.PrepareProposalResponse, error)
  • func (app *Application) ProcessProposal(ctx context.Context, req *types.ProcessProposalRequest) (*types.ProcessProposalResponse, error)
  • func (app *Application) Query(_ context.Context, reqQuery *types.QueryRequest) (*types.QueryResponse, error)
  • func (app *Application) SetGenBlockEvents()
• type State
  • func (s State) Hash() []byte

Constants

const (
	CodeTypeOK              uint32 = 0
	CodeTypeEncodingError   uint32 = 1
	CodeTypeInvalidTxFormat uint32 = 2
	CodeTypeUnauthorized    uint32 = 3
	CodeTypeExecuted        uint32 = 5
	CodeTypeExpired         uint32 = 5
)

Return codes for the examples.

const (
	ValidatorPrefix        = "val="
	AppVersion      uint64 = 1
)

Functions

func InitKVStore

func InitKVStore(ctx context.Context, app *Application) error

InitKVStore initializes the kvstore app with some data, which allows tests to pass and is fine as long as you don't make any tx that modify the validator state.

func MakeValSetChangeTx

func MakeValSetChangeTx(v types.ValidatorUpdate) []byte

MakeValSetChangeTx creates a transaction to add/remove/update a validator. To remove, set power to 0.

func NewRandomTx

func NewRandomTx(size int) []byte

NewRandomTx creates a new random transaction.

func NewRandomTxs

func NewRandomTxs(n int) [][]byte

NewRandomTxs creates n transactions.

func NewTx

func NewTx(key, value string) []byte

Create a new transaction.

func NewTxFromID

func NewTxFromID(i int) []byte

NewTxFromID creates a new transaction using the given ID.

func RandVal

func RandVal() types.ValidatorUpdate

RandVal creates one random validator, with a key derived from the input value.

func RandVals

func RandVals(cnt int) []types.ValidatorUpdate

RandVals returns a list of cnt validators for initializing the application. Note that the keys are deterministically derived from the index in the array, while the power is random (Change this if not desired).

Types

type Application

type Application struct {
	types.BaseApplication

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

Application is the kvstore state machine. It complies with the abci.Application interface. It takes transactions in the form of key=value and saves them in a database. This is a somewhat trivial example as there is no real state execution.

func NewApplication

func NewApplication(db dbm.DB) *Application

NewApplication creates an instance of the kvstore from the provided database.

func NewInMemoryApplication

func NewInMemoryApplication() *Application

NewInMemoryApplication creates a new application from an in memory database. Nothing will be persisted.

func NewPersistentApplication

func NewPersistentApplication(dbDir string) *Application

NewPersistentApplication creates a new application using the goleveldb database engine.

func (*Application) CheckTx

func (*Application) CheckTx(_ context.Context, req *types.CheckTxRequest) (*types.CheckTxResponse, error)

CheckTx handles inbound transactions or in the case of recheckTx assesses old transaction validity after a state transition. As this is called frequently, it's preferably to keep the check as stateless and as quick as possible. Here we check that the transaction has the correctly key=value format. For the KVStore we check that each transaction has the valid tx format: - Contains one and only one `=` - `=` is not the first or last byte. - if key is `val` that the validator update transaction is also valid.

func (*Application) Close

func (app *Application) Close() error

func (*Application) Commit

func (app *Application) Commit(context.Context, *types.CommitRequest) (*types.CommitResponse, error)

Commit is called after FinalizeBlock and after Tendermint state which includes the updates to AppHash, ConsensusParams and ValidatorSet has occurred. The KVStore persists the validator updates and the new key values.

func (*Application) FinalizeBlock

func (app *Application) FinalizeBlock(_ context.Context, req *types.FinalizeBlockRequest) (*types.FinalizeBlockResponse, error)

FinalizeBlock executes the block against the application state. It punishes validators who equivocated and updates validators according to transactions in a block. The rest of the transactions are regular key value updates and are cached in memory and will be persisted once Commit is called. ConsensusParams are never changed.

func (*Application) Info

func (app *Application) Info(context.Context, *types.InfoRequest) (*types.InfoResponse, error)

Info returns information about the state of the application. This is generally used every time a Tendermint instance begins and let's the application know what Tendermint versions it's interacting with. Based from this information, Tendermint will ensure it is in sync with the application by potentially replaying the blocks it has. If the Application returns a 0 appBlockHeight, Tendermint will call InitChain to initialize the application with consensus related data.

func (*Application) InitChain

func (app *Application) InitChain(_ context.Context, req *types.InitChainRequest) (*types.InitChainResponse, error)

InitChain takes the genesis validators and stores them in the kvstore. It returns the application hash in the case that the application starts prepopulated with values. This method is called whenever a new instance of the application starts (i.e. app height = 0).

func (*Application) PrepareProposal

func (app *Application) PrepareProposal(ctx context.Context, req *types.PrepareProposalRequest) (*types.PrepareProposalResponse, error)

PrepareProposal is called when the node is a proposer. CometBFT stages a set of transactions to the application. As the KVStore has two accepted formats, `:` and `=`, we modify all instances of `:` with `=` to make it consistent. Note: this is quite a trivial example of transaction modification. NOTE: we assume that CometBFT will never provide more transactions than can fit in a block.

func (*Application) ProcessProposal

func (app *Application) ProcessProposal(ctx context.Context, req *types.ProcessProposalRequest) (*types.ProcessProposalResponse, error)

ProcessProposal is called whenever a node receives a complete proposal. It allows the application to validate the proposal. Only validators who can vote will have this method called. For the KVstore we reuse CheckTx.

func (*Application) Query

func (app *Application) Query(_ context.Context, reqQuery *types.QueryRequest) (*types.QueryResponse, error)

Returns an associated value or nil if missing.

func (*Application) SetGenBlockEvents

func (app *Application) SetGenBlockEvents()

type State

type State struct {

	// Size is essentially the amount of transactions that have been processes.
	// This is used for the appHash
	Size   int64 `json:"size"`
	Height int64 `json:"height"`
	// contains filtered or unexported fields
}

func (State) Hash

func (s State) Hash() []byte

Hash returns the hash of the application state. This is computed as the size or number of transactions processed within the state. Note that this isn't a strong guarantee of state machine replication because states could have different kv values but still have the same size. This function is used as the "AppHash".