github.com/KYVENetwork/cometbft/v38@v38.0.3/spec/consensus/evidence.md (about) 1 --- 2 order: 4 3 --- 4 5 # Evidence 6 7 Evidence is an important component of CometBFT's security model. Whilst the core 8 consensus protocol provides correctness gaurantees for state machine replication 9 that can tolerate less than 1/3 failures, the evidence system looks to detect and 10 gossip byzantine faults whose combined power is greater than or equal to 1/3. It is worth noting that 11 the evidence system is designed purely to detect possible attacks, gossip them, 12 commit them on chain and inform the application running on top of CometBFT. 13 Evidence in itself does not punish "bad actors", this is left to the discretion 14 of the application. A common form of punishment is slashing where the validators 15 that were caught violating the protocol have all or a portion of their voting 16 power removed. Evidence, given the assumption that 1/3+ of the network is still 17 byzantine, is susceptible to censorship and should therefore be considered added 18 security on a "best effort" basis. 19 20 This document walks through the various forms of evidence, how they are detected, 21 gossiped, verified and committed. 22 23 > NOTE: Evidence here is internal to CometBFT and should not be confused with 24 > application evidence 25 26 ## Detection 27 28 ### Equivocation 29 30 Equivocation is the most fundamental of byzantine faults. Simply put, to prevent 31 replication of state across all nodes, a validator tries to convince some subset 32 of nodes to commit one block whilst convincing another subset to commit a 33 different block. This is achieved by double voting (hence 34 `DuplicateVoteEvidence`). A successful duplicate vote attack requires greater 35 than 1/3 voting power and a (temporary) network partition between the aforementioned 36 subsets. This is because in consensus, votes are gossiped around. When a node 37 observes two conflicting votes from the same peer, it will use the two votes of 38 evidence and begin gossiping this evidence to other nodes. [Verification](#duplicatevoteevidence) is addressed further down. 39 40 ```go 41 type DuplicateVoteEvidence struct { 42 VoteA Vote 43 VoteB Vote 44 45 // and abci specific fields 46 } 47 ``` 48 49 ### Light Client Attacks 50 51 Light clients also comply with the 1/3+ security model, however, by using a 52 different, more lightweight verification method they are subject to a 53 different kind of 1/3+ attack whereby the byzantine validators could sign an 54 alternative light block that the light client will think is valid. Detection, 55 explained in greater detail 56 [here](../light-client/detection/detection_003_reviewed.md), involves comparison 57 with multiple other nodes in the hope that at least one is "honest". An "honest" 58 node will return a challenging light block for the light client to validate. If 59 this challenging light block also meets the 60 [validation criteria](../light-client/verification/verification_001_published.md) 61 then the light client sends the "forged" light block to the node. 62 [Verification](#lightclientattackevidence) is addressed further down. 63 64 ```go 65 type LightClientAttackEvidence struct { 66 ConflictingBlock LightBlock 67 CommonHeight int64 68 69 // and abci specific fields 70 } 71 ``` 72 73 ## Verification 74 75 If a node receives evidence, it will first try to verify it, then persist it. 76 Evidence of byzantine behavior should only be committed once (uniqueness) and 77 should be committed within a certain period from the point that it occurred 78 (timely). Timelines is defined by the `EvidenceParams`: `MaxAgeNumBlocks` and 79 `MaxAgeDuration`. In Proof of Stake chains where validators are bonded, evidence 80 age should be less than the unbonding period so validators still can be 81 punished. Given these two propoerties the following initial checks are made. 82 83 1. Has the evidence expired? This is done by taking the height of the `Vote` 84 within `DuplicateVoteEvidence` or `CommonHeight` within 85 `LightClientAttakEvidence`. The evidence height is then used to retrieve the 86 header and thus the time of the block that corresponds to the evidence. If 87 `CurrentHeight - MaxAgeNumBlocks > EvidenceHeight` && `CurrentTime - 88 MaxAgeDuration > EvidenceTime`, the evidence is considered expired and 89 ignored. 90 91 2. Has the evidence already been committed? The evidence pool tracks the hash of 92 all committed evidence and uses this to determine uniqueness. If a new 93 evidence has the same hash as a committed one, the new evidence will be 94 ignored. 95 96 ### DuplicateVoteEvidence 97 98 Valid `DuplicateVoteEvidence` must adhere to the following rules: 99 100 - Validator Address, Height, Round and Type must be the same for both votes 101 102 - BlockID must be different for both votes (BlockID can be for a nil block) 103 104 - Validator must have been in the validator set at that height 105 106 - Vote signature must be correctly signed. This also uses `ChainID` so we know 107 that the fault occurred on this chain 108 109 ### LightClientAttackEvidence 110 111 Valid Light Client Attack Evidence must adhere to the following rules: 112 113 - If the header of the light block is invalid, thus indicating a lunatic attack, 114 the node must check that they can use `verifySkipping` from their header at 115 the common height to the conflicting header 116 117 - If the header is valid, then the validator sets are the same and this is 118 either a form of equivocation or amnesia. We therefore check that 2/3 of the 119 validator set also signed the conflicting header. 120 121 - The nodes own header at the same height as the conflicting header must have a 122 different hash to the conflicting header. 123 124 - If the nodes latest header is less in height to the conflicting header, then 125 the node must check that the conflicting block has a time that is less than 126 this latest header (This is a forward lunatic attack). 127 128 ## Gossiping 129 130 If a node verifies evidence it then broadcasts it to all peers, continously sending 131 the same evidence once every 10 seconds until the evidence is seen on chain or 132 expires. 133 134 ## Commiting on Chain 135 136 Evidence takes strict priority over regular transactions, thus a block is filled 137 with evidence first and transactions take up the remainder of the space. To 138 mitigate the threat of an already punished node from spamming the network with 139 more evidence, the size of the evidence in a block can be capped by 140 `EvidenceParams.MaxBytes`. Nodes receiving blocks with evidence will validate 141 the evidence before sending `Prevote` and `Precommit` votes. The evidence pool 142 will usually cache verifications so that this process is much quicker. 143 144 ## Sending Evidence to the Application 145 146 After evidence is committed, the block is then processed by the block executor 147 which delivers the evidence to the application via `EndBlock`. Evidence is 148 stripped of the actual proof, split up per faulty validator and only the 149 validator, height, time and evidence type is sent. 150 151 ```proto 152 enum EvidenceType { 153 UNKNOWN = 0; 154 DUPLICATE_VOTE = 1; 155 LIGHT_CLIENT_ATTACK = 2; 156 } 157 158 message Evidence { 159 EvidenceType type = 1; 160 // The offending validator 161 Validator validator = 2 [(gogoproto.nullable) = false]; 162 // The height when the offense occurred 163 int64 height = 3; 164 // The corresponding time where the offense occurred 165 google.protobuf.Timestamp time = 4 [ 166 (gogoproto.nullable) = false, (gogoproto.stdtime) = true]; 167 // Total voting power of the validator set in case the ABCI application does 168 // not store historical validators. 169 // https://github.com/tendermint/tendermint/issues/4581 170 int64 total_voting_power = 5; 171 } 172 ``` 173 174 `DuplicateVoteEvidence` and `LightClientAttackEvidence` are self-contained in 175 the sense that the evidence can be used to derive the `abci.Evidence` that is 176 sent to the application. Because of this, extra fields are necessary: 177 178 ```go 179 type DuplicateVoteEvidence struct { 180 VoteA *Vote 181 VoteB *Vote 182 183 // abci specific information 184 TotalVotingPower int64 185 ValidatorPower int64 186 Timestamp time.Time 187 } 188 189 type LightClientAttackEvidence struct { 190 ConflictingBlock *LightBlock 191 CommonHeight int64 192 193 // abci specific information 194 ByzantineValidators []*Validator 195 TotalVotingPower int64 196 Timestamp time.Time 197 } 198 ``` 199 200 These ABCI specific fields don't affect validity of the evidence itself but must 201 be consistent amongst nodes and agreed upon on chain. If evidence with the 202 incorrect abci information is sent, a node will create new evidence from it and 203 replace the ABCI fields with the correct information.