From ed71b706a020c95435ea8776ea755d246edb1dec Mon Sep 17 00:00:00 2001 From: Eugen Zalinescu Date: Wed, 1 Dec 2021 13:42:46 +0100 Subject: [PATCH 01/11] doc: remove misleading statement about migration commits --- docs/developer/proposal_testing.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/developer/proposal_testing.rst b/docs/developer/proposal_testing.rst index dda45d5cb5bd..85ab98271a68 100644 --- a/docs/developer/proposal_testing.rst +++ b/docs/developer/proposal_testing.rst @@ -16,10 +16,9 @@ contains both the new protocol and its migration code from the current active protocol. The current protocol proposal under development is referred to as the `Alpha protocol`. -Since the commits for migration code are only used once, we keep them clearly -separated by marking them with the tag ``Migration:``. The first step when -developing a new protocol is to revert the migration commits from the previous -protocol. The rest of the commits are used as a base for current proposals. +Since the migration code is only used once, it is a good practice to keep them clearly +separated by marking them with the tag ``Proto/Migration:``. +Note that a first step when developing a new protocol is to revert the migration code from the previous protocol. We next describe how to run unit tests and how to activate the Alpha protocol in sandboxed node. -- GitLab From 39b274bf008bf6b17f9ed2fecb67dfc07b4969c3 Mon Sep 17 00:00:00 2001 From: Lacramioara Astefanoaei Date: Wed, 1 Dec 2021 15:31:37 +0100 Subject: [PATCH 02/11] doc: add a small clarification about endorsing rewards --- docs/alpha/consensus.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/alpha/consensus.rst b/docs/alpha/consensus.rst index f89964026aa5..ddaecbe2c10d 100644 --- a/docs/alpha/consensus.rst +++ b/docs/alpha/consensus.rst @@ -294,10 +294,9 @@ validator slots above the threshold of :math:`\lceil CONSENSUS\_COMMITTEE\_SIZE the included endorsements represent. The bonus is also distributed immediately. -The endorsing rewards are shared among all validators, proportionally -to their *expected* number of validator slots. The endorsing reward -may be received even if the validator's endorsement is not included in -a block. However, two conditions must be met: +The endorsing rewards are distributed at the end of the cycle. +The endorsing reward may be received even if not all of the validator's endorsements are included in a block and is proportional to the validator's active stake (in other words, to its *expected* number of validator slots, and not its actual number of slots). +However, two conditions must be met: - the validator has revealed its nonce, and - the validator has been present during the cycle. @@ -310,7 +309,6 @@ corresponding level) of all the endorsements included by the delegate during the cycle represents at least ``MINIMAL_PARTICIPATION_RATIO`` of the delegate's expected number of validator slots for the current cycle (which is ``BLOCKS_PER_CYCLE * CONSENSUS_COMMITTEE_SIZE * active_stake / total_active_stake``). -The endorsing rewards are distributed at the end of the cycle. Regarding the concrete values for rewards, we first fix the total reward per level, call it ``total_rewards``, to ``80 / blocks_per_minute`` tez. -- GitLab From 6e035baa3895dbb27245a5c9a7803618404f63b4 Mon Sep 17 00:00:00 2001 From: Lacramioara Astefanoaei Date: Wed, 1 Dec 2021 15:32:55 +0100 Subject: [PATCH 03/11] doc: correct the value for bonus_per_slot --- docs/protocols/tenderbake.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/protocols/tenderbake.rst b/docs/protocols/tenderbake.rst index 6a04ec668fde..eb149293eacc 100644 --- a/docs/protocols/tenderbake.rst +++ b/docs/protocols/tenderbake.rst @@ -60,7 +60,7 @@ The following protocol parameters have been removed: The following protocol parameters have been introduced: * ``baking_reward_fixed_portion`` = 10 tez -* ``baking_reward_bonus_per_slot`` = 0.004285 tez +* ``baking_reward_bonus_per_slot`` = 0.004286 tez * ``endorsing_reward_per_slot`` = 0.002857 tez * ``delay_increment_per_round`` = 15 * ``minimal_participation_ratio`` = 2/3 -- GitLab From 8127ee5c937afdc192002abc717edcf8f84326e3 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Wed, 1 Dec 2021 16:57:49 +0100 Subject: [PATCH 04/11] doc: add back Endorser in howtorun.rst --- docs/introduction/howtorun.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/introduction/howtorun.rst b/docs/introduction/howtorun.rst index 0602f5abf2e1..5ed35dd774ee 100644 --- a/docs/introduction/howtorun.rst +++ b/docs/introduction/howtorun.rst @@ -268,6 +268,24 @@ baking for user *bob*:: If you are worried about the availability of your node when it is its turn to bake/endorse, there are other ways than duplicating your credentials (see the discussion in section :ref:`inactive_delegates`). **Never** use the same account on two daemons. +Endorser +~~~~~~~~ + +The endorser is a daemon that, once connected to an account, computes +the endorsing rights for that account and, upon reception of a new +block, verifies the validity of the block and emits an endorsement +operation. +It can endorse for a specific account or if omitted it endorses for +all accounts. + +.. note:: + + In the Alpha protocol, the endorser daemon no longer exists, its role being + played by the baker daemon in the corresponding consenus algorithm. + Therefore, there is no ``tezos-endorser-alpha`` executable, but endorser + executables ``tezos-endorser-NNN-*`` exist for protocols up to 011 + (Hangzhou). + Accuser ~~~~~~~ -- GitLab From 4f1e487d720a7e3379d74de8474d265ed52ed8f3 Mon Sep 17 00:00:00 2001 From: Eugen Zalinescu Date: Wed, 1 Dec 2021 22:55:42 +0000 Subject: [PATCH 05/11] doc: typos in howtorun --- docs/introduction/howtorun.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/introduction/howtorun.rst b/docs/introduction/howtorun.rst index 5ed35dd774ee..31a465b29ae5 100644 --- a/docs/introduction/howtorun.rst +++ b/docs/introduction/howtorun.rst @@ -276,12 +276,12 @@ the endorsing rights for that account and, upon reception of a new block, verifies the validity of the block and emits an endorsement operation. It can endorse for a specific account or if omitted it endorses for -all accounts. +all known accounts. .. note:: In the Alpha protocol, the endorser daemon no longer exists, its role being - played by the baker daemon in the corresponding consenus algorithm. + played by the baker daemon in the corresponding consensus algorithm. Therefore, there is no ``tezos-endorser-alpha`` executable, but endorser executables ``tezos-endorser-NNN-*`` exist for protocols up to 011 (Hangzhou). -- GitLab From 2b49ee622874870f1a1c63dd0f0267fde251db46 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Thu, 2 Dec 2021 12:24:06 +0100 Subject: [PATCH 06/11] doc: require documentation for new Michelson instructions --- docs/developer/michelson_instructions.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/developer/michelson_instructions.rst b/docs/developer/michelson_instructions.rst index 47cb26f81ac1..f624cc1a3aaa 100644 --- a/docs/developer/michelson_instructions.rst +++ b/docs/developer/michelson_instructions.rst @@ -15,6 +15,7 @@ Adding a new instruction requires providing the following elements (detailed in 3. :ref:`a translation rule ` 4. :ref:`an execution rule ` 5. :ref:`a gas cost model ` +6. :ref:`some documentation ` Once all of the above are provided, we may try compiling the protocol. We will most likely encounter some non-exhaustive pattern matching errors, but after the @@ -404,3 +405,16 @@ comparable results. More information on the gas model and on benchmarking the interpreter can be found on the pages dedicated to the ``snoop`` library: :doc:`snoop_interpreter`. + +.. _add_mich_documentation: + +Documentation +------------- + +Last but not least, the new instruction needs to be documented. +After all, nobody will ever use it otherwise! + +Documenting the instruction may involve: + +- Editing the :doc:`Michelson language page <../alpha/michelson>` (only the page corresponding to the Alpha protocol needs be changed, because injected protocols cannot be extended with new instructions). +- Updating the `Michelson reference website `__, by modifying the associated `repository `__. -- GitLab From 272bbd6767e452115799b6357fe50599c4ad2d6e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Cauderlier?= Date: Tue, 7 Dec 2021 13:31:56 +0000 Subject: [PATCH 07/11] doc: indicate source of Michelson's page. --- docs/developer/michelson_instructions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer/michelson_instructions.rst b/docs/developer/michelson_instructions.rst index f624cc1a3aaa..532ba763f156 100644 --- a/docs/developer/michelson_instructions.rst +++ b/docs/developer/michelson_instructions.rst @@ -416,5 +416,5 @@ After all, nobody will ever use it otherwise! Documenting the instruction may involve: -- Editing the :doc:`Michelson language page <../alpha/michelson>` (only the page corresponding to the Alpha protocol needs be changed, because injected protocols cannot be extended with new instructions). +- Editing the :doc:`Michelson language page <../alpha/michelson>` (only the page corresponding to the Alpha protocol needs be changed, because injected protocols cannot be extended with new instructions). The source for this page is :src:`docs/alpha/michelson.rst`. - Updating the `Michelson reference website `__, by modifying the associated `repository `__. -- GitLab From 3143a69dc7e29f612f8997ad992f63a28d33fb8f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Proust?= Date: Mon, 13 Dec 2021 13:17:56 +0000 Subject: [PATCH 08/11] CHANGES: fix typos --- CHANGES.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGES.rst b/CHANGES.rst index f98f2739b18c..6baeccd412a0 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -146,7 +146,7 @@ Node - The prevalidator (which handles operations which have been received but not yet included in a block) was made more restrictive: it now accepts a single manager operation from a given manager for a given block. This limitation - was already present implicitely if you were using the `tezos-client` commands. + was already present implicitly if you were using the `tezos-client` commands. Batches of operations can be used to get around this restriction, see the `multiple transfers` command to learn more. In addition, operations rejected because of this limitation are solely delayed to a future block. @@ -179,7 +179,7 @@ Client The value can be ``json``, ``binary`` or ``any``. - Added two options, ``--now`` and ``--level`` to the ``run script`` - and ``run view`` commands simulating exectution of Michelson + and ``run view`` commands simulating execution of Michelson code. These options can be used to override the values normally returned by the ``NOW`` and ``LEVEL`` instructions. -- GitLab From 9518af4bcf7fd59515cde11f1dfd03e619b3b6ee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Germ=C3=A1n=20Delbianco?= Date: Fri, 17 Dec 2021 11:55:23 +0000 Subject: [PATCH 09/11] doc: redirect link to NL blog --- docs/alpha/consensus.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/alpha/consensus.rst b/docs/alpha/consensus.rst index ddaecbe2c10d..4cdbed18ba30 100644 --- a/docs/alpha/consensus.rst +++ b/docs/alpha/consensus.rst @@ -447,5 +447,5 @@ Further External Resources -------------------------- * Tenderbake `report `_ -* Tenderbake `blog post `_. +* Tenderbake `blog post `_.r * Tenderbake `tzip `_. -- GitLab From cd1f33be8db077e7addc6a0b91baf7e0a0652bcf Mon Sep 17 00:00:00 2001 From: Lacramioara Astefanoaei Date: Fri, 17 Dec 2021 13:32:50 +0100 Subject: [PATCH 10/11] doc: replace mathjax expr by the name of the parameter and fix a tiny typo --- docs/alpha/consensus.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/alpha/consensus.rst b/docs/alpha/consensus.rst index 4cdbed18ba30..f98c3551af92 100644 --- a/docs/alpha/consensus.rst +++ b/docs/alpha/consensus.rst @@ -55,6 +55,7 @@ are called *validators*, which are delegates selected at random based on their stake, in the same way as endorsers are selected in Emmy*. We let ``CONSENSUS_COMMITTEE_SIZE`` be the number of validator slots per level. This constant has the role of ``ENDORSERS_PER_BLOCK`` in Emmy*. +Furthermore, we use ``CONSENSUS_THRESHOLD`` to denote two thirds of ``CONSENSUS_COMMITTEE_SIZE``. For each level, Tenderbake proceeds in rounds. Each *round* represents an attempt by the validators to agree on the content of the block for the current @@ -85,7 +86,7 @@ Unlike Emmy*, Tenderbake has `two types of votes `_: before endorsing a block ``b``, a validator preendorses ``b``. Furthermore, to be able to endorse, a validator must have observed a preendorsement *quorum*, that is a -set of preendorsements from validators having at least :math:`\lceil CONSENSUS\_COMMITTEE\_SIZE \times \frac{2}{3} \rceil` validator slots. Similarly, to be able to decide, a validator must have observed an endorsement quorum, that is, a set of endorsements from validators having at least :math:`\lceil CONSENSUS\_COMMITTEE\_SIZE \times \frac{2}{3} \rceil` validator slots. The +set of preendorsements from validators having at least ``CONSENSUS_THRESHOLD`` validator slots. Similarly, to be able to decide, a validator must have observed an endorsement quorum, that is, a set of endorsements from validators having at least ``CONSENSUS_THRESHOLD`` validator slots. The endorsement quorum for a block ``b`` is included in a block ``b'`` on top of ``b``, serving as a certification that ``b`` has been agreed upon. We also say that block ``b'`` confirms block ``b``. @@ -392,7 +393,7 @@ Consensus related protocol parameters * - ``CONSENSUS_COMMITTEE_SIZE`` - 7000 * - ``CONSENSUS_THRESHOLD`` - - ``ceil(2 * CONSENSUS_COMMITTEE_SIZE / 3)`` + - ``ceil(2 * CONSENSUS_COMMITTEE_SIZE / 3)`` = 4667 * - ``MINIMAL_BLOCK_DELAY`` - 30s * - ``DELAY_INCREMENT_PER_ROUND`` @@ -447,5 +448,5 @@ Further External Resources -------------------------- * Tenderbake `report `_ -* Tenderbake `blog post `_.r +* Tenderbake `blog post `_. * Tenderbake `tzip `_. -- GitLab From e66b166c494927779899a9d48e77af231d07ce11 Mon Sep 17 00:00:00 2001 From: Eugen Zalinescu Date: Mon, 3 Jan 2022 14:16:53 +0100 Subject: [PATCH 11/11] Docs/sync: properly show link and itemize consistently --- docs/shell/sync.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/shell/sync.rst b/docs/shell/sync.rst index 5e2258ad9baa..8711e0fc771d 100644 --- a/docs/shell/sync.rst +++ b/docs/shell/sync.rst @@ -20,11 +20,11 @@ synchronised with respect to its peers. The current synchronisation heuristic uses a **synchronisation status** as follows: -- ``Unsynced``: Not synchronised +- ``Unsynced``: not synchronised -- ``Synced``: Synchronised and the chain is not stuck +- ``Synced``: synchronised and the chain is not stuck -- ``Stuck``: Synchronised and the chain is stuck +- ``Stuck``: synchronised and the chain is stuck Bootstrapped ------------ @@ -49,12 +49,12 @@ most-recent such block advertised by the peer. The heuristic is parameterised by two values (see :doc:`node configuration <../user/node-configuration>`): -- A ``threshold`` (configuration parameter ``synchronisation_threshold``): The - number of candidates kept by the heuristic -- A ``latency`` (configuration parameter ``latency``): A delay in seconds to +- a ``threshold`` (configuration parameter ``synchronisation_threshold``): the + number of candidates kept by the heuristic; +- a ``latency`` (configuration parameter ``latency``): a delay in seconds to control possible forks and the latency of the network (see :ref:`Acceptable values for - parameters`) + parameters`). The heuristic maintains the most recent ``threshold`` candidates it is aware of, with the constraint that there is at most one candidate per @@ -75,11 +75,11 @@ Acceptable values for parameters The heuristic accepts any value for the ``threshold``, but values of ``1`` or less are mainly used for testing and debugging: -- If ``threshold`` is negative, then the status is always ``Unsynced`` +- If ``threshold`` is negative, then the status is always ``Unsynced``. -- If ``threshold`` is ``0``, then the status is always ``Synced`` +- If ``threshold`` is ``0``, then the status is always ``Synced``. -- If ``threshold`` is ``1``, then the status cannot be ``Stuck`` +- If ``threshold`` is ``1``, then the status cannot be ``Stuck``. Other values are acceptable for ``threshold``, but a small ``threshold`` (between ``2`` and ``10``; the default being ``4``) is @@ -128,4 +128,4 @@ bootstrapped, when actually it should be. The administrator of the node can use the RPC ``patch /chains/main {"bootstrapped": true}`` to force the node bootstrapped state, but this should be used carefully. If you see an issue with the current heuristic, please `report it -`. +`_. -- GitLab