# Token Supply Simulation Model

Tagion token supply model is split in two periods:
1. Fixed supply (first 4 years);
2. Elastic supply (after first 4 years).

This repository contains a simulation and visualization of the supply model that will be active during the first 4 years.

In Tagion network, fees are burned, and rewards are issued into supply. Thus fees decrease the total supply, and rewards - increase.

The goal is to end up with 100 billion tokens in circulation while having a small fee.

## Simulation structure
The simulation consists of the following interconnected concepts:
* The randomized amount of transactions each epoch;
* The dynamic reward (recalculated every 24 hours);
* The dynamic fee (recalculated every 24 hours).

### Supply correlation
To realize how the target supply and the actual one correlate within days, we will consider the issuance of tokens daily.

* Simulation duration: 4 * 365 (amount simulation days);
* Special period: 10 (period of issue tokens sold via SAFT);
* The start simulation date is 24.12.2021;
* Tokens we have already sold: 5 billon since February 2020;
* Tokens target: 100 billion for 4 years.

### Epoch parameters

To count the reward in each epoch, we need to understand the following epoch parameters:

* **Epochs time**: the real period of the network state when nodes update the database, lasting from 10 seconds to 2 minutes. We can select the probability of epoch time in this period.

 def get_random_time_epochs(day):
        epoch_time = []
        for i in range(1, 13): # 10 secods,120 seconds 
            epoch_time.append(i*10)
        time_duration = np.random.choice(epoch_time, 1, p = [0.6, 0.20, 0.08, 0.06, 0.03, 0.01, 0.007, 0.004, 0.003, 0.0025, 0.002, 0.0015])
        return time_duration

* **Epochs passed**: the number of epochs taken for the all passed period. We define the epochs pass as:

a = get_random_time_epochs(j)
epochs_passed = 60*60*24 / a[0] 

Where a - is the first single element of the time sequence epoch list.

* **Epochs average**: this function counts the epoch average number for the last 14 days.

### The simulation's state changes while it's running

To calculate rewards, fees, and tokens now, we need the following parameters:

* **Current Now**: the difference between currently issued and currently burned tokens;
* **Current Issued**: tokens issued presently;
* **Current Burned**: tokens burned presently;
* **Current Fee**: fee in TGN equal around 0.01 EUR;
* **Current Reward**: reward presently.

    def get_tokens_now():
        return current_issued - current_burned

    def calculate_rewards(current_reward, epochs_amount):
        return current_reward * epochs_amount

    def calculate_fees(current_fee, amount_transaction):
        return current_fee * amount_transaction

- Call functions.

   cumulative_reward = calculate_rewards(current_reward, epochs_passed)
   cumulative_fee = calculate_fees(current_fee, transactions_passed)
   current_supply = get_tokens_now()

### The reward recalculation
To recalculate the reward for the next iteration, we need to find the difference between the target supply and the current one:

* A positive difference - the target supply is higher than the current one. If the supply difference is more than 0, we calculate the current reward as supply difference divided by getting the average of the last amount of the epoch.
* A negative difference - the current supply is higher than the target one, and the current reward equals the minimal reward, where the minimal reward is 100.

### Transactions
The number of transactions is randomized with the different functions in seasons. A random amount of transactions (including boundary numbers) is generated for each season. The transactions are divided into the following categories:

* low amount transaction ((100,1000000);
* high amount transaction (1000000,4000000);
* normal transaction (4000000, 7000000);
* very high transaction (7000000,10000000).

### The Supply simulation model:

#### Step 1

* Make the simulation tokens for 4 years (from 1 to 1460 days) and use the input parameters we further defined.
* Create a target supply model consisting of day, tokens sold, tokens target, a particular period, and simulation duration.
* Calculate a random epoch time, which can last from 10 seconds to 2 minutes, so we find the time of an epoch with some probability.
* Calculate the amount of epochs passed during simulation. Then calculate an average of the last epochs for the previous 14 days. The number of epochs due to calculating rewards is required in this step.

#### Step 2
Add a random number of transactions, divided into the sections:
* low amount transactions;
* high amount transactions;
* normal transactions;
* very high transactions.

This step is needed to see how many transactions are expected in 4 years.

#### Step 3
Calculate the following simulation states while it is running:
* cumulative fee;
* currently issued tokens;
* currently burned tokens;
* current supply function.

These parameters are necessary to calculate rewards, fees, and tokens and be updated for plotting.

#### Step 4
Recalculate rewards for the next day and check the algorithm for controlling the reward works.
Consequently, a positive difference means the target supply is higher than the current one, while a negative difference means the current supply is higher than the target one.

#### Step 5
Visualize and show the results on separate charts.

Right now, the result is the only one and necessary for an accurate understanding of how many tokens will be issued in the next 4 years. The simulation algorithm is flexible and precise, and at any time, you can change the simulation from 4 years to a more extended period.

## Prerequisites
- Python 3.9

## Getting started
To run the simulation, execute the following command:

pip3 install -r requirements.txt
python3 simulation-supply-model.py

## Results

Our plots consist of axes:
- **X-axis**: the amount of days (default: 1460).
- **Y-axis**: the amount of tokens in the system.
- **Target Supply**: target supply consists of day, tokens_sold, tokens_target, a special period, simulation duration.
- **Actual Supply**: actual supply function shows the difference between current issued and current burned, and it shows which tokens are available now.
- **Rewards**: rewards is a bar chart showing rewards daily over 4 years.
- **Fee**: fee is a bar chart showing fees daily over 4 years.
- **Transaction**: transaction trace shows the amount of transactions changed daily over 4 years.
- **Epochs**: epochs trace shows the amount of epochs daily over 4 years.

### Default configuration

### Flowchart Supply Model

## Maintainers

- [@katerynaleontieva3860](https://github.com/katerynaleontieva3860)