diff --git a/docs/alpha/adaptive_issuance.rst b/docs/alpha/adaptive_issuance.rst index d07c3b1548217e0f27d4d9e1e8e3efedb93a9608..12a747f6c2680a0c4b9c21423fb1f5aa68e22af6 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 9a3bb9046c5b4d98415662858e3b143e4aaa4210..d4903697be8e8580ead87ea9ad614a46a8b3ff3d 100644 --- a/docs/alpha/dal_support.rst +++ b/docs/alpha/dal_support.rst @@ -1,20 +1,23 @@ -=========== -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 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 ====================== ``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: @@ -45,16 +48,70 @@ 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 ``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: + +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. -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 +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: @@ -74,13 +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`` (false): 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 -- ``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`) +- ``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 diff --git a/docs/alpha/token_management.rst b/docs/alpha/token_management.rst index a0fa244d6cf6c26274175df30b38043e63a0cbec..dc15b074e806bb9e3bfd6ab58f58a2606753f4ef 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"``. diff --git a/docs/quebec/dal_support.rst b/docs/quebec/dal_support.rst index 4ce773099d1b2d188bc6cbb4d6ced1455a93ebf7..a0f1de02c31c9402c195e96859faf6af84305948 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