Mana calculator

docs/learn/protocols/iota2.0/core-concepts/mana-calculator.md

@@ -0,0 +1,40 @@
+import ManaCalculator from '@site/src/components/ManaCalculator';
+
+# Mana Calculator 
+
+Mana is a scarce resource used to access the IOTA ledger and update its state through block creation. It is a spendable asset tracked in the ledger state, powering smart contracts, DeFi applications, block creation, and various other services. Our incentives scheme allows you to stake or delegate mana to receive Mana rewards, in addition to the Mana generation your IOTA holdings grant you without having to participate in any consensus-related activity.
+
+In this article, we introduce the Mana Calculator: a tool to help you make decisions about the type of participation that will suit you the most, to help you predict the Mana generation you’ll be granted, and to decide the number of IOTA tokens you should hold to have a particular desired level of access guaranteed in the future.
+
+## How to use the Calculator: Step-by-step instructions
+
+- **Choose the network you want to estimate the Mana Generation:** this calculator works for both Shimmer and the future IOTA 2.0 network. Those two networks will have their own type of Mana (IOTA Mana and Shimmer Mana), with their own parameters and, consequently, their own behavior. Be sure you select the correct scenario you want to simulate! 
+
+- **Choose your role:** are you going to delegate to a validator, be a validator yourself or just hold tokens? To be a validator, you must run a node and lock your tokens while you are performing such validation services, but this will give you higher rewards. If you wish to delegate to a validator, your tokens will not be locked and you won’t need to run a node, but this will give you less rewards than validating. Finally, just holding tokens grants you a certain Mana generation, but it will be less than the validating or delegating.
+
+- **Input the number of tokens you own:** no matter which network and role you choose, your Mana generation will depend on how many available tokens you have. Pay attention to the units! The input should be done in IOTA or Shimmer (not microIota or Glow).
+
+Now you are mostly done! With the inputs above, you can already estimate how much Mana you’ll be granted per epoch. But what does it mean in tps? How many blocks per second this Mana grants you? The answer to this question depends on the size of your block and the network congestion levels. However, we can use a default block size, which will be enough for most applications, and assume certain levels of congestion. This takes us to the very last step to be taken in this calculator:
+
+- **Choose a congestion level:** given a certain Mana generation per epoch, this can be translated into a number of blocks issued per seconds that depends on the congestion level. Choose one of the given congestion levels (low, stable, or extreme) to estimate how many blocks per second your tokens and participation grants you! This metric is also showed in a alternative way: time until block issuance, which tells you in which periodicity you’ll be able to issue a block.
+
+<ManaCalculator/>
+
+
+## Advanced settings
+
+The steps shown above are enough to roughly estimate your Mana generation and granted tps; however, if you wish, you can play with the advanced settings to have more precise results. 
+
+- **Change the state of the system:** the default settings assume a certain level of participation in the consensus (i.e., locked stake, delegated stake and performance factor of validators). Those settings can be changed unter the “Advanced settings - State of the System” tab. You can also add or delete validators and change their fixed costs. 
+
+- If you choose to delegate:
+   - **Change the validator you delegate to:** by the default settings, you'll be delegating to Validator 1 (which is  pool that, technically speaking, is under the "equilibrium state", see the WP for more details). However, you can change this setting and know your rewards if you participate in other pools, with different share of delegated to locked stake, and different performance factors.
+
+- If you choose to validate:
+   - **Change the amount of stake is delegated to you:** by the default settings of the calculator, you'll be assigned a certain share of the delegated stake automatically when you start validating. However, you can change this setting and know your rewards if you manage to atract more (or less) delegated stake than the default setting.
+   - **Change your performance factor:** by the default settings of the calculator, your performance factor is 0.95. However, you can change this to simulate larger or smaller shares of online time. 
+   - **Change your fixed costs:** by the default settings of the calculator, your fixed costs are zero. This setting can be changed so you spare part of the pool rowards just for yourself. However, notice that the fixed cost is a public parameter, that you define during registration. This means that the delegator know how you set this value and might consider it when choosing a validator to delegate. Furthermore, is you set this value too high, you'll be punished and won't get rewards at all.
+
+- **Simulate your Mana accumulation**: the default setting of the calculator assumes a stationary regime and calculates the block creation rate you guarantee depending on your stake and level of participation. However, specially in the early stages of the network you might want to save your mana to sell later. This tab simulates how much Mana you will accumulate in a certain time period. For that (besides the other already defined inputs), you just need to choose a initial and final epochs, and the tool will plot a graph of your accumulation during that period. In the same graph, you can also have an idea of how many blocks can be issued with this accumulated amount of Mana, for the different congestion levels (already defined in the non-advanced settings).
+
+

