From e02eeaedd6e1a831222ef75516bedaa4d3ac19df Mon Sep 17 00:00:00 2001 From: Marina Polubelova Date: Wed, 17 Jul 2024 16:59:45 +0200 Subject: [PATCH 1/5] Docs/Proto: remove -new suffix from picture names --- ...ive-slashing-new.jpeg => adaptive-slashing.jpeg} | Bin docs/alpha/adaptive_issuance.rst | 2 +- docs/alpha/adaptive_slashing.rst | 2 +- docs/alpha/{ai-min-max-new.jpeg => ai-min-max.jpeg} | Bin 4 files changed, 2 insertions(+), 2 deletions(-) rename docs/alpha/{adaptive-slashing-new.jpeg => adaptive-slashing.jpeg} (100%) rename docs/alpha/{ai-min-max-new.jpeg => ai-min-max.jpeg} (100%) diff --git a/docs/alpha/adaptive-slashing-new.jpeg b/docs/alpha/adaptive-slashing.jpeg similarity index 100% rename from docs/alpha/adaptive-slashing-new.jpeg rename to docs/alpha/adaptive-slashing.jpeg diff --git a/docs/alpha/adaptive_issuance.rst b/docs/alpha/adaptive_issuance.rst index c08dc004bbb1..7c3546af37b0 100644 --- a/docs/alpha/adaptive_issuance.rst +++ b/docs/alpha/adaptive_issuance.rst @@ -166,7 +166,7 @@ The following figure describes the progressive maximum and minimum values of Adaptive Issuance. -.. figure:: ai-min-max-new.jpeg +.. figure:: ai-min-max.jpeg Figure 1. A gradual widening of the range ensures a smooth transition to Adaptive Issuance. diff --git a/docs/alpha/adaptive_slashing.rst b/docs/alpha/adaptive_slashing.rst index dc52debfc675..031f80867b6a 100644 --- a/docs/alpha/adaptive_slashing.rst +++ b/docs/alpha/adaptive_slashing.rst @@ -44,7 +44,7 @@ attestations in a block. The shape of the slashing function for double attestations is the following: -.. figure:: adaptive-slashing-new.jpeg +.. figure:: adaptive-slashing.jpeg +------------------------------------------+----------------------------------------+ diff --git a/docs/alpha/ai-min-max-new.jpeg b/docs/alpha/ai-min-max.jpeg similarity index 100% rename from docs/alpha/ai-min-max-new.jpeg rename to docs/alpha/ai-min-max.jpeg -- GitLab From 2485ba6822c53f27dcf0e15ca5793f0d80d23ee2 Mon Sep 17 00:00:00 2001 From: Marina Polubelova Date: Wed, 17 Jul 2024 17:45:12 +0200 Subject: [PATCH 2/5] Docs/AI: remove math commands --- docs/alpha/adaptive_issuance.rst | 21 --------------------- 1 file changed, 21 deletions(-) diff --git a/docs/alpha/adaptive_issuance.rst b/docs/alpha/adaptive_issuance.rst index 7c3546af37b0..4f45b1228cdc 100644 --- a/docs/alpha/adaptive_issuance.rst +++ b/docs/alpha/adaptive_issuance.rst @@ -1,27 +1,6 @@ :math:`\newcommand\F[2]{\mathit{#1}\left(#2\right)}` -:math:`\newcommand{\minR}{\mathit{min_r}}` -:math:`\newcommand{\maxR}{\mathit{max_r}}` -:math:`\newcommand{\tmult}{\cdot}` -:math:`\newcommand\static[1]{\F{static}{#1}}` -:math:`\newcommand{\sfr}{\frac{1}{1600}}` :math:`\newcommand\tc{\tau_c}` -:math:`\newcommand\tr{\tau_r}` :math:`\newcommand\grf{\gamma}` -:math:`\newcommand\dyn[1]{\F{dyn}{#1}}` -:math:`\newcommand\sgn[1]{\F{sign}{#1}}` -:math:`\newcommand\dist[1]{\F{distance}{#1}}` -:math:`\newcommand\DTF{{\Delta t}}` :math:`\newcommand\IL[1]{\normalsize{#1}}` -:math:`\newcommand\MX[2]{\F{max}{#1,#2}}` -:math:`\newcommand\adr[1]{\F{adaptive}{#1}}` -:math:`\newcommand\clip[3]{\F{clip}{#1,#2,#3}}` -:math:`\newcommand\supply[1]{\F{supply}{#1}}` -:math:`\newcommand\iss[1]{\F{issuance}{#1}}` -:math:`\newcommand\isb[1]{\F{issuance_{block}}{#1}}` -:math:`\newcommand\tw{\Sigma_w}` -:math:`\newcommand\rw[2]{\F{reward_{#1}}{#2}}` -:math:`\newcommand\tip[2]{\F{tip_{#1}}{#2}}` :math:`\newcommand\exp[1]{\F{exp}{#1}}` -:math:`\newcommand{\vdf}{\mathit{VDF}}` - ============================= Adaptive Issuance and Staking -- GitLab From 3b4ae3ba2f8518b40722d7aa05c7f6770b770e00 Mon Sep 17 00:00:00 2001 From: Marina Polubelova Date: Wed, 17 Jul 2024 18:21:09 +0200 Subject: [PATCH 3/5] Docs/AI: remove section on Activation of AI and Staking --- docs/alpha/adaptive_issuance.rst | 73 ++++++-------------------------- docs/alpha/consensus.rst | 5 +-- docs/releases/version-18.rst | 4 +- 3 files changed, 17 insertions(+), 65 deletions(-) diff --git a/docs/alpha/adaptive_issuance.rst b/docs/alpha/adaptive_issuance.rst index 4f45b1228cdc..5c7114e4953b 100644 --- a/docs/alpha/adaptive_issuance.rst +++ b/docs/alpha/adaptive_issuance.rst @@ -109,8 +109,6 @@ The **dynamic reward rate** adjusts itself over time based on the distance betwe .. code-block:: python def dynamic_rate(cycle): - if cycle <= ai_activation_cycle: - return 0 seconds_per_cycle = blocks_per_cycle * minimal_block_delay days_per_cycle = seconds_per_cycle / 86400 previous_dynamic = dynamic_rate(cycle - 1) @@ -181,8 +179,7 @@ and can be generally defined as follows: Where: - ``ai_activation_cycle`` is the first cycle with Adaptive Issuance - active, that is, :ref:`5 cycles after the activation of the Paris - protocol`. + active, which was cycle 748 on mainnet. - ``initial_period`` is a predefined period of time, set to 1 month in Paris. - ``transition_period`` is a predefined period of time, set to 5 months in Paris. @@ -196,8 +193,7 @@ The issuance minimum rate for Adaptive Issuance curve is then defined as follows Where: - ``issuance_initial_min`` (4.5%) is the initial minimum - value. At the time of :ref:`Adaptive Issuance - activation`, the issuance rate is kept + value. The issuance rate is kept above this bound for the initial period. - ``issuance_global_min`` (0.25%) is the final value for the lower bound, reached at the end of the transition period. @@ -212,8 +208,7 @@ The issuance maximum rate for Adaptive Issuance curve is then defined as follows Where: - ``issuance_initial_max`` (5.5%) controls the initial maximum - value. At the time of :ref:`Adaptive Issuance - activation`, the issuance rate is kept + value. The issuance rate is kept 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. @@ -279,8 +274,8 @@ Finally, as mentioned before, the nominal adaptive issuance rate [1]_ for a cycl Adaptive rewards ---------------- -Before :ref:`Adaptive Issuance activation`, -participation rewards are fixed values defined by protocol +Before Adaptive Issuance activation, +participation rewards were fixed values defined by protocol 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, @@ -316,8 +311,6 @@ The coefficient to apply for reward computation is defined as follows. .. code-block:: python def reward_coeff(cycle): - if cycle < ai_activation_cycle: - return 1 rate = issuance_rate(cycle) total_supply = total_supply(cycle - consensus_rights_delay - 1) return (rate / 525600) * total_supply / base_total_issued_per_minute @@ -453,13 +446,12 @@ automatically shared between delegates and their stakers, delegates can use this parameter to collect an *edge* from the rewards attributable to their stakers. -After :ref:`the activation of Adaptive Issuance and -Staking`, freezing and unfreezing of staked -funds -will be controlled directly by delegates and stakers, and will no longer -be automatic. This entails that staked funds are frozen until manually -unfrozen by stakers. This is a two step process which spans for at least -4 cycles (cf. :ref:`Staked funds management `). +Since the activation of Adaptive Issuance in the Paris protocol, +freezing and unfreezing of staked funds are controlled directly by +delegates and stakers, and are no longer automatic. This entails +that staked funds are frozen until manually unfrozen by stakers. This +is a two step process which spans for at least 4 cycles +(cf. :ref:`Staked funds management `). A new user interface is provided for delegates and stakers to interact with the mechanism. It is based on four *pseudo-operations*: ``stake``, @@ -470,12 +462,9 @@ 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. -**NB** Until :ref:`the activation of Adaptive Issuance and Staking -`, only -*delegates* can stake funds and the relative weight of staked and -delegated funds remains unchanged. In the current implementation, only -*user accounts* can become stakers. In other words, smart contracts -cannot stake funds (they can of course still delegate them). +**NB** In the current implementation, only *user accounts* can become +stakers. In other words, smart contracts cannot stake funds (they can +of course still delegate them). .. _staking_policy_configuration_alpha: @@ -593,40 +582,6 @@ balance of the account is accounted in the new delegate's stake. It will not be possible to stake with the new delegate as long as there are unfinalizable unstake request for token staked with the old delegate. -.. _feature_activation_alpha: - -Activation of Adaptive Issuance and Staking -=========================================== - -The Adaptive Issuance and Staking features will not be active -immediately at the start of the Paris protocol. Instead, Adaptive -Issuance and Staking will be automatically activated **5 cycles, that -is, around 2 weeks** after the activation of Paris, in order to give -the community enough time to get ready for these features. - -Here is the list of features and related changes that will only become -active 5 cycles into the Paris protocol: - -- Adaptive issuance – including notably the changes to the computation - of consensus rewards. -- Ability for *delegators* to become *stakers* – until feature - activation delegates continue to be the only participants who can - **stake** funds. -- The changes in weight for staked and delegated funds towards the - computation of baking and voting rights. -- The new interface for stake manipulation based on - *pseudo-operations*. Note that this entails the deprecation of the - ``set/unset deposits limit`` interface and also the end of automatic - deposit freezing. On protocol activation, each delegate’s stake is - derived from the frozen deposits at the end of the last cycle of - Nairobi. -- The changes in slashing penalties (double-baking penalties are set to - 5% of the staked funds) and denunciation rewards (they amount to one - seventh of slashed funds). -- Changes to protocol constants. Note that this entails calculating - participation rewards using the weight-based - formulas, but these are defined so that they match the previous - values when :ref:`Adaptive Issuance ` is not active. .. [1] Note that if the nominal annual issuance rate is :math:`r`, the diff --git a/docs/alpha/consensus.rst b/docs/alpha/consensus.rst index 2020eeb5a4d7..30f7d1af80a4 100644 --- a/docs/alpha/consensus.rst +++ b/docs/alpha/consensus.rst @@ -156,10 +156,7 @@ Let us first (re)define these and related concepts. the case that the delegate behaves badly, its staked balance is partly :ref:`slashed`. This staked balance must be at least ``MINIMAL_FROZEN_STAKE`` tez, otherwise the delegate cannot - be selected as a validator. Note that until the :ref:`activation of - Adaptive Issuance and Staking`, the - staked balance is automatically updated at the end of each cycle to - maximize the active stake. + be selected as a validator. - The *spendable balance* of a delegate is its full balance minus its staked balance and unstaked frozen balance. diff --git a/docs/releases/version-18.rst b/docs/releases/version-18.rst index 784924fc3a43..92e4ad5ca4a3 100644 --- a/docs/releases/version-18.rst +++ b/docs/releases/version-18.rst @@ -28,7 +28,7 @@ Octez version 18 improves performance, notably to the block validation process: v18 also fixes a concurrency issue in the logging infrastructure which can cause the node to become temporarily unresponsive. -As Oxford includes a new Staking mechanism, version 18 of Octez implements new client commands for stake funds management, and to allow delegates to configure their staking policies. See :ref:`Adaptive Issuance and Staking ` for more details. +As Oxford includes a new Staking mechanism, version 18 of Octez implements new client commands for stake funds management, and to allow delegates to configure their staking policies. See :ref:`Adaptive Issuance and Staking ` for more details. Version 18.1 fixes an issue that would result in corrupted full and rolling snapshots being exported. Thus, the snapshots version is bumped from ``6`` to ``7``. @@ -52,7 +52,7 @@ Instead, these are guarded behind a *single* per-block vote mechanism, where bak Specifically, the Octez v18.0 Oxford baker executable introduces a dedicated option ``--adaptive-issuance-vote``, to allow bakers to manifest their choice. The use of this flag is *optional*, and defaults to **Pass** if not present. -See :ref:`here ` for further details on this additional activation vote mechanism. +See :ref:`here ` for further details on this additional activation vote mechanism. Update Instructions -- GitLab From cd52b40f29bfecd687865a7e0b91ee2702113c4e Mon Sep 17 00:00:00 2001 From: Marina Polubelova Date: Wed, 17 Jul 2024 18:56:39 +0200 Subject: [PATCH 4/5] Docs/AI: split adaptive_issuance file into two files --- docs/alpha/adaptive_issuance.rst | 196 +------------------------------ docs/alpha/protocol.rst | 5 + docs/alpha/staking.rst | 190 ++++++++++++++++++++++++++++++ 3 files changed, 196 insertions(+), 195 deletions(-) create mode 100644 docs/alpha/staking.rst diff --git a/docs/alpha/adaptive_issuance.rst b/docs/alpha/adaptive_issuance.rst index 5c7114e4953b..3f43d9da6ea0 100644 --- a/docs/alpha/adaptive_issuance.rst +++ b/docs/alpha/adaptive_issuance.rst @@ -2,18 +2,10 @@ :math:`\newcommand\IL[1]{\normalsize{#1}}` :math:`\newcommand\exp[1]{\F{exp}{#1}}` -============================= -Adaptive Issuance and Staking -============================= - -This document describes Adaptive Issuance and Staking, two new features (referred hereafter as the Adaptive-Issuance/Staking proposal) which together constitute a major evolution of Tezos’ :doc:`Proof-of-Stake mechanism `. - -.. note:: - - For operational details about the new staking mechanism and its configuration, see `a new staking mechanism tutorial `__. .. _adaptive_issuance_alpha: +================= Adaptive Issuance ================= @@ -396,192 +388,6 @@ endpoint `. It -introduces a new role for network participants, called **staker**, -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. - -When stakers **stake** funds towards a delegate’s **staking** -**balance**, the associated **baking** and **voting powers** accrue to -that delegate. Similarly to how delegated funds work, staked funds -remain within the staker’s account at all times. - -Staked and delegated funds **have different weights** in the computation -of delegates’ baking and voting powers: staked funds (both external -stakes by stakers and the delegate’s own) count **twice** as much as -delegated funds. - -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 ` -block proposals or consensus operations, and are subject to the same -withdrawal delays – colloquially, they are "frozen". - -Stakers are slashed proportionally to their contribution to the -delegate’s staking balance. To simplify slashing, double-baking -penalties are now proportional to staked funds: instead of the previous -fixed sum of 640 tez they are now set to 5% of the delegate’s stake. -Moreover, denunciation rewards (both for double-baking and -double-attestations) are reduced from one half to one seventh of the -slashed funds. The chosen value prevents adversarial delegates from -abusing the slashing mechanism for profit at the expense of their -stakers. - -*Delegates* :ref:`configure their staking -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 -to accrue to their own staked balance instead. -As :ref:`participation rewards ` are -automatically shared between delegates and their -stakers, delegates can use this parameter to collect an *edge* from the -rewards attributable to their stakers. - -Since the activation of Adaptive Issuance in the Paris protocol, -freezing and unfreezing of staked funds are controlled directly by -delegates and stakers, and are no longer automatic. This entails -that staked funds are frozen until manually unfrozen by stakers. This -is a two step process which spans for at least 4 cycles -(cf. :ref:`Staked funds management `). - -A new 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 `. -This approach was chosen to minimize the work required by wallets, -custodians, exchanges, and other parties to support the functionality. - -**NB** In the current implementation, only *user accounts* can become -stakers. In other words, smart contracts cannot stake funds (they can -of course still delegate them). - -.. _staking_policy_configuration_alpha: - -Staking policy configuration ----------------------------- - -*Delegates* can configure their staking policy by setting the following -parameters: - -- ``edge_of_baking_over_staking``: a ratio between 0 and 1, whose - default value is 1. This parameter determines the fraction of the - rewards that accrue to the delegate's frozen deposit – the - remainder is shared among its stakers. -- ``limit_of_staking_over_baking``: a non-negative number, denoting the - maximum portion of external stake by stakers over the delegate’s own - staked funds. It defaults to 0 – which entails that delegates do not - accept external stakes by default. It is moreover capped by a global - constant, set to 5 in the Adaptive-Issuance/Staking proposal, which ensures the baker controls a - significant part of the stake. - -Delegates can modify these staking parameters at all times, using the -``set_delegate_parameters`` pseudo-operation: that is, by transferring 0 -tez to their own ``set_delegate_parameters`` entry-point. The chosen values for both -parameters need to be supplied. The new parameters are then applied -``DELEGATE_PARAMETERS_ACTIVATION_DELAY`` (currently 5) cycles later. - -:: - - octez-client transfer 0 from to --entrypoint set_delegate_parameters --arg "Pair (Pair Unit)" - -or more conveniently:: - - octez-client set delegate parameters for --limit-of-staking-over-baking --edge-of-baking-over-staking - -**On overstaking and overdelegation.** Note that if a delegate’s -``limit_of_staking_over_baking`` is exceeded (that is, the delegate is -*overstaked*), the exceeding stake is automatically considered as -*delegation* for the delegate’s baking and voting power calculation, but -it does remain slashable. The new mechanism does not alter -*overdelegation* (delegated funds beyond 9 times the delegate’s own -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_alpha: - -Staked funds management ------------------------ - -Stakers (and delegates) can use the ``stake``, ``unstake``, and -``finalize_unstake`` pseudo-operations to control their stakes. Figure -2 illustrates their effect on a staker’s funds. Note that -while these pseudo-operations change the *state* of the involved funds, -they remain otherwise within the staker’s account at all times. - -.. figure:: staked_funds_transitions.png - - Figure 3: staked funds management using pseudo-operations. - -To *stake* funds, a delegator uses the ``stake`` pseudo-operation, -transferring the chosen amount of **spendable** tez to their own -``stake`` entry-point. The **staked** tez will then be frozen and -contribute to their chosen delegate’s staking balance. Note that the -``stake`` pseudo-operation will fail if the sender account is not -*delegated*. - -:: - - octez-client transfer from to --entrypoint stake - -or more conveniently:: - - octez-client stake for - -To *unstake* funds, a staker first submits an unstake request with the -``unstake`` pseudo-operation. This is implemented by transferring the -chosen amount in tez to their ``unstake`` entry-point:: - - octez-client transfer from to --entrypoint unstake - -or more conveniently:: - - octez-client unstake for - -The requested amount will be **unstaked** but will remain **frozen**. -After 4 cycles, unstaked frozen tokens are no longer considered at stake -nor slashable. They are said then to be both **unstaked** and -**finalizable**. - -A staker can retrieve all unstaked and finalizable tokens at any time, -making them spendable again. This is done using the ``finalize_unstake`` -entrypoint -– that is, by transferring 0 tez to their -``finalize_unstake`` entry-point:: - - octez-client transfer 0 from to --entrypoint finalize_unstake - -or more conveniently:: - - octez-client finalize unstake for - -In some circumstances, unstake and finalize can be done implicitly: any call -to ``stake`` or ``unstake`` will implicitly finalize all currently finalizable pending -unstake requests. Also, as we will see next, change of delegate triggers an -unstake operation. - -Change of delegate ------------------- - -When a staker changes its delegate, the operation will trigger an implicit unstake -request for the full frozen deposit of the staker. - -As long as the unstake request is not finalized, the frozen tokens will continue -to be delegated to the old delegate, however the spending -balance of the account is accounted in the new delegate's stake. -It will not be possible to stake with the new delegate as long as there are -unfinalizable unstake request for token staked with the old delegate. - .. [1] Note that if the nominal annual issuance rate is :math:`r`, the diff --git a/docs/alpha/protocol.rst b/docs/alpha/protocol.rst index 080d9f0023d5..3742c5845a17 100644 --- a/docs/alpha/protocol.rst +++ b/docs/alpha/protocol.rst @@ -117,6 +117,11 @@ Sapling, etc), and some details about its implementation. adaptive_issuance +.. toctree:: + :maxdepth: 2 + + staking + .. toctree:: :maxdepth: 2 diff --git a/docs/alpha/staking.rst b/docs/alpha/staking.rst new file mode 100644 index 000000000000..d4282f3bada2 --- /dev/null +++ b/docs/alpha/staking.rst @@ -0,0 +1,190 @@ +.. note:: + + For operational details about the staking mechanism and its configuration, see `a staking mechanism tutorial `__. + + +.. _new_staking_alpha: + +================= +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 ` +(also known as *baker*) and *delegator* roles. A staker must also be a +*delegator* – that is, they must first choose a delegate. + +When stakers **stake** funds towards a delegate’s **staking** +**balance**, the associated **baking** and **voting powers** accrue to +that delegate. Similarly to how delegated funds work, staked funds +remain within the staker’s account at all times. + +Staked and delegated funds **have different weights** in the computation +of delegates’ baking and voting powers: staked funds (both external +stakes by stakers and the delegate’s own) count **twice** as much as +delegated funds. + +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 ` +block proposals or consensus operations, and are subject to the same +withdrawal delays – colloquially, they are "frozen". + +Stakers are slashed proportionally to their contribution to the +delegate’s staking balance. To simplify slashing, double-baking +penalties are now proportional to staked funds: instead of the previous +fixed sum of 640 tez they are now set to 5% of the delegate’s stake. +Moreover, denunciation rewards (both for double-baking and +double-attestations) are reduced from one half to one seventh of the +slashed funds. The chosen value prevents adversarial delegates from +abusing the slashing mechanism for profit at the expense of their +stakers. + +*Delegates* :ref:`configure their staking +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 +to accrue to their own staked balance instead. +As :ref:`participation rewards ` are +automatically shared between delegates and their +stakers, delegates can use this parameter to collect an *edge* from the +rewards attributable to their stakers. + +Freezing and unfreezing of staked funds is controlled directly by delegates and +stakers. +This entails that staked funds are frozen until manually +unfrozen by stakers. This is a two step process which spans for at least +4 cycles (cf. :ref:`Staked funds management `). + +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 `. +This approach was chosen to minimize the work required by wallets, +custodians, exchanges, and other parties to support the functionality. + +**NB** In the current implementation, only *user accounts* can become +stakers. In other words, smart contracts cannot stake funds (they can +of course still delegate them). + +.. _staking_policy_configuration_alpha: + +Staking policy configuration +---------------------------- + +*Delegates* can configure their staking policy by setting the following +parameters: + +- ``edge_of_baking_over_staking``: a ratio between 0 and 1, whose + default value is 1. This parameter determines the fraction of the + rewards that accrue to the delegate's frozen deposit – the + remainder is shared among its stakers. +- ``limit_of_staking_over_baking``: a non-negative number, denoting the + maximum portion of external stake by stakers over the delegate’s own + staked funds. It defaults to 0 – which entails that delegates do not + accept external stakes by default. It is moreover capped by a global + constant, set to 5 in the Adaptive-Issuance/Staking proposal, which ensures the baker controls a + significant part of the stake. + +Delegates can modify these staking parameters at all times, using the +``set_delegate_parameters`` pseudo-operation: that is, by transferring 0 +tez to their own ``set_delegate_parameters`` entry-point. The chosen values for both +parameters need to be supplied. The new parameters are then applied +``DELEGATE_PARAMETERS_ACTIVATION_DELAY`` (currently 5) cycles later. + +:: + + octez-client transfer 0 from to --entrypoint set_delegate_parameters --arg "Pair (Pair Unit)" + +or more conveniently:: + + octez-client set delegate parameters for --limit-of-staking-over-baking --edge-of-baking-over-staking + +**On overstaking and overdelegation.** Note that if a delegate’s +``limit_of_staking_over_baking`` is exceeded (that is, the delegate is +*overstaked*), the exceeding stake is automatically considered as +*delegation* for the delegate’s baking and voting power calculation, but +it does remain slashable. The new mechanism does not alter +*overdelegation* (delegated funds beyond 9 times the delegate’s own +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_alpha: + +Staked funds management +----------------------- + +Stakers (and delegates) can use the ``stake``, ``unstake``, and +``finalize_unstake`` pseudo-operations to control their stakes. Figure +1 illustrates their effect on a staker’s funds. Note that +while these pseudo-operations change the *state* of the involved funds, +they remain otherwise within the staker’s account at all times. + +.. figure:: staked_funds_transitions.png + + Figure 1: staked funds management using pseudo-operations. + +To *stake* funds, a delegator uses the ``stake`` pseudo-operation, +transferring the chosen amount of **spendable** tez to their own +``stake`` entry-point. The **staked** tez will then be frozen and +contribute to their chosen delegate’s staking balance. Note that the +``stake`` pseudo-operation will fail if the sender account is not +*delegated*. + +:: + + octez-client transfer from to --entrypoint stake + +or more conveniently:: + + octez-client stake for + +To *unstake* funds, a staker first submits an unstake request with the +``unstake`` pseudo-operation. This is implemented by transferring the +chosen amount in tez to their ``unstake`` entry-point:: + + octez-client transfer from to --entrypoint unstake + +or more conveniently:: + + octez-client unstake for + +The requested amount will be **unstaked** but will remain **frozen**. +After 4 cycles, unstaked frozen tokens are no longer considered at stake +nor slashable. They are said then to be both **unstaked** and +**finalizable**. + +A staker can retrieve all unstaked and finalizable tokens at any time, +making them spendable again. This is done using the ``finalize_unstake`` +entrypoint -– that is, by transferring 0 tez to their +``finalize_unstake`` entry-point:: + + octez-client transfer 0 from to --entrypoint finalize_unstake + +or more conveniently:: + + octez-client finalize unstake for + +In some circumstances, unstake and finalize can be done implicitly: any call +to ``stake`` or ``unstake`` will implicitly finalize all currently finalizable pending +unstake requests. Also, as we will see next, change of delegate triggers an +unstake operation. + +Change of delegate +------------------ + +When a staker changes its delegate, the operation will trigger an implicit unstake +request for the full frozen deposit of the staker. + +As long as the unstake request is not finalized, the frozen tokens will continue +to be delegated to the old delegate, however the spending +balance of the account is accounted in the new delegate's stake. +It will not be possible to stake with the new delegate as long as there are +unfinalizable unstake request for token staked with the old delegate. -- GitLab From a65c23abeeca1b85ac336fbb4054aadc7757a793 Mon Sep 17 00:00:00 2001 From: Marina Polubelova Date: Thu, 18 Jul 2024 11:41:36 +0200 Subject: [PATCH 5/5] Docs/AI: remove mentions of AI/Staking proposal --- docs/alpha/adaptive_issuance.rst | 35 ++++++++++++++++---------------- docs/alpha/staking.rst | 13 ++++++------ 2 files changed, 25 insertions(+), 23 deletions(-) diff --git a/docs/alpha/adaptive_issuance.rst b/docs/alpha/adaptive_issuance.rst index 3f43d9da6ea0..0139e8ab544e 100644 --- a/docs/alpha/adaptive_issuance.rst +++ b/docs/alpha/adaptive_issuance.rst @@ -36,12 +36,12 @@ to encourage participants to stake and produce blocks, but *no more*. 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% in the Adaptive-Issuance/Staking proposal). Participation rewards -are recomputed to match that budget. When the staked -ratio decreases and diverges from the target, emission rates -increase, incentivizing participants to stake funds to re-approach the -target. Conversely, incentives decrease as the ratio increases beyond -the target. +protocol-defined target (set at 50% starting in the Paris +protocol). Participation rewards are recomputed to match that +budget. When the staked ratio decreases and diverges from the target, +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_alpha: @@ -89,7 +89,7 @@ The static rate is defined as follows: def static_rate(cycle): return 1 / 1600 * (1 / (staked_ratio(cycle) ** 2)) -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 current issuance rate (~4.6%). +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_alpha: @@ -143,7 +143,8 @@ values of Adaptive Issuance. The schedule consists of three periods: - an **initial** period, set to 1 month, where the minimum and maximum - issuance rates are close to the current issuance rate and stay + issuance rates are close to the issuance rate from the Oxford + protocol (before the activation of Adaptive Issuance) and stay constant, - a **transition** period, set to 5 months, where they evolve linearly, with a decreasing minimum, and an increasing maximum, and @@ -279,7 +280,7 @@ in proportion to their relative :ref:`weights Reward weights .............. -The Adaptive-Issuance/Staking proposal defines the weights for participation rewards as: +The weights for participation rewards are defined as: - Attestation (formerly, endorsing) rewards: 10,240. - Fixed baking reward: 5,120. @@ -325,10 +326,10 @@ The issuance per block is then distributed amongst the different rewards in prop return tez_from_weights(weight) * reward_coeff(cycle) -**Consensus rewards.** Since the adoption of Tenderbake, Tezos protocols -before the Adaptive-Issuance/Staking proposal have rewarded delegates :doc:`for their participation in -consensus ` -with the following rewards per block: +**Consensus rewards.** Since the adoption of Tenderbake, Tezos +protocols before Paris have rewarded delegates :doc:`for their +participation in consensus ` with the following rewards per +block: - A fixed **baking** reward, given to the delegate which produced the *payload* of the block (i.e. choosing transactions, and other @@ -382,10 +383,10 @@ Where: - ``blocks_per_commitment`` (192) is the interval in blocks between each revelation, both VDF and nonce. -The Adaptive-Issuance/Staking proposal implements a new `RPC -endpoint `__, -``/issuance/expected_issuance``, which reports the precomputed values of -all participation rewards, for the provided block and the next +The `RPC endpoint +`__, +``/issuance/expected_issuance`` reports the precomputed values of all +participation rewards for the provided block and the next ``consensus_rights_delay`` cycles. diff --git a/docs/alpha/staking.rst b/docs/alpha/staking.rst index d4282f3bada2..12113631f53c 100644 --- a/docs/alpha/staking.rst +++ b/docs/alpha/staking.rst @@ -85,12 +85,13 @@ parameters: default value is 1. This parameter determines the fraction of the rewards that accrue to the delegate's frozen deposit – the remainder is shared among its stakers. -- ``limit_of_staking_over_baking``: a non-negative number, denoting the - maximum portion of external stake by stakers over the delegate’s own - staked funds. It defaults to 0 – which entails that delegates do not - accept external stakes by default. It is moreover capped by a global - constant, set to 5 in the Adaptive-Issuance/Staking proposal, which ensures the baker controls a - significant part of the stake. +- ``limit_of_staking_over_baking``: a non-negative number, denoting + the maximum portion of external stake by stakers over the + delegate’s own staked funds. It defaults to 0 – which entails that + delegates do not accept external stakes by default. It is moreover + capped by a global constant, set to 5 starting in the Paris + protocol, which ensures the baker controls a significant part of + the stake. Delegates can modify these staking parameters at all times, using the ``set_delegate_parameters`` pseudo-operation: that is, by transferring 0 -- GitLab