From 872fb326c0bb085d446c7df6cbeaa90ffb27887d Mon Sep 17 00:00:00 2001 From: Eugen Zalinescu Date: Thu, 23 Jan 2025 07:22:50 +0100 Subject: [PATCH 1/4] Docs/Alpha: add doc about the DAL incentives scheme --- docs/alpha/adaptive_issuance.rst | 4 +- docs/alpha/dal_support.rst | 69 ++++++++++++++++++++++++++++++-- 2 files changed, 68 insertions(+), 5 deletions(-) diff --git a/docs/alpha/adaptive_issuance.rst b/docs/alpha/adaptive_issuance.rst index d07c3b154821..12a747f6c268 100644 --- a/docs/alpha/adaptive_issuance.rst +++ b/docs/alpha/adaptive_issuance.rst @@ -328,10 +328,11 @@ The weights for participation rewards are defined as: - Attestation rewards: 10,240. - Fixed baking reward: 5,120. - Bonus baking reward: 5,120. +- DAL rewards: 2,275. - Nonce revelation tip: 1. - VDF tip: 1. -The total sum ``sum_rewards_weight`` of all weights is 20482. +The total sum ``sum_rewards_weight`` of all weights is 22,757. .. code-block:: python @@ -339,6 +340,7 @@ The total sum ``sum_rewards_weight`` of all weights is 20482. attestation_rewards + fixed_baking_rewards + bonus_baking_rewards + + dal_rewards + nonce_revelation_tip + vdf_tip) diff --git a/docs/alpha/dal_support.rst b/docs/alpha/dal_support.rst index 9a3bb9046c5b..18a546e39ec8 100644 --- a/docs/alpha/dal_support.rst +++ b/docs/alpha/dal_support.rst @@ -2,10 +2,13 @@ DAL support =========== -The support for the :doc:`DAL <../shell/dal>` within the economic protocol relies on two operations: +The support for the :doc:`DAL <../shell/dal>` 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 +#. ``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. DAL publish commitment ====================== @@ -54,7 +57,61 @@ In the block’s metadata, there is a specific field for the DAL. This field ref Therefore, for data committed (published) at level ``L``, the slot's availability is determined by the metadata of the block at level ``L + attestation_lag``. Consequently, a smart rollup can only utilize this data from level ``L + attestation_lag + 1`` onward. -Smart rollups integration +.. _DAL_incentives_scheme_alpha: + +DAL incentives scheme +===================== + +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`. + +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. + +Minimal participation +--------------------- + +Any baker that can take part in consensus is eligible for rewards. + +Bakers meeting the minimum participation ratio ``minimal_participation_ratio`` over a cycle, set to 64%, receive rewards for that cycle. + +The participation ratio of the baker is the proportion of slots the baker attested over the total number of slots deemed available by the protocol in the cycle. + +DAL participation rewards +------------------------- + +A fixed percentage, defined by a protocol parameter called ``dal_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 value of ``dal_rewards_weight`` is such that it represents ``dal_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`. +For instance, the stakers' share of these reward is proportional to the weight of their stake in relation to their baker's baking power. + +Trap mechanism +-------------- + +A deterministic function ``trap(pkh, shard)`` returning a boolean flag indicates whether a shard is a trap for a specific baker identified by its public key hash (``pkh``). + +The protocol parameter ``traps_fraction`` controls the fraction of shards marked as traps. + +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 attestation operation containing the wrongly attested slot, the slot index, 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. + +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. + + +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: @@ -75,12 +132,16 @@ 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_alpha` on how to find the values for tests networks): - ``feature_enable`` (true): Whether the DAL is available -- ``incentives_enable`` (false): Whether baker incentives are available +- ``incentives_enable`` (true): Whether baker incentives are available - ``number_of_slots`` (32): How many slots are available per block - ``attestation_lag`` (8): The timeframe for bakers to download shards between the published level of a commitment and the time they must attest the availability of those shards -- ``attestation_threshold`` (66): The percentage of shards attested for a given slot to declare the slot available +- ``attestation_threshold`` (66%): The minimum percentage of shards attested for a given slot to declare the slot available - ``blocks_per_epoch`` (1): Unused. Could be removed in the future - ``page_size`` (3967B, ~4KiB): The size of a page (see :ref:`dal_slots`) - ``slot_size`` (126944B, ~128KiB): The size of a slot (see :ref:`dal_slots`) - ``redundancy_factor`` (8): The erasure-code factor (see :ref:`dal_slots`) - ``number_of_shards`` (512): The number of shards per slot (see :ref:`dal_slots`) +- ``minimal_participation_ratio`` (64%): The minimum percentage of slots attested by a baker during a cycle (among all slots deemed available) that entitles them to rewards +- ``dal_rewards_ratio`` (10%): The ratio of the DAL rewards over the total participation rewards +- ``rewards_weight`` (2275): The weight of the DAL rewards (relative to other participation rewards) +- ``traps_fraction`` (0.0005): The fraction of shards that are traps -- GitLab From 05f611b07428cc01ad72b6b3fec7bab6547fa6f9 Mon Sep 17 00:00:00 2001 From: Eugen Zalinescu Date: Thu, 23 Jan 2025 14:23:53 +0100 Subject: [PATCH 2/4] Docs/Alpha: capitalize parameter names in DAL page --- docs/alpha/dal_support.rst | 49 +++++++++++++++++++------------------- 1 file changed, 24 insertions(+), 25 deletions(-) diff --git a/docs/alpha/dal_support.rst b/docs/alpha/dal_support.rst index 18a546e39ec8..64b3ad95a229 100644 --- a/docs/alpha/dal_support.rst +++ b/docs/alpha/dal_support.rst @@ -15,9 +15,9 @@ DAL publish commitment ``DAL_publish_commitment`` is a manager operation that can be issued by a user wishing to publish data onto the DAL. The payload of this operation consists in the following fields: -- Slot index: Identifies the specific slot for which the data is being published. It is an integer between ``0`` and ``number_of_slots - 1``. +- Slot index: Identifies the specific slot for which the data is being published. It is an integer between ``0`` and ``NUMBER_OF_SLOTS - 1``. - Commitment: The `KZG commitment `__ over the data. -- Commitment proof: A proof that the commitment commits over data that does not exceed the size ``slot_size``. +- Commitment proof: A proof that the commitment commits over data that does not exceed the size ``SLOT_SIZE``. Users can create and manage these commitments and proofs through the :doc:`DAL node <../shell/dal_node>` using these RPCs: @@ -48,14 +48,14 @@ attempt. The least significant bit corresponds to the smallest slot index. Attestation timing ------------------ -When a commitment is published at a certain level, say level ``PL``, the corresponding DAL payloads are expected to be included in the attestations contained in the block at level ``PL + attestation_lag``. +When a commitment is published at a certain level, say level ``n``, the corresponding DAL payloads are expected to be included in the attestations contained in the block at level ``n + ATTESTATION_LAG``. Block metadata -------------- -In the block’s metadata, there is a specific field for the DAL. This field reflects the availability of slots based on the DAL payloads received. It is a bitfield with one bit per slot (its format is the same as the attestation payload of the ``attestation`` operation). The bit is set to 1 if the slot is declared available. The smallest slot index corresponds to the least significant bit. To consider a slot as available, there must be a minimum number of shards, as defined by the ``availability_threshold`` parameter, marked as available by the attesters for that slot (e.g. if the number of shards is 2048 and the availability threshold is 50%, then 1024 shards are required). +In the block’s metadata, there is a specific field for the DAL. This field reflects the availability of slots based on the DAL payloads received. It is a bitfield with one bit per slot (its format is the same as the attestation payload of the ``attestation`` operation). The bit is set to 1 if the slot is declared available. The smallest slot index corresponds to the least significant bit. To consider a slot as available, there must be a minimum number of shards, as defined by the ``AVAILABILITY_THRESHOLD`` parameter, marked as available by the attesters for that slot (e.g. if the number of shards is 2048 and the availability threshold is 50%, then 1024 shards are required). -Therefore, for data committed (published) at level ``L``, the slot's availability is determined by the metadata of the block at level ``L + attestation_lag``. Consequently, a smart rollup can only utilize this data from level ``L + attestation_lag + 1`` onward. +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_alpha: @@ -75,17 +75,17 @@ Minimal participation Any baker that can take part in consensus is eligible for rewards. -Bakers meeting the minimum participation ratio ``minimal_participation_ratio`` over a cycle, set to 64%, receive rewards for that cycle. +Bakers meeting the minimum participation ratio ``MINIMAL_PARTICIPATION_RATIO`` over a cycle, set to 64%, receive rewards for that cycle. The participation ratio of the baker is the proportion of slots the baker attested over the total number of slots deemed available by the protocol in the cycle. DAL participation rewards ------------------------- -A fixed percentage, defined by a protocol parameter called ``dal_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 ``DAL_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 value of ``dal_rewards_weight`` is such that it represents ``dal_rewards_ratio`` of all reward weights. +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 ``DAL_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`. For instance, the stakers' share of these reward is proportional to the weight of their stake in relation to their baker's baking power. @@ -95,7 +95,7 @@ Trap mechanism A deterministic function ``trap(pkh, shard)`` returning a boolean flag indicates whether a shard is a trap for a specific baker identified by its public key hash (``pkh``). -The protocol parameter ``traps_fraction`` controls the fraction of shards marked as traps. +The protocol parameter ``TRAPS_FRACTION`` controls the fraction of shards marked as traps. 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. @@ -103,7 +103,7 @@ The ``DAL_entrapment_evidence`` accusation operation can be used to accuse a bak This accusation operation includes the attestation operation containing the wrongly attested slot, the slot index, 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. +Accusations can be included during a period of ``DENUNCIATION_PERIOD`` cycles after the misbehavior event, which is that of the corresponding attestation operation. Penalties --------- @@ -131,17 +131,16 @@ 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_alpha` 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 -- ``number_of_slots`` (32): How many slots are available per block -- ``attestation_lag`` (8): The timeframe for bakers to download shards between the published level of a commitment and the time they must attest the availability of those shards -- ``attestation_threshold`` (66%): The minimum percentage of shards attested for a given slot to declare the slot available -- ``blocks_per_epoch`` (1): Unused. Could be removed in the future -- ``page_size`` (3967B, ~4KiB): The size of a page (see :ref:`dal_slots`) -- ``slot_size`` (126944B, ~128KiB): The size of a slot (see :ref:`dal_slots`) -- ``redundancy_factor`` (8): The erasure-code factor (see :ref:`dal_slots`) -- ``number_of_shards`` (512): The number of shards per slot (see :ref:`dal_slots`) -- ``minimal_participation_ratio`` (64%): The minimum percentage of slots attested by a baker during a cycle (among all slots deemed available) that entitles them to rewards -- ``dal_rewards_ratio`` (10%): The ratio of the DAL rewards over the total participation rewards -- ``rewards_weight`` (2275): The weight of the DAL rewards (relative to other participation rewards) -- ``traps_fraction`` (0.0005): The fraction of shards that are traps +- ``FEATURE_ENABLE`` (true): whether the DAL is available +- ``INCENTIVES_ENABLE`` (true): whether baker incentives are available +- ``NUMBER_OF_SLOTS`` (32): how many slots are available per block +- ``ATTESTATION_LAG`` (8 level): the timeframe for bakers to download shards between the published level of a commitment and the time they must attest the availability of those shards +- ``ATTESTATION_THRESHOLD`` (66%): the minimum percentage of shards attested for a given slot to declare the slot available +- ``PAGE_SIZE`` (3967B, ~4KiB): the size of a page (see :ref:`dal_slots`) +- ``SLOT_SIZE`` (126944B, ~128KiB): the size of a slot (see :ref:`dal_slots`) +- ``REDUNDANCY_FACTOR`` (8): the erasure-code factor (see :ref:`dal_slots`) +- ``NUMBER_OF_SHARDS`` (512): the number of shards per slot (see :ref:`dal_slots`) +- ``MINIMAL_PARTICIPATION_RATIO`` (64%): the minimum percentage of slots attested by a baker during a cycle (among all slots deemed available) that entitles them to rewards +- ``DAL_REWARDS_RATIO`` (10%): the ratio of the DAL rewards over the total participation rewards +- ``DAL_REWARDS_WEIGHT`` (2275): the weight of the DAL rewards (relative to other participation rewards) +- ``TRAPS_FRACTION`` (0.0005): the fraction of shards that are traps -- GitLab From 6001f4eb62f0b498c4dc82fcefb23549e33e5db7 Mon Sep 17 00:00:00 2001 From: Eugen Zalinescu Date: Fri, 24 Jan 2025 11:51:27 +0100 Subject: [PATCH 3/4] Docs/Alpha: rename DAL support to DAL integration --- docs/alpha/dal_support.rst | 8 ++++---- docs/quebec/dal_support.rst | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/alpha/dal_support.rst b/docs/alpha/dal_support.rst index 64b3ad95a229..d4903697be8e 100644 --- a/docs/alpha/dal_support.rst +++ b/docs/alpha/dal_support.rst @@ -1,8 +1,8 @@ -=========== -DAL support -=========== +=============== +DAL integration +=============== -The support for the :doc:`DAL <../shell/dal>` within the economic protocol relies on three operations: +The integration for the :doc:`DAL <../shell/dal>` 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 diff --git a/docs/quebec/dal_support.rst b/docs/quebec/dal_support.rst index 4ce773099d1b..a0f1de02c31c 100644 --- a/docs/quebec/dal_support.rst +++ b/docs/quebec/dal_support.rst @@ -1,8 +1,8 @@ -=========== -DAL support -=========== +=============== +DAL integration +=============== -The support for the :doc:`DAL <../shell/dal>` within the economic protocol relies on two operations: +The integration for the :doc:`DAL <../shell/dal>` within the economic protocol relies on two 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 -- GitLab From d6c446c8868652fe5bd1d3f0997a62a0fee95bf6 Mon Sep 17 00:00:00 2001 From: Eugen Zalinescu Date: Fri, 24 Jan 2025 12:09:58 +0100 Subject: [PATCH 4/4] Docs/Alpha: describe balance updates for the DAL --- docs/alpha/token_management.rst | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/alpha/token_management.rst b/docs/alpha/token_management.rst index a0fa244d6cf6..dc15b074e806 100644 --- a/docs/alpha/token_management.rst +++ b/docs/alpha/token_management.rst @@ -65,6 +65,7 @@ The value of the additional field ``category`` designates one of the following f * ``"attesting rewards"`` is the source of tokens minted to reward delegates for attesting blocks * ``"baking rewards"`` is the source of tokens minted to reward delegates for creating blocks * ``"baking bonuses"`` is the source of tokens minted to reward delegates for validating blocks and including extra attestations +* ``"DAL attesting rewards"`` is the source of tokens minted to reward delegates for attesting DAL slots * ``"subsidy"`` is the source of tokens minted to subsidize the liquidity baking CPMM contract * ``"invoice"`` is the source of tokens minted to compensate some users who have contributed to the betterment of the chain * ``"commitment"`` is the source of tokens minted to match commitments made by some users to supply funds for the chain @@ -142,6 +143,9 @@ The field ``category`` of a sink account may have one of the following values: - the field ``delegate`` contains the public key hash of the delegate - the field ``participation`` has the value ``"true"`` if participation was not sufficient and has the value ``"false"`` otherwise - the field ``revelation`` has the value ``"true"`` if the delegate has not revealed his nonce and has the value ``"false"`` otherwise. +* ``"lost DAL attesting rewards"`` is the destination of DAL rewards that were not distributed to a delegate. + This category comes with the additional field ``delegate`` containing the public key hash of the delegate. + * ``"Sc_rollup_refutation_punishments"`` is the destination of tokens burned as punishment for submitting bad commitments that have been refuted * ``"burned"`` is only for internal use and testing. It will not appear on mainnet, but may appear on test networks or in sandboxed mode. @@ -239,6 +243,9 @@ For example, for an amount of ``100`` mutez in rewards not distributed due to in "revelation": "false", "change": "100", ...} ] -Double signing evidence rewards and nonce revelation rewards are analogous to attesting rewards, except that the source accounts used are ``"double signing evidence rewards"`` and ``"nonce revelation rewards"``. -Depending on the staking parameters set by the delegate, some portion of the attesting rewards +DAL attesting rewards are analogous to attesting rewards, except that the source account used is ``DAL attesting rewards``. + +Depending on the staking parameters set by the delegate, some portion of the (DAL) attesting rewards will go to the freezer container, as for baking rewards and bonuses. + +Double signing evidence rewards and nonce revelation rewards are analogous to attesting rewards, except that the source accounts used are ``"double signing evidence rewards"`` and ``"nonce revelation rewards"``. -- GitLab