From ec2d730ea527999fb594ae36e3c1dccad955c6b6 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Fri, 29 Oct 2021 18:09:13 +0200 Subject: [PATCH 1/8] doc: fold RPC index & full-description in a single menu entry, RPC reference --- docs/doc_gen/rpc_doc.ml | 2 +- docs/include/rpc_introduction.rst.inc | 9 ++++++--- docs/shell/rpc_introduction.rst.inc | 5 ++++- 3 files changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/doc_gen/rpc_doc.ml b/docs/doc_gen/rpc_doc.ml index 7e61d560f1cc..6ccd9516631c 100644 --- a/docs/doc_gen/rpc_doc.ml +++ b/docs/doc_gen/rpc_doc.ml @@ -346,7 +346,7 @@ let pp_document ppf descriptions version = Format.pp_set_max_indent ppf 9000 ; let version_suffix = if version = "" then "" else "_" ^ version in Format.fprintf ppf "%a" Rst.pp_ref ("rpc_index" ^ version_suffix) ; - Rst.pp_h2 ppf "RPCs - Index" ; + Rst.pp_h1 ppf "RPCs - Reference" ; List.iter (fun (name, intro, prefix, rpc_dir) -> (* If provided, insert the introductory include *) diff --git a/docs/include/rpc_introduction.rst.inc b/docs/include/rpc_introduction.rst.inc index f8195992215e..badc9de66955 100644 --- a/docs/include/rpc_introduction.rst.inc +++ b/docs/include/rpc_introduction.rst.inc @@ -1,4 +1,7 @@ -Shell and Protocol -================== +RPCs - Index +************ -The protocol-independent RPCs are described :ref:`here `. +Shell +===== + +The protocol-independent RPCs are described :doc:`here <../shell/rpc>`. diff --git a/docs/shell/rpc_introduction.rst.inc b/docs/shell/rpc_introduction.rst.inc index 72950bff19c1..32b382da8303 100644 --- a/docs/shell/rpc_introduction.rst.inc +++ b/docs/shell/rpc_introduction.rst.inc @@ -1,5 +1,8 @@ +RPCs - Index +************ + Protocol ======== Some RPCs are specific to a particular version of the Tezos protocol. -Those of the protocol currently active on Mainnet are described :ref:`here `. +Those of the protocol currently active on Mainnet are described :doc:`here <../active/rpc>`. -- GitLab From 265ee4a39bf73241e936f5db6d21339a175c3249 Mon Sep 17 00:00:00 2001 From: Lacramioara Astefanoaei Date: Fri, 5 Nov 2021 10:23:52 +0100 Subject: [PATCH 2/8] Doc: fix typos in consensus --- docs/alpha/consensus.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/alpha/consensus.rst b/docs/alpha/consensus.rst index 9764029c6cd6..06600d1f7d61 100644 --- a/docs/alpha/consensus.rst +++ b/docs/alpha/consensus.rst @@ -332,6 +332,9 @@ The bonus per additional endorsement slot is in turn ``bonus / ``CONSENSUS_COMMITTEE_SIZE / 3`` validator slots corresponding to the additional endorsements included in a block). The rewards per endorsement slot are ``endorsing_rewards / CONSENSUS_COMMITTEE_SIZE``. +Assuming ``CONSENSUS_COMMITTEE_SIZE = 8000``, we obtain a bonus per slot of +``10 / (8000 / 3) = 0.00375`` tez and an endorsing +rewards per slot of ``20 / 8000 = 0.0025`` tez. Let's take an example. Say a block has round 1, is proposed by delegate B, and contains the payload from round 0 produced by delegate @@ -349,13 +352,12 @@ included during that cycle has been ``3,123,456`` slots. Given that this number bigger than the minimum required (``3,276,800 * 2 / 3``), it receives an endorsing reward of ``3,276,800 * 0.0025 = 8192`` tez for that cycle. - .. _slashing_alpha: Slashing ^^^^^^^^ -Like in Emmy*, not revealing nonces and double singing are punishable. If a +Like in Emmy*, not revealing nonces and double signing are punishable. If a validator does not reveal its nonce by the end of the cycle, it does not receive its endorsing rewards. If a validator double signs, that is, it double bakes or it double (pre)endorses (which means voting on two different proposals at the @@ -391,7 +393,7 @@ Consensus protocol parameters * - ``CONSENSUS_COMMITTEE_SIZE`` - 7000 * - ``CONSENSUS_THRESHOLD`` - - ``ceil(2*CONSENSUS_COMMITTEE_SIZE/3)`` + - ``ceil(2 * CONSENSUS_COMMITTEE_SIZE / 3)`` * - ``ROUND_DURATIONS`` - [30s, 45s] * - ``MINIMAL_PARTICIPATION_RATIO`` @@ -407,9 +409,9 @@ Consensus protocol parameters * - ``BAKING_REWARD_FIXED_PORTION`` - 10 tez * - ``BAKING_REWARD_BONUS_PER_SLOT`` - - ``bonus / (CONSENSUS_COMMITTEE_SIZE / 3)`` tez + - ``bonus / (CONSENSUS_COMMITTEE_SIZE / 3)`` = 0.004286 tez * - ``ENDORSING_REWARD_PER_SLOT`` - - ``endorsing_reward / CONSENSUS_COMMITTEE_SIZE`` tez + - ``endorsing_reward / CONSENSUS_COMMITTEE_SIZE`` = 0.002857 tez Further External Resources -- GitLab From aa779c83cb56f78044c5d1e976fc03eee888f824 Mon Sep 17 00:00:00 2001 From: Eugen Zalinescu Date: Mon, 8 Nov 2021 12:08:51 +0100 Subject: [PATCH 3/8] Doc/Alpha: rolls are not used anymore (glossary) --- docs/alpha/glossary.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/alpha/glossary.rst b/docs/alpha/glossary.rst index 82924b7fa384..8d156c35386c 100644 --- a/docs/alpha/glossary.rst +++ b/docs/alpha/glossary.rst @@ -45,7 +45,7 @@ _`Baking`/_`Endorsing rights` A delegate_ is allowed to bake/endorse a block_ if he holds the baking/endorsing right for that block_. At the start of a Cycle_, baking and endorsing rights are computed for all the block_ heights in the - cycle_, based on the proportion of Rolls owned by each account. + cycle_, based on the proportion of the stake owned by each account. For each block_ height, there are several accounts that are allowed to bake. These different accounts are given different Priorities. -- GitLab From 0ec9b490b990c16a4dd73acffdf510fc7d95f88b Mon Sep 17 00:00:00 2001 From: Lacramioara Astefanoaei Date: Mon, 8 Nov 2021 14:32:08 +0100 Subject: [PATCH 4/8] doc: add reference to roll in voting --- docs/alpha/voting.rst | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/alpha/voting.rst b/docs/alpha/voting.rst index 869c77139ea9..ee5b5044f58d 100644 --- a/docs/alpha/voting.rst +++ b/docs/alpha/voting.rst @@ -11,8 +11,6 @@ protocol itself. Consequently the amendment rules themselves are subject to amendments. The rest of this page gives more details about the amendment and voting process. -Other than this page, there is an excellent overview from `Jacob -Arluck on medium `__. Periods ------- @@ -35,7 +33,7 @@ The five periods are as follows: At the end of a **proposal period**, the proposal with most support is selected and we move to an **exploration period**. Note that support is - measured in the cumulated number of rolls that delegates supporting the + measured in the cumulated number of :ref:`rolls ` that delegates supporting the proposal have. E.g., a proposal supported by a single delegate with 100 rolls has more support than a proposal supported by two delegates with 20 rolls each. @@ -315,8 +313,13 @@ ballots can be submitted once with:: tezos-client submit ballot for -Other resources -~~~~~~~~~~~~~~~ +Further External Resources +-------------------------- + +Further details and explanations on the voting procedure can be found at: + +- `the Open Tezos entry`_ +- `the Tezos Agora entry`_. For more details on the client commands refer to the manual at :ref:`client_manual_alpha`. -- GitLab From b3801a4bb13c52ff9fec59d00db59130b0c962e1 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 9 Nov 2021 15:20:42 +0100 Subject: [PATCH 5/8] doc: fix broken odoc links in shell/p2p.rst --- docs/shell/p2p.rst | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/docs/shell/p2p.rst b/docs/shell/p2p.rst index 83929902c63b..1eddd3f9527a 100644 --- a/docs/shell/p2p.rst +++ b/docs/shell/p2p.rst @@ -49,9 +49,9 @@ are used to store incoming (resp. outgoing) messages for each peer. This further restricts the speed at which communication is possible with a peer; when a queue is full, it is not possible to read (resp. write) an additional message. The high-level -`P2p_socket.connection -<../api/odoc/tezos-p2p/Tezos_p2p/P2p_socket/index.html#type-connection>`__ -type by the P2P layer is basically a UNIX socket upgraded with I/O +`P2p_socket.t +<../api/odoc/_html/tezos-p2p/Tezos_p2p/P2p_socket/index.html#type-t>`__ +type defined by the P2P layer is basically a UNIX socket upgraded with I/O scheduling, peer metadata, cryptographic keys, and two message queues operated by dedicated workers which operate on those queues. @@ -59,7 +59,7 @@ Pool of connections ~~~~~~~~~~~~~~~~~~~ All the above modules are used in `P2p_pool -<../api/odoc/tezos-p2p/Tezos_p2p/P2p_pool/index.html>`__, which +<../api/api-inline.html#tezos-p2p/Tezos_p2p/P2p_pool/index.html>`__, which constitutes the core of the P2P layer, together with the worker processes described below. It comprises various tables of connections as well as methods to query them, also connections are extended with @@ -67,19 +67,17 @@ another message queue where lower-level messages (like responses to ping) are filtered out and only application-level messages are kept. The main entry point of the P2P layer is in module `P2p -<../api/odoc/tezos-p2p/Tezos_p2p/P2p/index.html>`__. See below +<../api/api-inline.html#tezos-p2p/Tezos_p2p/P2p/index.html>`__. See below for a description of workers acting onto the P2P layer. -Welcome worker --------------- +Welcome worker & connect handler +-------------------------------- -The welcome worker is responsible for accepting incoming connections -and register them into the pool of connections managed by the P2P -layer. It basically runs the ``accept(2)`` syscall and call -`P2p_pool.accept -<../api/odoc/tezos-p2p/Tezos_p2p/P2p_pool/index.html#val-accept>`__ so -that it is made aware of an incoming connection. From there, the pool -will decide how this new connection must be handled. +The welcome worker & the connect handler are responsible for accepting incoming +connections and register them into the pool of connections managed by the P2P +layer. It basically runs the ``accept(2)`` syscall and build the stack of types +that composed a connection. They decide how this new connection must be +handled. {Black, White, Grey}lists ~~~~~~~~~~~~~~~~~~~~~~~~~ -- GitLab From 9151a3aeb6b6691b840dd3a2f922cc6f05d525f7 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Wed, 10 Nov 2021 17:12:23 +0100 Subject: [PATCH 6/8] doc: fix typo in proof-of-stake --- docs/010/consensus.rst | 2 +- docs/011/consensus.rst | 2 +- docs/alpha/consensus.rst | 2 +- docs/alpha/proof_of_stake.rst | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/010/consensus.rst b/docs/010/consensus.rst index 53fe408595df..75fd7acace8f 100644 --- a/docs/010/consensus.rst +++ b/docs/010/consensus.rst @@ -273,7 +273,7 @@ that cycle. .. _cs_constants_010: Consensus protocol parameters -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------- In this section we map the above notation to their corresponding parameter values. diff --git a/docs/011/consensus.rst b/docs/011/consensus.rst index 76d1c0299796..a53bc9e06fc0 100644 --- a/docs/011/consensus.rst +++ b/docs/011/consensus.rst @@ -269,7 +269,7 @@ that cycle. .. _cs_constants_011: Consensus protocol parameters -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------- In this section we map the above notation to their corresponding parameter values. diff --git a/docs/alpha/consensus.rst b/docs/alpha/consensus.rst index 06600d1f7d61..0b4090c9562f 100644 --- a/docs/alpha/consensus.rst +++ b/docs/alpha/consensus.rst @@ -382,7 +382,7 @@ participation of a selfish baker does not have an impact. .. _cs_constants_alpha: Consensus protocol parameters -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------- .. list-table:: :widths: 55 25 diff --git a/docs/alpha/proof_of_stake.rst b/docs/alpha/proof_of_stake.rst index 116e636f55f1..ec2169517417 100644 --- a/docs/alpha/proof_of_stake.rst +++ b/docs/alpha/proof_of_stake.rst @@ -39,7 +39,7 @@ A delegate participates in consensus and in governance with a weight proportional with their delegated stake, which includes the balances of all the accounts that delegate to it, and also the balance of the delegate itself. To participate in consensus or in governance, a -delegate needs to have at a minimal stake, which is given by the +delegate needs to have at least a minimal stake, which is given by the ``TOKENS_PER_ROLL`` :ref:`protocol constant `. -- GitLab From 704a54553bf779105e7c39a07842eb13f1edc608 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 23 Nov 2021 13:32:09 +0100 Subject: [PATCH 7/8] doc: emphasize warning for client w/o a node --- docs/introduction/howtouse.rst | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/docs/introduction/howtouse.rst b/docs/introduction/howtouse.rst index 47e17f02b5d8..fd3a85006fca 100644 --- a/docs/introduction/howtouse.rst +++ b/docs/introduction/howtouse.rst @@ -52,14 +52,23 @@ To see the usage of one specific command, you may also type the command without tezos-client transfer -However, beware that the commands available on the client depend on the specific -protocol run by the node. For instance, ``transfer`` is not available when -the node runs the genesis protocol, which may happen for a few minutes when -launching a node for the first time, or when the client is not connected to a -node. In the last case, the above command generates a warning:: - - Warning: - Failed to acquire the protocol version from the node +.. warning:: + + Beware that the commands available on the client depend on the specific + protocol run by the node. For instance, ``transfer`` is not available when + the node runs the genesis protocol, which may happen for a few minutes when + launching a node for the first time, **or when the client is not connected + to a node**. In the last case, the above command generates a warning + followed by an error:: + + Warning: + Failed to acquire the protocol version from the node + [...] + Error: + Unrecognized command. + Try using the man command to get more information. + Usage: + [...] .. _tezos_client_protocol: -- GitLab From 3109daacd13dfcdf9512cce574d87d7dba64e0c4 Mon Sep 17 00:00:00 2001 From: Lacramioara Astefanoaei Date: Wed, 24 Nov 2021 13:04:56 +0100 Subject: [PATCH 8/8] doc: fix typo in tenderbake.rst --- docs/protocols/tenderbake.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/protocols/tenderbake.rst b/docs/protocols/tenderbake.rst index cfaa150e2714..418f17ef0fa5 100644 --- a/docs/protocols/tenderbake.rst +++ b/docs/protocols/tenderbake.rst @@ -2,14 +2,14 @@ Tenderbake ========== This page contains a summary of the changes brought by the Tenderbake merge request (:gl:`!3738`). -Please refer to :doc:`the documentation<../alpha/consensus>` and to this `blog post`_ for an overview of the Tenderbake consensus algorithm and its motivation. +Please refer to :doc:`the documentation<../alpha/consensus>` and to this `blog post `_ for an overview of the Tenderbake consensus algorithm and its motivation. Protocol -------- The whole incentives scheme has been updated. In particular the security deposit mechanism has been overhauled. -See :doc:`../alpha/consensus`. +See :doc:`the documentation<../alpha/consensus>`. Rolls do not play an essential role anymore, in that the computation of delegates' rights is based directly on the delegates' stake. Snapshots are still used: it is the entire delegate's stake that is snapshot. @@ -25,7 +25,7 @@ Operations The layout of the endorsement operations has changed. It consists of a level, a round, a slot, and a payload hash. -There is a new consensus operation, `preendorsements`, with the same layout as an endorsement. +There is a new consensus operation, `preendorsement`, with the same layout as an endorsement. There is a new anonymous operation, `double preendorsement evidence`, with the same layout as a double endorsement evidence. -- GitLab