From 7bc9cdd91aecf3977ec27de67669db6cd180fd09 Mon Sep 17 00:00:00 2001 From: Albin Coquereau Date: Fri, 7 Jul 2023 15:16:34 +0200 Subject: [PATCH 1/5] docs: rename endors in alpha documentation --- docs/alpha/blocks_ops.rst | 24 +++---- docs/alpha/consensus.rst | 99 ++++++++++++++-------------- docs/alpha/glossary.rst | 26 ++++---- docs/alpha/liquidity_baking.rst | 2 +- docs/alpha/randomness_generation.rst | 2 +- docs/alpha/token_management.rst | 22 +++---- docs/alpha/validation.rst | 8 +-- 7 files changed, 92 insertions(+), 91 deletions(-) diff --git a/docs/alpha/blocks_ops.rst b/docs/alpha/blocks_ops.rst index 98355f31d820..43bf2249a36e 100644 --- a/docs/alpha/blocks_ops.rst +++ b/docs/alpha/blocks_ops.rst @@ -59,12 +59,12 @@ to implement the :doc:`consensus algorithm`. There are two kinds of consensus operations, each belonging to the different voting phases required to agree on the next block. -- A ``Preendorsement`` operation implements a first vote for a +- A ``Preattestation`` operation implements a first vote for a :ref:`candidate block ` with the aim of - building a :ref:`preendorsement quorum `. + building a :ref:`preattestation quorum `. -- An ``Endorsement`` operation implements a vote for a candidate block - for which a preendorsement quorum certificate (PQC) has been +- An ``Attestation`` operation implements a vote for a candidate block + for which a preattestation quorum certificate (PQC) has been observed. .. _voting_operations_alpha: @@ -122,16 +122,16 @@ which engage in Byzantine behaviour` -- notably delegates which :ref:`"double sign" ` blocks, or emit conflicting :ref:`consensus operations`: -- The ``Double_preendorsement_evidence`` operation allows for accusing - a delegate of having *double-preendorsed* -- i.e., of having - preendorsed two different block candidates, at the same level and at +- The ``Double_preattestation_evidence`` operation allows for accusing + a delegate of having *double-preattested* -- i.e., of having + preattested two different block candidates, at the same level and at the same round. The bulk of the evidence, the two arguments - provided, consists of the two offending preendorsements. + provided, consists of the two offending preattestations. -- Similarly, the ``Double_endorsement_evidence`` operation allows for - accusing a delegate of having *double-endorsed* -- i.e., of having - endorsed two different block candidates at the same level and the - same round -- by providing the two offending endorsements. +- Similarly, the ``Double_attestation_evidence`` operation allows for + accusing a delegate of having *double-attested* -- i.e., of having + attested two different block candidates at the same level and the + same round -- by providing the two offending attestations. - The ``Double_baking_evidence`` allows for accusing a delegate of having "double-baked" a block -- i.e., of having signed two diff --git a/docs/alpha/consensus.rst b/docs/alpha/consensus.rst index b6c6da26afc9..43e96196eb73 100644 --- a/docs/alpha/consensus.rst +++ b/docs/alpha/consensus.rst @@ -89,10 +89,10 @@ Schematically, a round consists in the following steps: 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 ``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``, +before attesting a block ``b``, a validator preattests ``b``. Furthermore, +to be able to attest, a validator must have observed a preattestation *quorum*, that is a +set of preattestations from validators having at least ``CONSENSUS_THRESHOLD`` validator slots. Similarly, to be able to decide, a validator must have observed an attestation quorum, that is, a set of attestations from validators having at least ``CONSENSUS_THRESHOLD`` validator slots. The +attestation 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``. @@ -100,7 +100,7 @@ The validator's whose turn is to inject a candidate block at a given round is called the *proposer* at that round. Proposers in Tenderbake are selected similarly to bakers in Emmy*: the proposer at round ``r`` is the validator who has the validator slot ``r``. A proposer who has observed a -preendorsement quorum for a candidate block in a previous round, is required to propose a block with +preattestation quorum for a candidate block in a previous round, is required to propose a block with the same *payload* as the initial block. We talk about a *re-proposal* in this case. @@ -111,8 +111,8 @@ 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 endorsement quorum) for the previous -payload. Thanks to the endorsement quorum, Tenderbake guarantees **transaction finality +Indeed, as hinted above, a block contains the certification (that is, the attestation quorum) for the previous +payload. Thanks to the attestation quorum, Tenderbake guarantees **transaction finality after 1 confirmation**. It may be possible that different validators decide at different rounds, though on the same payload. The blocks at these different rounds differ precisely because they contain, in the header, as part of the block fitness, @@ -205,7 +205,7 @@ before updating the delegates' :ref:`activity status`. PRESERVED_CYCLES``, the rights for cycle ``c + 2 * PRESERVED_CYCLES + 1`` are computed, and only then is the delegate declared passive. Here "participation" means *having baked a final - block* or *having a preendorsement or endorsement included in a final + block* or *having a preattestation or attestation included in a final block*. Intuitively, the active stake is set to 10 times the delegate's chosen frozen @@ -254,7 +254,7 @@ during the last 8 cycles). We note in passing that this new schema basically solves the main problem of over-delegation: a delegate will not fail anymore to bake -and endorse because of an insufficient balance to pay the +and attest because of an insufficient balance to pay the deposit. However, a delegate can still be over-delegated, and it will be rewarded based on its active stake, not on its staking balance. @@ -268,18 +268,18 @@ behavior. Notable changes however are as follows: transactions to be included in the block (and was the first to propose a block with that payload). In case of re-proposal, the payload producer might be different from the block proposer, the baker who injects the block. -* Including extra endorsements, that is, more than the minimal required to +* Including extra attestations, that is, more than the minimal required to obtain a quorum, is rewarded with a bonus. -* Endorsing rewards are shared equally among all validators. Participation above +* Attesting rewards are shared equally among all validators. Participation above a minimal threshold per cycle is however required. * Deposits are no longer frozen and unfrozen, instead a percentage of the active stake is always locked. A delegate with an empty deposit cannot bake nor - (pre)endorse. -* Validators are rewarded instantaneously for baking blocks and including extra endorsements, and not at the end of the cycle like in Emmy*. + (pre)attest. +* Validators are rewarded instantaneously for baking blocks and including extra attestations, and not at the end of the cycle like in Emmy*. * At the end of a cycle ``c``, the following actions happen: - the selection of the consensus committee cycle ``c + PRESERVED_CYCLES``, based on the current active stake distribution, - - the distribution of endorsing rewards, + - the distribution of attesting rewards, - the adjustment of frozen deposits. @@ -303,20 +303,20 @@ block. Rewards ^^^^^^^ -There are three kinds of rewards: baking rewards, endorsing rewards, and a bonus for including extra endorsements. +There are three kinds of rewards: baking rewards, attesting rewards, and a bonus for including extra attestations. The baking rewards are treated in the same way as fees: they go to the *payload* producer and are distributed immediately. To encourage fairness and participation, the *block* proposer receives -a bonus for the extra endorsements it includes in the block. +a bonus for the extra attestations it includes in the block. The bonus is proportional to the number of validator slots above the threshold of ``CONSENSUS_COMMITTEE_SIZE * 2 / 3`` that -the included endorsements represent. The bonus is also distributed +the included attestations represent. The bonus is also distributed immediately. -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). +The attesting rewards are distributed at the end of the cycle. +The attesting reward may be received even if not all of the validator's attestations 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 @@ -325,8 +325,8 @@ However, two conditions must be met: Not giving rewards in case of missing revelations is not new as it is :ref:`adapted` from Emmy*. The second condition is new. We say that a delegate is *present* during a cycle -if the endorsing power (that is, the number of validator slots at the -corresponding level) of all the endorsements included by the delegate during the +if the attesting power (that is, the number of validator slots at the +corresponding level) of all the attestations 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``). @@ -338,7 +338,7 @@ We define: - ``BAKING_REWARD_FIXED_PORTION := baking_reward_ratio * total_rewards`` - ``bonus := (1 - baking_reward_ratio) * bonus_ratio * total_rewards`` is the max bonus -- ``endorsing_reward := (1 - baking_reward_ratio) * (1 - bonus_ratio) * total_rewards`` +- ``attesting_reward := (1 - baking_reward_ratio) * (1 - bonus_ratio) * total_rewards`` where: @@ -346,30 +346,30 @@ where: - ``bonus_ratio`` to ``1 / 3``. Thus, we obtain ``BAKING_REWARD_FIXED_PORTION = 5`` tez, -(maximum) ``bonus = 5`` tez, and ``endorsing_rewards = 10`` tez. -The bonus per additional endorsement slot is in turn ``bonus / +(maximum) ``bonus = 5`` tez, and ``attesting_rewards = 10`` tez. +The bonus per additional attestation slot is in turn ``bonus / (CONSENSUS_COMMITTEE_SIZE / 3)`` (because there are at most ``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``. +additional attestations included in a block). The rewards per +attestation slot are ``attesting_rewards / CONSENSUS_COMMITTEE_SIZE``. Assuming ``CONSENSUS_COMMITTEE_SIZE = 7000``, we obtain a bonus per slot of -``5 / (7000 / 3) = 0.002143`` tez and an endorsing +``5 / (7000 / 3) = 0.002143`` tez and an attesting rewards per slot of ``10 / 7000 = 0.001428`` 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 -A. Also, B includes endorsements with endorsing power ``5251``. Then A receives +A. Also, B includes attestations with attesting power ``5251``. Then A receives the fees and 10 tez (the ``BAKING_REWARD_FIXED_PORTION``) as a reward for producing the block's payload. Concerning the bonus, given that ``CONSENSUS_COMMITTEE_SIZE = 7000``, the minimum required validator slots is ``4667``, and there are ``2333 = 7000 - 4667`` additional validator slots. Therefore B receives the bonus ``(5251 - 4667) * 0.002143 = 1.251512`` tez. (Note -that B only included endorsements corresponding to 584 = 5251 - 4667 additional validator slots, about a quarter of the -maximum 2333 extra endorsements it could have theoretically included.) Finally, consider some +that B only included attestations corresponding to 584 = 5251 - 4667 additional validator slots, about a quarter of the +maximum 2333 extra attestations it could have theoretically included.) Finally, consider some delegate C, whose active stake at some cycle is 5% of the total stake. Note that his expected number of validator slots for that cycle is ``5/100 * 8192 * 7000 = -2,867,200`` slots. Assume also that the endorsing power of C's endorsements +2,867,200`` slots. Assume also that the attesting power of C's attestations included during that cycle has been ``2,123,456`` slots. Given that this number is -bigger than the minimum required (``2,867,200 * 2 / 3``), it receives an endorsing +bigger than the minimum required (``2,867,200 * 2 / 3``), it receives an attesting reward of ``2,867,200 * 0.001428 = 4094.3616`` tez for that cycle. .. _slashing_alpha: @@ -379,25 +379,26 @@ Slashing 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 -(which means signing different blocks at the same level and same round) or -it double (pre)endorses (which means voting on two different proposals at the -same level and round), a part of the frozen deposit is slashed. The slashed amount for double baking -is ``DOUBLE_BAKING_PUNISHMENT``. The slashed amount for double (pre)endorsing is -a fixed percentage ``RATIO_OF_FROZEN_DEPOSITS_SLASHED_PER_DOUBLE_ENDORSEMENT`` -of the frozen deposit. The payload producer that includes the misbehavior -evidence is rewarded half of the slashed amount. +its attesting rewards. If a validator double signs, that is, it double bakes +(which means signing different blocks at the same level and same round) or it +double (pre)attests (which means voting on two different proposals at the same +level and round), a part of the frozen deposit is slashed. The slashed amount +for double baking is ``DOUBLE_BAKING_PUNISHMENT``. The slashed amount for double +(pre)attesting is a fixed percentage +``PERCENTAGE_OF_FROZEN_DEPOSITS_SLASHED_PER_DOUBLE_ATTESTATION`` of the frozen +deposit. The payload producer that includes the misbehavior evidence is rewarded +half of the slashed amount. The evidence for double signing at a given level can be collected by any :ref:`accuser` and included as an *accusation* operation in a block for a period of ``MAX_SLASHING_PERIOD``. If a delegates' deposit is smaller than the slashed amount, the deposit is -simply emptied, which leads to the delegate losing its baking and endorsing +simply emptied, which leads to the delegate losing its baking and attesting rights for the rest of the cycle. We note that selfish baking is not an issue in Tenderbake: say we are at round -``r`` and the validator which is proposer at round ``r+1`` does not (pre)endorse +``r`` and the validator which is proposer at round ``r+1`` does not (pre)attest at round ``r`` in the hope that the block at round ``r`` is not agreed upon and its turn comes to propose at round ``r+1``. Under the assumption that the correct validators have more than two thirds of the total stake, these correct @@ -431,14 +432,14 @@ Consensus related protocol parameters - 2 cycles * - ``DOUBLE_BAKING_PUNISHMENT`` - 640 tez - * - ``RATIO_OF_FROZEN_DEPOSITS_SLASHED_PER_DOUBLE_ENDORSEMENT`` - - 1/2 + * - ``PERCENTAGE_OF_FROZEN_DEPOSITS_SLASHED_PER_DOUBLE_ATTESTATION`` + - 50% * - ``BAKING_REWARD_FIXED_PORTION`` - 5 tez * - ``BAKING_REWARD_BONUS_PER_SLOT`` - ``bonus / (CONSENSUS_COMMITTEE_SIZE / 3)`` = 0.002143 tez - * - ``ENDORSING_REWARD_PER_SLOT`` - - ``endorsing_reward / CONSENSUS_COMMITTEE_SIZE`` = 0.001428 tez + * - ``ATTESTING_REWARD_PER_SLOT`` + - ``attesting_reward / CONSENSUS_COMMITTEE_SIZE`` = 0.001428 tez These are a subset of the :ref:`protocol constants `. @@ -475,11 +476,11 @@ Furthermore, we also allow to change the predecessor block when it has a :ref:`s Therefore the fitness also includes the opposite of predecessor block's round as the forth component (the predecessor is taken for technical reasons). Finally, to (partially) enforce :ref:`the rule on re-proposals`, the fitness also includes, as the third -component, the round at which a preendorsement quorum was observed by +component, the round at which a preattestation quorum was observed by the baker, if any (this component can therefore be empty). By the way, -preendorsements are present in a block if and only if the locked round +preattestations are present in a block if and only if the locked round component is non-empty and if so, the locked round has to match the -round of the included preendorsements. +round of the included preattestations. Next, we provide two examples of fitness values: ``02::00001000::::ffffffff::00000000`` and diff --git a/docs/alpha/glossary.rst b/docs/alpha/glossary.rst index ed045b444e28..c015b4951f7a 100644 --- a/docs/alpha/glossary.rst +++ b/docs/alpha/glossary.rst @@ -121,12 +121,12 @@ _`Baking` The act of creating a new block_ by a baker_. _`Baking rights` - Baking_/endorsing_ a block_ can only be done by a delegate_ who holds the - baking/endorsing right for that block level_ and round_. At the start of a cycle_, - baking and endorsing rights are computed for all the block_ levels and rounds in the + Baking_/attesting_ a block_ can only be done by a delegate_ who holds the + baking/attesting right for that block level_ and round_. At the start of a cycle_, + baking and attesting rights are computed for all the block_ levels and rounds in the cycle_, based on the proportion of the stake_ of each delegate_. - For each block_ level and round_, there is exactly one account that is allowed to bake, but several accounts are allowed to endorse. + For each block_ level and round_, there is exactly one account that is allowed to bake, but several accounts are allowed to attest. _`Burn` To ensure responsible use of the storage space on the public blockchain, @@ -171,7 +171,7 @@ _`Delegate` _`Delegation` An operation_ in which an account_ designates a delegate_. The delegating account's balance increases the delegate_'s stake_ and consequently - its `baking rights`_ and `endorsing rights`_. However, the delegate_ does not control the funds of + its `baking rights`_ and `attesting rights`_. However, the delegate_ does not control the funds of the delegating account_, e.g., it can not spend them. .. _def_double_signing_alpha: @@ -180,8 +180,8 @@ _`Double signing` The situation when a baker_ signs two different block_\ s at the same level and same round, is called double baking. Double baking is detrimental to the network and might be indicative of an attempt to double spend. - The same goes for signing two different endorsements at the same level and the same round. - As such, double signing (i.e., double baking or double endorsing) is punished by the + The same goes for signing two different attestations at the same level and the same round. + As such, double signing (i.e., double baking or double attesting) is punished by the network: an accuser_ can provide proof of the double signing to be awarded part of the double signer's deposit -- see :ref:`Slashing`. @@ -193,12 +193,12 @@ _`Failing Noop` :ref:`sign arbitrary messages` which have no computational semantics. -_`Endorsing` +_`Attesting` When a block_ is created and propagated on the network, delegates that have - `endorsing rights`_ for the matching block level_ and round_ can emit an endorsement operation_. - Endorsement operations are included in the next block_. + `attesting rights`_ for the matching block level_ and round_ can emit an attestation operation_. + Attestation operations are included in the next block_. -_`Endorsing rights` +_`Attesting rights` See `baking rights`_. .. _def_fee_alpha: @@ -262,7 +262,7 @@ _`Minimal stake` _`Operation kinds` The main kinds of operations in the protocol are transactions (to transfer funds or to execute smart contracts), accusations, activations, delegations, - endorsements, and originations. + attestations, and originations. For the full list of operations, see :doc:`./blocks_ops`. _`Originated account` @@ -302,7 +302,7 @@ _`Smart Optimistic Rollups` _`Stake` The amount of tokens that determines a delegate_'s weight in the governance process and in the selection of its baking and - `endorsing rights`_. A delegate's stake is usually given by the + `attesting rights`_. A delegate's stake is usually given by the delegate's own tokens plus the sum of tokens delegated to it. However, there are cases when this is not the case, see :ref:`here` for details. diff --git a/docs/alpha/liquidity_baking.rst b/docs/alpha/liquidity_baking.rst index 52df74c5d011..2eab657a14e7 100644 --- a/docs/alpha/liquidity_baking.rst +++ b/docs/alpha/liquidity_baking.rst @@ -26,7 +26,7 @@ The LIGO and Michelson code for these contracts, as well as detailed documentati Subsidy ~~~~~~~ -At every block in the chain, a small amount of tez is minted and credited to the CPMM contract, and the CPMM's ``%default`` entrypoint is called to update the ``xtz_pool`` balance in its storage. The amount that is minted and sent to the CPMM contract is 1/16th of the rewards for a block of round 0 with all endorsements; currently these rewards are 20 tez per block so the amount that is sent to the CPMM contract is 1.25 tez per block. +At every block in the chain, a small amount of tez is minted and credited to the CPMM contract, and the CPMM's ``%default`` entrypoint is called to update the ``xtz_pool`` balance in its storage. The amount that is minted and sent to the CPMM contract is 1/16th of the rewards for a block of round 0 with all attestations; currently these rewards are 20 tez per block so the amount that is sent to the CPMM contract is 1.25 tez per block. So the credits to the CPMM contract can be accounted for by indexers, they are included in block metadata as a balance update with a new constructor for ``update_origin``, ``Subsidy``. diff --git a/docs/alpha/randomness_generation.rst b/docs/alpha/randomness_generation.rst index 6e2d21933fce..c470f092b8b1 100644 --- a/docs/alpha/randomness_generation.rst +++ b/docs/alpha/randomness_generation.rst @@ -104,7 +104,7 @@ commitment is simply the hash of the nonce. The committed nonce must be revealed by the original block proposer during the nonce revelation phase, that is during the first ``NONCE_REVELATION_THRESHOLD`` blocks, of cycle ``n-1-PRESERVED_CYCLES`` under penalty of forfeiting all of -its expected endorsing rewards for that cycle. The associated security deposit +its expected attesting rewards for that cycle. The associated security deposit and baking rewards are not affected. The RANDAO output is then computed and stored on-chain as the temporary seed for cycle ``n``. The RANDAO output is the bitstring obtained by iterating through the nonces revealed in cycle ``n-1`` as diff --git a/docs/alpha/token_management.rst b/docs/alpha/token_management.rst index 464273b52781..c154a89dbe2a 100644 --- a/docs/alpha/token_management.rst +++ b/docs/alpha/token_management.rst @@ -61,9 +61,9 @@ The value of the additional field ``category`` designates one of the following f * ``"nonce revelation rewards"`` is the source of tokens minted to reward delegates for revealing their nonces * ``"double signing evidence rewards"`` is the source of tokens minted to reward delegates for injecting a double signing evidence -* ``"endorsing rewards"`` is the source of tokens minted to reward delegates for endorsing blocks +* ``"attesting rewards"`` is the source of tokens minted to reward delegates for attesting blocks * ``"baking rewards"`` is the source of tokens minted to reward delegates for creating blocks -* ``"baking bonuses"`` is the source of tokens minted to reward delegates for validating blocks and including extra endorsements +* ``"baking bonuses"`` is the source of tokens minted to reward delegates for validating blocks and including extra attestations * ``"subsidy"`` is the source of tokens minted to subsidize the liquidity baking CPMM contract * ``"invoice"`` is the source of tokens minted to compensate some users who have contributed to the betterment of the chain * ``"commitment"`` is the source of tokens minted to match commitments made by some users to supply funds for the chain @@ -113,8 +113,8 @@ The value of the additional field ``category`` allows to identify more specifica The field ``category`` of a sink account may have one of the following values: * ``"storage fees"`` is the destination of storage fees burned for consuming storage space on the chain -* ``"punishments"`` is the destination of tokens burned as punishment for a delegate that has double baked or double endorsed -* ``"lost endorsing rewards"`` is the destination of rewards that were not distributed to a delegate. +* ``"punishments"`` is the destination of tokens burned as punishment for a delegate that has double baked or double attested +* ``"lost attesting rewards"`` is the destination of rewards that were not distributed to a delegate. This category comes with the following additional fields: - the field ``delegate`` contains the public key hash of the delegate @@ -176,28 +176,28 @@ For example, the balance updates generated for an amount of ``100`` mutez in bak [ {"kind": "minted", "category": "baking bonus", "change": "-100", ...}, {"kind": "contract", "contract": "tz1b...", "change": "100", ...} ] -Endorsing, double signing evidence, and nonce revelation rewards +Attesting, double signing evidence, and nonce revelation rewards ---------------------------------------------------------------- -Endorsing rewards are reflected in balance updates as a transfer of tokens from the ``"endorsing rewards"`` source account to the account of the delegate that receives the reward. +Attesting rewards are reflected in balance updates as a transfer of tokens from the ``"attesting rewards"`` source account to the account of the delegate that receives the reward. Hence, for a reward of ``100`` mutez, the following two balance updates are generated: :: - [ {"kind": "minted", "category": "endorsing rewards", "change": "-100", ...}, + [ {"kind": "minted", "category": "attesting rewards", "change": "-100", ...}, {"kind": "contract", "contract": "tz1...", "change": "100", ...} ] -When endorsing rewards are not distributed to the delegate due to insufficient participation or for not revealing nonces, they are transferred instead to the sink account identified by the quadruple ``("lost endorsing rewards", delegate, participation, revelation)``. +When attesting rewards are not distributed to the delegate due to insufficient participation or for not revealing nonces, they are transferred instead to the sink account identified by the quadruple ``("lost attesting rewards", delegate, participation, revelation)``. For example, for an amount of ``100`` mutez in rewards not distributed due to insufficient participation, the following balance updates are generated: :: - [ {"kind": "minted", "category": "endorsing rewards", "change": "-100", ...}, + [ {"kind": "minted", "category": "attesting rewards", "change": "-100", ...}, {"kind": "burned", - "category": "lost endorsing rewards", + "category": "lost attesting rewards", "delegate": "tz1...", "participation": "true", "revelation": "false", "change": "100", ...} ] -Double signing evidence rewards and nonce revelation rewards are analogous to endorsing rewards, except that the source accounts used are ``"double signing evidence rewards"`` and ``"nonce revelation rewards"``. +Double signing evidence rewards and nonce revelation rewards are analogous to attesting rewards, except that the source accounts used are ``"double signing evidence rewards"`` and ``"nonce revelation rewards"``. diff --git a/docs/alpha/validation.rst b/docs/alpha/validation.rst index f4aaf072b895..8558f61b0dfd 100644 --- a/docs/alpha/validation.rst +++ b/docs/alpha/validation.rst @@ -163,7 +163,7 @@ protocol environment: any possible context from its future successors, but it might still be valid in an alternative branch. For example: a manager operation with a smaller counter than the one expected (a - *"counter-in-the-past"* error), an unexpected endorsement for the + *"counter-in-the-past"* error), an unexpected attestation for the current level, etc. - ``Permanent``: the operation is invalid in the current context, and @@ -173,7 +173,7 @@ protocol environment: - ``Outdated``: the operation is *too old* to be included in a block. Furthermore, there might be still some value in the information provided by an ``Outdated`` operation. An example is the - case of an endorsement which was received *too late*, but that could + case of an attestation which was received *too late*, but that could still be used to form a consensus quorum. .. _partial_application_alpha: @@ -198,7 +198,7 @@ proceeds to "partially apply" each block of this branch using the common ancestor's context. Indeed, by relying on the ancestor context, this mode can *only* -assert the validity of consensus-related preconditions (endorsing +assert the validity of consensus-related preconditions (attesting power, block fitness, etc.), as future consensus slots are known in advance -- how much in advance being specified by the ```` protocol constant. Thus, the ``Partial @@ -237,7 +237,7 @@ considered as invalid. The last step in the block validation process, known as "block finalization", aims to verify that the collected consensus operations constitute a sufficiently large :ref:`quorum`. That is, -it will verify that the total endorsing power present in the block is +it will verify that the total attesting power present in the block is greater than the ``CONSENSUS_THRESHOLD`` constant. This sequence of three steps also yields a new context -- the -- GitLab From 6b5939d08f3f214769322f3a3f0bce65ee41e31c Mon Sep 17 00:00:00 2001 From: Albin Coquereau Date: Fri, 7 Jul 2023 15:18:02 +0200 Subject: [PATCH 2/5] docs: rename endors in introduction documentation --- docs/introduction/howtoget.rst | 1 - docs/introduction/howtorun.rst | 22 +++++++++++----------- 2 files changed, 11 insertions(+), 12 deletions(-) diff --git a/docs/introduction/howtoget.rst b/docs/introduction/howtoget.rst index 4886c4453c5b..82e8285f82ea 100644 --- a/docs/introduction/howtoget.rst +++ b/docs/introduction/howtoget.rst @@ -7,7 +7,6 @@ In this how-to we explain how to get up-to-date binaries to run Tezos (more precisely, the "Octez" implementation of Tezos software) on any network (either on the mainnet or on one of the test networks). Octez consists of :ref:`several binaries ` (i.e., executable files), including: a client, a node, and a baker. -(Before the :doc:`Ithaca protocol<../protocols/012_ithaca>` it also included an endorser.) There are several options for getting the binaries, depending on how you plan to use Octez: diff --git a/docs/introduction/howtorun.rst b/docs/introduction/howtorun.rst index 985ff0d5012e..ca045e18a6ae 100644 --- a/docs/introduction/howtorun.rst +++ b/docs/introduction/howtorun.rst @@ -75,12 +75,12 @@ When a delegator spends their tokens, the delegated balance of their delegate de Running a delegate ------------------ -A delegate is responsible for baking blocks, endorsing blocks and +A delegate is responsible for baking blocks, attesting blocks and accusing other delegates in case they try to double bake or double -endorse. A delegate is also responsible for taking part in the +attest. A delegate is also responsible for taking part in the :doc:`governance process<../active/voting>`. -Rights for baking and endorsing are randomly assigned +Rights for baking and attesting are randomly assigned to delegates proportionally to their :ref:`active stake`, which usually is the same as their staking balance, that is, their own balance plus their delegated balance. @@ -149,8 +149,8 @@ operations during 5 cycles to remain active. If for some reason your delegate is marked inactive you can reactivate it simply by re-registering again like above. -To avoid your Tezos delegate being marked inactive while pausing it for maintenance work, it is advised to check the schedule of future baking and endorsing slots assigned to it, using a block explorer in the :ref:`Tezos community `. -Alternatively, you may use the baking rights RPC and the endorsing rights RPC (see :doc:`../api/openapi`), which is able to return a list of baking/endorsing slots for a given delegate (see :ref:`example `). +To avoid your Tezos delegate being marked inactive while pausing it for maintenance work, it is advised to check the schedule of future baking and attesting slots assigned to it, using a block explorer in the :ref:`Tezos community `. +Alternatively, you may use the baking rights RPC and the attesting rights RPC (see :doc:`../api/openapi`), which is able to return a list of baking/attesting slots for a given delegate (see :ref:`example `). .. _baker_run: @@ -163,7 +163,7 @@ all accounts whose secret keys are known. During its run, the baker bakes blocks (by selecting transactions from the mempool and arranging them in a new block) and emits consensus -operations like endorsements. It does so whenever the associated +operations like attestations. It does so whenever the associated accounts have the necessary rights. Let's launch the daemon pointing to the standard node directory and @@ -181,8 +181,8 @@ Note that ``--liquidity-baking-toggle-vote`` must be placed .. warning:: - **Remember that having two bakers running connected to the same account could lead to double baking/endorsing and the loss of all your bonds.** - 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`). + **Remember that having two bakers running connected to the same account could lead to double baking/attesting and the loss of all your bonds.** + If you are worried about the availability of your node when it is its turn to bake/attest, there are other ways than duplicating your credentials (see the discussion in section :ref:`inactive_delegates`). **Never** use the same account on two daemons. However, it is safe (and actually necessary) to temporarily run two bakers just before a protocol activation: the baker for the protocol being replaced and the baker for the protocol to be activated. @@ -190,7 +190,7 @@ However, it is safe (and actually necessary) to temporarily run two bakers just .. note:: - It is possible to bake and endorse using a dedicated :ref:`consensus_key` instead of the delegate's key. + It is possible to bake and attest using a dedicated :ref:`consensus_key` instead of the delegate's key. Accuser ~~~~~~~ @@ -199,11 +199,11 @@ The accuser is a daemon that monitors all blocks received on all chains and looks for: * bakers who signed two blocks at the same level and the same round -* bakers who injected more than one pre-endorsements or endorsement operation for the +* bakers who injected more than one pre-attestations or attestation operation for the same level and round (more details :doc:`here <../active/consensus>`) Upon finding such irregularity, it will emit respectively a -double-baking, double-pre-endorsing, or double-endorsing denunciation operation, which will +double-baking, double-pre-attesting, or double-attesting denunciation operation, which will cause the offender to be :ref:`slashed`, that is, to lose part of its security deposit. :: -- GitLab From e1aab282e32935247ebf1c19d488aa6897e3cb55 Mon Sep 17 00:00:00 2001 From: Albin Coquereau Date: Fri, 7 Jul 2023 15:22:00 +0200 Subject: [PATCH 3/5] docs: rename endors in shell documentation --- docs/shell/sync.rst | 4 ++-- docs/shell/validation.rst | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/shell/sync.rst b/docs/shell/sync.rst index 8711e0fc771d..2b348302cad0 100644 --- a/docs/shell/sync.rst +++ b/docs/shell/sync.rst @@ -2,8 +2,8 @@ Synchronisation heuristic ========================= When a new node joins the network, it must **bootstrap**: fetch and -validate the chain before starting to bake or endorse new blocks. A -bootstrapping node cannot bake or endorse new blocks, so for +validate the chain before starting to bake or attest new blocks. A +bootstrapping node cannot bake or attest new blocks, so for efficiency it should not bother to track a **mempool**: a pool of active operations. diff --git a/docs/shell/validation.rst b/docs/shell/validation.rst index f103492a19f3..cac757c84388 100644 --- a/docs/shell/validation.rst +++ b/docs/shell/validation.rst @@ -119,10 +119,10 @@ is in a close enough time window. In protocol Alpha, the check performed on block headers is that the baking slots, baker signatures, and timestamp deltas are right. It can also detect too large fitness gaps, as the fitness difference between two consecutive blocks is -bounded in Alpha. The operations that act on fitness are endorsements, -whose checks consist in verifying the endorsement slots and endorsers' +bounded in Alpha. The operations that act on fitness are attestations, +whose checks consist in verifying the attestation slots and attesters' signatures. For that to be sound, the fork limit is set to not allow -rewinding before the baking and endorsing slots are set. +rewinding before the baking and attesting slots are set. Each of these three peer validator tasks (head increment, bootstrap pipeline, or multi-pass) will interact with the distributed DB to get -- GitLab From 4546d2e117dc0e0f878f6b4995bf8267c6c03c49 Mon Sep 17 00:00:00 2001 From: Albin Coquereau Date: Fri, 7 Jul 2023 15:25:01 +0200 Subject: [PATCH 4/5] docs: rename endors in user documentation --- docs/user/key-management.rst | 14 ++-- docs/user/mockup.rst | 125 ++++++++++++++++++++++--------- docs/user/node-configuration.rst | 4 +- 3 files changed, 98 insertions(+), 45 deletions(-) diff --git a/docs/user/key-management.rst b/docs/user/key-management.rst index 1db91bb37f27..67aa4018b057 100644 --- a/docs/user/key-management.rst +++ b/docs/user/key-management.rst @@ -10,7 +10,7 @@ Indeed, by default: - Private keys are stored unencrypted in file ``$OCTEZ_CLIENT_DIR/secret_keys``. - The client uses these keys to sign user operations (e.g. transfers) by itself. -- The baker daemon uses these keys to automatically sign its operations (e.g. (pre-)endorsements). +- The baker daemon uses these keys to automatically sign its operations (e.g. (pre-)attestations). The solutions provided to strengthen the security of the default key management and signing are the following: @@ -18,7 +18,7 @@ The solutions provided to strengthen the security of the default key management + store your private keys securely + sign user operations (e.g. transfers) interactively on the wallet - + automatically sign baking operations, such as (pre-)endorsements, more securely. + + automatically sign baking operations, such as (pre-)attestations, more securely. - If you don't have a hardware wallet, the option ``--encrypted`` of the client offers a first protection for storing your keys. @@ -85,7 +85,7 @@ Tezos Baking app In Ledger Live (with Developer Mode enabled), there is also a ``Tezos Baking`` app which allows a delegate to sign automatically (i.e., there is no need -to manually sign every block or (pre-)endorsement). +to manually sign every block or (pre-)attestation). Of course, the application is restricted to only sign baking operations; it never signs a transfer, for example. Furthermore, the application keeps track of the last level baked and only allows baking for subsequent levels. @@ -130,7 +130,7 @@ In the case of blocks or consensus operations for example, this format is instan -Starting with Octez v12 (supporting the Ithaca protocol), consensus operations also include :ref:`preendorsements `. The magic byte distinguishes pre-Ithaca messages from (post-)Ithaca messages, as follows: +Starting with Octez v12 (supporting the Ithaca protocol), consensus operations also include :ref:`preattestations `. The magic byte distinguishes pre-Ithaca messages from (post-)Ithaca messages, as follows: .. list-table:: :widths: 55 25 @@ -150,9 +150,9 @@ Starting with Octez v12 (supporting the Ithaca protocol), consensus operations a - 0x05 * - Block - 0x11 - * - Pre-endorsement + * - Pre-attestation - 0x12 - * - Endorsement + * - Attestation - 0x13 The magic byte values to be used by the signer can be restricted using its option ``--magic-bytes``, as explained in the :ref:`signer's manual `. @@ -270,7 +270,7 @@ Consensus Key The "consensus key" feature is available starting with the Tezos :doc:`Lima<../protocols/015_lima>` protocol. By default, the baker's key, also called manager key, is used to sign in the consensus protocol, i.e. signing blocks while baking, -and signing consensus operations (preendorsements and endorsements). +and signing consensus operations (preattestations and attestations). A delegate may elect instead to choose a dedicated key: the *consensus key*. It can then be changed without redelegation. diff --git a/docs/user/mockup.rst b/docs/user/mockup.rst index 307c8f18dde8..54b0be7c8b73 100644 --- a/docs/user/mockup.rst +++ b/docs/user/mockup.rst @@ -252,43 +252,96 @@ commands. The following was generated: .. code-block:: JSON { - "initial_timestamp": "1970-01-01T00:00:00Z", - "chain_id": "NetXynUjJNZm7wi", - "delay_per_missing_endorsement": "1", - "initial_endorsers": 1, - "min_proposal_quorum": 500, - "quorum_max": 7000, - "quorum_min": 2000, - "hard_storage_limit_per_operation": "60000", - "cost_per_byte": "250", - "endorsement_reward": [ - "1250000", - "833333" - ], - "baking_reward_per_endorsement": [ - "1250000", - "187500" - ], - "endorsement_security_deposit": "64000000", - "block_security_deposit": "512000000", - "origination_size": 257, - "seed_nonce_revelation_tip": "125000", - "michelson_maximum_type_size": 1000, - "tokens_per_roll": "8000000000", - "proof_of_work_threshold": "-1", - "hard_gas_limit_per_block": "10400000", - "hard_gas_limit_per_operation": "1040000", - "endorsers_per_block": 32, - "time_between_blocks": [ - "1", - "0" - ], - "cycles_per_voting_period": 8, - "blocks_per_roll_snapshot": 4, - "blocks_per_commitment": 4, + "preserved_cycles": 2, "blocks_per_cycle": 8, - "preserved_cycles": 2 - } + "blocks_per_commitment": 4, + "nonce_revelation_threshold": 4, + "blocks_per_stake_snapshot": 4, + "cycles_per_voting_period": 8, + "hard_gas_limit_per_operation": "1040000", + "hard_gas_limit_per_block": "2600000", + "proof_of_work_threshold": "4611686018427387903", + "minimal_stake": "6000000000", + "vdf_difficulty": "50000", + "origination_size": 257, + "reward_weights": { + "base_total_rewards_per_minute": "85007812", + "baking_reward_fixed_portion_weight": 5120, + "baking_reward_bonus_weight": 5120, + "attesting_reward_weight": 10240, + "liquidity_baking_subsidy_weight": 1280, + "seed_nonce_revelation_tip_weight": 1, + "vdf_revelation_tip_weight": 1 + }, + "cost_per_byte": "250", + "hard_storage_limit_per_operation": "60000", + "quorum_min": 2000, + "quorum_max": 7000, + "min_proposal_quorum": 500, + "liquidity_baking_toggle_ema_threshold": 1000000000, + "max_operations_time_to_live": 240, + "minimal_block_delay": "1", + "delay_increment_per_round": "1", + "consensus_committee_size": 256, + "consensus_threshold": 0, + "minimal_participation_ratio": { + "numerator": 2, + "denominator": 3 + }, + "max_slashing_period": 2, + "delegation_over_baking_limit": 19, + "percentage_of_frozen_deposits_slashed_per_double_baking": 10, + "percentage_of_frozen_deposits_slashed_per_double_attestation": 50, + "cache_script_size": 100000000, + "cache_stake_distribution_cycles": 8, + "cache_sampler_state_cycles": 8, + "dal_parametric": { + "feature_enable": false, + "number_of_slots": 16, + "attestation_lag": 4, + "attestation_threshold": 50, + "blocks_per_epoch": 2, + "redundancy_factor": 8, + "page_size": 128, + "slot_size": 32768, + "number_of_shards": 64 + }, + "smart_rollup_enable": true, + "smart_rollup_arith_pvm_enable": false, + "smart_rollup_origination_size": 6314, + "smart_rollup_challenge_window_in_blocks": 80640, + "smart_rollup_stake_amount": "10000000000", + "smart_rollup_commitment_period_in_blocks": 60, + "smart_rollup_max_lookahead_in_blocks": 172800, + "smart_rollup_max_active_outbox_levels": 80640, + "smart_rollup_max_outbox_messages_per_level": 100, + "smart_rollup_number_of_sections_in_dissection": 32, + "smart_rollup_timeout_period_in_blocks": 40320, + "smart_rollup_max_number_of_cemented_commitments": 5, + "smart_rollup_max_number_of_parallel_games": 32, + "smart_rollup_reveal_activation_level": { + "raw_data": { "Blake2B": 0 }, + "metadata": 0, + "dal_page": 0 + }, + "zk_rollup_enable": false, + "zk_rollup_origination_size": 4000, + "zk_rollup_min_pending_to_process": 10, + "zk_rollup_max_ticket_payload_size": 2048, + "staking_over_baking_global_limit": 5, + "staking_over_delegation_edge": 2, + "adaptive_inflation_launch_ema_threshold": 1600000000, + "adaptive_rewards_params": { + "reward_ratio_min": { "numerator": "1", "denominator": "200" }, + "reward_ratio_max": { "numerator": "1", "denominator": "10" }, + "max_bonus": "50000000000000", + "growth_rate": "115740740", + "center_dz": { "numerator": "1", "denominator": "2" }, + "radius_dz": { "numerator": "1", "denominator": "50" } + }, + "chain_id": "NetXynUjJNZm7wi", + "initial_timestamp": "1970-01-01T00:00:00Z" + } Besides usual protocol constants, there are 2 additional fields supported in Mockup mode: diff --git a/docs/user/node-configuration.rst b/docs/user/node-configuration.rst index f7c7a82d9352..ed520a9a4866 100644 --- a/docs/user/node-configuration.rst +++ b/docs/user/node-configuration.rst @@ -225,7 +225,7 @@ remote address. A common situation is when one wants to accept only safe RPC requests coming from remote hosts, but enable all RPCs for localhost (which is for instance necessary -to perform baking and endorsing). Since all RPCs are available to localhost by +to perform baking and attesting). Since all RPCs are available to localhost by default, it is sufficient to open another listening address:: $ octez-node run --rpc-addr localhost --rpc-addr 0.0.0.0 @@ -267,7 +267,7 @@ take two main forms: Thus all costly or risky endpoints are blocked by default. This can be relaxed or tightened by modifying the configuration file. It's worth noting that this default policy among other things disallows baking and -endorsing by bakers running on remote servers, +attesting by bakers running on remote servers, because endpoints such as ``/injection/block`` are not open remotely. Rather than opening them remotely, the recommended practice for baking is to run a node locally listening to ``localhost``, with the default ACL policy. -- GitLab From f73dbc94ef63fd0ca0775de6b7680369dbe8e8d4 Mon Sep 17 00:00:00 2001 From: Albin Coquereau Date: Fri, 7 Jul 2023 15:28:16 +0200 Subject: [PATCH 5/5] docs: rename endors in developer documentation --- docs/developer/guidelines.rst | 2 +- docs/developer/proposal_testing.rst | 8 ++++---- docs/developer/snoop_tutorial.rst | 2 +- docs/developer/testing.rst | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/developer/guidelines.rst b/docs/developer/guidelines.rst index ad644a3425cf..9200a41d1361 100644 --- a/docs/developer/guidelines.rst +++ b/docs/developer/guidelines.rst @@ -418,7 +418,7 @@ During the development of the codebase a lot of RPC endpoints were created, some of which are responsible for delicate or computationally intense tasks like validating blocks or executing Michelson scripts. While some of them are necessary for the node's users to interact with the blockchain, others are there -to expose API to processes responsible for baking and endorsing, for +to expose API to processes responsible for baking and attesting, for configuration or debugging purposes or to facilitate development of smart contracts. diff --git a/docs/developer/proposal_testing.rst b/docs/developer/proposal_testing.rst index 122b6bcc3c4c..8a0bd98a34b8 100644 --- a/docs/developer/proposal_testing.rst +++ b/docs/developer/proposal_testing.rst @@ -401,7 +401,7 @@ system's temp directory (in our example, ``/tmp``) as given by the path argument yes-wallet folder in the default path ``./yes-wallet``. The command above will generate a wallet containing approximately 400 -keys. If you wish to restrict to a given percentage of the endorsing +keys. If you wish to restrict to a given percentage of the attesting power by retrieving the first bakers (with the biggest staking power), you can also use the ``--staking-share`` option to provide a limit. For instance, the first largest bakers with an accumulated @@ -413,14 +413,14 @@ stake of at least 75 percent can be kept with:: Prior to switching to the Tenderbake consensus algorithm it was sufficient to create a minimal yes-wallet with 8 Foundation keys. Starting from Protocol I this is no longer the case, because - a number of bakers holding at least 2/3rds of the total endorsing - power have to endorse a block for it to be considered valid. + a number of bakers holding at least 2/3rds of the total attesting + power have to attest a block for it to be considered valid. By restricting the accumulated stake to 75% as in the command above, the wallet is both "lighter" (it may contain around 30-40 keys and therefore some commands like ``octez-client bake for`` will execute faster) and its keys will represent more than the 2/3rds of the -endorsing power for any given level. +attesting power for any given level. Batch Steps 1--7 Above ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/developer/snoop_tutorial.rst b/docs/developer/snoop_tutorial.rst index 2f7b08ec8e8b..89da9cfce71d 100644 --- a/docs/developer/snoop_tutorial.rst +++ b/docs/developer/snoop_tutorial.rst @@ -321,7 +321,7 @@ Developing a new feature in the protocol ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When a feature is added in the protocol, it must account for the gas that bakers -and endorsers will spend by running the feature. Here is a typical workflow: +and attesters will spend by running the feature. Here is a typical workflow: - developers implement the feature; - they also implement the corresponding benchmarks (usually in diff --git a/docs/developer/testing.rst b/docs/developer/testing.rst index 6525523bb93f..03ded8851dec 100644 --- a/docs/developer/testing.rst +++ b/docs/developer/testing.rst @@ -86,7 +86,7 @@ in more detail. "-- -- Michelson interpreter",":ref:`AT `","","",":ref:`TZ `",":ref:`TZ `" "Client",":ref:`EXP `",":ref:`QC `","",":ref:`TZ `","",":ref:`LTF `" "Networked nodes","--","",":ref:`TZ `","", "" - "Endorser","","","","" + "Attester","","","","" "Baker","","","","" @@ -162,7 +162,7 @@ Typical use cases: Example tests: - Testing baking (in :src:`tezt/tests/basic.ml`) - - Testing double baking and double endorsement scenarios (in + - Testing double baking and double attestation scenarios (in :src:`tezt/tests/double_bake.ml`). - Testing absence of regressions in encodings (in :src:`tezt/tests/encoding.ml`) -- GitLab