github.com/aakash4dev/cometbft@v0.38.2/evidence/doc.go (about)

     1  /*
     2  Package evidence handles all evidence storage and gossiping from detection to block proposal.
     3  For the different types of evidence refer to the `evidence.go` file in the types package
     4  or https://github.com/aakash4dev/cometbft/blob/main/spec/consensus/light-client/accountability.md.
     5  
     6  # Gossiping
     7  
     8  The core functionality begins with the evidence reactor (see reactor.
     9  go) which operates both the sending and receiving of evidence.
    10  
    11  The `Receive` function takes a list of evidence and does the following:
    12  
    13  1. Checks that it does not already have the evidence stored
    14  
    15  2. Verifies the evidence against the node's state (see state/validation.go#VerifyEvidence)
    16  
    17  3. Stores the evidence to a db and a concurrent list
    18  
    19  The gossiping of evidence is initiated when a peer is added which starts a go routine to broadcast currently
    20  uncommitted evidence at intervals of 60 seconds (set by the by broadcastEvidenceIntervalS).
    21  It uses a concurrent list to store the evidence and before sending verifies that each evidence is still valid in the
    22  sense that it has not exceeded the max evidence age and height (see types/params.go#EvidenceParams).
    23  
    24  There are two buckets that evidence can be stored in: Pending & Committed.
    25  
    26  1. Pending is awaiting to be committed (evidence is usually broadcasted then)
    27  
    28  2. Committed is for those already on the block and is to ensure that evidence isn't submitted twice
    29  
    30  All evidence is proto encoded to disk.
    31  
    32  # Proposing
    33  
    34  When a new block is being proposed (in state/execution.go#CreateProposalBlock),
    35  `PendingEvidence(maxBytes)` is called to send up to the maxBytes of uncommitted evidence, from the evidence store,
    36  prioritized in order of age. All evidence is checked for expiration.
    37  
    38  When a node receives evidence in a block it will use the evidence module as a cache first to see if it has
    39  already verified the evidence before trying to verify it again.
    40  
    41  Once the proposed evidence is submitted,
    42  the evidence is marked as committed and is moved from the broadcasted set to the committed set.
    43  As a result it is also removed from the concurrent list so that it is no longer gossiped.
    44  
    45  # Minor Functionality
    46  
    47  As all evidence (including POLC's) are bounded by an expiration date, those that exceed this are no longer needed
    48  and hence pruned. Currently, only committed evidence in which a marker to the height that the evidence was committed
    49  and hence very small is saved. All updates are made from the `Update(block, state)` function which should be called
    50  when a new block is committed.
    51  */
    52  package evidence