Clarify some of proposal 165 based on discussion

1 files changed, 33 insertions, 19 deletions

diff --git a/doc/spec/proposals/165-simple-robust-voting.txt b/doc/spec/proposals/165-simple-robust-voting.txt
index d8993c9e95..e33d1772c9 100644
--- a/doc/spec/proposals/165-simple-robust-voting.txt
+++ b/doc/spec/proposals/165-simple-robust-voting.txt
@@ -50,16 +50,21 @@ Motivation:
 Proposed protocol design:
 
    A "Voting Set" is a set of authorities.  Each authority has a list of
-   the voting sets it considers acceptable.  These sets must always
-   contain the authority itself.  Each authority lists all of these
-   voting sets in its votes.
+   the voting sets it considers acceptable.  These sets are chosen
+   manually by the authority operators. they must always contain the
+   authority itself.  Each authority lists all of these voting sets in
+   its votes.
 
    Authorities exchange votes with every other authority in any of their
    voting sets.
 
    When it comes time to calculate a consensus, an authority votes with
    whichever voting set it lists that is listed by the most members of
-   that set.
+   that set.  In other words, given two sets S1 and S2 that an authority
+   lists, that authority will prefer to vote with S1 over S2 whenever
+   the number of other authorities in S1 that themselves list S1 is
+   higher than the number of other authorities in S2 that themselves
+   list S2.
 
    For example, suppose authority A recognizes two sets, "A B C D" and
    "A E F G H".  Suppose that the first set is recognized by all of A,
@@ -72,21 +77,30 @@ Proposed protocol design:
 
 How to migrate authority sets:
 
-   In steady state, each authority should list only the current actual
-   voting set as accepted.
-
-   When we want to add an authority, we list two voting sets: one
-   containing all the old authorities, and one containing the old
-   authorities and the new authority too.  Once all authorities are
-   listing the new set of authorities, they will start preferring that
-   set because of its size.
-
-   When we want to remove an authority, we list two voting sets: one
-   containing all the authorities, and one omitting the authority we
-   want to remove.  Once enough authorities list the new set as
-   acceptable, we start having authorities stop listing the old set.
-   Once there are more listing the new set than the old set, the new set
-   will win.
+   In steady state, each authority operator should list only the current
+   actual voting set as accepted.
+
+   When we want to add an authority, each authority operator configures
+   his or her server to list two voting sets: one containing all the old
+   authorities, and one containing the old authorities and the new
+   authority too.  Once all authorities are listing the new set of
+   authorities, they will start voting with that set because of its
+   size.
+
+   What if one or two authority operators are slow to list the new set?
+   Then the other operators can stop listing the old set once there are
+   enough authorities listing the new set to make its voting successful.
+   (Note that these authorities not listing the new set will still have
+   their votes counted, since they themselves will be members of the new
+   set.  They will only fail to sign the consensus generated by the
+   other authorities who are using the new set.)
+
+   When we want to remove an authority, the operators list two voting
+   sets: one containing all the authorities, and one omitting the
+   authority we want to remove.  Once enough authorities list the new
+   set as acceptable, we start having authority operators stop listing
+   the old set.  Once there are more listing the new set than the old
+   set, the new set will win.
 
 Data format changes: