github.com/aakash4dev/cometbft@v0.38.2/spec/core/state.md (about)

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