github.com/badrootd/celestia-core@v0.0.0-20240305091328-aa4207a4b25d/spec/core/data_structures.md (about)

     1  ---
     2  order: 1
     3  ---
     4  
     5  # Data Structures
     6  
     7  Here we describe the data structures in the CometBFT blockchain and the rules for validating them.
     8  
     9  The CometBFT blockchain consists of a short list of data types:
    10  
    11  - [Data Structures](#data-structures)
    12      - [Block](#block)
    13      - [Execution](#execution)
    14      - [Header](#header)
    15      - [Version](#version)
    16      - [BlockID](#blockid)
    17      - [PartSetHeader](#partsetheader)
    18      - [Part](#part)
    19      - [Time](#time)
    20      - [Data](#data)
    21      - [Commit](#commit)
    22      - [CommitSig](#commitsig)
    23      - [BlockIDFlag](#blockidflag)
    24      - [Vote](#vote)
    25      - [CanonicalVote](#canonicalvote)
    26      - [Proposal](#proposal)
    27      - [SignedMsgType](#signedmsgtype)
    28      - [Signature](#signature)
    29      - [EvidenceList](#evidencelist)
    30      - [Evidence](#evidence)
    31          - [DuplicateVoteEvidence](#duplicatevoteevidence)
    32          - [LightClientAttackEvidence](#lightclientattackevidence)
    33      - [LightBlock](#lightblock)
    34      - [SignedHeader](#signedheader)
    35      - [ValidatorSet](#validatorset)
    36      - [Validator](#validator)
    37      - [Address](#address)
    38      - [ConsensusParams](#consensusparams)
    39          - [BlockParams](#blockparams)
    40          - [EvidenceParams](#evidenceparams)
    41          - [ValidatorParams](#validatorparams)
    42          - [VersionParams](#versionparams)
    43      - [Proof](#proof)
    44  
    45  
    46  ## Block
    47  
    48  A block consists of a header, transactions, votes (the commit),
    49  and a list of evidence of malfeasance (ie. signing conflicting votes).
    50  
    51  | Name   | Type              | Description                                                                                                                                                                          | Validation                                               |
    52  |--------|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|
    53  | Header | [Header](#header) | Header corresponding to the block. This field contains information used throughout consensus and other areas of the protocol. To find out what it contains, visit [header](#header) | Must adhere to the validation rules of [header](#header) |
    54  | Data       | [Data](#data)                  | Data contains a list of transactions. The contents of the transaction is unknown to CometBFT.                                                                                      | This field can be empty or populated, but no validation is performed. Applications can perform validation on individual transactions prior to block creation using [checkTx](https://github.com/cometbft/cometbft/blob/v0.34.x/spec/abci/abci%2B%2B_methods.md#checktx).
    55  | Evidence   | [EvidenceList](#evidencelist) | Evidence contains a list of infractions committed by validators.                                                                                                                     | Can be empty, but when populated the validations rules from [evidenceList](#evidencelist) apply |
    56  | LastCommit | [Commit](#commit)              | `LastCommit` includes one vote for every validator.  All votes must either be for the previous block, nil or absent. If a vote is for the previous block it must have a valid signature from the corresponding validator. The sum of the voting power of the validators that voted must be greater than 2/3 of the total voting power of the complete validator set. The number of votes in a commit is limited to 10000 (see `types.MaxVotesCount`).                                                                                             | Must be empty for the initial height and must adhere to the validation rules of [commit](#commit).  |
    57  
    58  ## Execution
    59  
    60  Once a block is validated, it can be executed against the state.
    61  
    62  The state follows this recursive equation:
    63  
    64  ```go
    65  state(initialHeight) = InitialState
    66  state(h+1) <- Execute(state(h), ABCIApp, block(h))
    67  ```
    68  
    69  where `InitialState` includes the initial consensus parameters and validator set,
    70  and `ABCIApp` is an ABCI application that can return results and changes to the validator
    71  set (TODO). Execute is defined as:
    72  
    73  ```go
    74  func Execute(state State, app ABCIApp, block Block) State {
    75   // Function ApplyBlock executes block of transactions against the app and returns the new root hash of the app state,
    76   // modifications to the validator set and the changes of the consensus parameters.
    77   AppHash, ValidatorChanges, ConsensusParamChanges := app.ApplyBlock(block)
    78  
    79   nextConsensusParams := UpdateConsensusParams(state.ConsensusParams, ConsensusParamChanges)
    80   return State{
    81    ChainID:         state.ChainID,
    82    InitialHeight:   state.InitialHeight,
    83    LastResults:     abciResponses.DeliverTxResults,
    84    AppHash:         AppHash,
    85    LastValidators:  state.Validators,
    86    Validators:      state.NextValidators,
    87    NextValidators:  UpdateValidators(state.NextValidators, ValidatorChanges),
    88    ConsensusParams: nextConsensusParams,
    89    Version: {
    90     Consensus: {
    91      AppVersion: nextConsensusParams.Version.AppVersion,
    92     },
    93    },
    94   }
    95  }
    96  ```
    97  
    98  Validating a new block is first done prior to the `prevote`, `precommit` & `finalizeCommit` stages.
    99  
   100  The steps to validate a new block are:
   101  
   102  - Check the validity rules of the block and its fields.
   103  - Check the versions (Block & App) are the same as in local state.
   104  - Check the chainID's match.
   105  - Check the height is correct.
   106  - Check the `LastBlockID` corresponds to BlockID currently in state.
   107  - Check the hashes in the header match those in state.
   108  - Verify the LastCommit against state, this step is skipped for the initial height.
   109      - This is where checking the signatures correspond to the correct block will be made.
   110  - Make sure the proposer is part of the validator set.
   111  - Validate bock time.
   112      - Make sure the new blocks time is after the previous blocks time.
   113      - Calculate the medianTime and check it against the blocks time.
   114      - If the blocks height is the initial height then check if it matches the genesis time.
   115  - Validate the evidence in the block. Note: Evidence can be empty
   116  
   117  ## Header
   118  
   119  A block header contains metadata about the block and about the consensus, as well as commitments to
   120  the data in the current block, the previous block, and the results returned by the application:
   121  
   122  | Name              | Type                      | Description                                                                                                                                                                                                                                                                                                                                                                           | Validation                                                                                                                                                                                       |
   123  |-------------------|---------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
   124  | Version           | [Version](#version)       | Version defines the application and protocol version being used.                                                                                                                                                                                                                                                                                                                       | Must adhere to the validation rules of [Version](#version)                                                                                                                                       |
   125  | ChainID           | String                    | ChainID is the ID of the chain. This must be unique to your chain.                                                                                                                                                                                                                                                                                                                    | ChainID must be less than 50 bytes.                                                                                                                                                              |
   126  | Height            | uint64                     | Height is the height for this header.                                                                                                                                                                                                                                                                                                                                                 | Must be > 0, >= initialHeight, and == previous Height+1                                                                                                                                          |
   127  | Time              | [Time](#time)             | The timestamp is equal to the weighted median of validators present in the last commit. Read more on time in the [BFT-time section](../consensus/bft-time.md). Note: the timestamp of a vote must be greater by at least one millisecond than that of the block being voted on.                                                                                                       | Time must be >= previous header timestamp + consensus parameters TimeIotaMs.  The timestamp of the first block must be equal to the genesis time (since there's no votes to compute the median). |
   128  | LastBlockID       | [BlockID](#blockid)       | BlockID of the previous block.                                                                                                                                                                                                                                                                                                                                                        | Must adhere to the validation rules of [blockID](#blockid). The first block has `block.Header.LastBlockID == BlockID{}`.                                                                         |
   129  | LastCommitHash    | slice of bytes (`[]byte`) | MerkleRoot of the lastCommit's signatures. The signatures represent the validators that committed to the last block. The first block has an empty slices of bytes for the hash.                                                                                                                                                                                                       | Must  be of length 32                                                                                                                                                                            |
   130  | DataHash          | slice of bytes (`[]byte`) | MerkleRoot of the hash of transactions. **Note**: The transactions are hashed before being included in the merkle tree, the leaves of the Merkle tree are the hashes, not the transactions themselves.                                                                                                                                                                                | Must  be of length 32                                                                                                                                                                            |
   131  | ValidatorHash     | slice of bytes (`[]byte`) | MerkleRoot of the current validator set. The validators are first sorted by voting power (descending), then by address (ascending) prior to computing the MerkleRoot.                                                                                                                                                                                                                 | Must  be of length 32                                                                                                                                                                            |
   132  | NextValidatorHash | slice of bytes (`[]byte`) | MerkleRoot of the next validator set. The validators are first sorted by voting power (descending), then by address (ascending) prior to computing the MerkleRoot.                                                                                                                                                                                                                    | Must  be of length 32                                                                                                                                                                            |
   133  | ConsensusHash     | slice of bytes (`[]byte`) | Hash of the protobuf encoded consensus parameters.                                                                                                                                                                                                                                                                                                                                    | Must  be of length 32                                                                                                                                                                            |
   134  | AppHash           | slice of bytes (`[]byte`) | Arbitrary byte array returned by the application after executing and committing the previous block. It serves as the basis for validating any merkle proofs that comes from the ABCI application and represents the state of the actual application rather than the state of the blockchain itself. The first block's `block.Header.AppHash` is given by `ResponseInitChain.app_hash`. | This hash is determined by the application, CometBFT can not perform validation on it.                                                                                                         |
   135  | LastResultHash    | slice of bytes (`[]byte`) | `LastResultsHash` is the root hash of a Merkle tree built from `ResponseDeliverTx` responses (`Log`,`Info`, `Codespace` and `Events` fields are ignored).                                                                                                                                                                                                                             | Must  be of length 32. The first block has `block.Header.ResultsHash == MerkleRoot(nil)`, i.e. the hash of an empty input, for RFC-6962 conformance.                                             |
   136  | EvidenceHash      | slice of bytes (`[]byte`) | MerkleRoot of the evidence of Byzantine behavior included in this block.                                                                                                                                                                                                                                                                                                             | Must  be of length 32                                                                                                                                                                            |
   137  | ProposerAddress   | slice of bytes (`[]byte`) | Address of the original proposer of the block. Validator must be in the current validatorSet.                                                                                                                                                                                                                                                                                         | Must  be of length 20                                                                                                                                                                            |
   138  
   139  ## Version
   140  
   141  NOTE: that this is more specifically the consensus version and doesn't include information like the
   142  P2P Version. (TODO: we should write a comprehensive document about
   143  versioning that this can refer to)
   144  
   145  | Name  | type   | Description                                                                                                     | Validation                                                                                                         |
   146  |-------|--------|-----------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|
   147  | Block | uint64 | This number represents the version of the block protocol and must be the same throughout an operational network | Must be equal to protocol version being used in a network (`block.Version.Block == state.Version.Consensus.Block`) |
   148  | App   | uint64 | App version is decided on by the application. Read [here](https://github.com/cometbft/cometbft/blob/v0.34.x/spec/abci/abci++_app_requirements.md)                                 | `block.Version.App == state.Version.Consensus.App`                                                                 |
   149  
   150  ## BlockID
   151  
   152  The `BlockID` contains two distinct Merkle roots of the block. The `BlockID` includes these two hashes, as well as the number of parts (ie. `len(MakeParts(block))`)
   153  
   154  | Name          | Type                            | Description                                                                                                                                                      | Validation                                                             |
   155  |---------------|---------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------|
   156  | Hash          | slice of bytes (`[]byte`)       | MerkleRoot of all the fields in the header (ie. `MerkleRoot(header)`.                                                                                            | hash must be of length 32                                              |
   157  | PartSetHeader | [PartSetHeader](#partsetheader) | Used for secure gossiping of the block during consensus, is the MerkleRoot of the complete serialized block cut into parts (ie. `MerkleRoot(MakeParts(block))`). | Must adhere to the validation rules of [PartSetHeader](#partsetheader) |
   158  
   159  See [MerkleRoot](./encoding.md#MerkleRoot) for details.
   160  
   161  ## PartSetHeader
   162  
   163  | Name  | Type                      | Description                       | Validation           |
   164  |-------|---------------------------|-----------------------------------|----------------------|
   165  | Total | int32                     | Total amount of parts for a block | Must be > 0          |
   166  | Hash  | slice of bytes (`[]byte`) | MerkleRoot of a serialized block  | Must be of length 32 |
   167  
   168  ## Part
   169  
   170  Part defines a part of a block. In CometBFT blocks are broken into `parts` for gossip.
   171  
   172  | Name  | Type            | Description                       | Validation           |
   173  |-------|-----------------|-----------------------------------|----------------------|
   174  | index | int32           | Total amount of parts for a block | Must be > 0          |
   175  | bytes | bytes           | MerkleRoot of a serialized block  | Must be of length 32 |
   176  | proof | [Proof](#proof) | MerkleRoot of a serialized block  | Must be of length 32 |
   177  
   178  ## Time
   179  
   180  CometBFT uses the [Google.Protobuf.Timestamp](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp)
   181  format, which uses two integers, one 64 bit integer for Seconds and a 32 bit integer for Nanoseconds.
   182  
   183  ## Data
   184  
   185  Data is just a wrapper for a list of transactions, where transactions are arbitrary byte arrays:
   186  
   187  | Name | Type                       | Description            | Validation                                                                  |
   188  |------|----------------------------|------------------------|-----------------------------------------------------------------------------|
   189  | Txs  | Matrix of bytes ([][]byte) | Slice of transactions. | Validation does not occur on this field, this data is unknown to CometBFT |
   190  
   191  ## Commit
   192  
   193  Commit is a simple wrapper for a list of signatures, with one for each validator. It also contains the relevant BlockID, height and round:
   194  
   195  | Name       | Type                             | Description                                                          | Validation                                                                                               |
   196  |------------|----------------------------------|----------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------|
   197  | Height     | uint64                            | Height at which this commit was created.                             | Must be > 0                                                                                              |
   198  | Round      | int32                            | Round that the commit corresponds to.                                | Must be > 0                                                                                              |
   199  | BlockID    | [BlockID](#blockid)              | The blockID of the corresponding block.                              | Must adhere to the validation rules of [BlockID](#blockid).                                              |
   200  | Signatures | Array of [CommitSig](#commitsig) | Array of commit signatures that correspond to current validator set. | Length of signatures must be > 0 and adhere to the validation of each individual [Commitsig](#commitsig) |
   201  
   202  ## CommitSig
   203  
   204  `CommitSig` represents a signature of a validator, who has voted either for nil,
   205  a particular `BlockID` or was absent. It's a part of the `Commit` and can be used
   206  to reconstruct the vote set given the validator set.
   207  
   208  | Name             | Type                        | Description                                                                                                                                                      | Validation                                                        |
   209  |------------------|-----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
   210  | BlockIDFlag      | [BlockIDFlag](#blockidflag) | Represents the validators participation in consensus: its vote was not received, voted for the block that received the majority, or voted for nil | Must be one of the fields in the [BlockIDFlag](#blockidflag) enum |
   211  | ValidatorAddress | [Address](#address)         | Address of the validator                                                                                                                                         | Must be of length 20                                              |
   212  | Timestamp        | [Time](#time)               | This field will vary from `CommitSig` to `CommitSig`. It represents the timestamp of the validator.                                                              | [Time](#time)                                                     |
   213  | Signature        | [Signature](#signature)     | Signature corresponding to the validators participation in consensus.                                                                                            | The length of the signature must be > 0 and < than  64            |
   214  
   215  NOTE: `ValidatorAddress` and `Timestamp` fields may be removed in the future
   216  (see [ADR-25](https://github.com/cometbft/cometbft/blob/v0.34.x/docs/architecture/adr-025-commit.md)).
   217  
   218  ## BlockIDFlag
   219  
   220  BlockIDFlag represents which BlockID the [signature](#commitsig) is for.
   221  
   222  ```go
   223  enum BlockIDFlag {
   224    BLOCK_ID_FLAG_UNKNOWN = 0; // indicates an error condition
   225    BLOCK_ID_FLAG_ABSENT  = 1; // the vote was not received
   226    BLOCK_ID_FLAG_COMMIT  = 2; // voted for the block that received the majority
   227    BLOCK_ID_FLAG_NIL     = 3; // voted for nil
   228  }
   229  ```
   230  
   231  ## Vote
   232  
   233  A vote is a signed message from a validator for a particular block.
   234  The vote includes information about the validator signing it. When stored in the blockchain or propagated over the network, votes are encoded in Protobuf.
   235  
   236  | Name             | Type                            | Description                                                                                 | Validation                                                                                           |
   237  |------------------|---------------------------------|---------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|
   238  | Type             | [SignedMsgType](#signedmsgtype) | Either prevote or precommit. [SignedMsgType](#signedmsgtype)                                | A Vote is valid if its corresponding fields are included in the enum [signedMsgType](#signedmsgtype) |
   239  | Height           | uint64                           | Height for which this vote was created for                                                  | Must be > 0                                                                                          |
   240  | Round            | int32                           | Round that the commit corresponds to.                                                       | Must be > 0                                                                                          |
   241  | BlockID          | [BlockID](#blockid)             | The blockID of the corresponding block.                                                     | [BlockID](#blockid)                                                                                  |
   242  | Timestamp        | [Time](#time)                   | Timestamp represents the time at which a validator signed.                                  | [Time](#time)                                                                                        |
   243  | ValidatorAddress | slice of bytes (`[]byte`)       | Address of the validator                                                                    | Length must be equal to 20                                                                           |
   244  | ValidatorIndex   | int32                           | Index at a specific block height that corresponds to the Index of the validator in the set. | must be > 0                                                                                          |
   245  | Signature        | slice of bytes (`[]byte`)       | Signature by the validator if they participated in consensus for the associated bock.       | Length of signature must be > 0 and < 64                                                             |
   246  
   247  ## CanonicalVote
   248  
   249  CanonicalVote is for validator signing. This type will not be present in a block. Votes are represented via `CanonicalVote` and also encoded using protobuf via `type.SignBytes` which includes the `ChainID`, and uses a different ordering of
   250  the fields.
   251  
   252  ```proto
   253  message CanonicalVote {
   254    SignedMsgType             type      = 1;
   255    fixed64                  height    = 2;
   256    sfixed64                  round     = 3;
   257    CanonicalBlockID          block_id  = 4;
   258    google.protobuf.Timestamp timestamp = 5;
   259    string                    chain_id  = 6;
   260  }
   261  ```
   262  
   263  For signing, votes are represented via [`CanonicalVote`](#canonicalvote) and also encoded using protobuf via
   264  `type.SignBytes` which includes the `ChainID`, and uses a different ordering of
   265  the fields.
   266  
   267  We define a method `Verify` that returns `true` if the signature verifies against the pubkey for the `SignBytes`
   268  using the given ChainID:
   269  
   270  ```go
   271  func (vote *Vote) Verify(chainID string, pubKey crypto.PubKey) error {
   272   if !bytes.Equal(pubKey.Address(), vote.ValidatorAddress) {
   273    return ErrVoteInvalidValidatorAddress
   274   }
   275   v := vote.ToProto()
   276   if !pubKey.VerifyBytes(types.VoteSignBytes(chainID, v), vote.Signature) {
   277    return ErrVoteInvalidSignature
   278   }
   279   return nil
   280  }
   281  ```
   282  
   283  ## Proposal
   284  
   285  Proposal contains height and round for which this proposal is made, BlockID as a unique identifier
   286  of proposed block, timestamp, and POLRound (a so-called Proof-of-Lock (POL) round) that is needed for
   287  termination of the consensus. If POLRound >= 0, then BlockID corresponds to the block that
   288  is locked in POLRound. The message is signed by the validator private key.
   289  
   290  | Name      | Type                            | Description                                                                           | Validation                                              |
   291  |-----------|---------------------------------|---------------------------------------------------------------------------------------|---------------------------------------------------------|
   292  | Type      | [SignedMsgType](#signedmsgtype) | Represents a Proposal [SignedMsgType](#signedmsgtype)                                 | Must be `ProposalType`  [signedMsgType](#signedmsgtype) |
   293  | Height    | uint64                           | Height for which this vote was created for                                            | Must be > 0                                             |
   294  | Round     | int32                           | Round that the commit corresponds to.                                                 | Must be > 0                                             |
   295  | POLRound  | int64                           | Proof of lock                                                                         | Must be > 0                                             |
   296  | BlockID   | [BlockID](#blockid)             | The blockID of the corresponding block.                                               | [BlockID](#blockid)                                     |
   297  | Timestamp | [Time](#time)                   | Timestamp represents the time at which a validator signed.                            | [Time](#time)                                           |
   298  | Signature | slice of bytes (`[]byte`)       | Signature by the validator if they participated in consensus for the associated bock. | Length of signature must be > 0 and < 64                |
   299  
   300  ## SignedMsgType
   301  
   302  Signed message type represents a signed messages in consensus.
   303  
   304  ```proto
   305  enum SignedMsgType {
   306  
   307    SIGNED_MSG_TYPE_UNKNOWN = 0;
   308    // Votes
   309    SIGNED_MSG_TYPE_PREVOTE   = 1;
   310    SIGNED_MSG_TYPE_PRECOMMIT = 2;
   311  
   312    // Proposal
   313    SIGNED_MSG_TYPE_PROPOSAL = 32;
   314  }
   315  ```
   316  
   317  ## Signature
   318  
   319  Signatures in CometBFT are raw bytes representing the underlying signature.
   320  
   321  See the [signature spec](./encoding.md#key-types) for more.
   322  
   323  ## EvidenceList
   324  
   325  EvidenceList is a simple wrapper for a list of evidence:
   326  
   327  | Name     | Type                           | Description                            | Validation                                                      |
   328  |----------|--------------------------------|----------------------------------------|-----------------------------------------------------------------|
   329  | Evidence | Array of [Evidence](#evidence) | List of verified [evidence](#evidence) | Validation adheres to individual types of [Evidence](#evidence) |
   330  
   331  ## Evidence
   332  
   333  Evidence in CometBFT is used to indicate breaches in the consensus by a validator.
   334  
   335  More information on how evidence works in CometBFT can be found [here](../consensus/evidence.md)
   336  
   337  ### DuplicateVoteEvidence
   338  
   339  `DuplicateVoteEvidence` represents a validator that has voted for two different blocks
   340  in the same round of the same height. Votes are lexicographically sorted on `BlockID`.
   341  
   342  | Name             | Type          | Description                                                        | Validation                                          |
   343  |------------------|---------------|--------------------------------------------------------------------|-----------------------------------------------------|
   344  | VoteA            | [Vote](#vote) | One of the votes submitted by a validator when they equivocated    | VoteA must adhere to [Vote](#vote) validation rules |
   345  | VoteB            | [Vote](#vote) | The second vote submitted by a validator when they equivocated     | VoteB must adhere to [Vote](#vote) validation rules |
   346  | TotalVotingPower | int64         | The total power of the validator set at the height of equivocation | Must be equal to nodes own copy of the data         |
   347  | ValidatorPower   | int64         | Power of the equivocating validator at the height                  | Must be equal to the nodes own copy of the data     |
   348  | Timestamp        | [Time](#time) | Time of the block where the equivocation occurred                  | Must be equal to the nodes own copy of the data     |
   349  
   350  ### LightClientAttackEvidence
   351  
   352  `LightClientAttackEvidence` is a generalized evidence that captures all forms of known attacks on
   353  a light client such that a full node can verify, propose and commit the evidence on-chain for
   354  punishment of the malicious validators. There are three forms of attacks: Lunatic, Equivocation
   355  and Amnesia. These attacks are exhaustive. You can find a more detailed overview of this [here](../light-client/accountability#the_misbehavior_of_faulty_validators)
   356  
   357  | Name                 | Type                               | Description                                                          | Validation                                                       |
   358  |----------------------|------------------------------------|----------------------------------------------------------------------|------------------------------------------------------------------|
   359  | ConflictingBlock     | [LightBlock](#lightblock)          | Read Below                                                           | Must adhere to the validation rules of [lightBlock](#lightblock) |
   360  | CommonHeight         | int64                              | Read Below                                                           | must be > 0                                                      |
   361  | Byzantine Validators | Array of [Validators](#validator) | validators that acted maliciously                                    | Read Below                                                       |
   362  | TotalVotingPower     | int64                              | The total power of the validator set at the height of the infraction | Must be equal to the nodes own copy of the data                  |
   363  | Timestamp            | [Time](#time)                      | Time of the block where the infraction occurred                      | Must be equal to the nodes own copy of the data                  |
   364  
   365  ## LightBlock
   366  
   367  LightBlock is the core data structure of the [light client](../light-client/README.md). It combines two data structures needed for verification ([signedHeader](#signedheader) & [validatorSet](#validatorset)).
   368  
   369  | Name         | Type                          | Description                                                                                                                            | Validation                                                                          |
   370  |--------------|-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|
   371  | SignedHeader | [SignedHeader](#signedheader) | The header and commit, these are used for verification purposes. To find out more visit [light client docs](../light-client/README.md) | Must not be nil and adhere to the validation rules of [signedHeader](#signedheader) |
   372  | ValidatorSet | [ValidatorSet](#validatorset) | The validatorSet is used to help with verify that the validators in that committed the infraction were truly in the validator set.     | Must not be nil and adhere to the validation rules of [validatorSet](#validatorset) |
   373  
   374  The `SignedHeader` and `ValidatorSet` are linked by the hash of the validator set(`SignedHeader.ValidatorsHash == ValidatorSet.Hash()`.
   375  
   376  ## SignedHeader
   377  
   378  The SignedhHeader is the [header](#header) accompanied by the commit to prove it.
   379  
   380  | Name   | Type              | Description       | Validation                                                                        |
   381  |--------|-------------------|-------------------|-----------------------------------------------------------------------------------|
   382  | Header | [Header](#header) | [Header](#header) | Header cannot be nil and must adhere to the [Header](#header) validation criteria |
   383  | Commit | [Commit](#commit) | [Commit](#commit) | Commit cannot be nil and must adhere to the [Commit](#commit) criteria            |
   384  
   385  ## ValidatorSet
   386  
   387  | Name       | Type                             | Description                                        | Validation                                                                                                        |
   388  |------------|----------------------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|
   389  | Validators | Array of [validator](#validator) | List of the active validators at a specific height | The list of validators can not be empty or nil and must adhere to the validation rules of [validator](#validator) |
   390  | Proposer   | [validator](#validator)          | The block proposer for the corresponding block     | The proposer cannot be nil and must adhere to the validation rules of  [validator](#validator)                    |
   391  
   392  ## Validator
   393  
   394  | Name             | Type                      | Description                                                                                       | Validation                                        |
   395  |------------------|---------------------------|---------------------------------------------------------------------------------------------------|---------------------------------------------------|
   396  | Address          | [Address](#address)       | Validators Address                                                                                | Length must be of size 20                         |
   397  | Pubkey           | slice of bytes (`[]byte`) | Validators Public Key                                                                             | must be a length greater than 0                   |
   398  | VotingPower      | int64                     | Validators voting power                                                                           | cannot be < 0                                     |
   399  | ProposerPriority | int64                     | Validators proposer priority. This is used to gauge when a validator is up next to propose blocks | No validation, value can be negative and positive |
   400  
   401  ## Address
   402  
   403  Address is a type alias of a slice of bytes. The address is calculated by hashing the public key using sha256 and truncating it to only use the first 20 bytes of the slice.
   404  
   405  ```go
   406  const (
   407    TruncatedSize = 20
   408  )
   409  
   410  func SumTruncated(bz []byte) []byte {
   411    hash := sha256.Sum256(bz)
   412    return hash[:TruncatedSize]
   413  }
   414  ```
   415  
   416  ## ConsensusParams
   417  
   418  | Name      | Type                                | Description                                                                  | Field Number |
   419  |-----------|-------------------------------------|------------------------------------------------------------------------------|--------------|
   420  | block     | [BlockParams](#blockparams)         | Parameters limiting the size of a block and time between consecutive blocks. | 1            |
   421  | evidence  | [EvidenceParams](#evidenceparams)   | Parameters limiting the validity of evidence of byzantine behavior.         | 2            |
   422  | validator | [ValidatorParams](#validatorparams) | Parameters limiting the types of public keys validators can use.             | 3            |
   423  | version   | [BlockParams](#blockparams)         | The ABCI application version.                                                | 4            |
   424  
   425  ### BlockParams
   426  
   427  | Name         | Type  | Description                                                                                                                                                                                                 | Field Number |
   428  |--------------|-------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
   429  | max_bytes    | int64 | Max size of a block, in bytes.                                                                                                                                                                              | 1            |
   430  | max_gas      | int64 | Max sum of `GasWanted` in a proposed block. NOTE: blocks that violate this may be committed if there are Byzantine proposers. It's the application's responsibility to handle this when processing a block! | 2            |
   431  
   432  ### EvidenceParams
   433  
   434  | Name               | Type                                                                                                                               | Description                                                                                                                                                                                                                                                                    | Field Number |
   435  |--------------------|------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
   436  | max_age_num_blocks | int64                                                                                                                              | Max age of evidence, in blocks.                                                                                                                                                                                                                                                | 1            |
   437  | max_age_duration   | [google.protobuf.Duration](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Duration) | Max age of evidence, in time. It should correspond with an app's "unbonding period" or other similar mechanism for handling [Nothing-At-Stake attacks](https://github.com/ethereum/wiki/wiki/Proof-of-Stake-FAQ#what-is-the-nothing-at-stake-problem-and-how-can-it-be-fixed). | 2            |
   438  | max_bytes          | int64                                                                                                                              | maximum size in bytes of total evidence allowed to be entered into a block                                                                                                                                                                                                     | 3            |
   439  
   440  ### ValidatorParams
   441  
   442  | Name          | Type            | Description                                                           | Field Number |
   443  |---------------|-----------------|-----------------------------------------------------------------------|--------------|
   444  | pub_key_types | repeated string | List of accepted public key types. Uses same naming as `PubKey.Type`. | 1            |
   445  
   446  ### VersionParams
   447  
   448  | Name        | Type   | Description                   | Field Number |
   449  |-------------|--------|-------------------------------|--------------|
   450  | app_version | uint64 | The ABCI application version. | 1            |
   451  
   452  ## Proof
   453  
   454  | Name      | Type           | Description                                   | Field Number |
   455  |-----------|----------------|-----------------------------------------------|--------------|
   456  | total     | int64          | Total number of items.                        | 1            |
   457  | index     | int64          | Index item to prove.                          | 2            |
   458  | leaf_hash | bytes          | Hash of item value.                           | 3            |
   459  | aunts     | repeated bytes | Hashes from leaf's sibling to a root's child. | 4            |