diff --git a/CHANGES.rst b/CHANGES.rst index f98f2739b18c7c6268986207404ee73b6beeca1d..6baeccd412a0898bb06b32cea043593a5d5cef79 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. diff --git a/docs/alpha/consensus.rst b/docs/alpha/consensus.rst index f89964026aa5c2811c1a53cd991faf2a365d9d13..f98c3551af923ced03f63e1835ecfa4af5b2c7ad 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``. @@ -294,10 +295,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 +310,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. @@ -394,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`` @@ -449,5 +448,5 @@ Further External Resources -------------------------- * Tenderbake `report `_ -* Tenderbake `blog post `_. +* Tenderbake `blog post `_. * Tenderbake `tzip `_. diff --git a/docs/developer/michelson_instructions.rst b/docs/developer/michelson_instructions.rst index 47cb26f81ac106426b1f53e8e48d1d76371158d9..532ba763f156ec29966ac135d8c5f4678a44ea04 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). The source for this page is :src:`docs/alpha/michelson.rst`. +- Updating the `Michelson reference website `__, by modifying the associated `repository `__. diff --git a/docs/developer/proposal_testing.rst b/docs/developer/proposal_testing.rst index dda45d5cb5bd7d1c459b9b2ac6b458c59105f387..85ab98271a68f72efd686d51ccb43d4dbba17b76 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. diff --git a/docs/introduction/howtorun.rst b/docs/introduction/howtorun.rst index 0602f5abf2e12a0150f05364ce1be0510fb182fe..31a465b29ae5cbdf0f44b84fc7a54828340b9570 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 known accounts. + +.. note:: + + In the Alpha protocol, the endorser daemon no longer exists, its role being + 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). + Accuser ~~~~~~~ diff --git a/docs/protocols/tenderbake.rst b/docs/protocols/tenderbake.rst index 6a04ec668fdead4af2df69a3e5d65aefc6bed056..eb149293eacca1c0a35c62f51c9fb8728a6cb0f3 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 diff --git a/docs/shell/sync.rst b/docs/shell/sync.rst index 5e2258ad9baafff5fbc1b2653cbb44c9d330b052..8711e0fc771dd272ea9c32d4182c5a086ac301ce 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 -`. +`_.