From 1a7903fb29a8ba15119f4dd60c008a8af422dbf6 Mon Sep 17 00:00:00 2001 From: Lucas Tortora Date: Wed, 18 Oct 2023 09:55:38 -0300 Subject: [PATCH 1/7] add validatpors articles and images --- .../iota2.0/core-concepts/validators.md | 134 ++++++++++++++++++ docs/learn/sidebars.ts | 1 + .../core-concepts/validators/timeline.png | Bin 0 -> 47553 bytes 3 files changed, 135 insertions(+) create mode 100644 docs/learn/protocols/iota2.0/core-concepts/validators.md create mode 100644 static/img/learn/protocols/iota2.0/core-concepts/validators/timeline.png diff --git a/docs/learn/protocols/iota2.0/core-concepts/validators.md b/docs/learn/protocols/iota2.0/core-concepts/validators.md new file mode 100644 index 00000000000..aa26b18f79c --- /dev/null +++ b/docs/learn/protocols/iota2.0/core-concepts/validators.md @@ -0,0 +1,134 @@ +# Validators, Their Selection and Rotation + +Validators are special nodes that issue validation blocks to enable the entire network to agree on the ledger's state and the set of blocks in the Tangle. Validators directly contribute to the progress of the ledger and its security, and in turn, they are rewarded with Mana. The primary [responsibilities of validators](#responsibilities-and-actions-of-validators) include determining the inclusion of blocks in the Tangle, validating transactions, resolving double spends, and finalizing slot commitments. + +IOTA 2.0 uses Delegated Proof-of-Stake (DPoS) to determine which validators secure the network. For each epoch, a committee selection procedure determines a subset of all available validators to carry out the consensus protocol during the epoch. The validators included in the subset are referred to as the committee members for the epoch. + +## The Role of Validators and Committees + +Validators and committees bring several important properties to the IOTA 2.0 protocol: + +### Security + +Validators and committees prevent double spending and malicious manipulation of the consensus. Both validator and non-validator nodes accept blocks and transactions approved by the committee and follow the slot commitment chain adopted by a majority of the committee. + +### Ledger Progress + +The ledger needs to be not only secure but also live, i.e., transactions issued by honest participants must update the ledger in a timely manner. One of the main responsibilities of epoch committees is to approve blocks with transactions promptly, ensuring that the ledger progresses efficiently. + +### Efficient Consensus + +The bounded size of a committee reduces the number of blocks required to reach an agreement in the network. Since the outcome of the IOTA 2.0 consensus protocol is solely based on the validation blocks, this allows for fast confirmation times and reasonable communication complexity. + +### Decentralized Democracy + +There is no minimum stake requirement to become a validator in IOTA 2.0, allowing for easy participation by many nodes. In addition, users (more precisely, [accounts](mana.md#accounts)) can also participate implicitly by delegating their stake to a trusted validator, increasing their chance of being elected to the committee. This promotes a more democratic and inclusive validation process. + +## Validator Registration and Committee Selection Process + +To be included in the committee of an epoch $e$ in IOTA 2.0, a node must go through three steps: + +1. [Registration](#registration). +2. [Activity](#activity). +3. [Selection](#selection-and-voting-weight). + +The timeline of this process is depicted below (the actual duration of each period is not accurately depicted; instead, it depends on the value of the corresponding protocol parameters): + +![Timeline](/img/learn/protocols/iota2.0/core-concepts/validators/timeline.png 'An example of the timeline for the committee selection process.') +**Image:** An example of the timeline for the committee selection process. + +### Registration + +To register as a validator for epoch $e$, an actor has to issue a block with a transaction that mutates an account to add a corresponding staking feature. Both block and transaction have to be issued before `epochStart-epochSetupDuration-activityDuration`, where `epochStart` is the beginning of epoch $e$. The registration must provide the following information: + +- **Account ID**: A human-readable identifier of the actor. +- **Profit Margin**: A fixed fraction of combined validator’s and delegators’ rewards that intends to be retained by the actor. +- **Fixed Cost**: A fixed amount deducted to cover the validator’s operating costs. +- **Locked Funds (stake)**: A user-chosen amount of funds that will be locked. +- **Unbonding Time**: A timestamp until the locked funds cannot be moved. + +The registration is only considered successful when the registration block and the mutating transaction get accepted (i.e., approved by more than $2/3$ of the current online committee) and committed to the respective slot commitment. You can set the unbonding time to "unlimited" (or a reasonably large timestamp), so you only need to register once. + +### Activity + +In the _activity period_, defined as `[epochStart-epochSetupDuration-activityDuration, epochStart-epochSetupDuration)`, an actor has to have at least one accepted block. This block can be of any type, e.g., it could be a validation block. All actors who have an accepted block within the activity period are called $`e`$-`preActive`. Note that this step needs to be done before every epoch if a validator wants to participate in the committee. + +### Selection and Voting Weight + +The stake of each validator is the sum of the locked funds and the delegated stake from other nodes. Let $S_i(e)=L_i(e)+D_i(e)$ denote the pool's stake of node $i$ for epoch $e$, where $L_i(e)$ is the token value locked by node $i$ and $D_i(e)$ is the token value delegated to node $i$. The value $S_i(e)$ is fixed at the slot that ends at `epochStart-epochSetupDuration`. The stake vector of all $e$-preActive validators is considered, i.e. $`\mathbf{S}(e)=(S_j(e))|_{j \ \text{is }e\text{-preActive}}`$. + +Then, the next committee is formed by taking `committeeTotalSeats` validators who have the largest stake in $\mathbf{S}(e)$. When deciding between equal stakeholders, ties are broken deterministically by using a hash function. The voting weight of all selected committee members is equal to $1$. + +The selected committee will become the actual committee for epoch $e$ only if the slot that ends `epochStart-epochSetupDuration` (slot $s$ in the image) is finalized during epoch $e-1$. Otherwise, the committee of epoch $e-1$ becomes the committee of epoch $e$. The committee is naturally incentivized to finalize that slot since the [rewards](#rewards-and-incentives) will not be paid for the following epochs and the locked funds remain locked until finalization happens. + +Therefore, committees evolve across epochs due to changes in the delegation of stake and the set of active validators. + +:::note Upoming Updates + +The committee selection procedure will be changed in one of the next upgrades. Eventually, it will be based on a random lottery, where a stakeholder is selected for the committee with a probability that depends on the stake in the corresponding pool. + +::: + +## Responsibilities and Actions of Validators + +The main responsibility of validators is to issue validation blocks. The congestion control component of the protocol ensures that the members of an epoch committee have a guaranteed throughput allowance without burning any Mana during the epoch. To provide high-quality service, validation blocks should satisfy certain properties: + +### Regular Block Issuance + +The timestamp difference between two consecutive validation blocks by a given committee member should be at most `frequencyValidationBlock` seconds. The [rewards](#rewards-and-incentives) for validators are distributed according to their performance factors, which are computed per slot and take into account the number of accepted blocks and the expected number of validation blocks per slot. + +### Proper Referencing + +Since only validation blocks are important for the consensus for IOTA 2.0, epoch committee members use a hybrid tip selection algorithm: + +- Referencing latest validation blocks: to improve confirmation time, it is important to reference all the latest validation blocks within the adopted slot commitment chain. +- Uniform tip selection algorithm: committee members should pick up and reference not only validation blocks but choose uniformly at random `blockMaxParent` eligible blocks in their tip pool. + +### Correct Voting + +The opinion that a validation block expresses through different references should be aligned with the preferred reality of the block issuer. For instance, the block should not represent a vote for two transactions that are conflicting with each other. In the latter case, the vote of the issuer is not counted in the consensus protocol. + +### Regular Committing to Slots + +Committee members should commit to a slot once the slot becomes committable. This ensures that the slot commitment chain is consistently updated and finalization functions properly. + +## Rewards and Incentives + +Well-performing validators are eligible for Mana rewards. Let $R(s)$ denote the target reward for a slot $s$ in epoch $e$. The rewards $R_i(s)$ to an epoch-$`e`$ committee member $i$ for slot $s$ are calculated as follows + +$$ +R_i(s) = \dfrac{R(s)}{1+\alpha}\left(\dfrac{L_i(e) + D_{i}(e)}{L(e) + D(e)}+\alpha \dfrac{L_i(e)}{L(e)}\right)\varphi_i +$$ + +**Where**: + +- $`\varphi_i\in [0,1]`$ is the "performance factor", which measures the quality of validator $i$'s services at slot $s$; +- $L_i(e)$ and $D_i(e)$ are the token value locked by committee member $i$ and delegated to committee member $i$ for epoch $e$; +- $L(e)$ and $D(e)$ are the token value locked by the whole committee and delegated to all committee members for epoch $e$; +- $\alpha>0$ is a global parameter specified by the protocol. + +Since the parameter $\alpha>0$, the reward distribution privileges pools with a larger locked stake. + +After epoch $e$ ends, the delegators of the validator's pool can claim their Mana rewards. The validator may continue to stake or end its stake by going through an unbonding period of its locked tokens. After this period ends, the validator can unlock their tokens and claim their Mana rewards by creating a transaction that consumes the original output that was staked and includes the Mana on the output side of the transaction. + +## Handling Misbehavior and Adversarial Validators + +In general, the consensus protocol in IOTA 2.0 handles adversarial validators with at most $1/3$ of the total voting weight, where adversarial actors can misbehave. Here are some examples of adversarial misbehavior and how the protocol can handle them: + +### Censoring Valid Blocks + +An adversarial committee member could censor a valid block by not referencing it. However, honest validators will still reference these valid blocks. That means that to successfully censor a valid block, the adversarial validator would need to avoid all blocks built on top of the censored block. Eventually, this will result in the adversarial node's blocks being isolated and orphaned. + +### Stop Issuing Blocks + +Adversarial validators can stop issuing validation blocks. In this case, the Tangle and the ledger will not stop growing since block and transaction acceptance requires only approval from the "online" committee. In addition, validators, who didn't issue validation blocks regularly, will get fewer rewards, if any. + +### Manipulation With Slot Commitment Chains + +#### Many competing chains + +It is easy for the adversary to create many competing slot commitment chains. Recall that by the consensus protocol, honest nodes prefer the heaviest chain with the most recent quorum certificate. Honest nodes will simply ignore blocks with unfamiliar commitments lacking sufficient support. + +#### Incorrect extension of the chain + +Suppose the adversary produces a slot commitment prematurely (e.g., not all conflicting transactions within the slot are resolved). In that case, the honest committee members will keep the corresponding block in the waiting tip pool to verify its accuracy once the respected slot becomes committable. Blocks with incorrect slot commitments will ultimately be discarded from the tip pool. diff --git a/docs/learn/sidebars.ts b/docs/learn/sidebars.ts index 18fae6efcb5..632277edc90 100644 --- a/docs/learn/sidebars.ts +++ b/docs/learn/sidebars.ts @@ -78,6 +78,7 @@ module.exports = { 'protocols/iota2.0/core-concepts/consensus/relevant-algorithms', ], }, + 'protocols/iota2.0/core-concepts/validators', ], }, ], diff --git a/static/img/learn/protocols/iota2.0/core-concepts/validators/timeline.png b/static/img/learn/protocols/iota2.0/core-concepts/validators/timeline.png new file mode 100644 index 0000000000000000000000000000000000000000..359bbecde776d93f228c30d3fe02e8ccf4e18899 GIT binary patch literal 47553 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 Date: Wed, 18 Oct 2023 10:53:19 -0300 Subject: [PATCH 2/7] Apply suggestions from code review Co-authored-by: Nikita Polianskii <91725722+polinikita@users.noreply.github.com> --- .../iota2.0/core-concepts/validators.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/learn/protocols/iota2.0/core-concepts/validators.md b/docs/learn/protocols/iota2.0/core-concepts/validators.md index aa26b18f79c..8192311ca32 100644 --- a/docs/learn/protocols/iota2.0/core-concepts/validators.md +++ b/docs/learn/protocols/iota2.0/core-concepts/validators.md @@ -18,7 +18,7 @@ The ledger needs to be not only secure but also live, i.e., transactions issued ### Efficient Consensus -The bounded size of a committee reduces the number of blocks required to reach an agreement in the network. Since the outcome of the IOTA 2.0 consensus protocol is solely based on the validation blocks, this allows for fast confirmation times and reasonable communication complexity. +The bounded size of a committee reduces the number of blocks required to reach an agreement in the network. Since the outcome of the IOTA 2.0 [consensus protocol](consensus/introduction.md) is solely based on the validation blocks, this allows for fast confirmation times and reasonable communication complexity. ### Decentralized Democracy @@ -51,11 +51,11 @@ The registration is only considered successful when the registration block and t ### Activity -In the _activity period_, defined as `[epochStart-epochSetupDuration-activityDuration, epochStart-epochSetupDuration)`, an actor has to have at least one accepted block. This block can be of any type, e.g., it could be a validation block. All actors who have an accepted block within the activity period are called $`e`$-`preActive`. Note that this step needs to be done before every epoch if a validator wants to participate in the committee. +In the _activity period_, defined as `[epochStart-epochSetupDuration-activityDuration, epochStart-epochSetupDuration)`, an actor has to have at least one accepted block. This block can be of any type, e.g., it could be a validation block. All actors who have an accepted block within the activity period are called $e$-`preActive`. Note that this step needs to be done before every epoch if a validator wants to participate in the committee. ### Selection and Voting Weight -The stake of each validator is the sum of the locked funds and the delegated stake from other nodes. Let $S_i(e)=L_i(e)+D_i(e)$ denote the pool's stake of node $i$ for epoch $e$, where $L_i(e)$ is the token value locked by node $i$ and $D_i(e)$ is the token value delegated to node $i$. The value $S_i(e)$ is fixed at the slot that ends at `epochStart-epochSetupDuration`. The stake vector of all $e$-preActive validators is considered, i.e. $`\mathbf{S}(e)=(S_j(e))|_{j \ \text{is }e\text{-preActive}}`$. +The stake of each validator is the sum of the locked funds and the delegated stake from other nodes. Let $S_i(e)=L_i(e)+D_i(e)$ denote the pool's stake of node $i$ for epoch $e$, where $L_i(e)$ is the token value locked by node $i$ and $D_i(e)$ is the token value delegated to node $i$. The value $S_i(e)$ is fixed at the slot that ends at `epochStart-epochSetupDuration`. The stake vector of all $e$-preActive validators is considered, i.e. $\mathbf{S}(e)=(S_j(e))|_{j \ \text{is }e\text{-preActive}}$. Then, the next committee is formed by taking `committeeTotalSeats` validators who have the largest stake in $\mathbf{S}(e)$. When deciding between equal stakeholders, ties are broken deterministically by using a hash function. The voting weight of all selected committee members is equal to $1$. @@ -79,22 +79,21 @@ The timestamp difference between two consecutive validation blocks by a given co ### Proper Referencing -Since only validation blocks are important for the consensus for IOTA 2.0, epoch committee members use a hybrid tip selection algorithm: +Since only validation blocks are important for the consensus for IOTA 2.0, epoch committee members use a [tip selection algorithm](consensus/tip-selection-algorithm.md) with an increased number of parents: -- Referencing latest validation blocks: to improve confirmation time, it is important to reference all the latest validation blocks within the adopted slot commitment chain. -- Uniform tip selection algorithm: committee members should pick up and reference not only validation blocks but choose uniformly at random `blockMaxParent` eligible blocks in their tip pool. +- Uniform tip selection algorithm: committee members should select uniformly at random `blockTypeValidatorMaxParent` eligible blocks in their tip pool as strong parents. ### Correct Voting -The opinion that a validation block expresses through different references should be aligned with the preferred reality of the block issuer. For instance, the block should not represent a vote for two transactions that are conflicting with each other. In the latter case, the vote of the issuer is not counted in the consensus protocol. +The opinion that a validation block expresses through different [references](consensus/preliminaries.md#block-references) should be aligned with the [preferred reality](consensus/preliminaries.md#reality) of the block issuer. For instance, the block should not represent a vote for two transactions that are conflicting with each other. In the latter case, the vote of the issuer is not counted in the consensus protocol. ### Regular Committing to Slots -Committee members should commit to a slot once the slot becomes committable. This ensures that the slot commitment chain is consistently updated and finalization functions properly. +Committee members should commit to a slot once the slot becomes committable. This ensures that the [slot commitment chain](consensus/preliminaries.md#slot-commitment-chain) is consistently updated and [finalization](consensus/consensus-flags.md#finalization-flag) functions properly. ## Rewards and Incentives -Well-performing validators are eligible for Mana rewards. Let $R(s)$ denote the target reward for a slot $s$ in epoch $e$. The rewards $R_i(s)$ to an epoch-$`e`$ committee member $i$ for slot $s$ are calculated as follows +Well-performing validators are eligible for Mana rewards. Let $R(s)$ denote the target reward for a slot $s$ in epoch $e$. The rewards $R_i(s)$ to an epoch-$e$ committee member $i$ for slot $s$ are calculated as follows $$ R_i(s) = \dfrac{R(s)}{1+\alpha}\left(\dfrac{L_i(e) + D_{i}(e)}{L(e) + D(e)}+\alpha \dfrac{L_i(e)}{L(e)}\right)\varphi_i From 1dc0c87e42cac96011ca3a7c01806de65ff97406 Mon Sep 17 00:00:00 2001 From: Lucas Tortora <85233773+lucas-tortora@users.noreply.github.com> Date: Wed, 18 Oct 2023 11:07:48 -0300 Subject: [PATCH 3/7] Update docs/learn/protocols/iota2.0/core-concepts/validators.md Co-authored-by: Nikita Polianskii <91725722+polinikita@users.noreply.github.com> --- docs/learn/protocols/iota2.0/core-concepts/validators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/learn/protocols/iota2.0/core-concepts/validators.md b/docs/learn/protocols/iota2.0/core-concepts/validators.md index 8192311ca32..50aae85e872 100644 --- a/docs/learn/protocols/iota2.0/core-concepts/validators.md +++ b/docs/learn/protocols/iota2.0/core-concepts/validators.md @@ -126,7 +126,7 @@ Adversarial validators can stop issuing validation blocks. In this case, the Tan #### Many competing chains -It is easy for the adversary to create many competing slot commitment chains. Recall that by the consensus protocol, honest nodes prefer the heaviest chain with the most recent quorum certificate. Honest nodes will simply ignore blocks with unfamiliar commitments lacking sufficient support. +It is easy for the adversary to create many competing slot commitment chains. Recall that by the consensus protocol, honest nodes prefer the heaviest chain with the most recent finalized commitment. Honest nodes will simply ignore blocks with unfamiliar commitments lacking sufficient support. #### Incorrect extension of the chain From de36a3fb3b8c77337ce450ce6c8a0ce9de99b4a4 Mon Sep 17 00:00:00 2001 From: Lucas Tortora <85233773+lucas-tortora@users.noreply.github.com> Date: Wed, 18 Oct 2023 16:33:35 -0300 Subject: [PATCH 4/7] Update docs/learn/protocols/iota2.0/core-concepts/validators.md Co-authored-by: Nikita Polianskii <91725722+polinikita@users.noreply.github.com> --- docs/learn/protocols/iota2.0/core-concepts/validators.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/learn/protocols/iota2.0/core-concepts/validators.md b/docs/learn/protocols/iota2.0/core-concepts/validators.md index 50aae85e872..a9a71e90734 100644 --- a/docs/learn/protocols/iota2.0/core-concepts/validators.md +++ b/docs/learn/protocols/iota2.0/core-concepts/validators.md @@ -96,10 +96,10 @@ Committee members should commit to a slot once the slot becomes committable. Thi Well-performing validators are eligible for Mana rewards. Let $R(s)$ denote the target reward for a slot $s$ in epoch $e$. The rewards $R_i(s)$ to an epoch-$e$ committee member $i$ for slot $s$ are calculated as follows $$ -R_i(s) = \dfrac{R(s)}{1+\alpha}\left(\dfrac{L_i(e) + D_{i}(e)}{L(e) + D(e)}+\alpha \dfrac{L_i(e)}{L(e)}\right)\varphi_i +R_i(s) = \dfrac{R(s)}{1+\alpha}\left(\dfrac{L_i(e) + D_{i}(e)}{L(e) + D(e)}+\alpha \dfrac{L_i(e)}{L(e)}\right)\varphi_i, $$ -**Where**: +where: - $`\varphi_i\in [0,1]`$ is the "performance factor", which measures the quality of validator $i$'s services at slot $s$; - $L_i(e)$ and $D_i(e)$ are the token value locked by committee member $i$ and delegated to committee member $i$ for epoch $e$; From 32e05338c04121d764b9ff35aa166bfece845669 Mon Sep 17 00:00:00 2001 From: Lucas Tortora <85233773+lucas-tortora@users.noreply.github.com> Date: Wed, 18 Oct 2023 16:33:52 -0300 Subject: [PATCH 5/7] Update docs/learn/protocols/iota2.0/core-concepts/validators.md Co-authored-by: Nikita Polianskii <91725722+polinikita@users.noreply.github.com> --- docs/learn/protocols/iota2.0/core-concepts/validators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/learn/protocols/iota2.0/core-concepts/validators.md b/docs/learn/protocols/iota2.0/core-concepts/validators.md index a9a71e90734..1b66663b2fd 100644 --- a/docs/learn/protocols/iota2.0/core-concepts/validators.md +++ b/docs/learn/protocols/iota2.0/core-concepts/validators.md @@ -63,7 +63,7 @@ The selected committee will become the actual committee for epoch $e$ only if th Therefore, committees evolve across epochs due to changes in the delegation of stake and the set of active validators. -:::note Upoming Updates +:::note Upcoming Updates The committee selection procedure will be changed in one of the next upgrades. Eventually, it will be based on a random lottery, where a stakeholder is selected for the committee with a probability that depends on the stake in the corresponding pool. From 03ed3b0693061d079e67410eee83fe7137c90ac4 Mon Sep 17 00:00:00 2001 From: Lucas Tortora <85233773+lucas-tortora@users.noreply.github.com> Date: Wed, 18 Oct 2023 16:34:05 -0300 Subject: [PATCH 6/7] Update docs/learn/protocols/iota2.0/core-concepts/validators.md Co-authored-by: Nikita Polianskii <91725722+polinikita@users.noreply.github.com> --- docs/learn/protocols/iota2.0/core-concepts/validators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/learn/protocols/iota2.0/core-concepts/validators.md b/docs/learn/protocols/iota2.0/core-concepts/validators.md index 1b66663b2fd..91f3aab459d 100644 --- a/docs/learn/protocols/iota2.0/core-concepts/validators.md +++ b/docs/learn/protocols/iota2.0/core-concepts/validators.md @@ -101,7 +101,7 @@ $$ where: -- $`\varphi_i\in [0,1]`$ is the "performance factor", which measures the quality of validator $i$'s services at slot $s$; +- $\varphi_i\in [0,1]$ is the "performance factor", which measures the quality of validator $i$'s services at slot $s$; - $L_i(e)$ and $D_i(e)$ are the token value locked by committee member $i$ and delegated to committee member $i$ for epoch $e$; - $L(e)$ and $D(e)$ are the token value locked by the whole committee and delegated to all committee members for epoch $e$; - $\alpha>0$ is a global parameter specified by the protocol. From 76fab044ff5e97cfb46ef25e3f0f93068f9257b5 Mon Sep 17 00:00:00 2001 From: Lucas Tortora <85233773+lucas-tortora@users.noreply.github.com> Date: Wed, 18 Oct 2023 16:35:11 -0300 Subject: [PATCH 7/7] Update docs/learn/protocols/iota2.0/core-concepts/validators.md --- docs/learn/protocols/iota2.0/core-concepts/validators.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/learn/protocols/iota2.0/core-concepts/validators.md b/docs/learn/protocols/iota2.0/core-concepts/validators.md index 91f3aab459d..7ab2ef7140f 100644 --- a/docs/learn/protocols/iota2.0/core-concepts/validators.md +++ b/docs/learn/protocols/iota2.0/core-concepts/validators.md @@ -110,6 +110,12 @@ Since the parameter $\alpha>0$, the reward distribution privileges pools with a After epoch $e$ ends, the delegators of the validator's pool can claim their Mana rewards. The validator may continue to stake or end its stake by going through an unbonding period of its locked tokens. After this period ends, the validator can unlock their tokens and claim their Mana rewards by creating a transaction that consumes the original output that was staked and includes the Mana on the output side of the transaction. +:::note + +More details about Mana rewards and incentives can be found in [Tokenomics: Mana, Accounts, Staking and Delegation](mana.md) + +::: + ## Handling Misbehavior and Adversarial Validators In general, the consensus protocol in IOTA 2.0 handles adversarial validators with at most $1/3$ of the total voting weight, where adversarial actors can misbehave. Here are some examples of adversarial misbehavior and how the protocol can handle them: