Files
nym/documentation/docs/pages/operators/tokenomics/mixnet-rewards.mdx
2025-03-27 11:50:16 +00:00

403 lines
24 KiB
Plaintext
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import { Callout } from 'nextra/components';
import { Tabs } from 'nextra/components';
import { MyTab } from 'components/generic-tabs.tsx';
import { RunTabs } from 'components/operators/nodes/node-run-command-tabs';
import { VarInfo } from 'components/variable-info.tsx';
import { MigrateTabs } from 'components/operators/nodes/node-migrate-command-tabs';
import NyxPercentStake from 'components/outputs/nyx-outputs/nyx-percent-stake.md';
import NyxTotalStake from 'components/outputs/nyx-outputs/nyx-total-stake.md';
import { TimeNow } from 'components/time-now.tsx';
import { AccordionTemplate } from 'components/accordion-template.tsx';
import { Clt } from 'components/callout-custom/CalloutCustom.jsx';
# Nym Operators Rewards
<Callout type="warning">
**Nym Network Rewarded set selection had been upgraded recently. Make sure to read the chapter *[Rewarded Set Selection](#rewarded-set-selection)* below carefully to fully understand all requirements to be rewarded!**
</Callout>
<TimeNow />
* Nym tokenomics are based on the research paper [*Reward Sharing for Mixnets*](https://nymtech.net/nym-cryptoecon-paper.pdf)
* For a more comprehensive overview, live data and supply graphs, visit [*nymtech.net/about/token*](https://nymtech.net/about/token)
We are working on the final architecture of [*Fair Mixnet*](#fair-mixnet) tokenomics implementation and its detailed documentation. **The current design is called [*Naive rewarding*](#naive-rewarding).** It is an intermediate step, allowing operators to migrate to `nym-node` in Mixnet smart contract and for the first time recieve delegations and earn rewards for any `nym-node` functionality, in opposite to the past system, where only Mixnodes were able to recieve delegations and rewards.
**Please read the [roadmap section below](#roadmap) to see the planned development.**
{/*
**Formulas and Examples Annotation**
To make it easier for the reader, we use a highlighting line on the left side, with a specific color:
<Clt borderColor='#008080' backgroundColor='#20b2aa' pointPosition='right' pointOffset='3rem' pointAlignment='center'>
> **Turquoise with red pin for formulas.**
</Clt>
<Callout borderColor="#966fd6" backgroundColor="#b19cd9" emoji="">
<AccordionTemplate name="Example">
> Purple collapsible for examples.
</AccordionTemplate>
</Callout>
*/}
<Callout type="info" emoji="️">
Nodes bonded with vesting tokens are [not allowed to join rewarded set](https://github.com/nymtech/nym/pull/5129) - read more on [Nym operators forum](https://forum.nymtech.net/t/vesting-accounts-are-no-longer-supported/827).
</Callout>
## Overview
This is a quick summary, to understand the full picture, please see detailed [*Rewards Logic & Calculation*](#rewards-logic--calculation) chapter below.
* The operators of `nym-node` get rewarded from Mixmining pool, which emits around 6000 NYM per hour.
* A [rewarded set](../tokenomics.mdx#active-set) of `nym-nodes` selected for Nym network routing and mixing can be is currently 240 nodes in total and it's selected for each new epoch (60 min). The number can be adjusted - look here for the current value: [validator.nymtech.net/api/v1/epoch/reward_params](https://validator.nymtech.net/api/v1/epoch/reward_params)
* `nym-nodes` can run in mode `entry-gateway`, `exit-gateway` and `mixnode`, which are positioned into layers
* NymVPN users can chose to route through Nym Network in two ways:
- Mixnet: 5 layers routing and mixing - full privacy
- Wireguard: 2 layers routing, skipping 3 mixing layers - fast mode
* **The current reward system is [*Naive rewarding*](#naive-rewarding) - an intermediate step - where each layer get's rewarded the same**
* In the final model, nodes will get rewarded based on their layer position and the work they do (collected user tickets), where and the reward distribution per layer will be according to a [decision made by the operators](https://forum.nymtech.net/t/poll-what-should-be-the-split-of-mixmining-rewards-among-the-layers-of-the-nym-mixnet/407) as follows:
- 5-hop: 16%-16%-16%-16%-36%
- 2-hop: 33%-67%
* Currently Gateways earn rewards only from taking a part in the rewarded set. The operators can sign up to a grant program as a substitution for 2-hop routing.
* To read more about the final design and future implementation, see [*Roadmap*](#roadmap) chapter for more details.
## Rewards Logic & Calculation
**Note that in the current intermediate model we use one active set to reward all nodes and they are asign same (naive) work factor of 1 / 240, whether they work as Mixnode or Gateway of any kind, in both 2-hop and 5-hop mode. In reality it means that all nodes are rewarded within 5-hop reward scheme only.**
**However NymVPN client can chose any `nym-node --mode entry-gateway` and `--mode exit-gateway` in the network to route through the mixnet and as well as any of those which passed [wireguard probing test](https://harbourmaster.nymtech.net) to route as dVPN nodes.**
### Nym Network rewarded set distribution
<div>
<Tabs items={[
<strong>Mixnet mode (5-hop)</strong>,
<strong>dVPN mode (2-hop)</strong>,
]} defaultIndex="0">
<MyTab>
```ascii
Network
layer: 1. 2. 3. 4. 5.
--------
┌► mixnode ─┐ mixnode mixnode
│ │
Node entry │ │ exit
type: gateway ──┘ mixnode │ mixnode ┌─► mixnode ───► gateway
│ │
│ │
mixnode └─► mixnode ─┘ mixnode
```
| **Network layer** | **1** | **2** | **3** | **4** | **5** |
| :-- | :---: | :---: | :---: | :---: | :---: |
| Node functionality in layer | Entry Gateway | Mixnode | Mixnode | Mixnode | Exit Gateway |
| Nodes in [active set](tokenomics.mdx#active-set) | 50 | 40 | 40 | 40 | 70 |
| Naive rewarding: Rewards distribution per node | 1 / 240 | 1 / 240 | 1 / 240 | 1 / 240 | 1 / 240 |
| Final model: Rewards distribution per node | 0.16 / 240 | 0.16 / 240 | 0.16 / 240 | 0.16 / 240 | 0.36 / 240 |
</MyTab>
<MyTab>
```ascii
Network
layer: 1. 2.
--------
Node entry exit
type: gateway ──────────────────────────────────────────► gateway
```
| **Network layer** | **1** | **2** |
| :-- | :---: | :---: |
| Node functionality in layer | Entry Gateway | Exit Gateway |
| Naive rewarding: Nodes in [active set](tokenomics.mdx#active-set) | 50 | 70 |
| Naive rewarding: Rewards distribution per node | 1 / 240 | 1 / 240 | 1 / 240 | 1 / 240 | 1 / 240 |
| Final model: Active nodes | All following criteria for eligibility | All following criteria for eligibility |
| Final model: Rewards distribution per node | 0.33 \* collected_user_tickets | 0.67 \* collected_user_tickets |
</MyTab>
</Tabs>
</div>
### Rewarded Set Selection
For a node to be rewarded, the node must be part of a [Rewarded set](https://validator.nymtech.net/api/v1/epoch/reward_params) (which currently = active set) in the first place. The Rewarded set is freshly selected at the start of each epoch (every 60 min), and it consists of 240 Nym nodes that are probabilistically chosen from all the available nodes. These 240 nodes include 120 gateways and 120 mixnodes (40 for each of 3 mixnet layers).
Rewarded set nodes are randomly selected, and their selection chances increase with a node score that includes three parameters:
1. [Config score](#config-score-calculation): highest (`1`) when the node is running the latest version of the software with [T&C's accepted](../nodes/nym-node/setup.mdx#terms--conditions)
2. [Performance](#performance-calculation): highest (`1`) when the node is consistently online and correctly processes all the received traffic
3. [Stake saturation](../tokenomics.mdx#stake-saturation): including bond and delegated stake
Besides these values, the API is also looking whether the node is bonded in Mixnet smart contract as a Nym Node or legacy node (Mixnode or Gateway). **Only nodes bonded as Nym Node in Mixnet smart contract can be selected to the Rewrded set, if you haven't migrated your node yet, please [follow these steps](../nodes/nym-node/bonding#migrate-to-nym-node-in-mixnet-smart-contract)!**
**The node score is calculated with this formula:**
<Callout type="info" emoji="📌">
> **active_set_selection_probability = total_stake \* (( config_score \* node_performance ) ^ 20 )**
</Callout>
Note that the score helps prioritize some nodes over others. If all available nodes have the same score, then the selection is done uniformly at random. By raising the config and performance components to 20, values of these parameters that are below one incur a heavy penalization for the nodes selection chances.
Besides these values, the API is also checks whether the node is bonded in Mixnet smart contract as a Nym Node or legacy node (Mixnode or Gateway). **Only nodes bonded as Nym Node in Mixnet smart contract can be selected to the Rewrded set. Thus, if you haven't migrated your node yet, please [follow these steps](../nodes/nym-node/bonding#migrate-to-nym-node-in-mixnet-smart-contract)!**
#### Config Score Calculation
The nodes selection to the active set has a new parameter - `config_score`. Config score currently looks into three paramteres:
1. If the node binary is `nym-node` (not legacy `nym-mixnode` or `nym-gateway`): `1` if `True`, `0` if `False`
2. If [Terms & Conditions](../nodes/nym-node/setup.mdx#terms--conditions) are accepted: `1` if `True`, `0` if `False`
3. Version of `nym-node` binary: decreasing weight for outdated versions, as explained below
**The `config_score` parameter calculation formula:**
<Callout type="info" emoji="📌">
> **config_score = is_tc_accepted \* is_nym-node_binary \* ( 0.995 ^ ( ( X * versions_behind) ^ 1.65 ) )**
</Callout>
First two points have binary values of either 0 or 1, with a following logic:
| **Run `nym-node` binary** | **T&C's accepted** | **Value** |
| :-- | :-- | ---: |
| True | True | 1 |
| True | False | 0 |
| False | True | 0 |
| False | False | 0 |
Only if both conditions above are `True` the node can have any chance to be selected, as otherwise the probability will always be 0.
**The `versions_behind` parameter in `config_score` calculation**
From release `2024.14-crunch` (`nym-node v1.2.0`), the `config_score` parameter takes into account also nodes version. The "current version" is the one marked as `Latest` in our repository. The parameter `versions_behind` indicates the number of versions between the `Latest` version and the version run by the node, and it is factored into the config score with the formula:
<Callout type="info" emoji="📌">
> **0.995 ^ ( ( X * versions_behind ) ^ 1.65 )**
>
> where: <br />
> **X = 1; for patches** <br />
> **X = 10; for minor versions** <br />
> **X = 100; for major versions**
</Callout>
> The exact parameters are live accessible on [`/v1/status/config-score-details`](https://validator.nymtech.net/api/swagger/index.html#/Status/config_score_details).
Our versioning convention is: `major_version . minor_version . patch`
For example `nym-node` on version `1.2.0` is on 1st major version, 2nd minor and 0 patches.
Note that the `X` multiplier heavily lowers the `config_score` when nodes are outdated with respect to more significant updates. See the the table and graph below:
| **Version behind** | **Patches (X = 1)** | **Minor versions (X = 10)** | **Major versions (X = 100)** |
| :-- | --: | --: | --: |
| 0 (current version) | 1.0 | 1.0 | 1.0 |
| 1 | 0.995 | 0.7994 | 0.0000 |
| 2 | 0.9844 | 0.4953 | 0.0000 |
| 3 | 0.9698 | 0.2536 | 0.0000 |
| 4 | 0.9518 | 0.1102 | 0.0000 |
| 5 | 0.9311 | 0.0413 | 0.0000 |
![](/images/operators/tokenomics/reward_version_graph.png)
As you can see above, the algorithm is designed to give maximum selection score (`1`) to the latest version, while non-upgraded nodes receive a lower score. The score decreases faster when the node has failed to make a major version upgrade, and slower when the node is behind only with minor updates. This scoring de-prioritizes the selection of outdated nodes, even if their saturation and performance are high. Nodes are selected probabilistically in each epoch (60 min), according to their scores, to be part of the Rewarded set. This scoring mechanism gives priority to the operators running up-to-date nodes, ensuring that the network is as updated as possible.
#### Performance Calculation
Performance is measured by Nym Network Monitor which sends thousands of packages through different routes every 15 minutes and measures how many were dropped on the way. Test result represents percentage of packets succesfully returned (can be anything between 0 and 1). Performance value is nodes average of these tests in last 24h.
Good performance is much more essential than [total stake](../tokenomics.mdx#stake-saturation), because it's lifted to 20th power in the selection formula.
For a comparison we made an example with 5 nodes, where first number is node performance and second stake saturation (assuming all of them `config_score` = 1 for simplification):
<br />
<AccordionTemplate name="✏️ Example: Performance ^ 20 * total_stake calculation">
> node_1 = 1.00 ^ 20 \* 1.0 = 1 <br />
> node_2 = 1.00 ^ 20 \* 0.5 = 0.5 <br />
> node_3 = 0.99 ^ 20 \* 1.0 = 0.818 <br />
> node_4 = 0.95 ^ 20 \* 1.0 = 0.358 <br />
> node_5 = 0.90 ^ 20 \* 1.0 = 0.122 <br />
</AccordionTemplate>
As you can see the performance (also known as *Routing score*) is much more important during the Rewarded set selection. A node with 100% performance but only 50% stake saturation has much bigger chance to be chosen than a node with 95% performance but full stake saturation and incomparably bigger chance than 90% performing node with 100% stake saturation.
The nodes are chosen probababilistically in each epoch (60 min), so even nodes with lower performance will eventually be chosen, just much less often, as their chances decrease.
### Layer Distribution
Once the rewarded set (currently 120 Mixnodes and 120 Gateways) is selected, the nodes can start to route and mix packets in the Nym Network. Each hour a total of 6000 NYM is distributed between the layers from Mixmining pool. Currently in our *Naive rewarding* intermediate design, all layers get a same portion, therefore each node is *naively* assigned same working factor and therefore earns 1/240 of the rewards per epoch.
We are working on the final design with the ratio implementing a [decision made by the operators](https://forum.nymtech.net/t/poll-what-should-be-the-split-of-mixmining-rewards-among-the-layers-of-the-nym-mixnet/407) as follows:
<Callout type="info" borderColor="#008080" backgroundColor="#20b2aa" emoji="📌">
>5-hop mixnet mode: <br />
> 16%; 16%; 16%; 16%; 36% <br/>
> <br/>
> 2-hop dVPN mode: <br />
> 33%; 67%
</Callout>
{/*
In real numbers: If hourly revenue to all 240 nodes is 6000 NYM, the layer compartmentalisation is 960 NYM for Entry Gateway layer and each Mixnode layer and 2160 NYM for Exit Gateway layer. The calculation is in the example below:
<Callout borderColor="#966fd6" backgroundColor="#b19cd9" emoji="">
<AccordionTemplate name="Example">
> Purple collapsible for examples.
5-hop mixnet mode:
$0.16 * 6000 = 960; 0.16 * 6000 = 960; 0.16 * 6000 = 960; 0.16 * 6000 = 960; 0.36 * 6000 2160$
2-hop wireguard mode:
$33\% - 67\%$
</AccordionTemplate>
</Callout>
### Node Rewards within Same Layer
### Operation Cost, Profit Margin & Delegation
### APR Calculation
*/}
## Roadmap
We are working on the final architecture of [*Fair Mixnet*](#fair-mixnet) tokenomics implementation. The current design is called [*Naive rewarding*](#naive-rewarding). This is an intermediate step, expecting operators to migrate to `nym-node` in Mixnet smart contract and be able to recieve delegations and earn rewards for any `nym-node` functionality, in opposite to the past system, where only Mixnodes were able to recieve delegations and rewards.
On November 5th, we presented a release roadmap in live [Operators Townhall](https://www.youtube.com/watch?v=3G1pJqvO2VM) where we explained in detail the steps of Nym node and tokenomics development and the effect it will have on node operators and put it into a rough timeline.
![](/images/operators/tokenomics/roadmap_24-q4.png)
### Naive Rewarding
***Naive rewarding* is the current tokenomics design.** The table below lists features and logic of this design.
![](/images/operators/tokenomics/roadmap_naive.png)
### Fair Mixnet
***Fair Mixnet* is the final architecture model that we work towards.** The table below lists features and logic of the design once implemented.
![](/images/operators/tokenomics/roadmap_fair.png)
{/*
## Stats
NYM token is capped at 1b. Below is a table with actual\* token supply distribution.
mdrun cd ../../../scripts/cdmrun && ./api_targets.py s --api mainnet --endpoint circulating-supply --format
ADD MIXNET STATS GRAPHS
DROPPING THIS FROM THE MAINTENANCE PAGE - NEEDS REWORK
## Mix Node Reward Estimation API endpoint
THIS NEEDS REDO
The Reward Estimation API endpoint allows Mix Node operators to estimate the rewards they could earn for running a Nym Mix Node with a specific `MIX_ID`.
> The `<MIX_ID>` can be found in the "Mix ID" column of the [Harbourmaster](https://harbourmaster/nymtech.net).
The endpoint is a particularly common for Mix Node operators as it can provide an estimate of potential earnings based on factors such as the amount of traffic routed through the Mix Node, the quality of the Mix Node's performance, and the overall demand for Mix Nodes in the network. This information can be useful for Mix Node operators in deciding whether or not to run a Mix Node and in optimizing its operations for maximum profitability.
We have available API endpoints which can be accessed via [Swagger UI page](https://validator.nymtech.net/api/swagger/index.html). Or by querying the endpoints directly:
```sh
curl -X 'GET' \
'https://validator.nymtech.net/api/v1/status/mixnode/<MIX_ID>/reward-estimation' \
-H 'accept: application/json'sh
```
Query response will look like this:
```sh
"estimation": {
"total_node_reward": "942035.916721770541325331",
"operator": "161666.263307386408152071",
"delegates": "780369.65341438413317326",
"operating_cost": "54444.444444444444444443"
},
```
> The unit of value is measured in `uNYM`.
<Callout borderColor="#008080" backgroundColor="#20b2aa" emoji="📌">
$1 \ NYM = 1 \_ 000 \_ 000 \ uNYM$
</Callout>
- `estimated_total_node_reward` - An estimate of the total amount of rewards that a particular Mix Node can expect to receive during the current epoch. This value is calculated by the Nym Validator based on a number of factors, including the current state of the network, the number of Mix Nodes currently active in the network, and the amount of network traffic being processed by the Mix Node.
- `estimated_operator_reward` - An estimate of the amount of rewards that a particular Mix Node operator can expect to receive. This value is calculated by the Nym Validator based on a number of factors, including the amount of traffic being processed by the Mix Node, the quality of service provided by the Mix Node, and the operator's stake in the network.
- `estimated_delegators_reward` - An estimate of the amount of rewards that Mix Node delegators can expect to receive individually. This value is calculated by the Nym Validator based on a number of factors, including the amount of traffic being processed by the Mix Node, the quality of service provided by the Mix Node, and the delegator's stake in the network.
- `estimated_node_profit` - An estimate of the profit that a particular Mix node operator can expect to earn. This value is calculated by subtracting the Mix Node operator's `operating_costs` from their `estimated_operator_reward` for the current epoch.
- `estimated_operator_cost` - An estimate of the total cost that a particular Mix Node operator can expect to incur for their participation. This value is calculated by the Nym Validator based on a number of factors, including the cost of running a Mix Node, such as server hosting fees, and other expenses associated with operating the Mix Node.
*/}
{/*
?DROPPING THIS FROM THE OLD MAINTENANCE PAGE
### Mix Node Reward Estimation API endpoint
The Reward Estimation API endpoint allows Mix Node operators to estimate the rewards they could earn for running a Nym Mix Node with a specific `MIX_ID`.
> The `<MIX_ID>` can be found in the "Mix ID" column of the [Network Explorer](https://nym.com/explorer).
The endpoint is a particularly common for Mix Node operators as it can provide an estimate of potential earnings based on factors such as the amount of traffic routed through the Mix Node, the quality of the Mix Node's performance, and the overall demand for Mix Nodes in the network. This information can be useful for Mix Node operators in deciding whether or not to run a Mix Node and in optimizing its operations for maximum profitability.
Using this API endpoint returns information about the Reward Estimation:
```sh
/status/mixnode/<MIX_ID>/reward-estimation
```
Query Response:
```sh
"estimation": {
"total_node_reward": "942035.916721770541325331",
"operator": "161666.263307386408152071",
"delegates": "780369.65341438413317326",
"operating_cost": "54444.444444444444444443"
},
```
> The unit of value is measured in `uNYM`.
- `estimated_total_node_reward` - An estimate of the total amount of rewards that a particular Mix Node can expect to receive during the current epoch. This value is calculated by the Nym Validator based on a number of factors, including the current state of the network, the number of Mix Nodes currently active in the network, and the amount of network traffic being processed by the Mix Node.
- `estimated_operator_reward` - An estimate of the amount of rewards that a particular Mix Node operator can expect to receive. This value is calculated by the Nym Validator based on a number of factors, including the amount of traffic being processed by the Mix Node, the quality of service provided by the Mix Node, and the operator's stake in the network.
- `estimated_delegators_reward` - An estimate of the amount of rewards that Mix Node delegators can expect to receive individually. This value is calculated by the Nym Validator based on a number of factors, including the amount of traffic being processed by the Mix Node, the quality of service provided by the Mix Node, and the delegator's stake in the network.
- `estimated_node_profit` - An estimate of the profit that a particular Mix node operator can expect to earn. This value is calculated by subtracting the Mix Node operator's `operating_costs` from their `estimated_operator_reward` for the current epoch.
- `estimated_operator_cost` - An estimate of the total cost that a particular Mix Node operator can expect to incur for their participation. This value is calculated by the Nym Validator based on a number of factors, including the cost of running a Mix Node, such as server hosting fees, and other expenses associated with operating the Mix Node.
### Validator: Installing and configuring nginx for HTTPS
#### Setup
[Nginx](https://www.nginx.com/resources/glossary/nginx) is an open source software used for operating high-performance web servers. It allows us to set up reverse proxying on our validator server to improve performance and security.
Install `nginx` and allow the 'Nginx Full' rule in your firewall:
*/}