Documentation

Index

Constants

View Source
const (
	// MetricsSubsystem is a subsystem shared by all metrics exposed by this
	// package.
	MetricsSubsystem = "state"
)

Variables

View Source
var InitStateVersion = tmstate.Version{
	Consensus: tmversion.Consensus{
		Block: version.BlockProtocol,
		App:   0,
	},
	Software: version.TMCoreSemVer,
}

    InitStateVersion sets the Consensus.Block and Software versions, but leaves the Consensus.App version blank. The Consensus.App version will be set during the Handshake, once we hear from the app what protocol version it is running.

    Functions

    func ABCIResponsesResultsHash

    func ABCIResponsesResultsHash(ar *tmstate.ABCIResponses) []byte

      ABCIResponsesResultsHash returns the root hash of a Merkle tree of ResponseDeliverTx responses (see ABCIResults.Hash)

      See merkle.SimpleHashFromByteSlices

      func ExecCommitBlock

      func ExecCommitBlock(
      	appConnConsensus proxy.AppConnConsensus,
      	block *types.Block,
      	logger log.Logger,
      	store Store,
      	initialHeight int64,
      ) ([]byte, error)

        ExecCommitBlock executes and commits a block on the proxyApp without validating or mutating the state. It returns the application root hash (result of abci.Commit).

        func MakeGenesisDocFromFile

        func MakeGenesisDocFromFile(genDocFile string) (*types.GenesisDoc, error)

          MakeGenesisDocFromFile reads and unmarshals genesis doc from the given file.

          func MedianTime

          func MedianTime(commit *types.Commit, validators *types.ValidatorSet) time.Time

            MedianTime computes a median time for a given Commit (based on Timestamp field of votes messages) and the corresponding validator set. The computed time is always between timestamps of the votes sent by honest processes, i.e., a faulty processes can not arbitrarily increase or decrease the computed value.

            func TxPostCheck

            func TxPostCheck(state State) mempl.PostCheckFunc

              TxPostCheck returns a function to filter transactions after processing. The function limits the gas wanted by a transaction to the block's maximum total gas.

              func TxPreCheck

              func TxPreCheck(state State) mempl.PreCheckFunc

                TxPreCheck returns a function to filter transactions before processing. The function limits the size of a transaction to the block's maximum data size.

                Types

                type BlockExecutor

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

                  BlockExecutor provides the context and accessories for properly executing a block.

                  func NewBlockExecutor

                  func NewBlockExecutor(
                  	stateStore Store,
                  	logger log.Logger,
                  	proxyApp proxy.AppConnConsensus,
                  	mempool mempl.Mempool,
                  	evpool EvidencePool,
                  	options ...BlockExecutorOption,
                  ) *BlockExecutor

                    NewBlockExecutor returns a new BlockExecutor with a NopEventBus. Call SetEventBus to provide one.

                    func (*BlockExecutor) ApplyBlock

                    func (blockExec *BlockExecutor) ApplyBlock(
                    	state State, blockID types.BlockID, block *types.Block,
                    ) (State, int64, error)

                      ApplyBlock validates the block against the state, executes it against the app, fires the relevant events, commits the app, and saves the new state and responses. It returns the new state and the block height to retain (pruning older blocks). It's the only function that needs to be called from outside this package to process and commit an entire block. It takes a blockID to avoid recomputing the parts hash.

                      func (*BlockExecutor) Commit

                      func (blockExec *BlockExecutor) Commit(
                      	state State,
                      	block *types.Block,
                      	deliverTxResponses []*abci.ResponseDeliverTx,
                      ) ([]byte, int64, error)

                        Commit locks the mempool, runs the ABCI Commit message, and updates the mempool. It returns the result of calling abci.Commit (the AppHash) and the height to retain (if any). The Mempool must be locked during commit and update because state is typically reset on Commit and old txs must be replayed against committed state before new txs are run in the mempool, lest they be invalid.

                        func (*BlockExecutor) CreateProposalBlock

                        func (blockExec *BlockExecutor) CreateProposalBlock(
                        	height int64,
                        	state State, commit *types.Commit,
                        	proposerAddr []byte,
                        ) (*types.Block, *types.PartSet)

                          CreateProposalBlock calls state.MakeBlock with evidence from the evpool and txs from the mempool. The max bytes must be big enough to fit the commit. Up to 1/10th of the block space is allcoated for maximum sized evidence. The rest is given to txs, up to the max gas.

                          func (*BlockExecutor) SetEventBus

                          func (blockExec *BlockExecutor) SetEventBus(eventBus types.BlockEventPublisher)

                            SetEventBus - sets the event bus for publishing block related events. If not called, it defaults to types.NopEventBus.

                            func (*BlockExecutor) Store

                            func (blockExec *BlockExecutor) Store() Store

                            func (*BlockExecutor) ValidateBlock

                            func (blockExec *BlockExecutor) ValidateBlock(state State, block *types.Block) error

                              ValidateBlock validates the given block against the given state. If the block is invalid, it returns an error. Validation does not mutate state, but does require historical information from the stateDB, ie. to verify evidence from a validator at an old height.

                              type BlockExecutorOption

                              type BlockExecutorOption func(executor *BlockExecutor)

                              func BlockExecutorWithMetrics

                              func BlockExecutorWithMetrics(metrics *Metrics) BlockExecutorOption

                              type BlockStore

                              type BlockStore interface {
                              	Base() int64
                              	Height() int64
                              	Size() int64
                              
                              	LoadBaseMeta() *types.BlockMeta
                              	LoadBlockMeta(height int64) *types.BlockMeta
                              	LoadBlock(height int64) *types.Block
                              
                              	SaveBlock(block *types.Block, blockParts *types.PartSet, seenCommit *types.Commit)
                              
                              	PruneBlocks(height int64) (uint64, error)
                              
                              	LoadBlockByHash(hash []byte) *types.Block
                              	LoadBlockPart(height int64, index int) *types.Part
                              
                              	LoadBlockCommit(height int64) *types.Commit
                              	LoadSeenCommit(height int64) *types.Commit
                              }

                                BlockStore defines the interface used by the ConsensusState.

                                type EmptyEvidencePool

                                type EmptyEvidencePool struct{}

                                  EmptyEvidencePool is an empty implementation of EvidencePool, useful for testing. It also complies to the consensus evidence pool interface

                                  func (EmptyEvidencePool) AddEvidence

                                  func (EmptyEvidencePool) AddEvidence(types.Evidence) error

                                  func (EmptyEvidencePool) CheckEvidence

                                  func (EmptyEvidencePool) CheckEvidence(evList types.EvidenceList) error

                                  func (EmptyEvidencePool) PendingEvidence

                                  func (EmptyEvidencePool) PendingEvidence(maxBytes int64) (ev []types.Evidence, size int64)

                                  func (EmptyEvidencePool) ReportConflictingVotes

                                  func (EmptyEvidencePool) ReportConflictingVotes(voteA, voteB *types.Vote)

                                  func (EmptyEvidencePool) Update

                                  type ErrAppBlockHeightTooHigh

                                  type ErrAppBlockHeightTooHigh struct {
                                  	CoreHeight int64
                                  	AppHeight  int64
                                  }

                                  func (ErrAppBlockHeightTooHigh) Error

                                  func (e ErrAppBlockHeightTooHigh) Error() string

                                  type ErrAppBlockHeightTooLow

                                  type ErrAppBlockHeightTooLow struct {
                                  	AppHeight int64
                                  	StoreBase int64
                                  }

                                  func (ErrAppBlockHeightTooLow) Error

                                  func (e ErrAppBlockHeightTooLow) Error() string

                                  type ErrBlockHashMismatch

                                  type ErrBlockHashMismatch struct {
                                  	CoreHash []byte
                                  	AppHash  []byte
                                  	Height   int64
                                  }

                                  func (ErrBlockHashMismatch) Error

                                  func (e ErrBlockHashMismatch) Error() string

                                  type ErrInvalidBlock

                                  type ErrInvalidBlock error

                                  type ErrLastStateMismatch

                                  type ErrLastStateMismatch struct {
                                  	Height int64
                                  	Core   []byte
                                  	App    []byte
                                  }

                                  func (ErrLastStateMismatch) Error

                                  func (e ErrLastStateMismatch) Error() string

                                  type ErrNoABCIResponsesForHeight

                                  type ErrNoABCIResponsesForHeight struct {
                                  	Height int64
                                  }

                                  func (ErrNoABCIResponsesForHeight) Error

                                  type ErrNoConsensusParamsForHeight

                                  type ErrNoConsensusParamsForHeight struct {
                                  	Height int64
                                  }

                                  func (ErrNoConsensusParamsForHeight) Error

                                  type ErrNoValSetForHeight

                                  type ErrNoValSetForHeight struct {
                                  	Height int64
                                  }

                                  func (ErrNoValSetForHeight) Error

                                  func (e ErrNoValSetForHeight) Error() string

                                  type ErrProxyAppConn

                                  type ErrProxyAppConn error

                                  type ErrStateMismatch

                                  type ErrStateMismatch struct {
                                  	Got      *State
                                  	Expected *State
                                  }

                                  func (ErrStateMismatch) Error

                                  func (e ErrStateMismatch) Error() string

                                  type ErrUnknownBlock

                                  type ErrUnknownBlock struct {
                                  	Height int64
                                  }

                                  func (ErrUnknownBlock) Error

                                  func (e ErrUnknownBlock) Error() string

                                  type EvidencePool

                                  type EvidencePool interface {
                                  	PendingEvidence(maxBytes int64) (ev []types.Evidence, size int64)
                                  	AddEvidence(types.Evidence) error
                                  	Update(State, types.EvidenceList)
                                  	CheckEvidence(types.EvidenceList) error
                                  }

                                    EvidencePool defines the EvidencePool interface used by State.

                                    type Metrics

                                    type Metrics struct {
                                    	// Time between BeginBlock and EndBlock.
                                    	BlockProcessingTime metrics.Histogram
                                    }

                                      Metrics contains metrics exposed by this package.

                                      func NopMetrics

                                      func NopMetrics() *Metrics

                                        NopMetrics returns no-op Metrics.

                                        func PrometheusMetrics

                                        func PrometheusMetrics(namespace string, labelsAndValues ...string) *Metrics

                                          PrometheusMetrics returns Metrics build using Prometheus client library. Optionally, labels can be provided along with their values ("foo", "fooValue").

                                          type State

                                          type State struct {
                                          	Version tmstate.Version
                                          
                                          	// immutable
                                          	ChainID       string
                                          	InitialHeight int64 // should be 1, not 0, when starting from height 1
                                          
                                          	// LastBlockHeight=0 at genesis (ie. block(H=0) does not exist)
                                          	LastBlockHeight int64
                                          	LastBlockID     types.BlockID
                                          	LastBlockTime   time.Time
                                          
                                          	// LastValidators is used to validate block.LastCommit.
                                          	// Validators are persisted to the database separately every time they change,
                                          	// so we can query for historical validator sets.
                                          	// Note that if s.LastBlockHeight causes a valset change,
                                          	// we set s.LastHeightValidatorsChanged = s.LastBlockHeight + 1 + 1
                                          	// Extra +1 due to nextValSet delay.
                                          	NextValidators              *types.ValidatorSet
                                          	Validators                  *types.ValidatorSet
                                          	LastValidators              *types.ValidatorSet
                                          	LastHeightValidatorsChanged int64
                                          
                                          	// Consensus parameters used for validating blocks.
                                          	// Changes returned by EndBlock and updated after Commit.
                                          	ConsensusParams                  tmproto.ConsensusParams
                                          	LastHeightConsensusParamsChanged int64
                                          
                                          	// Merkle root of the results from executing prev block
                                          	LastResultsHash []byte
                                          
                                          	// the latest AppHash we've received from calling abci.Commit()
                                          	AppHash []byte
                                          }

                                            State is a short description of the latest committed block of the Tendermint consensus. It keeps all information necessary to validate new blocks, including the last validator set and the consensus params. All fields are exposed so the struct can be easily serialized, but none of them should be mutated directly. Instead, use state.Copy() or state.NextState(...). NOTE: not goroutine-safe.

                                            func MakeGenesisState

                                            func MakeGenesisState(genDoc *types.GenesisDoc) (State, error)

                                              MakeGenesisState creates state from types.GenesisDoc.

                                              func MakeGenesisStateFromFile

                                              func MakeGenesisStateFromFile(genDocFile string) (State, error)

                                                MakeGenesisStateFromFile reads and unmarshals state from the given file.

                                                Used during replay and in tests.

                                                func StateFromProto

                                                func StateFromProto(pb *tmstate.State) (*State, error)

                                                  StateFromProto takes a state proto message & returns the local state type

                                                  func (State) Bytes

                                                  func (state State) Bytes() []byte

                                                    Bytes serializes the State using protobuf. It panics if either casting to protobuf or serialization fails.

                                                    func (State) Copy

                                                    func (state State) Copy() State

                                                      Copy makes a copy of the State for mutating.

                                                      func (State) Equals

                                                      func (state State) Equals(state2 State) bool

                                                        Equals returns true if the States are identical.

                                                        func (State) IsEmpty

                                                        func (state State) IsEmpty() bool

                                                          IsEmpty returns true if the State is equal to the empty State.

                                                          func (State) MakeBlock

                                                          func (state State) MakeBlock(
                                                          	height int64,
                                                          	txs []types.Tx,
                                                          	commit *types.Commit,
                                                          	evidence []types.Evidence,
                                                          	proposerAddress []byte,
                                                          ) (*types.Block, *types.PartSet)

                                                            MakeBlock builds a block from the current state with the given txs, commit, and evidence. Note it also takes a proposerAddress because the state does not track rounds, and hence does not know the correct proposer. TODO: fix this!

                                                            func (*State) ToProto

                                                            func (state *State) ToProto() (*tmstate.State, error)

                                                              ToProto takes the local state type and returns the equivalent proto type

                                                              type Store

                                                              type Store interface {
                                                              	// LoadFromDBOrGenesisFile loads the most recent state.
                                                              	// If the chain is new it will use the genesis file from the provided genesis file path as the current state.
                                                              	LoadFromDBOrGenesisFile(string) (State, error)
                                                              	// LoadFromDBOrGenesisDoc loads the most recent state.
                                                              	// If the chain is new it will use the genesis doc as the current state.
                                                              	LoadFromDBOrGenesisDoc(*types.GenesisDoc) (State, error)
                                                              	// Load loads the current state of the blockchain
                                                              	Load() (State, error)
                                                              	// LoadValidators loads the validator set at a given height
                                                              	LoadValidators(int64) (*types.ValidatorSet, error)
                                                              	// LoadABCIResponses loads the abciResponse for a given height
                                                              	LoadABCIResponses(int64) (*tmstate.ABCIResponses, error)
                                                              	// LoadConsensusParams loads the consensus params for a given height
                                                              	LoadConsensusParams(int64) (tmproto.ConsensusParams, error)
                                                              	// Save overwrites the previous state with the updated one
                                                              	Save(State) error
                                                              	// SaveABCIResponses saves ABCIResponses for a given height
                                                              	SaveABCIResponses(int64, *tmstate.ABCIResponses) error
                                                              	// Bootstrap is used for bootstrapping state when not starting from a initial height.
                                                              	Bootstrap(State) error
                                                              	// PruneStates takes the height from which to start prning and which height stop at
                                                              	PruneStates(int64, int64) error
                                                              }

                                                                Store defines the state store interface

                                                                It is used to retrieve current state and save and load ABCI responses, validators and consensus parameters

                                                                func NewStore

                                                                func NewStore(db dbm.DB) Store

                                                                  NewStore creates the dbStore of the state pkg.

                                                                  Directories

                                                                  Path Synopsis
                                                                  kv