docs/learn/protocols/iota2.0/core-concepts/mana.md

@@ -1,3 +1,5 @@
+import ManaCalculator from '@site/src/components/ManaCalculator';
+
 # Tokenomics: Mana, Accounts, Staking and Delegation
 
 Mana is a scarce resource used to access the IOTA ledger and update its state through block creation. It is a spendable asset tracked in the ledger state, powering smart contracts, DeFi applications, block creation, and various other services, and is linked to [accounts](#accounts), which allow you to [stake or delegate](#staking-and-delegation-1) mana to receive [Mana rewards](#mana-rewards).
@@ -237,3 +239,7 @@ A reward scheme is always a powerful mechanism to incentivize actors to have cer
 - No incentives for centralizing the funds of validators and delegators.
   - By the construction of our reward formulas, there is no incentive for the centralization of validator funds. Technically speaking, this means that two different validators do not get more rewards by combining their stake.
   - Analogously, the concentration of delegator funds is disincentivized by the construction of our reward formula. As more delegated stake is concentrated on the same validator, the rewards of the delegators become smaller. Then, the delegators are incentivized to redelegate to validators with less delegated stake. In the long run, under the assumption that actors are rational, the system should stabilize around a constant ratio of delegated and validator stake among pools.
+
+## Mana Calculator
+
+<ManaCalculator/>

src/components/ManaCalculator/calculator.ts

@@ -0,0 +1,159 @@
+import {
+  GENERATION_PER_SLOT,
+  first_slot_of_epoch,
+  potential_Mana,
+  IOTA_SUPPLY,
+  targetReward,
+  EPOCH_DURATION,
+  decay,
+} from './utils';
+import { ValidatorParameters, ValidatorProps } from './types';
+
+export function calculateManaRewards(
+  stake: number,
+  yourPool: number,
+  validatorParameters: ValidatorParameters,
+  validators: ValidatorProps[],
+  initialEpoch: number,
+  finalEpoch: number,
+  yourRole: 'Validator' | 'Delegator',
+): number {
+  let totalTargetReward = 0;
+  let epochDiff = 1;
+  if (finalEpoch) {
+    for (let i = 0; i < epochDiff; i++) {
+      totalTargetReward += decay(targetReward(initialEpoch + i), epochDiff - i);
+    }
+  } else {
+    finalEpoch = initialEpoch + 1;
+    totalTargetReward = targetReward(initialEpoch);
+  }
+
+  const lockedStake: number[] = validators.map(
+    (validator) => validator.lockedStake,
+  );
+  const fixedCosts: number[] = validators.map(
+    (validator) => validator.fixedCost,
+  );
+  const performance: number[] = validators.map(
+    (validator) => validator.performanceFactor,
+  );
+  const delegatedStake: number[] = validators.map(
+    (validator) => validator.delegatedStake,
+  );
+
+  if (yourRole === 'Validator') {
+    lockedStake.push(stake * validatorParameters.shareOfYourStakeLocked);
+    fixedCosts.push(validatorParameters.fixedCost);
+    performance.push(validatorParameters.performanceFactor);
+    delegatedStake.push(
+      (1 - validatorParameters.shareOfYourStakeLocked) * stake +
+        validatorParameters.attractedNewDelegatedStake +
+        validatorParameters.attractedDelegatedStakeFromOtherPools *
+          delegatedStake.reduce((a, b) => a + b, 0),
+    );
+    for (let i = 0; i < validators.length; i++) {
+      delegatedStake[i] *=
+        1 - validatorParameters.attractedDelegatedStakeFromOtherPools;
+    }
+  }
+
+  if (yourRole === 'Delegator') {
+    delegatedStake[yourPool] += stake;
+  }
+
+  const totalValidatorsStake = lockedStake.reduce((a, b) => a + b, 0);
+  const totalDelegatedStake = delegatedStake.reduce((a, b) => a + b, 0);
+  const totalStake = totalDelegatedStake + totalValidatorsStake;
+  const restOfTokenHoldings = IOTA_SUPPLY - totalStake;
+  if (restOfTokenHoldings < 0) {
+    throw new Error('Pools must have (collectively) at most iotaSupply tokens');
+  }
+
+  // Calculates profit margin of the epoch (only when there are tokens stake, otherwise, it's set to None)
+  let profitMargin: number | null;
+  if (totalStake > 0) {
+    profitMargin = totalValidatorsStake / (totalValidatorsStake + totalStake);
+  } else {
+    profitMargin = null;
+  }
+
+  // Calculates the total rewards for each pool, already discounting the validator fixed cost
+  const poolRewards: number[] = new Array(lockedStake.length).fill(0);
+  if (totalStake > 0) {
+    if (totalValidatorsStake > 0) {
+      for (let i = 0; i < lockedStake.length; i++) {
+        poolRewards[i] =
+          ((lockedStake[i] + delegatedStake[i]) / totalStake +
+            lockedStake[i] / totalValidatorsStake) *
+            totalTargetReward *
+            (performance[i] / 2.0) -
+          epochDiff * fixedCosts[i];
+      }
+    } else {
+      for (let i = 0; i < lockedStake.length; i++) {
+        poolRewards[i] =
+          ((lockedStake[i] + delegatedStake[i]) / totalStake) *
+            totalTargetReward *
+            (performance[i] / 2.0) -
+          epochDiff * fixedCosts[i];
+      }
+    }
+  }
+
+  // Calculates the rewards for each validator
+  const validatorRewards: number[] = new Array(lockedStake.length).fill(0);
+  for (let i = 0; i < lockedStake.length; i++) {
+    if (poolRewards[i] < 0) {
+      validatorRewards[i] = 0;
+      poolRewards[i] = 0;
+    } else if (poolRewards[i] === 0) {
+      validatorRewards[i] = epochDiff * fixedCosts[i];
+    } else {
+      validatorRewards[i] =
+        epochDiff * fixedCosts[i] +
+        poolRewards[i] * profitMargin +
+        ((1 - profitMargin) * poolRewards[i] * lockedStake[i]) /
+          (delegatedStake[i] + lockedStake[i]);
+    }
+  }
+
+  const delegatorRewards: number[] = new Array(lockedStake.length).fill(0);
+  for (let i = 0; i < lockedStake.length; i++) {
+    if (poolRewards[i] > 0) {
+      delegatorRewards[i] =
+        (poolRewards[i] * (1 - profitMargin) * delegatedStake[i]) /
+        (delegatedStake[i] + lockedStake[i]);
+    }
+  }
+
+  let rewards = 0;
+  if (yourRole === 'Delegator') {
+    if (delegatorRewards[yourPool] > 0) {
+      rewards = (delegatorRewards[yourPool] * stake) / delegatedStake[yourPool];
+    }
+  }
+
+  if (yourRole === 'Validator') {
+    rewards = validatorRewards[lockedStake.length - 1];
+  }
+
+  return rewards;
+}
+
+export function calculatePassiveRewards(
+  tokens: number,
+  initialEpoch: number,
+  finalEpoch: number,
+): number {
+  return potential_Mana(
+    tokens,
+    first_slot_of_epoch(initialEpoch) - 1,
+    first_slot_of_epoch(finalEpoch) - 1,
+    GENERATION_PER_SLOT,
+  );
+}
+
+export function calculateTPS(mana: number, congestion: number): number {
+  return mana / congestion / EPOCH_DURATION;
+}