From f72a24608dce25eb2209704b87d9423a0bf293de Mon Sep 17 00:00:00 2001 From: serinko <97586125+serinko@users.noreply.github.com> Date: Mon, 12 Aug 2024 16:05:57 +0200 Subject: [PATCH] finish fair-mixnet page initial draft --- documentation/operators/src/SUMMARY.md | 4 +-- .../operators/src/tokenomics/fair-mixnet.md | 19 +++++------ .../src/tokenomics/mixnet-rewards.md | 22 ++++++------- documentation/scripts/cmdrun/api_targets.py | 33 +++++++++++-------- 4 files changed, 41 insertions(+), 37 deletions(-) diff --git a/documentation/operators/src/SUMMARY.md b/documentation/operators/src/SUMMARY.md index 2e6eafd80a..5157621200 100644 --- a/documentation/operators/src/SUMMARY.md +++ b/documentation/operators/src/SUMMARY.md @@ -48,8 +48,8 @@ # Token Economics - [Fair Mixnet](tokenomics/fair-mixnet.md) - - [Nym: Operators Rewards](tokenomics/mixnet-rewards.md) - - [Nyx: Validator Rewards](tokenomics/validator-rewards.md) +- [Nym Operators Rewards](tokenomics/mixnet-rewards.md) +- [Nyx Validator Rewards](tokenomics/validator-rewards.md) # FAQ diff --git a/documentation/operators/src/tokenomics/fair-mixnet.md b/documentation/operators/src/tokenomics/fair-mixnet.md index 0cfda15d63..5758cc4632 100644 --- a/documentation/operators/src/tokenomics/fair-mixnet.md +++ b/documentation/operators/src/tokenomics/fair-mixnet.md @@ -7,7 +7,7 @@ Nym Network is composed of two main elements, the Mixnet represented by [Nym Nodes](../nodes/nym-node.md) routing and mixing the data packets, and Nyx blockchain based on [validator set](validator-rewards.md), using smart contracts (based on [cosmwasm]()) to monitor and reward Nym Nodes by querying API endpoints and distributing NYM token to operators from Mixmining pool. All Nym nodes and validators are run by decentralised community of operators. * 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, cisit [nymtech.net/about/token](https://nymtech.net/about/token) +* For a more comprehensive overview, live data and supply graphs, visit [*nymtech.net/about/token*](https://nymtech.net/about/token) **Formulas and Examples Annotation** @@ -27,11 +27,11 @@ Besides the Mixnet itself, Nym Network is based on its own blockchain Nyx (IBC o * **Incentives:** Distribute rewards to decentralised nodes based on mixing and routing (work). This dynamic ensures that the network is as robust as possible - the nodes are chosen every hour according to their performance. -* **Network take over defense:** Another decisive factore for a node to be chosen to the network active set is reputation. Reputation is a size of stake (delegation) where delegators earn proportional percentage of nodes rewards. +* **Network take over defense:** Another decisive factor for a node to be chosen to the network active set is reputation. Reputation is a size of stake (delegation) where delegators earn proportional percentage of nodes rewards. * **Centralisation defense:** Any node can only have a certain stake (called stake saturation) to earn maximum rewards, increasing stake level per node leads to decreasing rewards for the operator and all delegators. This feature makes it more difficult for whales to over-stake their nodes or to attract more delegators (stakers) as they would become dis-advantaged. -To learn more about rewards calculation and distributtion, read the next page [*Nym Operators Rewards*](mixnet-rewards.md). +To learn more about rewards calculation and distribution, read the next page [*Nym Operators Rewards*](mixnet-rewards.md). ### Utility @@ -42,17 +42,17 @@ Nyx blockchain's validators run API to monitor the network and node performance. On one hand node operators get [rewarded](mixnet-rewards.md) for the work they do, but their revenue is not forgranted. Only best performing nodes with a solid reputation can take part in the network. This creates an incentive for people to operate Nym nodes as quality and reliable service. The reputation system also works as a network defense against a large adversary take over or sybil attacks. -On the other, node reputation is calculated by delegation. Delegation is a stake done by NYM token holders on top of nodes they want to support to join the network as it compensate the stakers with APR. Therefore there is an incetive for NYM holders to stake their token on top of nodes which they believe will perform well. To prevent a whale take-over and centralisation, the revenue grows alongside nodes stake size only until a certain point, after which the rewards per staker start to decrease. We call this mark *node stake saturation*. +On the other, node reputation is calculated by delegation. Delegation is a stake done by NYM token holders on top of nodes they want to support to join the network as it compensate the stakers with APR. Therefore there is an incetive for NYM holders to stake their token on top of nodes which they believe will perform well. To prevent a whale takeover and centralisation, the revenue grows alongside nodes stake size only until a certain point, after which the rewards per staker start to decrease. We call this mark *node stake saturation*. Thanks to Nyx blockchain API monitoring, the flow is dynamic and constantly optimized based on live metrics. Below is a detailed explanation and reckoning of Nym tokenomics logic. ### Tokenomics -Before we can arrive to a full comprehension of [node operators rewards](mixnet-rewards.md) and [delegators APR height](https://nymtech.net/about/token) we need to understand some basic logic and stats of Nym token economics. All the data can be [queryied from valdator API](#query-tokenomics-api). +Before we can arrive to a full comprehension of [node operators rewards](mixnet-rewards.md) and [delegators APR height](https://nymtech.net/about/token) we need to understand some basic logic and stats of Nym token economics. All the data can be [queried from valdator API](#query-tokenomics-api). **Supply** -NYM token is capped at 1b. Visit [Nym token page](https://nymtech.net/about/token) to see live data and graphs. Current\* circulating supply is NYM. +NYM token is capped at 1b. Visit [Nym token page](https://nymtech.net/about/token) to see live data and graphs. Current\* circulating supply is NYM. **Staking target** @@ -64,8 +64,7 @@ $staking\ target = staking\ supply\ scale\ factor * circulating\ supply$ Staking supply scale factor is currently\* it's set to be . -The value of this variable can be changed to optimize the metrics of the network. With a current circulating supply of NYM and staking supply scale factor , the staking target is NYM. - +The value of this variable can be changed to optimize the metrics of the network. With a current circulating supply of NYM and staking supply scale factor , the staking target is NYM. **Stake saturation** @@ -79,11 +78,11 @@ $stake\ saturation = circulating\ supply * staking\ target\ /\ total\ \#\ of\ no - staking target / # of nodes in the network --> -With current\* circulating supply of NYM, staking target of NYM divided the sum of [nodes bonded to the network](https://harbourmaster.nymtech.net), the stake saturation level is NYM per node. +With current\* circulating supply of NYM, staking target of NYM, divided by the sum of [nodes bonded to the network](https://harbourmaster.nymtech.net), the stake saturation level is NYM per node. **Active set** -Nym Network needs an optimised number of nodes to route and mix the packets. This healthy balance lies in between being too congested - which would detriment speed and user experience - on one side, and having too little traffic per node - which would could weaken anonymity - on the other. Currewntly the active set is 240 nodes, 120 with Gateway functionality (entry and exit layer) and 120 as Mixnode (2nd, 3rd and 4th mixing layer). The active set is chosen in the beggining of each epoch (60min). The best performing and reputated (stake saturation) nodes are chosen. Performace is much more ample as you can see in the formula below: +Nym Network needs an optimised number of nodes to route and mix the packets. This healthy balance lies in between being too congested - which would detriment speed and user experience - on one side, and having too little traffic per node - which would could weaken anonymity - on the other. Currently the active set is 240 nodes, 120 with Gateway functionality (entry and exit layer) and 120 as Mixnode (2nd, 3rd and 4th mixing layer). The active set is chosen in the beginning of each epoch (60min). The best performing and reputated (stake saturation) nodes are chosen. Performance is much more ample as you can see in the formula below: ```admonish tip title="" $$ diff --git a/documentation/operators/src/tokenomics/mixnet-rewards.md b/documentation/operators/src/tokenomics/mixnet-rewards.md index ed090c2f34..c679e18c61 100644 --- a/documentation/operators/src/tokenomics/mixnet-rewards.md +++ b/documentation/operators/src/tokenomics/mixnet-rewards.md @@ -5,7 +5,7 @@ ``` * 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, cisit [nymtech.net/about/token](https://nymtech.net/about/token) +* For a more comprehensive overview, live data and supply graphs, visit [*nymtech.net/about/token*](https://nymtech.net/about/token) **Formulas and Examples Annotation** @@ -40,14 +40,14 @@ This is a quick summarry, to understand the full picture, please see detailed [* * The reward distribution is per layer 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: (In future) 33%-67% - - Currently Gateways earn rewards only from 5-hop mode. The operators can sign up to a grant program as a substituion for 2-hop routing. + - Currently Gateways earn rewards only from 5-hop mode. The operators can sign up to a grant program as a substitution for 2-hop routing. * Each node is rewarded according to the layer in which it's positioned in the given epoch, divided uniformly between all nodes in that layer. * Nodes are selected to the active set based on their performance and stake saturation (slef bond + delegation) * In future a ticket system will be implemented where nodes will be rewarded according to the work they perform, with a revenue for both 2-hop and 5-hop work. The uniform naive distribution is an intermediate step. See [*Roadmap*](#roadmap) chapter for more details. ## Rewards Logic & Calculation -**Note that in the current intermediate model we use one active set for both 2-hop and 5-hop routing Gateways. In reality it means that all nodes are rewarded only within 5-hop reward scheme only. In the meantime, given that the 120 Gateways within the active set route traffic for 2-hop wireguard mode as well, without any extra rewards, the operators can get substituion in the form of grants.** +**Note that in the current intermediate model we use one active set for both 2-hop and 5-hop routing Gateways. In reality it means that all nodes are rewarded only within 5-hop reward scheme only. In the meantime, given that the 120 Gateways within the active set route traffic for 2-hop wireguard mode as well, without any extra rewards, the operators can get substitution in the form of grants.** ~~~admonish tip title="Nym network active set distribution" ```ascii @@ -89,7 +89,7 @@ This is a quick summarry, to understand the full picture, please see detailed [* For a node to be rewarded, the node must be part of an active set in the first place. The active set is selected in the beginning of each epoch (every 60min) where total of 240 nodes - represented by 120 mixnodes and 120 gateways, are randomly allocated across the layers. Mixnodes only work within the given layer, while any Exit Gateway can be chosen by a client as an Entry Gateway, not vice versa. -The algorithm chosing nodes into the active set takes into acount node's performance and stake saturation, both values being between 0 and 1. +The algorithm choosing nodes into the active set takes into account node's performance and stake saturation, both values being between 0 and 1. ```admonish tip title="" $$ @@ -116,7 +116,7 @@ As you can see the performance (also known as *Routing score*) is much more impo ### Layer Distribution -Once the active set of 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 distributedbetween the layers from Mixmining pool, following the ratio 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: +Once the active set of 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, following the ratio 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: ```admonish tip title="" 5-hop mixnet mode:
@@ -162,14 +162,15 @@ NYM token is capped at 1b. Below is a table with actual\* token supply distribut ## 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 `` can be found in the "Mix ID" column of the [Network Explorer](https://explorer.nymtech.net/network-components/mixnodes/active). +> The `` can be found in the "Mix ID" column of the [Harbourmaster](https://harbourmaster/nymtech.net). + 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: @@ -193,9 +194,8 @@ Query response will look like this: > The unit of value is measured in `uNYM`. ```admonish tip title="" -$1 NYM = 1000000 uNYM$ +$1 \ NYM = 1 \_ 000 \_ 000 \ 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. diff --git a/documentation/scripts/cmdrun/api_targets.py b/documentation/scripts/cmdrun/api_targets.py index 0f54e12dc1..d7491dec27 100755 --- a/documentation/scripts/cmdrun/api_targets.py +++ b/documentation/scripts/cmdrun/api_targets.py @@ -83,12 +83,20 @@ def display_supply_table(response, args): df = df.rename(columns={'index1': '**Item**', 'amount': '**Amount in NYM**'}) df['**Item**'] = df['**Item**'].apply(remove_underscore) df['**Amount in NYM**'] = df['**Amount in NYM**'].apply(convert_u_nym) - df['**Amount in NYM**'] = df['**Amount in NYM**'].apply(thousand_separator, args=(separator, )) desc_column = _get_desc_column() df.insert(1, '**Description**', desc_column, True) + stake_saturation = _get_stake_saturation() + df.loc[len(df.index)] = ['Stake Saturation', 'Optimal size of node self-bond + delegation', stake_saturation] + df['**Amount in NYM**'] = df['**Amount in NYM**'].apply(thousand_separator, args=(separator, )) table = df.to_markdown(index=False,colalign=("left","left","right")) print(table) +def _get_stake_saturation(): + reward_params = get_api("https://validator.nymtech.net/api/v1/epoch/reward_params") + stake_saturation = get_dict_value(reward_params,["interval","stake_saturation_point"]) + stake_saturation = convert_u_nym(stake_saturation) + return stake_saturation + def _get_desc_column(): supply = "Maximum amount of NYM token in existence" reserve = "Tokens releasing for operators rewards" @@ -109,24 +117,19 @@ def read_supply(args): elif args.format == "markdown": display_supply_table(response, args) else: - print(response) + value = response + print(value) elif args.endpoint == "epoch/reward_params": - value = get_reward_params(response, args) - value = thousand_separator(value, separator) + value = get_reward_params(response, args, separator) print(value) - else: - # placeholder for other endpoint args - pass -def get_reward_params(response, args): - #print(f"args.value = {args.value}, type = {type(args.value)}, lenm={len(args.value)}") - #print(f"RESPONSE = {response}") - value = get_nested_value(response, args) #THIS WILL COME OUT AS A VARIABVLE response["interval"]["staking_supply_scale_factor"]) - #value = response + keys +def get_reward_params(response, args, separator): + value = get_nested_value(response, args) if args.format == "percent": value = _return_percent_annotation(value) else: value = convert_u_nym(value) + value = thousand_separator(value, separator) return value def get_nested_value(response, args): @@ -149,7 +152,7 @@ def calculate(args): reward_params = get_api("https://validator.nymtech.net/api/v1/epoch/reward_params") circulating_supply = get_api("https://validator.nymtech.net/api/v1/circulating-supply") if args.staking_target: - display_staking_target(args, reward_params, circulating_supply) + display_staking_target(args, reward_params, circulating_supply, separator) def get_api(url): r = requests.get(url) @@ -157,13 +160,15 @@ def get_api(url): return response -def display_staking_target(args, reward_params, circulating_supply): +def display_staking_target(args, reward_params, circulating_supply, separator): keys = ["interval", "staking_supply_scale_factor"] staking_supply_scale_factor = get_dict_value(reward_params, keys) keys = ["circulating_supply", "amount"] circulating_supply = get_dict_value(circulating_supply, keys) staking_target = float(staking_supply_scale_factor) * float(circulating_supply) staking_target = convert_u_nym(staking_target) + if args.separator: + staking_target = thousand_separator(staking_target, separator) print(staking_target) def get_dict_value(json, keys):