From 27c5bc86c0f7d3d5be0e285fa6cf388745a1b6bf Mon Sep 17 00:00:00 2001 From: Marco Stronati Date: Mon, 4 Feb 2019 13:00:49 +0100 Subject: [PATCH] Doc: add client voting commands --- docs/whitedoc/voting.rst | 83 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 78 insertions(+), 5 deletions(-) diff --git a/docs/whitedoc/voting.rst b/docs/whitedoc/voting.rst index 453464ed2..f6061a763 100644 --- a/docs/whitedoc/voting.rst +++ b/docs/whitedoc/voting.rst @@ -5,7 +5,7 @@ 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. +implement 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 @@ -65,12 +65,13 @@ the current participation with the following coefficients:: newQ = oldQ * 8/10 + participation * 2/10 -More details can be found in the file ``amendment.ml``. +More details can be found in the file +``src/proto_alpha/lib_protocol/src/amendment.ml``. Operations ---------- -There two operations used by the delegates: ``proposals`` and ``ballot``. +There are two operations used by the delegates: ``proposals`` and ``ballot``. A proposal operation can only be submitted during a proposal period. :: @@ -104,5 +105,77 @@ 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``. +``src/proto_alpha/lib_protocol/src/operation_repr.ml``. +The binary format is described by ``tezos-client describe unsigned +operation``. + +Client Commands +--------------- + +Tezos' client provides a command to show the status of a voting period. +It displays different informations for different kind of periods, as +in the following samples:: + + $ tezos-client show voting period + Current period: "proposal" + Blocks remaining until end of period: 59 + Current proposals: + PsNa6jTtsRfbGaNSoYXNTNM5A7c3Lji22Yf2ZhpFUjQFC17iZVp 400 + + $ tezos-client show voting period + Current period: "testing_vote" + Blocks remaining until end of period: 63 + Current proposal: PsNa6jTtsRfbGaNSoYXNTNM5A7c3Lji22Yf2ZhpFUjQFC17iZVp + Ballots: { "yay": 400, "nay": 0, "pass": 0 } + Current participation 20.00%, necessary quorum 80.00% + Current in favor 400, needed supermajority 320 + + $ tezos-client show voting period + Current period: "testing" + Blocks remaining until end of period: 64 + Current proposal: PsNa6jTtsRfbGaNSoYXNTNM5A7c3Lji22Yf2ZhpFUjQFC17iZVp + +It should be noted that the number 400 above is a number of rolls. +The proposal has a total of 400 rolls, which may come from several +delegates. The same applies for the ballots, there are 400 rolls in +favor of testing protocol PsNa6jTt. + +Submit proposals +~~~~~~~~~~~~~~~~ + +During a proposal period, the list of proposals can be submitted with:: + + tezos-client submit proposals for ... + +Remember that each delegate can submit a maximum of 20 protocol +hashes including duplicates. +Moreover each proposal is accepted only if it meets one of the +following two conditions: + +- the protocol hash was already proposed on the network. In this case + we can submit an additional proposal that "upvotes" an existing one + and our rolls are added to the ones already supporting the proposal. +- the protocol is known by the node. In particular the first proposer + of a protocol should be able to successfully inject the protocol in + its node which performs some checks, compiles and loads the + protocol. + +Submit ballots +~~~~~~~~~~~~~~ + +During a voting period, being it a testing vote or a promotion vote, +ballots can be submitted once with:: + + tezos-client submit ballot for + +Other resources +~~~~~~~~~~~~~~~ + +For more details on the client commands refer to the manual at +:ref:`client_manual`. + +For vote related RPCs check the :ref:`rpc_index` under the prefix +``vote/``. + +For Ledger support refer to Obsidian Systems' `documentation +`_.