From 3109b7f02686dbb6c0986def0c747c8f1cc721b0 Mon Sep 17 00:00:00 2001 From: Marco Stronati Date: Sat, 8 Dec 2018 00:32:41 +0100 Subject: [PATCH] Doc: add voting page --- .gitlab-ci.yml | 2 +- Makefile | 4 +- docs/index.rst | 1 + docs/whitedoc/voting.rst | 108 +++++++++++++++++++++++++++++++++++++++ 4 files changed, 112 insertions(+), 3 deletions(-) create mode 100644 docs/whitedoc/voting.rst diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 844458074..75195f5ef 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -195,7 +195,7 @@ test:linkcheck: - sudo pip3 uninstall 'idna' --yes ## Fix up dependencies in alpine:3.8 - sudo pip3 install 'idna<2.7' - sudo ln -s /usr/bin/sphinx-build-3 /usr/bin/sphinx-build - - make doc-linkcheck + - make doc-html-and-linkcheck allow_failure: true test:validation: diff --git a/Makefile b/Makefile index f04a6bd57..3ecfa730d 100644 --- a/Makefile +++ b/Makefile @@ -62,8 +62,8 @@ doc-html: all @cp -r $$(pwd)/_build/default/_doc/* $$(pwd)/docs/_build/api/odoc/ @${MAKE} -C docs html -doc-linkcheck: - @${MAKE} -C docs linkcheck +doc-html-and-linkcheck: doc-html + @${MAKE} -C docs all build-test: @dune build @buildtest diff --git a/docs/index.rst b/docs/index.rst index 3d0c71a79..12175d264 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -121,6 +121,7 @@ in the :ref:`introduction `. whitedoc/validation whitedoc/michelson whitedoc/proof_of_stake + whitedoc/voting .. toctree:: :maxdepth: 2 diff --git a/docs/whitedoc/voting.rst b/docs/whitedoc/voting.rst new file mode 100644 index 000000000..453464ed2 --- /dev/null +++ b/docs/whitedoc/voting.rst @@ -0,0 +1,108 @@ +.. _voting: + +The Voting Process +================== + +The design of the Tezos Node allows the consensus protocol to be +amended, that is replaced by another set of OCaml files which +implements the API of a valid protocol. + +In the current protocol the amendment procedure is guided by a voting +procedure where delegates can propose, select and test a candidate +protocol before activating it. +Delegates take part in the amendment procedure with an influence +proportional to their stake, one roll one vote. + +The procedure consists of four periods, each of 32768 blocks (or +~three weeks), for a total of approximately three months. + +Other than this page, there is an excellent overview from `Jacob +Arluck on medium. +`_ + +Periods +------- + +The voting procedure works as follows: + +- `Proposal period`: delegates can submit protocol amendment proposals using + the `proposals` operation. At the end of a proposal period, the proposal with + most supporters is selected and we move to a testing_vote period. + If there are no proposals, or a tie between proposals, a new proposal + period starts. Each delegate can submit a maximum of 20 proposals, + including duplicates. +- `Testing_vote period`: delegates can cast one vote to test or not the winning + proposal using the `ballot` operation. + At the end of a testing_vote period if participation reaches the quorum + and the proposal has a super-majority in favor, we proceed to a testing + period. Otherwise we go back to a proposal period. +- `Testing period`: a test chain is forked for 48 hours to test a + correct migration of the context. + At the end of a testing period we move to a promotion_vote period. +- `Promotion_vote period`: delegates can cast one vote to promote or not the + tested proposal using the `ballot` operation. + At the end of a promotion_vote period if participation reaches the quorum + and the tested proposal has a super-majority in favor, it is activated as + the new protocol. Otherwise we go back to a proposal period. + +It is important to note that the stake of each delegated is computed +at the beginning of each period. + +Super-majority and Quorum +------------------------- + +Both voting periods work in the same way, only the subject of the +vote differs. +During a vote a delegate can cast a single Yea, Nay or Pass vote. +A vote is successful if it has super-majority and the participation +reaches the current quorum. + +`Super-majority` means the Yeas are more than 8/10 of Yeas+Nays votes. +The `participation` is the ratio of all received votes, including +passes, with respect to the number of possible votes. The `quorum` +starts at 80% and at each vote it is updated using the old quorum and +the current participation with the following coefficients:: + + newQ = oldQ * 8/10 + participation * 2/10 + +More details can be found in the file ``amendment.ml``. + +Operations +---------- + +There two operations used by the delegates: ``proposals`` and ``ballot``. +A proposal operation can only be submitted during a proposal period. + +:: + + Proposals : { + source: Signature.Public_key_hash.t ; + period: Voting_period_repr.t ; + proposals: Protocol_hash.t list ; } + +Source is the public key hash of the delegate, period is the unique +identifier of each voting period and proposals is a non-empty list of +maximum 20 protocol hashes. +The operation can be submitted more than once but only as long as the +cumulative length of the proposals lists is less than 20. + +A ballot operation can only be submitted during one of the voting +periods, and only once per period. + +:: + + Ballot : { + source: Signature.Public_key_hash.t ; + period: Voting_period_repr.t ; + proposal: Protocol_hash.t ; + ballot: Vote_repr.ballot ; } + +Source and period are the same as above, while proposal is the +currently selected proposal and ballot is one of ``Yea``, ``Nay`` or +``Pass``. +The pass vote allows a delegate to not influence a vote but still +allowing it to reach quorum. + +More details can be found, as for all operations, in +``operation_repr.ml``. The binary format is described by +``tezos-client describe unsigned operation``.