From bdfabfbfb708b81d2a5f092d0324a10b967a9f1c Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Thu, 10 Jul 2025 15:06:20 +0200 Subject: [PATCH 1/4] doc: rename directory s023 to seoul --- docs/protocols/{023_s023.rst => 023_seoul.rst} | 0 docs/{s023 => seoul}/accounts.rst | 0 docs/{s023 => seoul}/adaptive-slashing.jpeg | Bin docs/{s023 => seoul}/adaptive_issuance.rst | 0 docs/{s023 => seoul}/adaptive_maximum.png | Bin docs/{s023 => seoul}/adaptive_slashing.rst | 0 docs/{s023 => seoul}/ai-min-max.jpeg | Bin docs/{s023 => seoul}/baking_power.rst | 0 docs/{s023 => seoul}/blocks_ops.rst | 0 docs/{s023 => seoul}/cli-commands.rst | 0 docs/{s023 => seoul}/consensus.rst | 0 docs/{s023 => seoul}/dal_support.rst | 0 docs/{s023 => seoul}/event.rst | 0 docs/{s023 => seoul}/global_constants.rst | 0 docs/{s023 => seoul}/glossary.rst | 0 docs/{s023 => seoul}/index.rst | 0 docs/{s023 => seoul}/liquidity_baking.rst | 0 docs/{s023 => seoul}/mempool.rst | 0 docs/{s023 => seoul}/michelson.rst | 0 docs/{s023 => seoul}/michelson_anti_patterns.rst | 0 docs/{s023 => seoul}/native-multisig-accounts.png | Bin docs/{s023 => seoul}/native_multisig.rst | 0 docs/{s023 => seoul}/plugins.rst | 0 docs/{s023 => seoul}/proof_of_stake.rst | 0 docs/{s023 => seoul}/protocol.rst | 0 docs/{s023 => seoul}/protocol_overview.rst | 0 docs/{s023 => seoul}/randomness_generation.rst | 0 docs/{s023 => seoul}/rpc.rst | 0 docs/{s023 => seoul}/sapling.rst | 0 docs/{s023 => seoul}/smart_rollups.rst | 0 docs/{s023 => seoul}/staked_funds_transitions.png | Bin docs/{s023 => seoul}/staking.rst | 0 docs/{s023 => seoul}/tickets.rst | 0 docs/{s023 => seoul}/timelock.rst | 0 docs/{s023 => seoul}/token_management.rst | 0 docs/{s023 => seoul}/validation.rst | 0 docs/{s023 => seoul}/views.rst | 0 docs/{s023 => seoul}/voting.rst | 0 38 files changed, 0 insertions(+), 0 deletions(-) rename docs/protocols/{023_s023.rst => 023_seoul.rst} (100%) rename docs/{s023 => seoul}/accounts.rst (100%) rename docs/{s023 => seoul}/adaptive-slashing.jpeg (100%) rename docs/{s023 => seoul}/adaptive_issuance.rst (100%) rename docs/{s023 => seoul}/adaptive_maximum.png (100%) rename docs/{s023 => seoul}/adaptive_slashing.rst (100%) rename docs/{s023 => seoul}/ai-min-max.jpeg (100%) rename docs/{s023 => seoul}/baking_power.rst (100%) rename docs/{s023 => seoul}/blocks_ops.rst (100%) rename docs/{s023 => seoul}/cli-commands.rst (100%) rename docs/{s023 => seoul}/consensus.rst (100%) rename docs/{s023 => seoul}/dal_support.rst (100%) rename docs/{s023 => seoul}/event.rst (100%) rename docs/{s023 => seoul}/global_constants.rst (100%) rename docs/{s023 => seoul}/glossary.rst (100%) rename docs/{s023 => seoul}/index.rst (100%) rename docs/{s023 => seoul}/liquidity_baking.rst (100%) rename docs/{s023 => seoul}/mempool.rst (100%) rename docs/{s023 => seoul}/michelson.rst (100%) rename docs/{s023 => seoul}/michelson_anti_patterns.rst (100%) rename docs/{s023 => seoul}/native-multisig-accounts.png (100%) rename docs/{s023 => seoul}/native_multisig.rst (100%) rename docs/{s023 => seoul}/plugins.rst (100%) rename docs/{s023 => seoul}/proof_of_stake.rst (100%) rename docs/{s023 => seoul}/protocol.rst (100%) rename docs/{s023 => seoul}/protocol_overview.rst (100%) rename docs/{s023 => seoul}/randomness_generation.rst (100%) rename docs/{s023 => seoul}/rpc.rst (100%) rename docs/{s023 => seoul}/sapling.rst (100%) rename docs/{s023 => seoul}/smart_rollups.rst (100%) rename docs/{s023 => seoul}/staked_funds_transitions.png (100%) rename docs/{s023 => seoul}/staking.rst (100%) rename docs/{s023 => seoul}/tickets.rst (100%) rename docs/{s023 => seoul}/timelock.rst (100%) rename docs/{s023 => seoul}/token_management.rst (100%) rename docs/{s023 => seoul}/validation.rst (100%) rename docs/{s023 => seoul}/views.rst (100%) rename docs/{s023 => seoul}/voting.rst (100%) diff --git a/docs/protocols/023_s023.rst b/docs/protocols/023_seoul.rst similarity index 100% rename from docs/protocols/023_s023.rst rename to docs/protocols/023_seoul.rst diff --git a/docs/s023/accounts.rst b/docs/seoul/accounts.rst similarity index 100% rename from docs/s023/accounts.rst rename to docs/seoul/accounts.rst diff --git a/docs/s023/adaptive-slashing.jpeg b/docs/seoul/adaptive-slashing.jpeg similarity index 100% rename from docs/s023/adaptive-slashing.jpeg rename to docs/seoul/adaptive-slashing.jpeg diff --git a/docs/s023/adaptive_issuance.rst b/docs/seoul/adaptive_issuance.rst similarity index 100% rename from docs/s023/adaptive_issuance.rst rename to docs/seoul/adaptive_issuance.rst diff --git a/docs/s023/adaptive_maximum.png b/docs/seoul/adaptive_maximum.png similarity index 100% rename from docs/s023/adaptive_maximum.png rename to docs/seoul/adaptive_maximum.png diff --git a/docs/s023/adaptive_slashing.rst b/docs/seoul/adaptive_slashing.rst similarity index 100% rename from docs/s023/adaptive_slashing.rst rename to docs/seoul/adaptive_slashing.rst diff --git a/docs/s023/ai-min-max.jpeg b/docs/seoul/ai-min-max.jpeg similarity index 100% rename from docs/s023/ai-min-max.jpeg rename to docs/seoul/ai-min-max.jpeg diff --git a/docs/s023/baking_power.rst b/docs/seoul/baking_power.rst similarity index 100% rename from docs/s023/baking_power.rst rename to docs/seoul/baking_power.rst diff --git a/docs/s023/blocks_ops.rst b/docs/seoul/blocks_ops.rst similarity index 100% rename from docs/s023/blocks_ops.rst rename to docs/seoul/blocks_ops.rst diff --git a/docs/s023/cli-commands.rst b/docs/seoul/cli-commands.rst similarity index 100% rename from docs/s023/cli-commands.rst rename to docs/seoul/cli-commands.rst diff --git a/docs/s023/consensus.rst b/docs/seoul/consensus.rst similarity index 100% rename from docs/s023/consensus.rst rename to docs/seoul/consensus.rst diff --git a/docs/s023/dal_support.rst b/docs/seoul/dal_support.rst similarity index 100% rename from docs/s023/dal_support.rst rename to docs/seoul/dal_support.rst diff --git a/docs/s023/event.rst b/docs/seoul/event.rst similarity index 100% rename from docs/s023/event.rst rename to docs/seoul/event.rst diff --git a/docs/s023/global_constants.rst b/docs/seoul/global_constants.rst similarity index 100% rename from docs/s023/global_constants.rst rename to docs/seoul/global_constants.rst diff --git a/docs/s023/glossary.rst b/docs/seoul/glossary.rst similarity index 100% rename from docs/s023/glossary.rst rename to docs/seoul/glossary.rst diff --git a/docs/s023/index.rst b/docs/seoul/index.rst similarity index 100% rename from docs/s023/index.rst rename to docs/seoul/index.rst diff --git a/docs/s023/liquidity_baking.rst b/docs/seoul/liquidity_baking.rst similarity index 100% rename from docs/s023/liquidity_baking.rst rename to docs/seoul/liquidity_baking.rst diff --git a/docs/s023/mempool.rst b/docs/seoul/mempool.rst similarity index 100% rename from docs/s023/mempool.rst rename to docs/seoul/mempool.rst diff --git a/docs/s023/michelson.rst b/docs/seoul/michelson.rst similarity index 100% rename from docs/s023/michelson.rst rename to docs/seoul/michelson.rst diff --git a/docs/s023/michelson_anti_patterns.rst b/docs/seoul/michelson_anti_patterns.rst similarity index 100% rename from docs/s023/michelson_anti_patterns.rst rename to docs/seoul/michelson_anti_patterns.rst diff --git a/docs/s023/native-multisig-accounts.png b/docs/seoul/native-multisig-accounts.png similarity index 100% rename from docs/s023/native-multisig-accounts.png rename to docs/seoul/native-multisig-accounts.png diff --git a/docs/s023/native_multisig.rst b/docs/seoul/native_multisig.rst similarity index 100% rename from docs/s023/native_multisig.rst rename to docs/seoul/native_multisig.rst diff --git a/docs/s023/plugins.rst b/docs/seoul/plugins.rst similarity index 100% rename from docs/s023/plugins.rst rename to docs/seoul/plugins.rst diff --git a/docs/s023/proof_of_stake.rst b/docs/seoul/proof_of_stake.rst similarity index 100% rename from docs/s023/proof_of_stake.rst rename to docs/seoul/proof_of_stake.rst diff --git a/docs/s023/protocol.rst b/docs/seoul/protocol.rst similarity index 100% rename from docs/s023/protocol.rst rename to docs/seoul/protocol.rst diff --git a/docs/s023/protocol_overview.rst b/docs/seoul/protocol_overview.rst similarity index 100% rename from docs/s023/protocol_overview.rst rename to docs/seoul/protocol_overview.rst diff --git a/docs/s023/randomness_generation.rst b/docs/seoul/randomness_generation.rst similarity index 100% rename from docs/s023/randomness_generation.rst rename to docs/seoul/randomness_generation.rst diff --git a/docs/s023/rpc.rst b/docs/seoul/rpc.rst similarity index 100% rename from docs/s023/rpc.rst rename to docs/seoul/rpc.rst diff --git a/docs/s023/sapling.rst b/docs/seoul/sapling.rst similarity index 100% rename from docs/s023/sapling.rst rename to docs/seoul/sapling.rst diff --git a/docs/s023/smart_rollups.rst b/docs/seoul/smart_rollups.rst similarity index 100% rename from docs/s023/smart_rollups.rst rename to docs/seoul/smart_rollups.rst diff --git a/docs/s023/staked_funds_transitions.png b/docs/seoul/staked_funds_transitions.png similarity index 100% rename from docs/s023/staked_funds_transitions.png rename to docs/seoul/staked_funds_transitions.png diff --git a/docs/s023/staking.rst b/docs/seoul/staking.rst similarity index 100% rename from docs/s023/staking.rst rename to docs/seoul/staking.rst diff --git a/docs/s023/tickets.rst b/docs/seoul/tickets.rst similarity index 100% rename from docs/s023/tickets.rst rename to docs/seoul/tickets.rst diff --git a/docs/s023/timelock.rst b/docs/seoul/timelock.rst similarity index 100% rename from docs/s023/timelock.rst rename to docs/seoul/timelock.rst diff --git a/docs/s023/token_management.rst b/docs/seoul/token_management.rst similarity index 100% rename from docs/s023/token_management.rst rename to docs/seoul/token_management.rst diff --git a/docs/s023/validation.rst b/docs/seoul/validation.rst similarity index 100% rename from docs/s023/validation.rst rename to docs/seoul/validation.rst diff --git a/docs/s023/views.rst b/docs/seoul/views.rst similarity index 100% rename from docs/s023/views.rst rename to docs/seoul/views.rst diff --git a/docs/s023/voting.rst b/docs/seoul/voting.rst similarity index 100% rename from docs/s023/voting.rst rename to docs/seoul/voting.rst -- GitLab From 975eca0c12460db04487c403937685d8006f70cb Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Thu, 10 Jul 2025 15:07:28 +0200 Subject: [PATCH 2/4] doc: rename all labels _s023 to _seoul --- docs/Makefile | 10 ++-- docs/index.rst | 4 +- docs/protocols/023_seoul.rst | 14 ++--- docs/rio/accounts.rst | 3 ++ docs/seoul/accounts.rst | 14 ++--- docs/seoul/adaptive_issuance.rst | 42 +++++++-------- docs/seoul/adaptive_slashing.rst | 22 ++++---- docs/seoul/baking_power.rst | 56 +++++++++---------- docs/seoul/blocks_ops.rst | 80 ++++++++++++++-------------- docs/seoul/cli-commands.rst | 6 +-- docs/seoul/consensus.rst | 48 ++++++++--------- docs/seoul/dal_support.rst | 24 ++++----- docs/seoul/glossary.rst | 46 ++++++++-------- docs/seoul/liquidity_baking.rst | 4 +- docs/seoul/mempool.rst | 8 +-- docs/seoul/michelson.rst | 64 +++++++++++----------- docs/seoul/native_multisig.rst | 8 +-- docs/seoul/plugins.rst | 18 +++---- docs/seoul/proof_of_stake.rst | 38 ++++++------- docs/seoul/protocol_overview.rst | 34 ++++++------ docs/seoul/randomness_generation.rst | 10 ++-- docs/seoul/smart_rollups.rst | 14 ++--- docs/seoul/staking.rst | 22 ++++---- docs/seoul/validation.rst | 40 +++++++------- docs/seoul/voting.rst | 10 ++-- 25 files changed, 321 insertions(+), 318 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 6519364b7fa5..90f490f86748 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -16,17 +16,17 @@ P2PDOCEXE = $(TOPBUILDDIR)/default/docs/$(DOCGENDIR)/p2p_doc.exe RPCDOCEXE = $(TOPBUILDDIR)/default/docs/$(DOCGENDIR)/rpc_doc.exe ERRDOCEXE = $(TOPBUILDDIR)/default/docs/$(DOCERRORDIR)/error_doc.exe -NAMED_PROTOS = rio s023 +NAMED_PROTOS = rio seoul PROTOCOLS = $(NAMED_PROTOS) alpha # The following variables names are lowercase, so their names can be computed # from the names of the corresponding protocol directories rio_long = PsRiotumaAMotcRoDWW1bysEhQy2n1M5fy8JgRp8jjRfHGmfeA7 -s023_long = PtSeouLouXkxhg39oWzjxDWaCydNfR3RxCUrNe4Q9Ro8BTehcbh +seoul_long = PtSeouLouXkxhg39oWzjxDWaCydNfR3RxCUrNe4Q9Ro8BTehcbh alpha_long = ProtoALphaALphaALphaALphaALphaALphaALphaALphaDdp3zK rio_short = PsRiotum -s023_short = PtSeouLo +seoul_short = PtSeouLo alpha_short = alpha SCRIPTSDIR = scripts @@ -141,7 +141,7 @@ redirectcheck: # - on each other protocol including alpha, also checking label defs (option -l) .PHONY: xrefscheck xrefscheck: - $(CHECKXREFS) s023 + $(CHECKXREFS) seoul $(CHECKXREFS) rio $(CHECKXREFS) -l alpha @@ -315,5 +315,5 @@ clean: @-rm -Rf "$(BUILDDIR)" "$(BUILDDIRTXT)" linkcheck odoc.log @-rm -f $(ERRDOCEXE) $(RPCDOCEXE) $(P2PDOCEXE) @-rm -Rf api/errors.rst developer/metrics.csv user/node-config.json alpha/rpc.rst shell/rpc.rst shell/p2p_api.rst user/default-acl.json CHANGES-dev.rst developer/rollup_metrics.csv octezdoc.txt - @-rm -Rf api/octez-*.html api/octez-*.txt alpha/octez-*.html s023/octez-*.html rio/octez-*.html + @-rm -Rf api/octez-*.html api/octez-*.txt alpha/octez-*.html seoul/octez-*.html rio/octez-*.html @-rm -Rf ../openapi-tmp diff --git a/docs/index.rst b/docs/index.rst index 3b86ee005cd7..b6079ae10e8d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -195,7 +195,7 @@ You may also access this whole documentation as a single `text file - S023 Protocol Reference + Seoul Protocol Reference Alpha Dev Protocol Reference .. toctree:: @@ -223,7 +223,7 @@ You may also access this whole documentation as a single `text file `__. The code can be found in directory :src:`src/proto_023_PtSeouLo` of the ``master`` -branch of Octez and the full documentation in :doc:`this page <../s023/index>`. +branch of Octez and the full documentation in :doc:`this page <../seoul/index>`. Environment Version ------------------- @@ -70,17 +70,17 @@ Operations ---------- - Added new operation kinds :ref:`Preattestations_aggregate and - Attestations_aggregate`. (MRs + Attestations_aggregate`. (MRs :gl:`!15244`, :gl:`!17485`) - The ``Reveal`` operation has a new optional ``proof`` field, which is required if (and only if) the manager key is a :ref:`tz4 (BLS - key)`. This results in an increase of gas cost + key)`. This results in an increase of gas cost per reveal of a tz4 public key. (MR :gl:`!18095`) - The optional ``proof`` field of the ``Update_consensus_key`` operation is now required if (and only if) the new consensus key is - a :ref:`tz4 (BLS key)`. Its encoding now + a :ref:`tz4 (BLS key)`. Its encoding now exclusively accepts BLS signatures. (MR :gl:`!17360`) - Added a new manager operation kind ``Update_companion_key``, @@ -183,7 +183,7 @@ Minor Changes ------------- - The :ref:`finalize_unstake - pseudo-operation` can now be performed + pseudo-operation` can now be performed by any account, not just the owner of the unstaked funds. This allows finalization of unstake requests to be done automatically by a third party - for example a finalization bot. (MR :gl:`!17950`) diff --git a/docs/rio/accounts.rst b/docs/rio/accounts.rst index 9abcfe32f321..bdbb3fecf90c 100644 --- a/docs/rio/accounts.rst +++ b/docs/rio/accounts.rst @@ -71,6 +71,9 @@ Secp256r1. This is one of the curves for EcDSA recommended by NIST. It is also often the only cryptographic scheme supported by HSMs (Hardware Security Modules) of cloud providers. +.. _tz4_accounts: +.. _tz4_accounts_rio: + ``tz4``: BLS '''''''''''' diff --git a/docs/seoul/accounts.rst b/docs/seoul/accounts.rst index 5ae2e7c0e50f..114559bd9ed5 100644 --- a/docs/seoul/accounts.rst +++ b/docs/seoul/accounts.rst @@ -17,7 +17,7 @@ addresses: Finally, addresses prefixed with ``sr1`` identify :doc:`Smart Rollups <./smart_rollups>`. -.. _user_accounts_s023: +.. _user_accounts_seoul: User accounts ~~~~~~~~~~~~~ @@ -36,7 +36,7 @@ briefly described below from a user point of view. The sizes of public keys, secret keys and signatures may differ between the different schemes but addresses are always 20 bytes long. -.. _tz1_accounts_s023: +.. _tz1_accounts_seoul: ``tz1``: Ed25519 '''''''''''''''' @@ -50,7 +50,7 @@ because it offers better security guarantees than EcDSA and has good performance on most hardware. It may not be available in all wallets or on all dedicated chips which is why Tezos supports multiple schemes. -.. _tz2_accounts_s023: +.. _tz2_accounts_seoul: ``tz2``: Secp256k1 '''''''''''''''''' @@ -62,7 +62,7 @@ with the `Secp256k1 curve `_. Secp256k1 is notably the cryptographic scheme used by Bitcoin and Ethereum. This means that private keys and addresses used on Bitcoin can also be used on Tezos. -.. _tz3_accounts_s023: +.. _tz3_accounts_seoul: ``tz3``: P-256 '''''''''''''' @@ -76,7 +76,7 @@ Secp256r1. This is one of the curves for EcDSA recommended by NIST. It is also often the only cryptographic scheme supported by HSMs (Hardware Security Modules) of cloud providers. -.. _tz4_accounts_s023: +.. _tz4_accounts_seoul: ``tz4``: BLS '''''''''''' @@ -92,7 +92,7 @@ applications like multi-signatures schemes, multi-party key exchanges, signatures compaction, etc. BLS is notably used by Zcash and Ethereum 2.0. Starting in protocol S, ``tz4`` addresses can be used by bakers, to forge blocks -and :ref:`consensus operations `. The aggregatable property of BLS signatures is used with +and :ref:`consensus operations `. The aggregatable property of BLS signatures is used with consensus operations to reduce the size signatures take in each block. Such bakers that also wish to participate in the DAL are required to register a :ref:`companion key `, that is used to sign the DAL specific attestation and aggregate it with the regular attestation. @@ -101,4 +101,4 @@ Smart contracts ~~~~~~~~~~~~~~~ A transaction to a smart contract -address can provide data and optionally some tokens, and triggers the execution of the code, which may read and update the storage. The transaction can succeed or fail, according to the :ref:`transaction semantics `. +address can provide data and optionally some tokens, and triggers the execution of the code, which may read and update the storage. The transaction can succeed or fail, according to the :ref:`transaction semantics `. diff --git a/docs/seoul/adaptive_issuance.rst b/docs/seoul/adaptive_issuance.rst index b2225d5208fa..651431735f67 100644 --- a/docs/seoul/adaptive_issuance.rst +++ b/docs/seoul/adaptive_issuance.rst @@ -3,7 +3,7 @@ :math:`\newcommand\exp[1]{\F{exp}{#1}}` -.. _adaptive_issuance_s023: +.. _adaptive_issuance_seoul: ================= Adaptive Issuance @@ -34,7 +34,7 @@ ratio of staked tez to the total supply. This lets issuance roughly match the *actual* security budget the chain requires, the amount needed to encourage participants to stake and produce blocks, but *no more*. -At the end of each blockchain :ref:`cycle `, the +At the end of each blockchain :ref:`cycle `, the regular issuance is adjusted, to nudge the staked ratio towards a protocol-defined target (set at 50% starting in the Paris protocol). Participation rewards are recomputed to match that @@ -43,19 +43,19 @@ emission rates increase, incentivizing participants to stake funds to re-approach the target. Conversely, incentives decrease as the ratio increases beyond the target. -.. _adaptive_issuance_rate_s023: +.. _adaptive_issuance_rate_seoul: Adaptive issuance rate ---------------------- The adaptive issuance rate determines, at the end of cycle :math:`\IL{c}`, the issuance for cycle :math:`\IL{c + 3}`. The -adaptive issuance rate is the sum of a :ref:`static rate ` -and a :ref:`dynamic rate `. This value is kept within +adaptive issuance rate is the sum of a :ref:`static rate ` +and a :ref:`dynamic rate `. This value is kept within a minimal and a maximal value, to ensure nominal emissions remain within reasonable bounds. -.. _staked_ratio_s023: +.. _staked_ratio_seoul: Staked ratio ............ @@ -70,14 +70,14 @@ The **staked ratio** is the ratio of staked tez to the total supply. It is compu Where: - ``issuance_modification_delay`` is a :ref:`derived protocol - constant` which is set to the same value - as ``CONSENSUS_RIGHTS_DELAY`` (see :ref:`active_stake_s023`), that + constant` which is set to the same value + as ``CONSENSUS_RIGHTS_DELAY`` (see :ref:`active_stake_seoul`), that is, 2 cycles. - ``total_supply(cycle)`` returns the total supply of tez at the end of the given ``cycle``. - ``total_frozen_stake(cycle)`` returns the total frozen stake at the given ``cycle``. -.. _static_rate_s023: +.. _static_rate_seoul: Static rate ........... @@ -95,7 +95,7 @@ The static rate is defined as follows: The choice of a scaling factor ensures that the curve takes reasonable values for plausible staked ratios. Moreover, since Adaptive Issuance is activated with a dynamic rate of 0, and at current staked ratio (that is, ~7.5% of the total supply), this factor allows for a smooth transition from the issuance rate (~4.6%) from the Oxford protocol (before the activation of Adaptive Issuance). -.. _dynamic_rate_s023: +.. _dynamic_rate_seoul: Dynamic rate ............ @@ -124,9 +124,9 @@ Where: - ``days_per_cycle`` denotes the minimal duration in days of a Tezos cycle, assuming all blocks in the cycle are produced at the minimal allowed time – that is, every 8 seconds in Quebec. - ``growth_rate`` controls the speed at which the dynamic rate adjusts. The value is set so that a one percentage point deviation of the staked ratio changes the dynamic rate by 0.01 percentage points per day. -In a nutshell, ``dynamic_rate(c)`` increases and decreases by an amount proportional to the distance between the target rate and the interval ``[48%; 52%]``. Note that to ensure that the issuance rate is kept within :ref:`the minimum and maximum bounds `, the dynamic rate might be adjusted accordingly. More precisely, if :ref:`the issuance rate ` would surpass the maximum issuance allowed for a given cycle, then ``dynamic_rate(c)`` would be reduced to keep the issuance rate within the bounds (this part of the formula has been omitted from the above pseudocode for brevity). +In a nutshell, ``dynamic_rate(c)`` increases and decreases by an amount proportional to the distance between the target rate and the interval ``[48%; 52%]``. Note that to ensure that the issuance rate is kept within :ref:`the minimum and maximum bounds `, the dynamic rate might be adjusted accordingly. More precisely, if :ref:`the issuance rate ` would surpass the maximum issuance allowed for a given cycle, then ``dynamic_rate(c)`` would be reduced to keep the issuance rate within the bounds (this part of the formula has been omitted from the above pseudocode for brevity). -.. _minimum_and_maximum_rates_s023: +.. _minimum_and_maximum_rates_seoul: Minimum and maximum rates .......................... @@ -209,7 +209,7 @@ Where: below this bound for the initial period. - ``issuance_global_max`` (10%) is the final value for the upper bound, reached at the end of the transition period. -.. _adaptive_maximum_s023: +.. _adaptive_maximum_seoul: Adaptive Maximum ................ @@ -276,7 +276,7 @@ The function that defines the adaptive maximum is: .. note:: Until the final value of the :ref:`minimum - rate` is reached, it is possible, + rate` is reached, it is possible, with a high enough staked ratio, for the corresponding adaptive maximum to be smaller than the minimum rate. If this happens, then the minimum rate takes priority, that is, the total issuance rate @@ -285,7 +285,7 @@ The function that defines the adaptive maximum is: while fully satisfying the minimum rate. -.. _issuance_rate_s023: +.. _issuance_rate_seoul: Issuance rate ...................... @@ -294,8 +294,8 @@ Finally, as mentioned before, the nominal adaptive issuance rate [1]_ for a cycle ``c + issuance_modification_delay + 1`` is defined as the sum of the static rate and the dynamic rate computed for the cycle ``c``, bounded within the :ref:`minimum and maximum rates -`, along with the :ref:`adaptive -maximum `, computed for the cycle ``c + 1``. +`, along with the :ref:`adaptive +maximum `, computed for the cycle ``c + 1``. .. code-block:: python @@ -309,7 +309,7 @@ maximum `, computed for the cycle ``c + 1``. return max( min(total_rate, maximum_rate), minimum_rate ) -.. _adaptive_rewards_s023: +.. _adaptive_rewards_seoul: Adaptive rewards ---------------- @@ -320,9 +320,9 @@ constants. With the new mechanism, the adaptive issuance rate provides instead a budget for the whole cycle, which gets allocated equally to each block of the cycle and distributed between the various rewards, in proportion to their relative :ref:`weights -`. +`. -.. _rewards_weights_s023: +.. _rewards_weights_seoul: Reward weights .............. @@ -415,7 +415,7 @@ Where: **Nonce and VDF revelation tips.** The rewards allocated to delegates -for contributing to :ref:`random seed generation ` +for contributing to :ref:`random seed generation ` (that is, for revealing nonce seeds and posting VDF proofs) are not paid each block, but rather every 192 blocks. diff --git a/docs/seoul/adaptive_slashing.rst b/docs/seoul/adaptive_slashing.rst index d321a7c9b884..c97910afe2f6 100644 --- a/docs/seoul/adaptive_slashing.rst +++ b/docs/seoul/adaptive_slashing.rst @@ -23,15 +23,15 @@ incurs moderate penalties, while a high fraction of misconduct is deemed to be critical and faces more serious repercussions. This document presents the definition of the :ref:`adaptive slashing -function` implementing this idea, as well as the -:ref:`new forbidden period`. +function` implementing this idea, as well as the +:ref:`new forbidden period`. -.. _adaptive_slashing_fn_s023: +.. _adaptive_slashing_fn_seoul: Adaptive Slashing Function ========================== -.. _adaptive_slashing_informal_s023: +.. _adaptive_slashing_informal_seoul: Informal presentation --------------------- @@ -85,15 +85,15 @@ takes more than 2 cycles to complete the unstaking process. This ensures that the baker can't decrease their at-stake funds after being denunciated and before facing penalties. -.. _formal_adaptive_slashing_s023: +.. _formal_adaptive_slashing_seoul: A formal definition of slashing function for double-attestations ---------------------------------------------------------------- * :math:`\mathcal{W}` denotes the maximal possible *weight* of attestations in a block, that is, the fixed number of available - :ref:`slots` in any block. It is also known as - :ref:`CONSENSUS_COMMITTEE_SIZE`. + :ref:`slots` in any block. It is also known as + :ref:`CONSENSUS_COMMITTEE_SIZE`. * :math:`f(B)` is the *fraction of double attestations* for block :math:`B`, that is, the ratio of the total weight of double @@ -103,7 +103,7 @@ A formal definition of slashing function for double-attestations to be considered critical. A typical value for :math:`T` is :math:`{1 \over 3} \mathcal{W}`, which is the difference between :math:`\mathcal{W}` and the - :ref:`CONSENSUS_THRESHOLD` which is set to + :ref:`CONSENSUS_THRESHOLD` which is set to :math:`{2 \over 3} \mathcal{W}`. We define :math:`S(B)` the percentage of slashed funds for all @@ -124,7 +124,7 @@ where :math:`(b, B) \in C` means that: * :math:`C` is the last cycle of the denunciation period for :math:`B`. -.. _new_forbidden_period_s023: +.. _new_forbidden_period_seoul: New definition for the forbidden period ======================================= @@ -147,9 +147,9 @@ met: * all pending slashings for the delegate have occurred, and * the current total frozen stake for the delegate (sum of the - :ref:`staking balances` of the delegate itself + :ref:`staking balances` of the delegate itself and its stakers) is at least as high as the :ref:`active - stake` that was used ``CONSENSUS_RIGHTS_DELAY`` + stake` that was used ``CONSENSUS_RIGHTS_DELAY`` cycles ago to compute the consensus rights for the next cycle. The second condition may be fulfilled when the delegate and/or stakers diff --git a/docs/seoul/baking_power.rst b/docs/seoul/baking_power.rst index d8f0d61efbcd..4f8e9ca954fd 100644 --- a/docs/seoul/baking_power.rst +++ b/docs/seoul/baking_power.rst @@ -3,23 +3,23 @@ Baking Power The :doc:`proof-of-stake` mechanism used for the :doc:`consensus algorithm` assigns baking and attesting -:ref:`slots`, called **baking rights**, to each -:ref:`delegate a.k.a. baker`. For this selection +:ref:`slots`, called **baking rights**, to each +:ref:`delegate a.k.a. baker`. For this selection process, each baker is weighted according to its **baking power** -- -provided that it is :ref:`active` and meets the +provided that it is :ref:`active` and meets the :ref:`minimal power and own staked -requirements`. +requirements`. This page details how this baking power is determined from the :doc:`staked` and non-staked funds owned by the baker itself and all its delegators. Note that the :doc:`amendment and voting process` is based on -each delegate's :ref:`voting power` instead, which +each delegate's :ref:`voting power` instead, which is computed in a similar but simpler way. -.. _RPC_path_shortcut_s023: +.. _RPC_path_shortcut_seoul: .. note:: @@ -33,18 +33,18 @@ is computed in a similar but simpler way. :ref:`changelog` for more information. -.. _baking_power_overview_s023: +.. _baking_power_overview_seoul: Overview -------- -At the end of :ref:`cycle` ``n`` (that is, the +At the end of :ref:`cycle` ``n`` (that is, the beginning of cycle ``n + 1``), the protocol :doc:`randomly generates` the baking rights for cycle ``n + 1 + CONSENSUS_RIGHTS_DELAY = n + 3``, using the **current baking power** as the weight for each delegate that meets the -:ref:`requirements`. (``CONSENSUS_RIGHTS_DELAY -= 2`` is a :ref:`protocol constant`.) +:ref:`requirements`. (``CONSENSUS_RIGHTS_DELAY += 2`` is a :ref:`protocol constant`.) The ``.../delegates//baking_power`` RPC can be used to retrieve the current baking power of a delegate, that is, its baking @@ -68,9 +68,9 @@ Delegate, delegators, stakers ----------------------------- A **delegate**, a.k.a. **baker**, is a :ref:`user -account` that has registered as a delegate by +account` that has registered as a delegate by emitting a self-``delegation`` :ref:`manager -operation`. The list of all registered +operation`. The list of all registered delegates is queried with the ``.../delegates`` RPC. A **delegator** for a given baker is an :doc:`account` that @@ -81,7 +81,7 @@ delegate is queried with the ``.../delegates//delegators`` RPC. A **staker** is a delegator that has :doc:`staked` tez by -emitting a :ref:`stake operation`. This +emitting a :ref:`stake operation`. This includes the delegate itself if it has staked funds. Note that stakers are always user accounts, because smart contracts cannot emit ``stake`` operations. The list of a delegate's stakers and their @@ -92,7 +92,7 @@ An **external delegator** (resp. **external staker**) is a delegator (resp. staker) that is not the delegate itself. -.. _total_staked_s023: +.. _total_staked_seoul: Staked tez ---------- @@ -100,7 +100,7 @@ Staked tez Delegates and delegators have the option to :doc:`stake` their tez. **Staked tez** contribute to the baking power, but they also function as a security deposit for baking, meaning that they may -be :ref:`slashed` if the delegate misbehaves. That's +be :ref:`slashed` if the delegate misbehaves. That's why they are also known as **frozen deposits**. The **staked balance** of an account is its amount of staked tez. It @@ -154,13 +154,13 @@ tez. It is the sum of the following balances: finalizable unstake requests). These tez have been removed from the staked balance via an ``unstake`` operation, but have not been added back to the spendable balance yet; see - :ref:`staked_funds_management_s023`. Unstake requests can be + :ref:`staked_funds_management_seoul`. Unstake requests can be queried with RPC ``.../contracts//unstake_requests`` (returns a detailed view with unfinalizable/finalizable status, delegate-at-creation-time, cycle, and amount in mutez). - The **frozen bonds** are a deposit for :ref:`rollup - commitments`. They can be queried with RPC + commitments`. They can be queried with RPC ``.../contracts//frozen_bonds`` (in mutez). Together, the staked and delegated tez represent all the tez owned by @@ -173,7 +173,7 @@ an account, called the **full balance**. full_balance = staked + delegated -.. _total_delegated_s023: +.. _total_delegated_seoul: Delegated tez to a baker ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -225,7 +225,7 @@ For a given delegate, we define the following: total_delegated = own_delegated + external_delegated -.. _min_delegated_s023: +.. _min_delegated_seoul: Min-delegated-in-current-cycle ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -237,7 +237,7 @@ cycle** ``n``, called ``min_delegated_in_current_cycle``. The purpose of this mechanism is to prevent any manipulation of baking rights through short-duration transfers. (Note that such a mechanism is not needed for staked tez because they are inherently :ref:`frozen for at -least four cycles`, so short-duration +least four cycles`, so short-duration staking is already not possible.) Since the Paris protocol, the considered minimum is the minimum at any @@ -391,13 +391,13 @@ here we use tez for simplicity. (min: ``900``, level: ``200``). -.. _overstaking_s023: +.. _overstaking_seoul: Overstaking ----------- The **limit_of_staking_over_baking** is a :ref:`configurable delegate -parameter` that limits how much +parameter` that limits how much staked tez the external stakers can contribute to the baking power, relative to the baker's own staked tez. It defaults to ``0``, meaning no staked contribution from external stakers at all. It can be set to @@ -459,8 +459,8 @@ contributes to ensuring that all baking rights are covered by appropriate security deposits. Recall that the delegated amount used for baking rights is -:ref:`min_delegated_in_current_cycle`, and any -:ref:`overstaked` tez count as delegated +:ref:`min_delegated_in_current_cycle`, and any +:ref:`overstaked` tez count as delegated too. Therefore: .. code-block:: python @@ -468,14 +468,14 @@ too. Therefore: total_delegated_after_limits = min(min_delegated_in_current_cycle + overstaked, own_staked * 9) We finally have everything we need to compute the baking power -:ref:`as defined above`: +:ref:`as defined above`: .. code-block:: python baking_power = total_staked_after_limits + (total_delegated_after_limits / 3) -.. _minimal_baking_power_s023: +.. _minimal_baking_power_seoul: Minimal power and own staked requirements ----------------------------------------- @@ -485,10 +485,10 @@ requirements: - ``baking_power >= MINIMAL_STAKE`` - ``own_staked >= MINIMAL_FROZEN_STAKE`` -- The delegate must be :ref:`active` +- The delegate must be :ref:`active` where ``MINIMAL_STAKE = 6,000ꜩ`` and ``MINIMAL_FROZEN_STAKE = 600ꜩ`` -are :ref:`protocol constants`. +are :ref:`protocol constants`. If any of these conditions is not met at the end of cycle ``n``, the delegate still has a *baking power* as computed above, but receives no *baking diff --git a/docs/seoul/blocks_ops.rst b/docs/seoul/blocks_ops.rst index 7f3a899dc8ad..9a432fd7aff9 100644 --- a/docs/seoul/blocks_ops.rst +++ b/docs/seoul/blocks_ops.rst @@ -7,22 +7,22 @@ The content of a Tezos block is made up of a block header and a payload consisti 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_s023: +.. _proto_block_header_seoul: 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 `. +: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 +- ``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. +- ``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`. +There are two additional fields: ``payload_hash`` and ``payload_round`` which are needed for establishing if a block is :ref:`final`. Operations ~~~~~~~~~~ @@ -41,7 +41,7 @@ or available only on test networks, is given in the :package-api:`OCaml Documentation `. -.. _validation_passes_s023: +.. _validation_passes_seoul: Validation Passes ~~~~~~~~~~~~~~~~~ @@ -49,20 +49,20 @@ Validation Passes The different kinds of operations are grouped into classes. Each class has an associated index, a natural number, also known as a :ref:`validation pass`. There are currently four classes -of operations: :ref:`consensus `, -:ref:`voting `, -:ref:`anonymous`, and :ref:`manager -operations`. This order also specifies the -:ref:`validation and application` priority +of operations: :ref:`consensus `, +:ref:`voting `, +:ref:`anonymous`, and :ref:`manager +operations`. This order also specifies the +:ref:`validation and application` priority of each of these classes. Consensus operations are considered the highest priority ones, and manager operations the lowest. -Each kind of operation belongs to exactly one validation pass, except for the :ref:`failing_noop_s023` which belongs to no validation pass and therefore cannot be :ref:`applied`. +Each kind of operation belongs to exactly one validation pass, except for the :ref:`failing_noop_seoul` which belongs to no validation pass and therefore cannot be :ref:`applied`. In the sequel, we describe the different classes of operations, and the different kinds of operations belonging to each class. -.. _consensus_operations_s023: +.. _consensus_operations_seoul: Consensus Operations ~~~~~~~~~~~~~~~~~~~~ @@ -75,15 +75,15 @@ kinds of consensus operations, each belonging to the different voting phases required to agree on the next block. - A ``Preattestation`` operation implements a first vote for a - :ref:`candidate block ` with the aim of - building a :ref:`preattestation quorum `. + :ref:`candidate block ` with the aim of + building a :ref:`preattestation quorum `. - An ``Attestation`` operation implements a vote for a candidate block for which a preattestation quorum certificate (PQC) has been observed. These operations also hold information on :doc:`DAL attestations <../shell/dal_bakers>` when the attesting baker participates in the DAL. -.. _consensus_operations_aggregate_s023: +.. _consensus_operations_aggregate_seoul: Starting in protocol S, blocks are also able to include these operations in an aggregated form, using operations ``Attestations_aggregate`` and ``Preattestations_aggregate``. If the attesting baker uses a tz4 consensus key, thanks to the BLS signature scheme, @@ -92,7 +92,7 @@ which helps reducing the size and validation time of blocks without compromising security. A valid block can include at most one aggregated preattestation and at most one aggregated attestation. -.. _voting_operations_s023: +.. _voting_operations_seoul: Voting Operations ~~~~~~~~~~~~~~~~~ @@ -113,7 +113,7 @@ voting operations: Further details on each operation's implementation and semantics are provided in the dedicated entry for :doc:`on-chain governance`. -.. _anonymous_operations_s023: +.. _anonymous_operations_seoul: Anonymous Operations ~~~~~~~~~~~~~~~~~~~~ @@ -134,17 +134,17 @@ mechanism`: - The ``Vdf_revelation`` operation allows the submission of a solution to, and a proof of correctness of, the :ref:`VDF - challenge` corresponding to the VDF revelation period of + challenge` corresponding to the VDF revelation period of the randomness generation protocol. Further details on the latter operation's implementation and semantics are provided in the :ref:`random seed generation -protocol`. +protocol`. Two operations in this class are used to :ref:`punish participants -which engage in Byzantine behaviour` -- notably -delegates which :ref:`"double sign" ` blocks, or emit -conflicting :ref:`consensus operations`: +which engage in Byzantine behaviour` -- notably +delegates which :ref:`"double sign" ` blocks, or emit +conflicting :ref:`consensus operations`: - The ``Double_consensus_operation_evidence`` operation allows for accusing a delegate of having *double-preattested* or *double-attested* -- i.e., of having @@ -161,13 +161,13 @@ conflicting :ref:`consensus operations`: having "double-baked" a block -- i.e., of having signed two different blocks at the same level and at same round. The bulk of the evidence consists of the :ref:`block - headers` of each of the two offending blocks. + headers` of each of the two offending blocks. -See :ref:`here` for further detail on the semantics of +See :ref:`here` for further detail on the semantics of evidence-providing operations. The ``Activation`` operation allows users which participated in the -Tezos fundraiser to make their :ref:`accounts ` operational. +Tezos fundraiser to make their :ref:`accounts ` operational. Finally, the ``Drain_delegate`` operation allows an active consensus-key account, i.e., an account to which a baker delegated its @@ -178,7 +178,7 @@ key. The DAL also adds the anonymous operation ``DAL_entrapment_evidence``, see :doc:`./dal_support`. -.. _manager_operations_s023: +.. _manager_operations_seoul: Manager Operations ~~~~~~~~~~~~~~~~~~ @@ -193,9 +193,9 @@ Manager operations enable end-users to interact with the Tezos blockchain -- e.g., transferring funds or calling :doc:`smart contracts`. A manager operation is issued by a single *manager* account which signs the operation and pays the -:ref:`fees` to the baker for its inclusion in a block. Indeed, +:ref:`fees` to the baker for its inclusion in a block. Indeed, manager operations are the only fee-paying and -:ref:`gas-consuming` operations. +:ref:`gas-consuming` operations. - The ``Reveal`` operation reveals the public key of the sending manager. Knowing this public key is indeed necessary to check the signature @@ -203,11 +203,11 @@ manager operations are the only fee-paying and the manager must also include a proof of possession, which is the signature of the public key itself. - The ``Transaction`` operation allows users to transfer tez - between accounts, to invoke a smart contract, or to invoke :ref:`pseudo-operations ` on user accounts. -- The ``Delegation`` operation allows users to designate a :ref:`delegate` (a + between accounts, to invoke a smart contract, or to invoke :ref:`pseudo-operations ` on user accounts. +- The ``Delegation`` operation allows users to designate a :ref:`delegate` (a *baker*) for :ref:`delegating ` or :ref:`staking ` their coins, or to register themselves as delegates. - The ``Update_consensus_key`` operation allows users to register a - :ref:`consensus key`, which is a dedicated key + :ref:`consensus key`, which is a dedicated key for signing blocks and consensus-related operations. When the new consensus key is a tz4 (BLS key), the optional ``proof`` field must contain a proof of possession, which is the signature of the public key itself. - The ``Update_companion_key`` operation allows users to register a @@ -215,11 +215,11 @@ manager operations are the only fee-paying and for signing the DAL specific part of consensus operations, when using a tz4 consensus key. - The ``Origination`` operation is used to - :ref:`originate`, that is to deploy, smart contracts + :ref:`originate`, that is to deploy, smart contracts in the Tezos blockchain. - The ``Set_deposits_limit`` operation enables delegates to adjust the amount of stake a delegate :ref:`has locked in - bonds`. + bonds`. - Support for registering global constants is implemented with the ``Register_global_constant`` operation. - The ``Increase_paid_storage`` operation allows a sender to increase @@ -275,7 +275,7 @@ handled with dedicated manager operations. determine if it is called by a smart rollup using the ``SENDER`` Michelson instruction. -.. _manager_operations_batches_s023: +.. _manager_operations_batches_seoul: Manager Operation Batches """"""""""""""""""""""""" @@ -288,20 +288,20 @@ Batches satisfy the following properties: - All operations in a batch are issued by the same manager, which provides a single signature for the entire batch. -- A batch is :ref:`applied` +- A batch is :ref:`applied` atomically: all its operations are executed sequentially, without interleaving other operations. Either all the operations in the batch succeed, or none is applied. -.. _failing_noop_s023: +.. _failing_noop_seoul: Failing_noop operation ~~~~~~~~~~~~~~~~~~~~~~ The ``Failing_noop`` operation is not executable in the protocol: -- it can only be validated in :ref:`mempool mode `, by the :doc:`prevalidator component <../shell/prevalidation>`; -- consequently, this operation cannot be :ref:`applied `, and in fact will never be included into a block. +- it can only be validated in :ref:`mempool mode `, by the :doc:`prevalidator component <../shell/prevalidation>`; +- consequently, this operation cannot be :ref:`applied `, and in fact will never be included into a block. Rather, the ``Failing_noop`` operation allows to sign an arbitrary string, without introducing an operation that could be misinterpreted in the protocol. diff --git a/docs/seoul/cli-commands.rst b/docs/seoul/cli-commands.rst index 1804de402d34..10ee797e1366 100644 --- a/docs/seoul/cli-commands.rst +++ b/docs/seoul/cli-commands.rst @@ -16,7 +16,7 @@ using shell commands such as (:ref:`indicating the appropriate protocol `. -.. _client_manual_s023: +.. _client_manual_seoul: Client manual ============= @@ -27,7 +27,7 @@ This is the manual page of the command line tool ``octez-client``. See :ref:`how :file: octez-client.html -.. _baker_manual_s023: +.. _baker_manual_seoul: Baker manual ============ @@ -38,7 +38,7 @@ This is the manual page of the baker command line tool. See :ref:`baker_run` for :file: octez-baker.html -.. _accuser_manual_s023: +.. _accuser_manual_seoul: Accuser manual ============== diff --git a/docs/seoul/consensus.rst b/docs/seoul/consensus.rst index df419fe0dcf4..6145b1776ee0 100644 --- a/docs/seoul/consensus.rst +++ b/docs/seoul/consensus.rst @@ -50,12 +50,12 @@ length in the `technical report `_ and in a post `_. Here we only provide a user/developer perspective. -.. _tb_validator_s023: +.. _tb_validator_seoul: Tenderbake is executed for each new block level by a "committee" whose members are called *validators*, which are delegates selected at random based on their stake, in much the same way as endorsers were selected in Emmy*. We let -``CONSENSUS_COMMITTEE_SIZE`` be the number of validator :ref:`slots` per level. +``CONSENSUS_COMMITTEE_SIZE`` be the number of validator :ref:`slots` per level. Furthermore, we use ``CONSENSUS_THRESHOLD`` to denote two thirds of ``CONSENSUS_COMMITTEE_SIZE``. For each level, Tenderbake proceeds in rounds. Each *round* represents an @@ -79,13 +79,13 @@ Round durations thus increase linearly with ``DELAY_INCREMENT_PER_ROUND``. Schematically, a round consists in the following steps: -.. _candidate_block_s023: +.. _candidate_block_seoul: * a validator designated for that round injects a *candidate block* (representing a proposal) and consensus operations (representing votes) into the node to which it is attached, which then * diffuses those blocks and consensus operations to other nodes of the network, and thus * communicates them to the validators attached to those nodes, to carry out voting on which block to accept. -.. _quorum_s023: +.. _quorum_seoul: Unlike Emmy*, Tenderbake has `two types of votes `_: @@ -105,7 +105,7 @@ the same *payload* as the initial block. We talk about a *re-proposal* in this case. -.. _finality_s023: +.. _finality_seoul: Transaction and block finality ------------------------------ @@ -122,7 +122,7 @@ Consequently, to agree on a block, that is, on both the payload and the header, confirmation, and thus guarantees **block finality after 2 confirmations**. -.. _time_between_blocks_s023: +.. _time_between_blocks_seoul: Time between blocks ------------------- @@ -140,7 +140,7 @@ should be taken at round 0, meaning that the time between blocks would be :math:`round\_duration(0)` seconds i.e., parameter ``MINIMAL_BLOCK_DELAY``. -.. _active_stake_s023: +.. _active_stake_seoul: Validator selection ------------------- @@ -151,17 +151,17 @@ power is a function of all tez owned by the delegate and its delegators, with :doc:`staked` tez weighted more than non-staked tez, and there are additional considerations such as overstaking and overdelegation; see the :ref:`baking power -formula`. +formula`. The baking rights are determined -:ref:`CONSENSUS_RIGHTS_DELAY` in advance, which is -currently ``2`` :ref:`cycles`. More +:ref:`CONSENSUS_RIGHTS_DELAY` in advance, which is +currently ``2`` :ref:`cycles`. More precisely, at the end of cycle ``n`` and beginning of cycle ``n+1``, the baking rights for cycle ``n+1+CONSENSUS_RIGHTS_DELAY=n+3`` are :doc:`randomly generated` based on the current :doc:`baking power` of each delegate that meets the :ref:`minimal power and own staked -requirements`. +requirements`. Economic Incentives @@ -224,7 +224,7 @@ However, two conditions must be met: - the validator has revealed its nonces, and - the validator has been present during the cycle. -Not giving rewards in case of missing revelations is not new as it is :ref:`adapted` +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 attesting power (that is, the number of validator slots at the @@ -233,7 +233,7 @@ cycle represents at least ``MINIMAL_PARTICIPATION_RATIO`` of the delegate's expe validator slots for the current cycle (which is ``BLOCKS_PER_CYCLE * CONSENSUS_COMMITTEE_SIZE * active_stake / total_active_stake``). -The concrete values for rewards depend on the issuance which is dynamically adjusted by :ref:`Adaptive Issuance`. +The concrete values for rewards depend on the issuance which is dynamically adjusted by :ref:`Adaptive Issuance`. For each block it issues an amount ``total_rewards`` of rewarded tez, that varies with the total amount of tez at stake on the chain. To obtain some concrete values, we will use as an example the issuance before Adaptive Issuance, @@ -277,7 +277,7 @@ included during that cycle has been ``651,456`` slots. Given that this number is bigger than the minimum required (``756,000 * 2 / 3``), it receives an attesting reward of ``756,000 * 0.000761 = 575.316`` tez for that cycle. -.. _slashing_s023: +.. _slashing_seoul: Slashing ^^^^^^^^ @@ -301,12 +301,12 @@ If a delegate's deposit is smaller than the slashed amount, the deposit is simply emptied. The evidence for double signing at a given level can be collected by -any :ref:`accuser` and included as a *denunciation* +any :ref:`accuser` and included as a *denunciation* operation in a block in the same cycle as the double signing or in the ``DENUNCIATION_PERIOD`` next cycles. As soon as a delegate is denounced for any double signing, it is -immediately :ref:`forbidden` from both baking +immediately :ref:`forbidden` from both baking and attesting for at least 2 cycles. The actual slashing and denunciation rewarding happen at the end of @@ -321,21 +321,21 @@ 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. -.. _fitness_section_s023: +.. _fitness_section_seoul: 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`. +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`. In Emmy*, only the level mattered. But in Tenderbake, we need to, for instance, allow for new blocks at the same level to be accepted by nodes. Therefore the fitness also includes the block's round (as the fifth component). -Furthermore, we also allow to change the predecessor block when it has a :ref:`smaller round`. +Furthermore, we also allow to change the predecessor block when it has a :ref:`smaller round`. 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 +re-proposals`, the fitness also includes, as the third component, the round at which a preattestation quorum was observed by the baker, if any (this component can therefore be empty). By the way, preattestations are present in a block if and only if the locked round @@ -362,7 +362,7 @@ 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_s023: +.. _cs_constants_seoul: Consensus related protocol parameters ------------------------------------- @@ -408,14 +408,14 @@ Consensus related protocol parameters * - ``UNSTAKE_FINALIZATION_DELAY`` [#derived_cs+sd]_ - 3 cycles -The above list of protocol parameters is a subset of the :ref:`protocol constants `. +The above list of protocol parameters is a subset of the :ref:`protocol constants `. .. [#derived_cs] These :ref:`derived constants - ` are automatically set to + ` are automatically set to the same value as ``CONSENSUS_RIGHTS_DELAY``. .. [#derived_cs+sd] This :ref:`derived constant - ` is automatically set + ` is automatically set to ``CONSENSUS_RIGHTS_DELAY + SLASHING_DELAY``. diff --git a/docs/seoul/dal_support.rst b/docs/seoul/dal_support.rst index 4fd9efd578ec..e224f5f9dc9f 100644 --- a/docs/seoul/dal_support.rst +++ b/docs/seoul/dal_support.rst @@ -5,10 +5,10 @@ DAL integration The :doc:`DAL <../shell/dal>`'s integration within the economic protocol relies on three operations: #. ``DAL_publish_commitment``: a manager operation, allowing anyone to publish a DAL commitment -#. ``attestation``: the existing :ref:`consensus operation `, allowing bakers to attach a DAL payload attesting the data seen on the DAL P2P network +#. ``attestation``: the existing :ref:`consensus operation `, allowing bakers to attach a DAL payload attesting the data seen on the DAL P2P network #. ``DAL_entrapment_evidence``: an anonymous operation to denounce a baker that has attested a trap shard -and on an :ref:`incentives scheme` for the DAL. +and on an :ref:`incentives scheme` for the DAL. DAL publish commitment ====================== @@ -57,7 +57,7 @@ In the block’s metadata, there is a specific field for the DAL, called ``"dal_ Therefore, for data committed (published) at level ``n``, the slot's availability is determined by the metadata of the block at level ``n + ATTESTATION_LAG``. Consequently, a smart rollup can only utilize this data from level ``n + ATTESTATION_LAG + 1`` onward. -.. _DAL_incentives_scheme_s023: +.. _DAL_incentives_scheme_seoul: DAL incentives scheme ===================== @@ -66,7 +66,7 @@ Overview -------- Bakers must meet a 64% minimal participation threshold in a cycle to earn a fixed percentage of the total participation rewards allocated for them. -As part of participation rewards, the DAL rewards are subject to the adjustments done by :ref:`Adaptive Issuance`. +As part of participation rewards, the DAL rewards are subject to the adjustments done by :ref:`Adaptive Issuance`. To ensure DAL attestations match the actual availability of data shards, there are special shards, known as *traps*, which are designed to test whether bakers have genuinely downloaded and processed their assigned shards. Bakers must correctly identify these traps to avoid losing the DAL rewards allocated to them. @@ -110,12 +110,12 @@ corresponding to the following scenario. Suppose there are five delegates with e DAL participation rewards ------------------------- -A fixed percentage, defined by a protocol parameter called ``REWARDS_RATIO``, set to 10%, of the total :ref:`participation rewards` is allocated to the DAL. +A fixed percentage, defined by a protocol parameter called ``REWARDS_RATIO``, set to 10%, of the total :ref:`participation rewards` is allocated to the DAL. -The DAL rewards per level are implicitly given by their weight, ``DAL_REWARDS_WEIGHT``, as for the other types of :ref:`participation rewards`. +The DAL rewards per level are implicitly given by their weight, ``DAL_REWARDS_WEIGHT``, as for the other types of :ref:`participation rewards`. The value of ``DAL_REWARDS_WEIGHT`` is such that it represents ``REWARDS_RATIO`` of all reward weights. -The rewards are distributed at the end of a cycle, and are computed in the same manner as for the other :ref:`participation rewards`. +The rewards are distributed at the end of a cycle, and are computed in the same manner as for the other :ref:`participation rewards`. For instance, the stakers' share of these reward is proportional to the weight of their stake in relation to their baker's baking power. The metadata of the last block of a cycle contains the :doc:`balance updates` corresponding to the allocated DAL rewards for that cycle. These balance updates are identified by two categories for DAL rewards, analogous to consensus attestation rewards, namely: @@ -138,7 +138,7 @@ The protocol parameter ``TRAPS_FRACTION`` controls the fraction of shards marked Bakers detect traps by retrieving shard content via their DAL node and applying the trap function. A trap invalidates the corresponding attestation: the baker should not attest a slot if one of the slot’s shards assigned to him is a trap. The ``DAL_entrapment_evidence`` accusation operation can be used to accuse a baker of wrongly attesting a slot due to an undetected trap. -This accusation operation includes the offending attestation operation (either individual or part of an :ref:`aggregate`), the offending baker's consensus slot, the wrongly attested DAL slot, and the undetected shard. +This accusation operation includes the offending attestation operation (either individual or part of an :ref:`aggregate`), the offending baker's consensus slot, the wrongly attested DAL slot, and the undetected shard. As for double-signing accusations, any baker can include a DAL accusation in its block. Accusations can be included during a period of ``DENUNCIATION_PERIOD`` cycles after the misbehavior event, which is that of the corresponding attestation operation. @@ -148,12 +148,12 @@ Penalties A baker that is correctly accused, through an accusation operation included in a block, loses their DAL rewards for the cycle containing the block. -.. _dal_rollups_integration_s023: +.. _dal_rollups_integration_seoul: Smart Rollups integration ========================= -The DAL is integrated with :doc:`smart rollups <../active/smart_rollups>` so that kernels can request pages from the DAL via the :ref:`reveal data channel `. A smart rollup can fetch any page from the DAL node if the commitment respects some conditions: +The DAL is integrated with :doc:`smart rollups <../active/smart_rollups>` so that kernels can request pages from the DAL via the :ref:`reveal data channel `. A smart rollup can fetch any page from the DAL node if the commitment respects some conditions: - The commitment should have been published after the rollup origination (this constraint will be leveraged so that the kernel can request any commitment in the past) - The commitment should not have been published in a level in the future after the level of the next commitment of the state (at most 30 levels in the future). @@ -163,12 +163,12 @@ If the kernel requests a page that does not satisfy the mentioned conditions, th Moreover, the rollup kernel has access to the protocol constants so that the same kernel code can be used on different test networks. -.. _dal_constants_s023: +.. _dal_constants_seoul: DAL-related protocol constants ============================== -This section describes the protocol constants specific to the DAL as well as their default values on mainnet (see :ref:`protocol_constants_s023` on how to find the values for tests networks): +This section describes the protocol constants specific to the DAL as well as their default values on mainnet (see :ref:`protocol_constants_seoul` on how to find the values for tests networks): - ``FEATURE_ENABLE`` (true): whether the DAL is available - ``INCENTIVES_ENABLE`` (true): whether baker incentives are available diff --git a/docs/seoul/glossary.rst b/docs/seoul/glossary.rst index 531764196fce..acfb335a8093 100644 --- a/docs/seoul/glossary.rst +++ b/docs/seoul/glossary.rst @@ -18,7 +18,7 @@ _`Block` The header itself decomposes into a :ref:`shell header` (common to all Tezos economic protocols), and a protocol-specific header. The shell header contains protocol-agnostic data such as the predecessor's block hash and the block's timestamp. -.. _def_context_s023: +.. _def_context_seoul: _`Context` The state of the blockchain. The context is defined by the @@ -44,7 +44,7 @@ _`Fitness` (a.k.a. score, weight) _`Height` See level_. -.. _def_level_s023: +.. _def_level_seoul: _`Level` (a.k.a. block height) The position of a block_ in the blockchain, that is, the number of blocks @@ -53,7 +53,7 @@ _`Level` (a.k.a. block height) _`Mempool` A pool (set) of operation_\ s maintained by a node_ and not yet included in a block_. -.. _def_metadata_s023: +.. _def_metadata_seoul: _`Metadata` A (block or operation) metadata is a piece of data @@ -99,7 +99,7 @@ _`Weight` Protocol terms -------------- -.. _def_accuser_s023: +.. _def_accuser_seoul: _`Accuser` When a delegate_ attempts `double signing`_ (or when it tries @@ -111,7 +111,7 @@ _`Accuser` When using :ref:`Octez `, accusation operations are emitted by the accuser daemon. Note that this daemon is not associated to a delegate: accusation operations are anonymous, and any delegate can include them in a block. -.. _def_account_s023: +.. _def_account_seoul: _`Account` An account is an address managed by the protocol. @@ -171,7 +171,7 @@ _`Burn` _`Constant` Protocols are parameterized by several parameters called protocol constants, which may vary from one protocol to another or from one network to another. -.. _def_cycle_s023: +.. _def_cycle_seoul: _`Cycle` A cycle is a sequence of consecutive block_\ s of fixed length (given by a protocol constant_). E.g., cycle 12 started at block @@ -185,7 +185,7 @@ _`Cycle` constant_, and thus might change across different Tezos protocols. -.. _def_delegate_s023: +.. _def_delegate_seoul: _`Delegate` A `user account`_ that can participate in consensus and in governance. @@ -199,7 +199,7 @@ _`Delegation` its `baking rights`_ and `attesting rights`_; it also increases its `voting power`_. However, the delegate_ does not control the funds of the delegating account_, e.g., it can not spend them. -.. _def_double_signing_s023: +.. _def_double_signing_seoul: _`Double signing` The situation when a baker_ signs two different block_\ s at the same level and same round, @@ -208,29 +208,29 @@ _`Double signing` 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`. + part of the double signer's deposit -- see :ref:`Slashing`. _`Failing Noop` The ``Failing_noop`` operation implements a *No-op*, which always - fails at :ref:`application time`, and + fails at :ref:`application time`, and should never appear in :ref:`applied - blocks`. This operation allows end-users to - :ref:`sign arbitrary messages` which have no + blocks`. This operation allows end-users to + :ref:`sign arbitrary messages` which have no computational semantics. -.. _def_fee_s023: +.. _def_fee_seoul: _`Fee` To ensure responsible use of computation resources of other nodes, and also to encourage active participation in the consensus protocol, users pay fees to bakers for including their operation_\ s in block_\ s. For example, fees are paid to a baker for operations such as a transaction_ or a revelation of a public key. - Currently, only :ref:`manager operations` + Currently, only :ref:`manager operations` require collecting fees from its sender account_. See also `burn`_. -.. _def_gas_s023: +.. _def_gas_seoul: _`Gas` A measure of the number of elementary steps performed during @@ -257,7 +257,7 @@ _`Layer 2` _`Michelson` The built-in language used by a `smart contract`_. -.. _def_minimal_stake_s023: +.. _def_minimal_stake_seoul: _`Minimal stake` An amount of tez (e.g., 6000ꜩ) serving as a minimal amount for a @@ -272,7 +272,7 @@ _`Operation kinds` _`Originated account` See `smart contract`_. -.. _def_origination_s023: +.. _def_origination_seoul: _`Origination` A manager operation_ whose purpose is to create -- that @@ -330,7 +330,7 @@ _`Rollup outbox` cemented (hence, at least two weeks after the actual execution of the operation). -.. _def_round_s023: +.. _def_round_seoul: _`Round` An attempt to reach consensus on a block at a given level. @@ -352,13 +352,13 @@ _`Smart Rollup` (e.g., an EVM-compatible one), or an application-specific DApp. See :doc:`smart_rollups`. -.. _def_staker_s023: +.. _def_staker_seoul: _`Staker` A `user account`_ that made a security deposit. The user account must have set a delegate. The security deposit accrues to the stake of the user account's delegate and is - subject to slashing in case the delegate misbehaves -- see :ref:`Slashing`. + subject to slashing in case the delegate misbehaves -- see :ref:`Slashing`. _`Tez` A unit of the cryptocurrency native to a Tezos_ chain, such as in "I sent you 2 tez." Tez is invariable. It is not capitalized except at the beginning of a sentence or when you would otherwise capitalize a noun. @@ -368,7 +368,7 @@ _`Transaction` An operation_ to transfer tez between two accounts, or to run the code of a `smart contract`_. -.. _def_user_account_s023: +.. _def_user_account_seoul: _`User account` An account_ that is linked to a public key. Contrary to a `smart @@ -387,7 +387,7 @@ _`Validation pass` An index (a natural number) associated with a particular kind of operations, allowing to group them into classes. Validation passes enable prioritizing the :ref:`validation and - application` of certain classes of + application` of certain classes of operations. _`Voting period` @@ -399,7 +399,7 @@ _`Voting power` The amount of tokens that determines a delegate_'s weight in the voting process. A delegate's voting power is computed from the delegate's own tokens and the sum of tokens delegated to - it. See :ref:`voting_power_s023` for details. + it. See :ref:`voting_power_seoul` for details. _`Voting listings` The list calculated at the beginning of each `voting period`_ that contains diff --git a/docs/seoul/liquidity_baking.rst b/docs/seoul/liquidity_baking.rst index 24663f684214..0b7df797c61b 100644 --- a/docs/seoul/liquidity_baking.rst +++ b/docs/seoul/liquidity_baking.rst @@ -34,7 +34,7 @@ One can easily compute the value of the per block subsidy by taking into account 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``. -.. _toggle_s023: +.. _toggle_seoul: Toggle vote ~~~~~~~~~~~ @@ -89,4 +89,4 @@ file is deleted or becomes malformed while the baker is running, the last valid value read is used. If neither a valid vote file is provided nor a CLI value given, the baker will fail on the first block after it was started. See also the :ref:`baker man -page`. +page`. diff --git a/docs/seoul/mempool.rst b/docs/seoul/mempool.rst index 02385e11a8c8..39a0befd43c5 100644 --- a/docs/seoul/mempool.rst +++ b/docs/seoul/mempool.rst @@ -9,20 +9,20 @@ that can be safely used to bake a new block. It ensures that : -- Every operation contained are :ref:`valid`; +- Every operation contained are :ref:`valid`; -- every operation are :ref:`co-valid`: they can be +- every operation are :ref:`co-valid`: they can be safely included in a block in any arbitrary order, meaning operations commute; - the merging of two mempools also maintains the aforementioned properties. The protocol leverages the :ref:`partial construction -mode` to incrementally validate new operations while +mode` to incrementally validate new operations while maintaining the aforementioned invariants. During validation, operations are never actually applied, as it is unnecessary -for asserting their :ref:`validity`. +for asserting their :ref:`validity`. Merging Mempools ---------------- diff --git a/docs/seoul/michelson.rst b/docs/seoul/michelson.rst index deb07cca23fb..d471c60de2ff 100644 --- a/docs/seoul/michelson.rst +++ b/docs/seoul/michelson.rst @@ -29,7 +29,7 @@ the specification. The document also starts with a less formal explanation of the context: how Michelson code interacts with the blockchain. -.. _transaction_semantics_s023: +.. _transaction_semantics_seoul: Semantics of smart contracts and transactions --------------------------------------------- @@ -112,7 +112,7 @@ Internal operations are not included in any block, and are not signed. Internal operations are run in an atomic sequence with the external operation who triggered the contract call, *after* the contract execution, in depth-first order. This implies in particular that any contract calls emitted by a contract C are executed after contract C successfully finishes execution returning its result (the list of internal operations and the new storage). -Note that :ref:`manager operations batches ` contain a sequence of external operations signed as a whole by a source user account, which are executed atomically. +Note that :ref:`manager operations batches ` contain a sequence of external operations signed as a whole by a source user account, which are executed atomically. For example, in case of a batch of two external operations, execution proceeds as follows: :: @@ -299,7 +299,7 @@ constructors is fixed by this specification. Michelson does not let the programmer introduce its own types. Be aware that the syntax used in the specification may differ from -the :ref:`concrete syntax `. In particular +the :ref:`concrete syntax `. In particular some instructions are annotated with types that are not present in the concrete language because they are synthesized by the typechecker. @@ -325,7 +325,7 @@ The concrete language also has some syntax sugar to group some common sequences of operations as one. This is described in this specification using a simple regular expression style recursive instruction rewriting. -.. _michelson_type_system_s023: +.. _michelson_type_system_seoul: Introduction to the type system and notations --------------------------------------------- @@ -455,7 +455,7 @@ the program on an abstract stack representing the input type provided by the programmer, and checking that the resulting symbolic stack is consistent with the expected result, also provided by the programmer. -.. _type_normalization_s023: +.. _type_normalization_seoul: Type normalization ~~~~~~~~~~~~~~~~~~ @@ -468,7 +468,7 @@ See `type pair `__ for d The node RPC ``/helpers/script/normalize_type`` is available to normalize a given Michelson type (see :doc:`../api/openapi`, within the protocol-dependent RPCs). This RPC is intended for tool developers wanting to support the type shorthands in their tools without reimplementing their normalization. -However, one side effect of this RPC is the stripping of :ref:`annotations `. +However, one side effect of this RPC is the stripping of :ref:`annotations `. As a consequence, a tool needing to preserve annotations on shorthand data types should implement its own type normalization instead of relying on this RPC. Side note @@ -762,7 +762,7 @@ A typing rule can be inferred: Concrete syntax --------------- -.. _ConcreteSyntax_s023: +.. _ConcreteSyntax_seoul: The concrete language is very close to the formal notation of the specification. Its structure is extremely simple: an expression in the @@ -830,7 +830,7 @@ parameters require sequences in the concrete syntax. IF { instr1_true ; instr2_true ; ... } { instr1_false ; instr2_false ; ... } -.. _syntax_of_scripts_s023: +.. _syntax_of_scripts_seoul: Main program structure ~~~~~~~~~~~~~~~~~~~~~~ @@ -841,7 +841,7 @@ of three primitive applications (in no particular order) that provide its See the next section for a concrete example. -.. _annotations_s023: +.. _annotations_seoul: Annotations ----------- @@ -866,7 +866,7 @@ We distinguish three kinds of annotations: - variable annotations, written ``@var_annot``, - and field or constructors annotations, written ``%field_annot``. -Note that all annotations are stripped during :ref:`type normalization `. +Note that all annotations are stripped during :ref:`type normalization `. Type annotations ~~~~~~~~~~~~~~~~ @@ -1167,7 +1167,7 @@ Primitive applications can receive one or many annotations. An annotation is a sequence of characters that matches the regular expression ``@%|@%%|%@|[@:%][_0-9a-zA-Z][_0-9a-zA-Z\.%@]*``. Note however that ``@%``, ``@%%`` and ``%@`` are -:ref:`special annotations ` and are not allowed everywhere. +:ref:`special annotations ` and are not allowed everywhere. Annotations come after the primitive name and before its potential arguments. @@ -1321,7 +1321,7 @@ type (which can be changed). For instance the annotated typing rule for Special annotations ~~~~~~~~~~~~~~~~~~~ -.. _SpecialAnnotations_s023: +.. _SpecialAnnotations_seoul: The special variable annotations ``@%`` and ``@%%`` can be used on instructions ``CAR``, ``CDR``, and ``UNPAIR``. It means to use the accessed field name (if any) as @@ -1664,7 +1664,7 @@ data include not only a description of the action to perform but also the address of the multisig contract and a counter that gets incremented at each successful call to the contract. -The multisig commands of :ref:`Octez command line client ` +The multisig commands of :ref:`Octez command line client ` use this smart contract. Moreover, `functional correctness of this contract has been verified @@ -2021,7 +2021,7 @@ The language is implemented in OCaml as follows: ``Prim ("If", ...)`` into an ``If``, a ``Prim ("Dup", ...)`` into a ``Dup``, etc. -.. _michelson_tzt_s023: +.. _michelson_tzt_seoul: TZT, a Syntax extension for writing unit tests ---------------------------------------------- @@ -2045,7 +2045,7 @@ is :doc:`../shell/micheline`. TZT unit test files usually have the extension ``.tzt``. A unit test file describes a single unit test. It consists of a Micheline sequence of primitive applications (see :doc:`../shell/micheline`), in no particular order. This is -:ref:`similar to Michelson scripts ` but +:ref:`similar to Michelson scripts ` but the set of primitives allowed at the toplevel differ; in Michelson scripts, the allowed toplevel primitives are ``parameter`` (mandatory), ``storage`` (mandatory), ``code`` (mandatory), and @@ -2073,7 +2073,7 @@ Each of the mandatory primitives ``input``, ``code``, and ``output`` must occur exactly once in a unit test file in no particular order. The ``input`` primitive is used to declare the input stack (see the -:ref:`syntax of concrete stacks `). +:ref:`syntax of concrete stacks `). The ``code`` primitive is used to declare the instruction or sequence of instructions to execute. @@ -2082,9 +2082,9 @@ The ``output`` primitive is used to declare if the execution is expected to succeed or fail and what result is expected from the execution. For executions expected to succeed, the argument of the ``output`` primitive is simply the expected output stack (see the -:ref:`syntax of errors `). For executions +:ref:`syntax of errors `). For executions expected to fail, the argument is the expected error. In both cases, -the :ref:`wildcard pattern ` can +the :ref:`wildcard pattern ` can be used to omit part of the expected output. The simplest test which can be written asserts that executing no @@ -2192,12 +2192,12 @@ particular order. - ``other_contracts`` (optional, defaults to ``{}``): mapping between the contract addresses that are assumed to exist and their parameter types (see the :ref:`syntax of other contracts - specifications `) + specifications `) - ``big_maps`` (optional, defaults to ``{}``): mapping between integers representing ``big_map`` indices and descriptions of big maps (see the :ref:`syntax of extra big maps specifications - `) + `) The following test example asserts that the default value for the `NOW `__ @@ -2221,7 +2221,7 @@ instruction return a chosen timestamp: code NOW; output { Stack_elt timestamp "2020-01-08T07:13:51Z" } -.. _syntax_of_concrete_stacks_s023: +.. _syntax_of_concrete_stacks_seoul: Syntax of concrete stacks ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2233,7 +2233,7 @@ Stack_elt nat 42 }`` is a concrete stack of length 2 whose top element is the boolean ``True`` and the bottom element is the natural number ``42``. -.. _omitting_parts_of_the_output_s023: +.. _omitting_parts_of_the_output_seoul: Omitting parts of the output ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2299,11 +2299,11 @@ The wildcard pattern is typically used to omit unspecified aspects of the Michelson language when writing portable tests; in particular the cryptographic nonces in values of type ``operation`` (see the :ref:`syntax of concrete operations -`) or implementation-specific +`) or implementation-specific parts of error outputs (see the :ref:`syntax of errors -`). +`). -.. _output_normalization_s023: +.. _output_normalization_seoul: Output normalization ~~~~~~~~~~~~~~~~~~~~ @@ -2331,7 +2331,7 @@ test; for example these two tests pass: output {Stack_elt address 0x0000e7670f32038107a59a2b9cfefae36ea21f5aa63c} This normalization feature is however incompatible with using the -:ref:`wildcard pattern ` in the +:ref:`wildcard pattern ` in the output; when using wildcards the output must be formatted using the readable format so the following test does not pass: @@ -2349,7 +2349,7 @@ but the following test does pass: code {}; output {Stack_elt _ "tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN"} -.. _syntax_of_errors_s023: +.. _syntax_of_errors_seoul: Syntax of errors ~~~~~~~~~~~~~~~~ @@ -2362,7 +2362,7 @@ raise: - ``(StaticError )``: an error occurred before the instruction was executed; the error description format is unspecified so consider using a :ref:`wildcard - ` such as ``(StaticError _)`` + ` such as ``(StaticError _)`` to write portable tests; - ``(Failed )``: the execution reached a ``FAILWITH`` @@ -2413,7 +2413,7 @@ instruction. code { DUP "foo" }; output (StaticError _) -.. _syntax_of_concrete_operations_s023: +.. _syntax_of_concrete_operations_seoul: Syntax of concrete operations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2445,7 +2445,7 @@ and ``SET_DELEGATE`` have respectively the following shapes: The computation of the cryptographic nonce is not specified. To write portable tests, the nonces appearing in output stack expectations should be replaced by :ref:`a wildcard pattern -`. +`. Here is an example unit test for the ``SET_DELEGATE`` instruction used to set the delegate of the current contract to the account at address @@ -2457,7 +2457,7 @@ to set the delegate of the current contract to the account at address code SET_DELEGATE ; output { Stack_elt operation (Set_delegate (Some "tz1NwQ6hkenkn6aYYio8VnJvjtb4K1pfeU1Z") _) } -.. _syntax_of_other_contracts_s023: +.. _syntax_of_other_contracts_seoul: Syntax of other contracts specifications ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2476,7 +2476,7 @@ Micheline sequence whose elements have the form ``Contract "KT1..." ```` is the type of its parameter. Each address should appear at most once and the order is irrelevant. -.. _syntax_of_extra_big_maps_s023: +.. _syntax_of_extra_big_maps_seoul: Syntax of extra big maps specifications ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/seoul/native_multisig.rst b/docs/seoul/native_multisig.rst index 3ca11dad5c76..973b74b693ba 100644 --- a/docs/seoul/native_multisig.rst +++ b/docs/seoul/native_multisig.rst @@ -21,13 +21,13 @@ effective, it presents two main challenges: as it does not allow for multiple users to manage the account collectively. -Both problems are usually solved by using a multisig **contract**, that allows to share its ownership and its associated balance or assets, between several participants. Tezos provides specific support for multisig contracts in the form of a :doc:`builtin multisig contract <../user/multisig>` and even a set of related client commands to interact with it. However, this solution is not applicable in all use cases, and most importantly in the case of collectively staking or baking. This is because in Tezos, a smart contract cannot be a :ref:`delegate `, and not even a :ref:`staker `. +Both problems are usually solved by using a multisig **contract**, that allows to share its ownership and its associated balance or assets, between several participants. Tezos provides specific support for multisig contracts in the form of a :doc:`builtin multisig contract <../user/multisig>` and even a set of related client commands to interact with it. However, this solution is not applicable in all use cases, and most importantly in the case of collectively staking or baking. This is because in Tezos, a smart contract cannot be a :ref:`delegate `, and not even a :ref:`staker `. Native multisig **accounts** address the above limitations with a cryptographic solution based on BLS multi-signature schemes. BLS signatures are particularly well-suited for this purpose due to their *aggregation* properties. Tezos supports BLS signatures -with :ref:`tz4 address accounts `, +with :ref:`tz4 address accounts `, and starting with protocol S, these adopt a proof-of-possession (PoP) scheme. As a result, protocols starting with S can benefit from faster verification of multiple signatures of the @@ -35,7 +35,7 @@ same message without breaking compatibility with the existing support for BLS (and ``tz4`` accounts). The multisig accounts implementation offers :ref:`RPCs and client -commands ` to facilitate the signing of +commands ` to facilitate the signing of operations in a native multisig setup. As a result, the protocol does not need to differentiate between a ``tz4`` address belonging to a single user account and one associated with a multisig account. @@ -91,7 +91,7 @@ of a multisig ``stake`` operation would look like this: (the source and destination are both the address of the multisig account, because staking is implemented by a pseudo-operation consisting in sending a transaction to oneself). -.. _native_multisig_rpc_cli_s023: +.. _native_multisig_rpc_cli_seoul: Octez CLI commands and RPC endpoints ------------------------------------ diff --git a/docs/seoul/plugins.rst b/docs/seoul/plugins.rst index 6e85c917d962..dcfbce449705 100644 --- a/docs/seoul/plugins.rst +++ b/docs/seoul/plugins.rst @@ -27,15 +27,15 @@ In turn protocol plugins may, for example: - perform protocol-dependent computations that require data not available in the amendable part of the protocol like accessing the current time - to reason on timestamps (see :ref:`consensus_filter_s023`); + to reason on timestamps (see :ref:`consensus_filter_seoul`); - preserve the opacity/abstraction barrier of the protocol's internal data by performing computations on internal data without revealing it: e.g., there are some RPCs that can introspect the protocol-dependent content for certain operations; - implement some common operations that are customized for each - protocol (e.g., :ref:`prevalidator_filters_s023`). + protocol (e.g., :ref:`prevalidator_filters_seoul`). -.. _prevalidator_filters_s023: +.. _prevalidator_filters_seoul: Prevalidator filters -------------------- @@ -55,7 +55,7 @@ The interface of the prevalidator plugin is described at the following filtering strategies are implemented in the :package-api:`pre_filter`. -.. _fees_filter_s023: +.. _fees_filter_seoul: Fees filter ........... @@ -66,10 +66,10 @@ prevalidator filter currently restricts operations based on their associated fees, to reject "too cheap" or "zero-fees" operations. This can be configured via the ``minimal_fees``, ``minimal_nanotez_per_gas_unit`` and ``minimal_nanotez_per_byte`` (see -:ref:`filter RPCs`) parameters of the filter +:ref:`filter RPCs`) parameters of the filter configuration of your node. -.. _consensus_filter_s023: +.. _consensus_filter_seoul: Consensus filter ................ @@ -83,7 +83,7 @@ This filter will classify a consensus operation as ``Branch_refused`` if the operation concerns a level and round combination that is far-fetched in the future in regard to the latest proposal predecessor and the current timestamp. It can be configured via the ``clock_drift`` (see :ref:`filter -RPCs`) parameter of the filter configuration of your +RPCs`) parameter of the filter configuration of your node. Operations prioritization and ordering @@ -93,13 +93,13 @@ In addition to quick filtering of undesired operations, the ``prefilter`` provides a priority for each successfully filtered operation. Concretely, the priority is either ``High``, ``Medium`` or ``Low`` in the current implementation, depending on the :ref:`validation -pass`. Some extra information (like the fees, or the +pass`. Some extra information (like the fees, or the gas/fees ratio of manager operations) are also provided along the priorities to enable fine-grained operations ordering. This extra information is similar to the one used by the baker's operations selection mechanism, that decides which operations will be included in the next block. -.. _active_filter_rpc_s023: +.. _active_filter_rpc_seoul: Filters RPCs ------------ diff --git a/docs/seoul/proof_of_stake.rst b/docs/seoul/proof_of_stake.rst index 06fb1dec7388..46b521b438ee 100644 --- a/docs/seoul/proof_of_stake.rst +++ b/docs/seoul/proof_of_stake.rst @@ -13,12 +13,12 @@ Tezos :doc:`governance `. If one does not have enough stake to participate on its own or does not want to set up the needed infrastructure, (s)he can use :ref:`delegation `, possibly complemented with :ref:`staking -`. Indeed, in Tezos, it is the :ref:`delegates` +`. Indeed, in Tezos, it is the :ref:`delegates` that may participate in consensus. However, at each level, not all delegates necessarily participate, and their participation weight may differ. The selection of the delegates' participation rights at a level is done by running a PRNG (pseudo-random number generator). -The PRNG's :ref:`seeds ` are obtained from random +The PRNG's :ref:`seeds ` are obtained from random data that are regularly produced and stored on the blockchain. Thus, the procedure is deterministic in that delegates' rights are uniquely determined from the seed; and it is random, in that its seed (and hence its results) cannot @@ -28,17 +28,17 @@ be predicted too much in advance. Delegation and Staking ---------------------- -A *delegate* is any :ref:`user account ` registered as +A *delegate* is any :ref:`user account ` registered as such. This is done by *self-delegating*, that is, emitting a delegation operation (see below) in which the specified delegate is the same as the operation emitter (its signer). -Any :ref:`account ` (user account or smart contract) can specify a delegate +Any :ref:`account ` (user account or smart contract) can specify a delegate through a delegation operation. Any non-delegate account can change or revoke its delegate at any time, again through a delegation operation. However, the change only -becomes effective after ``CONSENSUS_RIGHTS_DELAY + 2`` :ref:`cycles `. The +becomes effective after ``CONSENSUS_RIGHTS_DELAY + 2`` :ref:`cycles `. The value ``CONSENSUS_RIGHTS_DELAY`` is a :ref:`protocol constant -`. A delegate cannot stop self-delegating. +`. A delegate cannot stop self-delegating. A delegate participates in consensus and in governance in proportion to their *baking power* and *voting power* respectively. @@ -54,10 +54,10 @@ to their *baking power* and *voting power* respectively. :doc:`Baking Power` page for more details. Moreover, to participate in consensus and governance, the delegate -needs to be :ref:`active` and to meet -:ref:`minimal balance requirements`. +needs to be :ref:`active` and to meet +:ref:`minimal balance requirements`. -.. _security_deposit_s023: +.. _security_deposit_seoul: Delegates and delegators may :doc:`stake` their tez. Staked tez are security deposits that may be forfeited in case the baker does @@ -66,7 +66,7 @@ mentioned above, staked tez are weighted higher than non-staked tez when computing the baking power. -.. _consensus_key_s023: +.. _consensus_key_seoul: Consensus key ^^^^^^^^^^^^^ @@ -83,7 +83,7 @@ actually becomes the *active consensus key* that must be used to sign blocks and consensus operations; until then, it is called a *pending consensus key*. More precisely, the key becomes active after the cycle containing the ``Update_consensus_key`` operation is over and then -another :ref:`CONSENSUS_KEY_ACTIVATION_DELAY` full +another :ref:`CONSENSUS_KEY_ACTIVATION_DELAY` full cycles have passed: if the update happens during cycle ``n``, then the key becomes active at the beginning of cycle ``n + CONSENSUS_KEY_ACTIVATION_DELAY + 1``. @@ -104,7 +104,7 @@ including client commands that are helpful for handling consensus keys. Active and passive delegates ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. _active_delegate_s023: +.. _active_delegate_seoul: A delegate can be marked as either active or passive. A passive delegate cannot participate in the consensus algorithm. @@ -130,7 +130,7 @@ Tezos being proof-of-stake, the delegates' rights are selected at random based on their :doc:`baking power`. Let us detail the selection mechanism used in Tezos. -.. _random_seed_s023: +.. _random_seed_seoul: Random seed ^^^^^^^^^^^ @@ -141,8 +141,8 @@ values in the protocol, in particular for selecting delegates to participate in For more information on randomness generation, see :doc:`randomness-generation`. -.. _rights_s023: -.. _slots_s023: +.. _rights_seoul: +.. _slots_seoul: Slot selection ^^^^^^^^^^^^^^ @@ -154,7 +154,7 @@ using `Vose's algorithm (see also `this more pedagogic description `_; the algorithm is the last one listed there). This algorithm samples from a discrete probability distribution, which is given by -the :ref:`stakes` of a specific cycle: the probability to sample a +the :ref:`stakes` of a specific cycle: the probability to sample a particular delegate is its stake in the cycle over the total stake in that cycle. @@ -169,11 +169,11 @@ the mentioned algorithm is invoked to assign a delegate to the given slot. Its input is the probability distribution given by the stakes retained for the cycle to which the level belongs. And whenever the algorithm needs to draw a random value, this is obtained using a simple procedure which has as its initial state: the level, the -:ref:`random seed` for the cycle to which the +:ref:`random seed` for the cycle to which the level belongs, and the slot. -.. _ps_constants_s023: +.. _ps_constants_seoul: Proof-of-stake parameters ------------------------- @@ -203,7 +203,7 @@ found in the `whitepaper `_. -The adaptive issuance feature :ref:`documentation `. +The adaptive issuance feature :ref:`documentation `. Other presentations of the Tezos' proof-of-stake mechanism can be found in the diff --git a/docs/seoul/protocol_overview.rst b/docs/seoul/protocol_overview.rst index c201d934688d..59a8ad724853 100644 --- a/docs/seoul/protocol_overview.rst +++ b/docs/seoul/protocol_overview.rst @@ -30,10 +30,10 @@ Validity conditions are implemented in the ``apply`` function which is called whenever the node processes a block---see the dedicated :doc:`protocol validation and operation` entry for further detail into the validation and application process for -:ref:`blocks` and their -:ref:`operations`. +:ref:`blocks` and their +:ref:`operations`. -.. _shell_proto_interact_s023: +.. _shell_proto_interact_seoul: Shell-protocol interaction ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -52,30 +52,30 @@ that the shell uses when receiving a new block: - The shell changes the head of the chain to this new block only if the block is :doc:`valid<../shell/validation>`, and it has a higher fitness than the current head; a block is - :ref:`valid` only if all the + :ref:`valid` only if all the operations included are also - :ref:`valid`. + :ref:`valid`. The support provided by the protocol for validating blocks can be modulated by different :ref:`validation -modes`. They allow using this same +modes`. They allow using this same interface for quite different use cases, as follows: -- being able to :ref:`apply` a block, +- being able to :ref:`apply` a block, typically used by the shell's :doc:`validator <../shell/validation>` component; -- being able to :ref:`construct` a block, +- being able to :ref:`construct` a block, typically used by the baker daemon to *bake* -- that is, to produce -- a new block; -- being able to :ref:`partially construct` +- being able to :ref:`partially construct` a block, typically used by the :doc:`prevalidator <../shell/prevalidation>` to determine valid operations in the mempool; and, -- being able to :ref:`pre-apply` a +- being able to :ref:`pre-apply` a block, typically used in the :doc:`validator <../shell/validation>` to precheck a block, avoiding to further consider invalid blocks. -.. _block_contents_s023: +.. _block_contents_seoul: Blocks, Operations and their Validation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -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 @@ -101,7 +101,7 @@ safely included in the Tezos blockchain -- and *application* -- that is, how the effects of operations and blocks are taken into account -- for this economic protocol. -.. _protocol_constants_s023: +.. _protocol_constants_seoul: Protocol constants ~~~~~~~~~~~~~~~~~~ @@ -150,10 +150,10 @@ The *values* of protocol constants in any given protocol can be found using spec Further documentation of various protocol constants can be found in the subsystems where they conceptually belong. See, for example: -- :ref:`proof-of-stake parameters ` -- :ref:`consensus-related parameters ` -- :ref:`randomness generation parameters ` -- :ref:`DAL parameters ` +- :ref:`proof-of-stake parameters ` +- :ref:`consensus-related parameters ` +- :ref:`randomness generation parameters ` +- :ref:`DAL parameters ` See also ~~~~~~~~ diff --git a/docs/seoul/randomness_generation.rst b/docs/seoul/randomness_generation.rst index 9baa7821734e..77c151c57734 100644 --- a/docs/seoul/randomness_generation.rst +++ b/docs/seoul/randomness_generation.rst @@ -46,7 +46,7 @@ if a malicious participant can make sure she is the last revealer, then she can choose whether to reveal its committed value, effectively choosing between two different predetermined seeds. -.. _vdf_s023: +.. _vdf_seoul: Verifiable Delay Function ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -77,7 +77,7 @@ cheaper and based on a weaker security assumption (low order assumption). Protocol -------- -.. _randomness_generation_s023: +.. _randomness_generation_seoul: Randomness generation overview ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -114,7 +114,7 @@ iterated revealed nonce. A *nonce revelation* is an operation and multiple nonce revelations can thus be included in a block. A reward ``seed_nonce_revelation_tip``, :ref:`potentially adjusted -by the adaptive issuance coefficient ` +by the adaptive issuance coefficient ` and weighted by constant ``SEED_NONCE_REVELATION_TIP_WEIGHT``, is given for including a revelation. Revelations are free operations which do not compete with transactions for block space. Up to ``MAX_ANON_OPS_PER_BLOCK`` revelations, @@ -138,11 +138,11 @@ solution. A *VDF revelation* is an operation. A reward ``seed_nonce_revelation_tip`` :ref:`potentially adjusted by the adaptive issuance coefficient -` and weighted by constant ``SEED_NONCE_REVELATION_TIP_WEIGHT``, +` and weighted by constant ``SEED_NONCE_REVELATION_TIP_WEIGHT``, is given for the first correct VDF revelation, subsequent VDF revelation operations being discarded. -.. _rg_constants_s023: +.. _rg_constants_seoul: Randomness generation parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/seoul/smart_rollups.rst b/docs/seoul/smart_rollups.rst index fecfabe7439e..a46208bfb8d5 100644 --- a/docs/seoul/smart_rollups.rst +++ b/docs/seoul/smart_rollups.rst @@ -143,7 +143,7 @@ the Layer 1 pushes one final internal message “End of level”. Similarly to “Start of level“, this internal message does not come with any payload. -.. _reveal_data_channel_smart_rollups_s023: +.. _reveal_data_channel_smart_rollups_seoul: Reveal data channel """"""""""""""""""" @@ -179,7 +179,7 @@ A smart rollup is characterized by: - the Michelson type of the entrypoint used by Layer 1 smart contracts to send internal messages to it, and - an optional list of addresses used as a white-list of allowed -committers (see :ref:`private_rollups_s023`). +committers (see :ref:`private_rollups_seoul`). All these characteristics are provided when originating a new smart rollup. @@ -207,7 +207,7 @@ implements the exact same semantics as the PVM. The PVM is only ever used by the rollup node when it needs to produce a proof during the last step of the refutation mechanism. -.. _commitments_s023: +.. _commitments_seoul: Commitments ^^^^^^^^^^^ @@ -238,7 +238,7 @@ must be wrong. An operator publishing a commitment is called a **committer**. Notice that, in order to publish a commitment, the operator must freeze a -deposit of 10,000 tez, called :ref:`**frozen bonds**`. For this reason, the +deposit of 10,000 tez, called :ref:`**frozen bonds**`. For this reason, the committer is sometimes called a (smart rollup) *staker*. However, in order to avoid confusion with the :doc:`staker` role in Tezos Layer 1's Proof-of-Stake mechanism, we prefer to use the term "committer" throughout this documentation. @@ -276,9 +276,9 @@ to avoid type confusion: namely, a kernel transferring a tuple that the Layer 1 interprets as a ticket. Lastly, the outbox message can contain a white-list update. This message can only be executed for a rollup that is private since its origination (see -:ref:`private_rollups_s023`). +:ref:`private_rollups_seoul`). -.. _bonds_s023: +.. _bonds_seoul: Bonds ^^^^^ @@ -346,7 +346,7 @@ published a concurrent commitment. However, assuming the existence of an honest participant *H*, then *H* will start the refutation game with all concurrent committers to avoid the rollup getting stuck. -.. _private_rollups_s023: +.. _private_rollups_seoul: Private rollups ^^^^^^^^^^^^^^^ diff --git a/docs/seoul/staking.rst b/docs/seoul/staking.rst index 696e1483407b..077bd89b5b7f 100644 --- a/docs/seoul/staking.rst +++ b/docs/seoul/staking.rst @@ -11,7 +11,7 @@ Staking mechanism Staking is an evolution of the existing Tezos :doc:`Liquid Proof-of-Stake mechanism `. It introduces a new role for network participants, called **staker**, -complementary to the existing :ref:`delegate ` +complementary to the existing :ref:`delegate ` (also known as *baker*) and *delegator* roles. A staker must also be a *delegator* – that is, they must first choose a delegate. @@ -28,8 +28,8 @@ This ratio is defined by the protocol constant ``EDGE_OF_STAKING_OVER_DELEGATION Unlike delegated funds, staked funds are considered to contribute to the security deposit associated with their chosen delegate. Thus, they are -subject to :ref:`slashing ` if -the delegate misbehaves by :ref:`double-signing ` +subject to :ref:`slashing ` if +the delegate misbehaves by :ref:`double-signing ` block proposals or consensus operations, and are subject to the same withdrawal delays – colloquially, they are "frozen". @@ -43,14 +43,14 @@ slashed funds. The chosen value prevents adversarial delegates from abusing the slashing mechanism for profit at the expense of their stakers. -:ref:`Participation rewards ` are automatically shared +:ref:`Participation rewards ` are automatically shared between delegates and their stakers. Staker's rewards are proportional to their participation in the delegate's total staked at the time the rewards are given. This means that the staker gets rewards for staked tez as soon as they are staked, and stops receiving rewards as soon as the tez are unstaked, disregarding the fact that baking rights for the delegate are computed with some delays. *Delegates* :ref:`configure their staking -policy ` by setting staking parameters +policy ` by setting staking parameters which regulate whether they accept stakers (the default being to reject them), and if so, up to which fraction of their total staking balance. They can also configure which proportion of the staking rewards from other stakers is set @@ -62,16 +62,16 @@ stakers. This entails that staked funds are frozen until manually unfrozen by stakers. This is a two step process which spans for at least ``UNSTAKE_FINALIZATION_DELAY`` cycles (cf. :ref:`Staked funds -management `). +management `). -.. _pseudo_operations_s023: +.. _pseudo_operations_seoul: A user interface is provided for delegates and stakers to interact with the mechanism. It is based on four *pseudo-operations*: ``stake``, ``unstake``, ``finalize_unstake``, and ``set_delegate_parameters``. Pseudo-operations are self-transfers: a transfer operation where the destination matches the source – each involving a special entry-point of -the same name introduced for :ref:`user accounts `. +the same name introduced for :ref:`user accounts `. This approach was chosen to minimize the work required by wallets, custodians, exchanges, and other parties to support the functionality. @@ -79,7 +79,7 @@ custodians, exchanges, and other parties to support the functionality. stakers. In other words, smart contracts cannot stake funds (they can of course still delegate them). -.. _staking_policy_configuration_s023: +.. _staking_policy_configuration_seoul: Staking policy configuration ---------------------------- @@ -136,7 +136,7 @@ stake) nor its consequence on voting and baking powers. That is, overdelegated funds are not counted towards a delegate baking power, but they do increase their voting power. -.. _staked_funds_management_s023: +.. _staked_funds_management_seoul: Staked funds management ----------------------- @@ -192,7 +192,7 @@ a.k.a. **unfinalizable**. After ``UNSTAKE_FINALIZATION_DELAY + 1`` cycles (more precisely, after the cycle in which the unstake was requested has ended and then -another :ref:`UNSTAKE_FINALIZATION_DELAY` full +another :ref:`UNSTAKE_FINALIZATION_DELAY` full cycles have passed), unstaked frozen tokens are no longer considered at stake nor slashable. They are said then to be both **unstaked** and **finalizable**. diff --git a/docs/seoul/validation.rst b/docs/seoul/validation.rst index d8e925ebb5c5..9fefc84f4020 100644 --- a/docs/seoul/validation.rst +++ b/docs/seoul/validation.rst @@ -30,7 +30,7 @@ From a higher-level, *abstract* perspective, the validation system in the Tezos protocol implements this business logic in a functional, state-passing machine where: -- Its state is given by the :ref:`context`, the internal +- Its state is given by the :ref:`context`, the internal representation of the state of the Tezos ledger at a given blockchain level. For instance, the context contains the information of all activated accounts and contracts, and their balances. More @@ -60,7 +60,7 @@ does not implement this business logic *monolithically*, as described above, but it rather presents a more fine-grained API. The rationale is to provide specialized variations of the core *validation* and *application* functionality, dubbed :ref:`Validation -modes`. For example, these modes enable the +modes`. For example, these modes enable the protocol to distinguish operations "in the mempool", whose validation is triggered by the :doc:`prevalidator<../shell/prevalidation>`, from operations included in newly received blocks, whose validation is @@ -79,7 +79,7 @@ the different validation modes implemented by this Tezos economic protocol, and then we delve deeper into the particulars of validation and application for blocks and the operations supported. -.. _validation_modes_s023: +.. _validation_modes_seoul: Validation modes ================ @@ -93,7 +93,7 @@ specified by the protocol environment offers an entry point so that protocol-agnostic components, the Tezos shell for instance, are able to use these different modes. -.. _full_application_s023: +.. _full_application_seoul: Full Application ~~~~~~~~~~~~~~~~ @@ -108,7 +108,7 @@ signature is correct, and **all** operations included in the block are valid; the correct amount of consensus operations have been included in order to satisfy the consensus' threshold, etc. -.. _full_construction_s023: +.. _full_construction_seoul: Full Construction ~~~~~~~~~~~~~~~~~ @@ -126,7 +126,7 @@ construction is finalized. In Octez, this mode is mainly used by the baker daemon. -.. _partial_construction_s023: +.. _partial_construction_seoul: Partial Construction ~~~~~~~~~~~~~~~~~~~~ @@ -142,7 +142,7 @@ potential validity of operations (and whether they can safely included into a block), so that the latter can **classify** incoming operations, and further decide how to process them accordingly. -.. _protocol_classification_s023: +.. _protocol_classification_seoul: The protocol provides the shell with the following classification of an operation, consisting of one valid kind -- ``Applied`` --, and @@ -176,7 +176,7 @@ protocol environment: case of an attestation which was received *too late*, but that could still be used to form a consensus quorum. -.. _partial_application_s023: +.. _partial_application_seoul: Partial Application ~~~~~~~~~~~~~~~~~~~ @@ -205,7 +205,7 @@ application`` mode provides an over-approximation of the branch's validity, and as a result intermediate results are not committed on disk in order to prevent potential attacks. -.. _block_validation_overview_s023: +.. _block_validation_overview_seoul: Block Validation ================ @@ -222,20 +222,20 @@ The first step in the process is to decide whether a candidate block is *well-formed*, that is, that it has the expected "shape" of a valid block under the current Tezos economic protocol. Given a block candidate, the block validation process will then verify that the -candidate block declares consistent :ref:`level`, -:ref:`round`, and timestamp values; that it carries a valid +candidate block declares consistent :ref:`level`, +:ref:`round`, and timestamp values; that it carries a valid signature, etc. At this step, the block validation process will also initialize the data-structures required for subsequent steps. The second step iterates over the block's operations and proceeds to apply them sequentially. When at least one operation is found to be invalid, under the conditions described in -:ref:`operation_validity_s023` further below, the whole block is +:ref:`operation_validity_seoul` further below, the whole block is 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, +constitute a sufficiently large :ref:`quorum`. That is, it will verify that the total attesting power present in the block is greater than the ``CONSENSUS_THRESHOLD`` constant. @@ -245,14 +245,14 @@ candidate block. The shell may decide to commit this context to disk. The Tezos economic protocol also offers a cheap (read "faster") alternative to determine an over-approximation of the validity of a -block (see :ref:`partial_application_s023` above). This feature +block (see :ref:`partial_application_seoul` above). This feature allows the shell to propagate blocks faster without needing to fully validate them, speeding-up block propagation over the network. Of course, as this is an over-approximation, this feature cannot be considered to provide a safe guarantee that a block will be valid: in particular, it does not validate all kinds of operations. -.. _operation_validity_s023: +.. _operation_validity_seoul: Operation Validation and Application ==================================== @@ -279,7 +279,7 @@ application process for each of the different validation passes. Expand validity and application for other validation classes. -.. _manager_operations_validity_s023: +.. _manager_operations_validity_seoul: Validity of operations ~~~~~~~~~~~~~~~~~~~~~~ @@ -302,7 +302,7 @@ suitable for inclusion in a block. Validity of Individual Manager Operations ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:ref:`Manager operations` are a class of +:ref:`Manager operations` are a class of operations, issued by a single *manager* account which signs the operation and pays their fees. The different manager operation kinds share several common fields: @@ -338,7 +338,7 @@ conditions hold: Validity of Manager Operation Batches ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -A :ref:`batch` of manager operations +A :ref:`batch` of manager operations includes one or more manager operations for sequential and atomic execution. The atomicity property imposes that the validity of a batch should entail the validity of each individual operation in the batch, @@ -365,7 +365,7 @@ defined as the conjunction of the following conditions: solvent to pay the announced fees for all the operations in the batch. -.. _co-valid_operations_s023: +.. _co-valid_operations_seoul: Co-valid operations ^^^^^^^^^^^^^^^^^^^ @@ -393,7 +393,7 @@ operations is co-valid. In this case, the operations could be included in the next block in any order, modulo block limits (eg. maximum gas, block size limit, etc). -.. _manager_operations_application_s023: +.. _manager_operations_application_seoul: Application of Manager Operations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/seoul/voting.rst b/docs/seoul/voting.rst index f4f738f6e5f7..9c5e285167ea 100644 --- a/docs/seoul/voting.rst +++ b/docs/seoul/voting.rst @@ -35,7 +35,7 @@ The five periods are as follows: At the end of a **proposal period**, if participation reaches a :ref:`proposal quorum `, the proposal with most support is selected and we move to an **exploration period**. Note that support is - measured in the :ref:`voting power ` that delegates supporting the + measured in the :ref:`voting power ` that delegates supporting the proposal have. E.g., a proposal supported by a single delegate with 600,000 tz of voting power has more support than a proposal supported by two delegates with 100,000 tz each of voting power. @@ -110,7 +110,7 @@ might be introduced, a different selection mechanism may be used, the quorum requirement might differ, etc. -.. _voting_power_s023: +.. _voting_power_seoul: Voting Power ------------ @@ -121,8 +121,8 @@ all its delegators (including the delegate itself of course), no matter whether they are :doc:`staked` or not. More precisely, the voting power of a delegate during a voting period -is the sum of its :ref:`total_staked` and -:ref:`total_delegated` amounts, measured in +is the sum of its :ref:`total_staked` and +:ref:`total_delegated` amounts, measured in *mutez*, and snapshotted at the beginning of the voting period. (Note the differences from the validator selection for consensus, which is based on the more complex :doc:`baking power` instead, @@ -352,7 +352,7 @@ Further details and explanations on the voting procedure can be found at: - `Tezos Governance `_ on Tezos Agora. For more details on the client commands refer to the manual at -:ref:`client_manual_s023`. +:ref:`client_manual_seoul`. For vote related RPCs check the :doc:`rpc` under the prefix ``votes/``. -- GitLab From f1ccead5fda24de48f62ee85b4db751f5061a0ba Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Thu, 10 Jul 2025 15:21:59 +0200 Subject: [PATCH 3/4] doc: continue series of proto names --- docs/protocols/naming.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/protocols/naming.rst b/docs/protocols/naming.rst index 78227fd94fee..d786877525db 100644 --- a/docs/protocols/naming.rst +++ b/docs/protocols/naming.rst @@ -42,8 +42,10 @@ sequence: * 016 Mumbai * 017 Nairobi * 018 Oxford -* 019 Paris -* 020 Quebec +* 019 ParisB +* 020 ParisC +* 021 Quebec +* 022 Rio * ... Due to the evolving nature of the in-use protocols, the above absolute protocol -- GitLab From b6542df7416d85945e7ffe304c6eb5c2e83b66ba Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Thu, 10 Jul 2025 16:43:54 +0200 Subject: [PATCH 4/4] fix last occurences of s023 --- docs/protocols/alpha.rst | 2 +- docs/seoul/rpc.rst | 16 ++++++++++++---- 2 files changed, 13 insertions(+), 5 deletions(-) diff --git a/docs/protocols/alpha.rst b/docs/protocols/alpha.rst index 438797258343..ff806f329b7b 100644 --- a/docs/protocols/alpha.rst +++ b/docs/protocols/alpha.rst @@ -2,7 +2,7 @@ Protocol Alpha ============== This page documents the changes brought by protocol Alpha with respect -to S023 (see :ref:`naming_convention`). +to Seoul (see :ref:`naming_convention`). For changes brought by Quebec with respect to Paris, see :doc:`../protocols/021_quebec`. diff --git a/docs/seoul/rpc.rst b/docs/seoul/rpc.rst index dbcbf89d778c..642bcc346ac5 100644 --- a/docs/seoul/rpc.rst +++ b/docs/seoul/rpc.rst @@ -78,10 +78,10 @@ -.. _rpc_index_s023 : +.. _rpc_index_seoul : -S023 RPCs - Reference -##################### +Seoul RPCs - Reference +###################### .. include:: /include/rpc_introduction.rst.inc @@ -14922,7 +14922,11 @@ Full description { "balance": $023-PtSeouLo.mutez, "delegate"?: $Signature.Public_key_hash, "script"?: $023-PtSeouLo.scripted.contracts, - "counter"?: $positive_bignum } + "counter"?: $positive_bignum, + "revealed"?: + boolean + /* field present for implicit account only: true means the manager pk + has been revealed */ } $023-PtSeouLo.mutez: $positive_bignum $023-PtSeouLo.scripted.contracts: { "code": any, "storage": any } @@ -14959,6 +14963,10 @@ Full description +--------------------------------+----------------------+-------------------------------------+ | counter | Determined from data | $N.t | +--------------------------------+----------------------+-------------------------------------+ + | ? presence of field "revealed" | 1 byte | boolean (0 for false, 255 for true) | + +--------------------------------+----------------------+-------------------------------------+ + | revealed | 1 byte | boolean (0 for false, 255 for true) | + +--------------------------------+----------------------+-------------------------------------+ N.t -- GitLab