github.com/badrootd/celestia-core@v0.0.0-20240305091328-aa4207a4b25d/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  Blocks should additionally be limited by the amount of "gas" consumed by the
   108  transactions in the block, though this is not yet implemented.
   109  
   110  ## Evidence
   111  
   112  For evidence in a block to be valid, it must satisfy:
   113  
   114  ```go
   115  block.Header.Time-evidence.Time < ConsensusParams.Evidence.MaxAgeDuration &&
   116   block.Header.Height-evidence.Height < ConsensusParams.Evidence.MaxAgeNumBlocks
   117  ```
   118  
   119  A block must not contain more than `ConsensusParams.Evidence.MaxBytes` of evidence. This is
   120  implemented to mitigate spam attacks.
   121  
   122  ## Validator
   123  
   124  Validators from genesis file and `ResponseEndBlock` must have pubkeys of type ∈
   125  `ConsensusParams.Validator.PubKeyTypes`.