github.com/pure-x-eth/consensus_tm@v0.0.0-20230502163723-e3c2ff987250/spec/core/state.md (about) 1 # State 2 3 The state contains information whose cryptographic digest is included in block headers, and thus is 4 necessary for validating new blocks. For instance, the validators set and the results of 5 transactions are never included in blocks, but their Merkle roots are: 6 the state keeps track of them. 7 8 The `State` object itself is an implementation detail, since it is never 9 included in a block or gossiped over the network, and we never compute 10 its hash. The persistence or query interface of the `State` object 11 is an implementation detail and not included in the specification. 12 However, the types in the `State` object are part of the specification, since 13 the Merkle roots of the `State` objects are included in blocks and values are used during 14 validation. 15 16 ```go 17 type State struct { 18 ChainID string 19 InitialHeight int64 20 21 LastBlockHeight int64 22 LastBlockID types.BlockID 23 LastBlockTime time.Time 24 25 Version Version 26 LastResults []Result 27 AppHash []byte 28 29 LastValidators ValidatorSet 30 Validators ValidatorSet 31 NextValidators ValidatorSet 32 33 ConsensusParams ConsensusParams 34 } 35 ``` 36 37 The chain ID and initial height are taken from the genesis file, and not changed again. The 38 initial height will be `1` in the typical case, `0` is an invalid value. 39 40 Note there is a hard-coded limit of 10000 validators. This is inherited from the 41 limit on the number of votes in a commit. 42 43 Further information on [`Validator`'s](./data_structures.md#validator), 44 [`ValidatorSet`'s](./data_structures.md#validatorset) and 45 [`ConsensusParams`'s](./data_structures.md#consensusparams) can 46 be found in [data structures](./data_structures.md) 47 48 ## Execution 49 50 State gets updated at the end of executing a block. Of specific interest is `ResponseEndBlock` and 51 `ResponseCommit` 52 53 ```go 54 type ResponseEndBlock struct { 55 ValidatorUpdates []ValidatorUpdate `protobuf:"bytes,1,rep,name=validator_updates,json=validatorUpdates,proto3" json:"validator_updates"` 56 ConsensusParamUpdates *types1.ConsensusParams `protobuf:"bytes,2,opt,name=consensus_param_updates,json=consensusParamUpdates,proto3" json:"consensus_param_updates,omitempty"` 57 Events []Event `protobuf:"bytes,3,rep,name=events,proto3" json:"events,omitempty"` 58 } 59 ``` 60 61 where 62 63 ```go 64 type ValidatorUpdate struct { 65 PubKey crypto.PublicKey `protobuf:"bytes,1,opt,name=pub_key,json=pubKey,proto3" json:"pub_key"` 66 Power int64 `protobuf:"varint,2,opt,name=power,proto3" json:"power,omitempty"` 67 } 68 ``` 69 70 and 71 72 ```go 73 type ResponseCommit struct { 74 // reserve 1 75 Data []byte `protobuf:"bytes,2,opt,name=data,proto3" json:"data,omitempty"` 76 RetainHeight int64 `protobuf:"varint,3,opt,name=retain_height,json=retainHeight,proto3" json:"retain_height,omitempty"` 77 } 78 ``` 79 80 `ValidatorUpdates` are used to add and remove validators to the current set as well as update 81 validator power. Setting validator power to 0 in `ValidatorUpdate` will cause the validator to be 82 removed. `ConsensusParams` are safely copied across (i.e. if a field is nil it gets ignored) and the 83 `Data` from the `ResponseCommit` is used as the `AppHash` 84 85 ## Version 86 87 ```go 88 type Version struct { 89 consensus Consensus 90 software string 91 } 92 ``` 93 94 [`Consensus`](./data_structures.md#version) contains the protocol version for the blockchain and the 95 application. 96 97 ## Block 98 99 The total size of a block is limited in bytes by the `ConsensusParams.Block.MaxBytes`. 100 Proposed blocks must be less than this size, and will be considered invalid 101 otherwise. 102 103 Blocks should additionally be limited by the amount of "gas" consumed by the 104 transactions in the block, though this is not yet implemented. 105 106 ## Evidence 107 108 For evidence in a block to be valid, it must satisfy: 109 110 ```go 111 block.Header.Time-evidence.Time < ConsensusParams.Evidence.MaxAgeDuration && 112 block.Header.Height-evidence.Height < ConsensusParams.Evidence.MaxAgeNumBlocks 113 ``` 114 115 A block must not contain more than `ConsensusParams.Evidence.MaxBytes` of evidence. This is 116 implemented to mitigate spam attacks. 117 118 ## Validator 119 120 Validators from genesis file and `ResponseEndBlock` must have pubkeys of type ∈ 121 `ConsensusParams.Validator.PubKeyTypes`.