From e9d55381079af1fdd22bc0f4cba2812e79f88967 Mon Sep 17 00:00:00 2001 From: Callum Michael Waters Date: Tue, 14 Apr 2020 13:40:59 +0200 Subject: [PATCH 1/4] created docs.go for evidence package --- evidence/doc.go | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 evidence/doc.go diff --git a/evidence/doc.go b/evidence/doc.go new file mode 100644 index 000000000..0dc5ecfca --- /dev/null +++ b/evidence/doc.go @@ -0,0 +1,36 @@ +/* +Package evidence handles all evidence storage and gossiping from detection to block proposal. +For the different types of evidence refer to the `evidence.go` file in the types package. + +## Gossiping + +The core functionality begins with the evidence reactor (see reactor. +go) which operates both the sending and receiving of evidence. + +The `Receive` function takes a list of evidence and does the following: + 1. breaks it down into individual evidence if it is `Composite Evidence` (see types/evidence. +go#ConflictingHeadersEvidence) + 2. checks that it does not already have the evidence stored + 3. verifies the evidence against the nodes state (see state/validation.go#VerifyEvidence) + 4. stores the evidence to a db and a concurrent list + +The gossiping of evidence is initiated when a peer is added which starts a go routine to broadcast currently +uncommitted evidence at intervals of 60 seconds (set by the by broadcastEvidenceIntervalS). +It uses a concurrent list to store the evidence and before sending verifies that each evidence is still valid in the +sense that it has not exceeded the max evidence age and height which should be set to be equal to the "trusting +period" (see types/params.go#EvidenceParams). + +## Proposing + +When a new block is being proposed (in state/execution.go#CreateProposalBlock), +`PendingEvidence(maxNum)` is called to send up to the maxNum number of uncommitted evidence, from the evidence store, +based on a priority that is a product of the age of the evidence and the voting power of the malicious validator. + +Once the proposed evidence is submitted, +the evidence is marked as committed and is moved from the broadcasted set to the committed set ( +the committed set is used to verify whether new evidence has actually already been submitted). +As a result it is also removed from the concurrent list so that it is no longer gossiped. + +Last Update: 14/04/20 +*/ +package evidence From b524b61252c3e86f4016a2344211855fe510cc7b Mon Sep 17 00:00:00 2001 From: Callum Date: Thu, 16 Apr 2020 12:28:25 +0200 Subject: [PATCH 2/4] clean up doc --- evidence/doc.go | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/evidence/doc.go b/evidence/doc.go index 0dc5ecfca..a669b7a28 100644 --- a/evidence/doc.go +++ b/evidence/doc.go @@ -1,6 +1,7 @@ /* Package evidence handles all evidence storage and gossiping from detection to block proposal. -For the different types of evidence refer to the `evidence.go` file in the types package. +For the different types of evidence refer to the `evidence.go` file in the types package +or https://github.com/tendermint/spec/blob/master/spec/consensus/light-client/accountability.md. ## Gossiping @@ -17,7 +18,7 @@ go#ConflictingHeadersEvidence) The gossiping of evidence is initiated when a peer is added which starts a go routine to broadcast currently uncommitted evidence at intervals of 60 seconds (set by the by broadcastEvidenceIntervalS). It uses a concurrent list to store the evidence and before sending verifies that each evidence is still valid in the -sense that it has not exceeded the max evidence age and height which should be set to be equal to the "trusting +sense that it has not exceeded the max evidence age and height. This should be set to be equal to the "trusting period" (see types/params.go#EvidenceParams). ## Proposing From 496ee91fccb25ea8757bbae99ba7ae91def43d16 Mon Sep 17 00:00:00 2001 From: Callum Date: Tue, 28 Apr 2020 06:35:10 +0200 Subject: [PATCH 3/4] made suggested changes --- evidence/doc.go | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/evidence/doc.go b/evidence/doc.go index a669b7a28..016ea555f 100644 --- a/evidence/doc.go +++ b/evidence/doc.go @@ -3,25 +3,27 @@ Package evidence handles all evidence storage and gossiping from detection to bl For the different types of evidence refer to the `evidence.go` file in the types package or https://github.com/tendermint/spec/blob/master/spec/consensus/light-client/accountability.md. -## Gossiping +Gossiping The core functionality begins with the evidence reactor (see reactor. go) which operates both the sending and receiving of evidence. The `Receive` function takes a list of evidence and does the following: - 1. breaks it down into individual evidence if it is `Composite Evidence` (see types/evidence. -go#ConflictingHeadersEvidence) - 2. checks that it does not already have the evidence stored - 3. verifies the evidence against the nodes state (see state/validation.go#VerifyEvidence) - 4. stores the evidence to a db and a concurrent list + +1. Breaks it down into individual evidence if it is `Composite Evidence` (see types/evidence.go#ConflictingHeadersEvidence) + +2. Checks that it does not already have the evidence stored + +3. Verifies the evidence against the node's state (see state/validation.go#VerifyEvidence) + +4. Stores the evidence to a db and a concurrent list The gossiping of evidence is initiated when a peer is added which starts a go routine to broadcast currently uncommitted evidence at intervals of 60 seconds (set by the by broadcastEvidenceIntervalS). It uses a concurrent list to store the evidence and before sending verifies that each evidence is still valid in the -sense that it has not exceeded the max evidence age and height. This should be set to be equal to the "trusting -period" (see types/params.go#EvidenceParams). +sense that it has not exceeded the max evidence age and height (see types/params.go#EvidenceParams). -## Proposing +Proposing When a new block is being proposed (in state/execution.go#CreateProposalBlock), `PendingEvidence(maxNum)` is called to send up to the maxNum number of uncommitted evidence, from the evidence store, @@ -31,7 +33,5 @@ Once the proposed evidence is submitted, the evidence is marked as committed and is moved from the broadcasted set to the committed set ( the committed set is used to verify whether new evidence has actually already been submitted). As a result it is also removed from the concurrent list so that it is no longer gossiped. - -Last Update: 14/04/20 */ package evidence From 1972b1f9feb92cad143499e6ecc1ded598e56467 Mon Sep 17 00:00:00 2001 From: Callum Date: Tue, 28 Apr 2020 06:38:40 +0200 Subject: [PATCH 4/4] lint fix --- evidence/doc.go | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/evidence/doc.go b/evidence/doc.go index 016ea555f..77bd8ef75 100644 --- a/evidence/doc.go +++ b/evidence/doc.go @@ -10,7 +10,8 @@ go) which operates both the sending and receiving of evidence. The `Receive` function takes a list of evidence and does the following: -1. Breaks it down into individual evidence if it is `Composite Evidence` (see types/evidence.go#ConflictingHeadersEvidence) +1. Breaks it down into individual evidence if it is `Composite Evidence` +(see types/evidence.go#ConflictingHeadersEvidence) 2. Checks that it does not already have the evidence stored