# x/evidence
# Abstract
x/evidence is an implementation of a Cosmos SDK module, per ADR 009 (opens new window),
that allows for the submission and handling of arbitrary evidence of misbehavior such
as equivocation and counterfactual signing.
The evidence module differs from standard evidence handling which typically expects the underlying consensus engine, e.g. Tendermint, to automatically submit evidence when it is discovered by allowing clients and foreign chains to submit more complex evidence directly.
All concrete evidence types must implement the Evidence interface contract. Submitted
Evidence is first routed through the evidence module's Router in which it attempts
to find a corresponding registered Handler for that specific Evidence type.
Each Evidence type must have a Handler registered with the evidence module's
keeper in order for it to be successfully routed and executed.
Each corresponding handler must also fulfill the Handler interface contract. The
Handler for a given Evidence type can perform any arbitrary state transitions
such as slashing, jailing, and tombstoning.
# Concepts
# Evidence
Any concrete type of evidence submitted to the x/evidence module must fulfill the
Evidence contract outlined below. Not all concrete types of evidence will fulfill
this contract in the same way and some data may be entirely irrelevant to certain
types of evidence. An additional ValidatorEvidence, which extends Evidence,
has also been created to define a contract for evidence against malicious validators.
# Registration & Handling
The x/evidence module must first know about all types of evidence it is expected
to handle. This is accomplished by registering the Route method in the Evidence
contract with what is known as a Router (defined below). The Router accepts
Evidence and attempts to find the corresponding Handler for the Evidence
via the Route method.
The Handler (defined below) is responsible for executing the entirety of the
business logic for handling Evidence. This typically includes validating the
evidence, both stateless checks via ValidateBasic and stateful checks via any
keepers provided to the Handler. In addition, the Handler may also perform
capabilities such as slashing and jailing a validator. All Evidence handled
by the Handler should be persisted.
# State
Currently the x/evidence module only stores valid submitted Evidence in state.
The evidence state is also stored and exported in the x/evidence module's GenesisState.
All Evidence is retrieved and stored via a prefix KVStore using prefix 0x00 (KeyPrefixEvidence).
# Messages
# MsgSubmitEvidence
Evidence is submitted through a MsgSubmitEvidence message:
Note, the Evidence of a MsgSubmitEvidence message must have a corresponding
Handler registered with the x/evidence module's Router in order to be processed
and routed correctly.
Given the Evidence is registered with a corresponding Handler, it is processed
as follows:
First, there must not already exist valid submitted Evidence of the exact same
type. Secondly, the Evidence is routed to the Handler and executed. Finally,
if there is no error in handling the Evidence, an event is emitted and it is persisted to state.
# Events
The x/evidence module emits the following events:
# Handlers
# MsgSubmitEvidence
| Type | Attribute Key | Attribute Value |
|---|---|---|
| submit_evidence | evidence_hash | |
| message | module | evidence |
| message | sender | |
| message | action | submit_evidence |
# Parameters
The evidence module does not contain any parameters.
# BeginBlock
# Evidence Handling
Tendermint blocks can include
Evidence (opens new window) that indicates if a validator committed malicious behavior. The relevant information is forwarded to the application as ABCI Evidence in abci.RequestBeginBlock so that the validator can be punished accordingly.
# Equivocation
The Cosmos SDK handles two types of evidence inside the ABCI BeginBlock:
DuplicateVoteEvidence,LightClientAttackEvidence.
The evidence module handles these two evidence types the same way. First, the Cosmos SDK converts the Tendermint concrete evidence type to an SDK Evidence interface using Equivocation as the concrete type.
For some Equivocation submitted in block to be valid, it must satisfy:
Evidence.Timestamp >= block.Timestamp - MaxEvidenceAge
Where:
Evidence.Timestampis the timestamp in the block at heightEvidence.Heightblock.Timestampis the current block timestamp.
If valid Equivocation evidence is included in a block, the validator's stake is
reduced (slashed) by SlashFractionDoubleSign as defined by the x/slashing module
of what their stake was when the infraction occurred, rather than when the evidence was discovered.
We want to "follow the stake", i.e., the stake that contributed to the infraction
should be slashed, even if it has since been redelegated or started unbonding.
In addition, the validator is permanently jailed and tombstoned to make it impossible for that validator to ever re-enter the validator set.
The Equivocation evidence is handled as follows:
Note: The slashing, jailing, and tombstoning calls are delegated through the x/slashing module
that emits informative events and finally delegates calls to the x/staking module. See documentation
on slashing and jailing in State Transitions.
# Client
# CLI
A user can query and interact with the evidence module using the CLI.
# Query
The query commands allows users to query evidence state.
# evidence
The evidence command allows users to list all evidence or evidence by hash.
Usage:
To query evidence by hash
Example:
Example Output:
To get all evidence
Example:
Example Output:
# REST
A user can query the evidence module using REST endpoints.
# Evidence
Get evidence by hash
Example:
Example Output:
# All evidence
Get all evidence
Example:
Example Output:
# gRPC
A user can query the evidence module using gRPC endpoints.
# Evidence
Get evidence by hash
Example:
Example Output:
# All evidence
Get all evidence
Example:
Example Output: