State

State

The state contains information whose cryptographic digest is included in block headers, and thus is necessary for validating new blocks. For instance, the validators set and the results of transactions are never included in blocks, but their Merkle roots are - the state keeps track of them.

Note that the State object itself is an implementation detail, since it is never included in a block or gossipped over the network, and we never compute its hash. Thus we do not include here details of how the State object is persisted or queried. That said, the types it contains are part of the specification, since their Merkle roots are included in blocks and their values are used in validation.

  1. type State struct {
  2.     Version     Version
  3.     LastResults []Result
  4.     AppHash []byte
  6.     LastValidators []Validator
  7.     Validators []Validator
  8.     NextValidators []Validator
  10.     ConsensusParams ConsensusParams
  11. }

Result

  1. type Result struct {
  2.     Code uint32
  3.     Data []byte
  4. }

Result is the result of executing a transaction against the application. It returns a result code and an arbitrary byte array (ie. a return value).

NOTE: the Result needs to be updated to include more fields returned from processing transactions, like gas variables and tags - see issue 1007.

Validator

A validator is an active participant in the consensus with a public key and a voting power. Validator’s also contain an address field, which is a hash digest of the PubKey.

  1. type Validator struct {
  2.     Address     []byte
  3.     PubKey      PubKey
  4.     VotingPower int64
  5. }

When hashing the Validator struct, the address is not included, because it is redundant with the pubkey.

The state.Validators, state.LastValidators, and state.NextValidators, must always by sorted by validator address, so that there is a canonical order for computing the MerkleRoot.

We also define a TotalVotingPower function, to return the total voting power:

  1. func TotalVotingPower(vals []Validators) int64{
  2.     sum := 0
  3.     for v := range vals{
  4.         sum += v.VotingPower
  5.     }
  6.     return sum
  7. }

ConsensusParams

ConsensusParams define various limits for blockchain data structures. Like validator sets, they are set during genesis and can be updated by the application through ABCI. When hashed, only a subset of the params are included, to allow the params to evolve without breaking the header.

  1. type ConsensusParams struct {
  2.     Block
  3.     Evidence
  4.     Validator
  5. }
  7. type hashedParams struct {
  8.     BlockMaxBytes int64
  9.     BlockMaxGas   int64
  10. }
  12. func (params ConsensusParams) Hash() []byte {
  13.     SHA256(hashedParams{
  14.         BlockMaxBytes: params.Block.MaxBytes,
  15.         BlockMaxGas: params.Block.MaxGas,
  16.     })
  17. }
  19. type BlockParams struct {
  20.     MaxBytes        int64
  21.     MaxGas          int64
  22.   TimeIotaMs      int64
  23. }
  25. type EvidenceParams struct {
  26.     MaxAge int64
  27. }
  29. type ValidatorParams struct {
  30.     PubKeyTypes []string
  31. }

Block

The total size of a block is limited in bytes by the ConsensusParams.Block.MaxBytes. Proposed blocks must be less than this size, and will be considered invalid otherwise.

Blocks should additionally be limited by the amount of “gas” consumed by the transactions in the block, though this is not yet implemented.

The minimal time between consecutive blocks is controlled by the ConsensusParams.Block.TimeIotaMs.

Evidence

For evidence in a block to be valid, it must satisfy:

  1. block.Header.Height - evidence.Height < ConsensusParams.Evidence.MaxAge

Validator

Validators from genesis file and ResponseEndBlock must have pubkeys of type ∈ ConsensusParams.Validator.PubKeyTypes.