From 3417a026125d198b05296e576735062338589f7a Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Thu, 11 Apr 2024 18:15:16 +0200 Subject: [PATCH 1/2] doc: move proto-specific header to page blocks_ops Co-authored-by: Lucas Randazzo Co-authored-by: Ryan Tan --- docs/alpha/blocks_ops.rst | 29 +++++++++++++++++++++++++++-- docs/alpha/consensus.rst | 24 +++--------------------- docs/alpha/protocol_overview.rst | 2 +- 3 files changed, 31 insertions(+), 24 deletions(-) diff --git a/docs/alpha/blocks_ops.rst b/docs/alpha/blocks_ops.rst index 44ad9aec972b..17b6211c7123 100644 --- a/docs/alpha/blocks_ops.rst +++ b/docs/alpha/blocks_ops.rst @@ -2,13 +2,38 @@ Blocks and Operations ===================== -The content of a Tezos block is made up of operations, which implement +The content of a Tezos block is made up of a block header and a payload consisting of a list of operations. + +This page first describes the protocol-specific part of the block header, and then explains what operations are. +For the protocol-independent part of the block header, see :ref:`shell_header`. + +.. _proto_block_header_alpha: + +Protocol-specific block header +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:ref:`Recall` that, for the shell to interact with the economic protocol, two notions are defined abstractly at the level of the shell and made concrete at the level of the consensus protocol. +Namely, these two notions are the protocol-specific header and the :ref:`fitness `. + +As in Emmy*, the protocol-specific header contains the fields: + +- ``signature``: a digital signature of the shell and protocol headers (excluding the signature itself) +- ``seed_nonce_hash``: a commitment to :ref:`a random number`, used to generate entropy on the chain +- ``proof_of_work_nonce``: a nonce used to pass a low-difficulty proof-of-work for the block, as a spam prevention measure +- ``liquidity_baking_toggle_vote``: :ref:`a vote` to continue the Liquidity Baking Subsidy, stop it, or abstain. + +There are two additional fields: ``payload_hash`` and ``payload_round`` which are needed for establishing if a block is :ref:`final`. + +Operations +~~~~~~~~~~ + +Operations implement and reify different functionalities provided by a Tezos economic protocol: from reaching consensus on the state of the Tezos blockchain, to performing smart contract calls and transactions. Each Tezos economic protocol can specify different kinds of operations. -This entry describes the operations supported by :doc:`the economic +This page only describes the operations supported by :doc:`the economic protocol <./protocol>` that implement *enabled* features -- that is, those available to end-users on Tezos Mainnet. The complete list of operations, including those corresponding to features in development diff --git a/docs/alpha/consensus.rst b/docs/alpha/consensus.rst index 564f17d78af4..35f5374d327c 100644 --- a/docs/alpha/consensus.rst +++ b/docs/alpha/consensus.rst @@ -451,29 +451,11 @@ Consensus related protocol parameters These are a subset of the :ref:`protocol constants `. -.. _shell_proto_revisit_alpha: - -Shell-protocol interaction revisited ------------------------------------- - -.. FIXME tezos/tezos#3914: - - Integrate protocol-specific block parts in the blocks and ops - entry. - -:ref:`Recall` that, for the shell to interact with the economic protocol, two notions are defined abstractly at the level of the shell and made concrete at the level of the consensus protocol. -Namely, these two notions are the protocol-specific header and the fitness. -As in Emmy*, the protocol-specific header contains the fields: - -- ``signature``: a digital signature of the shell and protocol headers (excluding the signature itself) -- ``seed_nonce_hash``: a commitment to :ref:`a random number`, used to generate entropy on the chain -- ``proof_of_work_nonce``: a nonce used to pass a low-difficulty proof-of-work for the block, as a spam prevention measure -- ``liquidity_baking_toggle_vote``: :ref:`a vote` to continue the Liquidity Baking Subsidy, stop it, or abstain. - -There are two additional fields: ``payload_hash`` and ``payload_round`` which are needed for establishing if a block is :ref:`final`. - .. _fitness_alpha: +Fitness +------- + The fitness is given by the tuple ``(version, level, locked_round, - predecessor_round - 1, round)``. The current version of the fitness is 2 (version 0 was used by Emmy, and version 1 by Emmy+ and Emmy*). The fitness encapsulates more information than in Emmy* because Tenderbake is more complex: recall that blocks at the last level only represent :ref:`candidate blocks`. diff --git a/docs/alpha/protocol_overview.rst b/docs/alpha/protocol_overview.rst index 59820bd83c1c..c560063fb7ef 100644 --- a/docs/alpha/protocol_overview.rst +++ b/docs/alpha/protocol_overview.rst @@ -87,7 +87,7 @@ Blocks, Operations and their Validation A block consists of a header and operations. A block's header is composed of two parts: :ref:`the protocol-agnostic part` -and :ref:`the protocol-specific part`. +and :ref:`the protocol-specific part`. This separation enables the shell to interact with different protocols. Each Tezos economic protocol can specify different kinds of operations, which are described further in detail in -- GitLab From 5a3357d31b66027738816a6c02b61cee17bebb00 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Thu, 11 Apr 2024 18:19:29 +0200 Subject: [PATCH 2/2] doc: restructure page consensus --- docs/alpha/consensus.rst | 86 ++++++++++++++++++++-------------------- 1 file changed, 42 insertions(+), 44 deletions(-) diff --git a/docs/alpha/consensus.rst b/docs/alpha/consensus.rst index 35f5374d327c..f6a9726ada62 100644 --- a/docs/alpha/consensus.rst +++ b/docs/alpha/consensus.rst @@ -108,7 +108,7 @@ the initial block. We talk about a *re-proposal* in this case. .. _finality_alpha: Transaction and block finality -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------ A transaction is final as soon as the block including it has a confirmation (that is, a block on top of it). Indeed, as hinted above, a block contains the certification (that is, the attestation quorum) for the previous @@ -123,7 +123,7 @@ confirmation, and thus guarantees **block finality after 2 confirmations**. Time between blocks -~~~~~~~~~~~~~~~~~~~~~~~ +------------------- The time between blocks represents the difference between the timestamps of the blocks. The timestamp of a block is given by the beginning of the round at which the block has been agreed upon. Thus, the time between blocks depends on the round at which decisions are taken. For example, if the decision at the previous level was taken at round 4 and at the current level at round 2, then the current block's delay relative to @@ -141,7 +141,7 @@ should be taken at round 0, meaning that the time between blocks would be .. _active_stake_alpha: Validator selection: staking balance, active stake, and frozen deposits -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------------------------------------------------- Validator selection is based on the stake, as in Emmy*, with the exception that it is based on the delegate's *active stake* instead of its *staking @@ -254,7 +254,7 @@ deposit. However, a delegate can still be over-delegated, and it will be rewarded based on its active stake, not on its staking balance. Economic Incentives -~~~~~~~~~~~~~~~~~~~ +------------------- As Emmy*, Tenderbake rewards participation in consensus and punishes bad behavior. Notable changes however are as follows: @@ -411,46 +411,6 @@ correct validators have more than two thirds of the total stake, these correct validators have sufficient power for agreement to be reached, thus the lack of participation of a selfish baker does not have an impact. -.. _cs_constants_alpha: - -Consensus related protocol parameters -------------------------------------- - -.. list-table:: - :widths: 55 25 - :header-rows: 1 - - * - Parameter name - - Parameter value - * - ``CONSENSUS_COMMITTEE_SIZE`` - - 7000 - * - ``CONSENSUS_THRESHOLD`` - - ``ceil(2 * CONSENSUS_COMMITTEE_SIZE / 3)`` = 4667 - * - ``MINIMAL_BLOCK_DELAY`` - - 10s - * - ``DELAY_INCREMENT_PER_ROUND`` - - 5s - * - ``MINIMAL_PARTICIPATION_RATIO`` - - 2/3 - * - ``FROZEN_DEPOSITS_PERCENTAGE`` - - 10 - * - ``MAX_SLASHING_PERIOD`` - - 2 cycles - * - ``PERCENTAGE_OF_FROZEN_DEPOSITS_SLASHED_PER_DOUBLE_BAKING`` - - 5% - * - ``PERCENTAGE_OF_FROZEN_DEPOSITS_SLASHED_PER_DOUBLE_ATTESTATION`` - - 50% - * - ``BAKING_REWARD_FIXED_PORTION`` - - 3.33 tez - * - ``BAKING_REWARD_BONUS_PER_SLOT`` - - ``bonus / (CONSENSUS_COMMITTEE_SIZE / 3)`` = 0.001429 tez - * - ``ATTESTING_REWARD_PER_SLOT`` - - ``attesting_reward / CONSENSUS_COMMITTEE_SIZE`` = 0.000952 tez - * - ``GLOBAL_LIMIT_OF_STAKING_OVER_BAKING`` - - 5 - -These are a subset of the :ref:`protocol constants `. - .. _fitness_alpha: Fitness @@ -492,7 +452,45 @@ inner sequences). So the first fitness is smaller than the second one, because of the third component, the empty bitstring being smaller than any other bitstring. +.. _cs_constants_alpha: + +Consensus related protocol parameters +------------------------------------- + +.. list-table:: + :widths: 55 25 + :header-rows: 1 + + * - Parameter name + - Parameter value + * - ``CONSENSUS_COMMITTEE_SIZE`` + - 7000 + * - ``CONSENSUS_THRESHOLD`` + - ``ceil(2 * CONSENSUS_COMMITTEE_SIZE / 3)`` = 4667 + * - ``MINIMAL_BLOCK_DELAY`` + - 10s + * - ``DELAY_INCREMENT_PER_ROUND`` + - 5s + * - ``MINIMAL_PARTICIPATION_RATIO`` + - 2/3 + * - ``FROZEN_DEPOSITS_PERCENTAGE`` + - 10 + * - ``MAX_SLASHING_PERIOD`` + - 2 cycles + * - ``PERCENTAGE_OF_FROZEN_DEPOSITS_SLASHED_PER_DOUBLE_BAKING`` + - 5% + * - ``PERCENTAGE_OF_FROZEN_DEPOSITS_SLASHED_PER_DOUBLE_ATTESTATION`` + - 50% + * - ``BAKING_REWARD_FIXED_PORTION`` + - 3.33 tez + * - ``BAKING_REWARD_BONUS_PER_SLOT`` + - ``bonus / (CONSENSUS_COMMITTEE_SIZE / 3)`` = 0.001429 tez + * - ``ATTESTING_REWARD_PER_SLOT`` + - ``attesting_reward / CONSENSUS_COMMITTEE_SIZE`` = 0.000952 tez + * - ``GLOBAL_LIMIT_OF_STAKING_OVER_BAKING`` + - 5 +The above list of protocol parameters is a subset of the :ref:`protocol constants `. Further External Resources -------------------------- -- GitLab