[DOCs/operators]: Release notes v2024.14-crunch & config score updates (

#5222)

* initialise tokenomics graph

* generate reward version config graph

* update tokenomics

* edit typo

* initialise release crunch release notes

* operators update

* add points to changelog

* update version graph and selection

* update iptables configuration

* add features to changelog

* comment redundant

* address review comments

* PR finish

documentation/docs/components/outputs/api-scraping-outputs/nyx-outputs/circulating-supply.md

@@ -1 +1 @@
-803_103_234
+804_560_131

documentation/docs/components/outputs/api-scraping-outputs/nyx-outputs/stake-saturation.md

@@ -1 +1 @@
-1_016_987
+1_020_023

documentation/docs/components/outputs/api-scraping-outputs/nyx-outputs/staking-target.md

@@ -1 +1 @@
-401_551_617
+402_280_065

documentation/docs/components/outputs/api-scraping-outputs/nyx-outputs/token-table.md

@@ -1,7 +1,7 @@
 | **Item**           | **Description**                                       |   **Amount in NYM** |
 |:-------------------|:------------------------------------------------------|--------------------:|
 | Total Supply       | Maximum amount of NYM token in existence              |       1_000_000_000 |
-| Mixmining Reserve  | Tokens releasing for operators rewards                |         196_896_265 |
+| Mixmining Reserve  | Tokens releasing for operators rewards                |         195_439_368 |
 | Vesting Tokens     | Tokens locked outside of cicrulation for future claim |                 500 |
-| Circulating Supply | Amount of unlocked tokens                             |         803_103_234 |
-| Stake Saturation   | Optimal size of node self-bond + delegation           |           1_016_987 |
+| Circulating Supply | Amount of unlocked tokens                             |         804_560_131 |
+| Stake Saturation   | Optimal size of node self-bond + delegation           |           1_020_023 |

documentation/docs/components/outputs/api-scraping-outputs/time-now.md

@@ -1 +1 @@
-Monday, November 25th 2024, 13:24:04 UTC
+Friday, December 6th 2024, 10:16:06 UTC

documentation/docs/components/outputs/command-outputs/nym-api-help.md

@@ -9,9 +9,9 @@ Commands:
 
 Options:
   -c, --config-env-file <CONFIG_ENV_FILE>
-          Path pointing to an env file that configures the Nym API
+          Path pointing to an env file that configures the Nym API [env: NYMAPI_CONFIG_ENV_FILE_ARG=]
       --no-banner
-          A no-op flag included for consistency with other binaries (and compatibility with nymvisor, oops)
+          A no-op flag included for consistency with other binaries (and compatibility with nymvisor, oops) [env: NYMAPI_NO_BANNER_ARG=]
   -h, --help
           Print help
   -V, --version

documentation/docs/components/outputs/command-outputs/nym-node-run-help.md

@@ -44,6 +44,8 @@ Options:
           Specify whether detailed system crypto hardware information should be exposed. default: true [env: NYMNODE_HTTP_EXPOSE_CRYPTO_HARDWARE=] [possible values: true, false]
       --mixnet-bind-address <MIXNET_BIND_ADDRESS>
           Address this node will bind to for listening for mixnet packets default: `0.0.0.0:1789` [env: NYMNODE_MIXNET_BIND_ADDRESS=]
+      --mixnet-announce-port <MIXNET_ANNOUNCE_PORT>
+          If applicable, custom port announced in the self-described API that other clients and nodes will use. Useful when the node is behind a proxy [env: NYMNODE_MIXNET_ANNOUNCE_PORT=]
       --nym-api-urls <NYM_API_URLS>
           Addresses to nym APIs from which the node gets the view of the network [env: NYMNODE_NYM_APIS=]
       --nyxd-urls <NYXD_URLS>
@@ -60,6 +62,8 @@ Options:
           The prefix denoting the maximum number of the clients that can be connected via Wireguard. The maximum value for IPv4 is 32 and for IPv6 is 128 [env: NYMNODE_WG_PRIVATE_NETWORK_PREFIX=]
       --verloc-bind-address <VERLOC_BIND_ADDRESS>
           Socket address this node will use for binding its verloc API. default: `0.0.0.0:1790` [env: NYMNODE_VERLOC_BIND_ADDRESS=]
+      --verloc-announce-port <VERLOC_ANNOUNCE_PORT>
+          If applicable, custom port announced in the self-described API that other clients and nodes will use. Useful when the node is behind a proxy [env: NYMNODE_VERLOC_ANNOUNCE_PORT=]
       --entry-bind-address <ENTRY_BIND_ADDRESS>
           Socket address this node will use for binding its client websocket API. default: `0.0.0.0:9000` [env: NYMNODE_ENTRY_BIND_ADDRESS=]
       --announce-ws-port <ANNOUNCE_WS_PORT>

documentation/docs/pages/operators/nodes/nym-node/configuration.mdx

@@ -301,8 +301,10 @@ chmod +x network_tunnel_manager.sh && \
 
 ###### 3. Setup IP tables rules
 
-- Apply the rules for IPv4 and IPv6:
+- Delete IP tables rules for IPv4 and IPv6 and apply new ones:
 ```sh
+./network_tunnel_manager.sh remove_duplicate_rules nymtun0
+
 ./network_tunnel_manager.sh apply_iptables_rules
 ```
 
@@ -363,9 +365,11 @@ operation check_nymtun_iptables completed successfully.
 ```
 </AccordionTemplate>
 
-###### 5. Apply rules for wireguad routing
+###### 5. Remove old and apply new rules for wireguad routing
 
 ```sh
+/network_tunnel_manager.sh remove_duplicate_rules nymwg
+
 ./network_tunnel_manager.sh apply_iptables_rules_wg
 ```
 
@@ -374,8 +378,15 @@ operation check_nymtun_iptables completed successfully.
 ```sh
 ./network_tunnel_manager.sh configure_dns_and_icmp_wg
 ```
+###### 7. Adjust and validate IP forwarding
+
+```sh
+./network_tunnel_manager.sh adjust_ip_forwarding
+
+./network_tunnel_manager.sh check_ipv6_ipv4_forwarding
+```
 
-###### 7. Check `nymtun0` interface and test routing configuration
+###### 8. Check `nymtun0` interface and test routing configuration
 
 ```sh
 ip addr show nymtun0
@@ -409,7 +420,7 @@ ip addr show nymtun0
 - **Note:** WireGuard will return only IPv4 joke, not IPv6. WG IPv6 is under development. Running IPR joke through the mixnet with `./network_tunnel_manager.sh joke_through_the_mixnet` should work with both IPv4 and IPv6!
 
 
-###### 8. Enable wireguard
+###### 9. Enable wireguard
 
 Now you can run your node with the `--wireguard-enabled true` flag or add it to your [systemd service config](#systemd). Restart your `nym-node` or [systemd](#2-following-steps-for-nym-nodes-running-as-systemd-service) service (recommended):
 

documentation/docs/pages/operators/nodes/nym-node/configuration/_meta.json

@@ -1,3 +1,3 @@
 {
-  "proxy-configuration": "WSS & Reverese Proxy"
+  "proxy-configuration": "WSS & Reverse Proxy"
 }

documentation/docs/pages/operators/nodes/nym-node/setup.mdx

@@ -17,10 +17,10 @@ This documentation page provides a guide on how to set up and run a [NYM NODE](.
 ```sh
 nym-node
 Binary Name:        nym-node
-Build Timestamp:    2024-11-29T13:10:51.813092288Z
-Build Version:      1.1.12
-Commit SHA:         4a9a5579c40ad956163ea02e01d7b53aef2ac8ef
-Commit Date:        2024-11-29T14:06:32.000000000+01:00
+Build Timestamp:    2024-12-11T13:49:11.974104790Z
+Build Version:      1.2.0
+Commit SHA:         a491e6a71a8cf862d77defd740a4ee8d65d8292a
+Commit Date:        2024-12-11T10:28:47.000000000+01:00
 Commit Branch:      HEAD
 rustc Version:      1.83.0
 rustc Channel:      stable
@@ -33,6 +33,7 @@ cargo Profile:      release
 
 ## Summary
 
+
 <VarInfo/ >
 
 To run a new node, you can simply execute the `nym-node` command without any flags. By default, the node will set necessary configurations. If you later decide to change a setting, you can use the `-w` flag.

documentation/docs/pages/operators/tokenomics/mixnet-rewards.mdx

@@ -12,6 +12,10 @@ 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)
@@ -42,6 +46,7 @@ To make it easier for the reader, we use a highlighting line on the left side, w
 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.
@@ -126,34 +131,94 @@ This is a quick summary, to understand the full picture, please see detailed [*R
 </div>
 
 
-### Active Set Selection
-
-*Performance matters!*
+### 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 active set is selected in the beginning of each epoch (every 60min) where total of 240 Nym nodes - represented by 120 mixnodes and 120 gateways, are randomly allocated across the layers.
 
-The algorithm choosing nodes into the active set takes into account node's performance and [stake saturation](../tolkenomics.mdx#stake-saturation), both values being between 0 and 1 and config score which is either 0 or 1.
+The algorithm choosing nodes into the active set takes into account these parameters:
+
+1. [Config score](#config-score-calculation)
+2. [Performance](#performance-calculation)
+3. [Stake saturation](../tokenomics.mdx#stake-saturation)
+
+Besides these values, the API is also looking whther 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 Rewarded set selection probablity formula:**
+
+<Callout type="info" emoji="📌">
+> **active_set_selection_probability = config_score \* ( node_performance ^ 20 ) \* stake_saturation**
+</Callout>
+
+#### Config Score Calculation
+
+The nodes selection to the active set has a new parameter - `config_score`. Config score currently looks into three paramteres:
 
-**Config score is introduced:** The nodes selection to the active set has a new parameter - `config_score`. Config score currently looks if the node binary is `nym-node` (not legacy `nym-mixnode` or `nym-gateway`) **AND** if [Terms & Conditions](nodes/nym-node/setup.mdx#terms--conditions) are accepted. Config score has binary values of either 0 or 1, with a following logic:
+1. If the node binary is `nym-node` (not legacy `nym-mixnode` or `nym-gateway`)
+2. If [Terms & Conditions](../nodes/nym-node/setup.mdx#terms--conditions) are accepted.
+3. Version of `nym-node` binary
+
+**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>
 
-| **Run `nym-node` binary** | **T&C's accepted** | **`config_score`** |
+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                  |
-| True                      | True               | 1                  |
 
+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 `version_behind` parameter in `config_score` calculation**
 
-The entire active set selection probablity:
+From release `2024.14-crunch` (`nym-node v1.2.0`), the `config_score` parameter takes into account also nodes version. Current version is the
+one marked as `Latest` in our repository. From that one we count the parameter `version_behind`, where every version back the number of `versions_behind` increases by 1 in this formula:
 
 <Callout type="info" emoji="📌">
-> **active_set_selection_probability = config_score \* stake_saturation \* node_performance ^ 20**
+> **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>
 
-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 and not 0):
+> 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. 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 on above, the algorithm is designed to give maximum probability (`1`) to the latest version and exponentialy dicrease the probability to non-upgraded nodes where the more important version the node is behind, the faster the cliff. This eliminates any older nodes despite their saturation and performance to take place in the Rewarded set and gives a priority to the operators running up-to-date nodes, ensuring as strong network 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 [stake saturation](../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):
 
 <br />
-<AccordionTemplate name="✏️  Example: Reward set selection probability calculation">
+<AccordionTemplate name="✏️  Example: Reward set selection algorithm 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 />
@@ -201,7 +266,7 @@ $33\% - 67\%$
 
 ## 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, 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.
+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.
 

documentation/scripts/rewards_version_graph.py

@@ -0,0 +1,67 @@
+import matplotlib.pyplot as plt
+import matplotlib.axes as ax
+import matplotlib.pylab as pylab
+from matplotlib.pyplot import figure
+import numpy as np
+
+plt.style.use('dark_background')
+
+a = 0.995
+b = 1.65
+
+# make data
+x1 = [0,1,2,3,4,5]
+x2 = x1
+x3 = x1
+x4 = x1
+
+y1 = [a**((v*1)**b) for v in x1]
+y2 = [a**((v*10)**b) for v in x1]
+y3 = [a**((v*100)**b) for v in x1]
+# y4 = [a**((11)**b) for v in x1]
+
+f = plt.figure()
+f.set_figwidth(12)
+f.set_figheight(9)
+
+# plot
+#fig, ax = plt.subplots()
+plt.plot(x1,y1, label=f'Patches behind:             config_score_multiplier = {a} ^ ((1 * versions_behind) ^ {b})')
+plt.plot(x2,y2, label=f'Minor versions behind:  config_score_multiplier = {a} ^ ((10 * versions_behind) ^ {b})')
+plt.plot(x3,y3, label=f'Major versions behind:  config_score_multiplier = {a} ^ ((100 * versions_behind) ^ {b})')
+#ax.plot(x, y, linewidth=2.0)
+
+
+# naming the x axis
+plt.xlabel('Nym Node versions behind the current one', fontsize=20)
+
+
+# naming the y axis
+plt.ylabel('Config score multiplier', fontsize=20)
+
+# giving a title to my graph
+plt.title('Nym node version config score multiplier', fontsize=28)
+
+
+#ax.Axes.set_xticks([x])
+#ax.Axes.set_yticks([y])
+
+plt.legend(fontsize=12)
+
+#params = {'legend.fontsize': 20,
+#         'axes.labelsize': 24,
+#         'axes.titlesize':'x-large',
+#         'xtick.labelsize':20,
+#         'ytick.labelsize':20}
+#
+#pylab.rcParams.update(params)
+
+# set the limits
+plt.xlim([0, 5])
+plt.ylim([0,1])
+
+
+
+#plt.show()
+
+plt.savefig('../docs/public/images/operators/tokenomics/reward_version_graph.png')