From 569928321843ff4a6bd44cf927090c129252da21 Mon Sep 17 00:00:00 2001 From: abzaremba Date: Tue, 24 Oct 2023 15:31:18 +0100 Subject: [PATCH] Documentation for most of the Model parts --- .gitignore | 1 + Model/parts/agents_behavior/__init__.py | 12 ++ .../agent_meta_bucket_behavior.py | 83 ++++++++- Model/parts/business/business_assumptions.py | 40 ++++- Model/parts/business/user_adoption.py | 50 +++++- Model/parts/ecosystem/__init__.py | 19 +++ Model/parts/ecosystem/airdrops.py | 49 +++++- Model/parts/ecosystem/burn.py | 42 ++++- Model/parts/ecosystem/incentivisation.py | 48 +++++- Model/parts/ecosystem/liquidity_pool.py | 161 +++++++++++++++++- Model/parts/ecosystem/token_economy.py | 58 ++++++- Model/parts/ecosystem/vesting.py | 26 ++- Model/parts/utilities/__init__.py | 22 +++ Model/parts/utilities/burning.py | 14 ++ Model/parts/utilities/holding.py | 18 +- Model/parts/utilities/liquidity_mining.py | 15 ++ Model/parts/utilities/staking_base_apr.py | 14 ++ Model/parts/utils.py | 37 ++++ "UserInterface/Inputs \360\237\247\256.py" | 2 +- 19 files changed, 673 insertions(+), 38 deletions(-) diff --git a/.gitignore b/.gitignore index 9a49956..555c1eb 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,7 @@ __pycache__ ./data/__pycache__ ./Model/__pycache__ ./Model/parts/__pycache__ +qtmvenv .ipynb_checkpoints ./Model/simulationData.db simulationData.db diff --git a/Model/parts/agents_behavior/__init__.py b/Model/parts/agents_behavior/__init__.py index e69de29..650d5df 100644 --- a/Model/parts/agents_behavior/__init__.py +++ b/Model/parts/agents_behavior/__init__.py @@ -0,0 +1,12 @@ +"""Describes the agent behaviour and meta bucket allocations. + +Contains policy functions and state update functions relevant for behaviour +of each type of agent and for meta bucket allocations. Allows for stochastic +or static behaviour. + +Modules: + agent_meta_bucket_behavior: agent and meta bucket related state update + functions and policy functions + + +""" \ No newline at end of file diff --git a/Model/parts/agents_behavior/agent_meta_bucket_behavior.py b/Model/parts/agents_behavior/agent_meta_bucket_behavior.py index 44961c4..f9367f8 100644 --- a/Model/parts/agents_behavior/agent_meta_bucket_behavior.py +++ b/Model/parts/agents_behavior/agent_meta_bucket_behavior.py @@ -1,7 +1,45 @@ +"""Agent and meta bucket related state update and policy functions. + +Contains policy functions (PF) and state update functions (SUF) +relevant for behaviour of each type of agent and for meta bucket allocations. + + +Functions: + generate_agent_meta_bucket_behavior: (PF) Define the agent behavior. + + agent_meta_bucket_allocations: (PF) Define the meta bucket token allocations + of all agents. + + update_agent_meta_bucket_behavior: (SUF) Function to update the agent behaviors. + + update_agent_meta_bucket_allocations: (SUF) Function to update the agent meta + bucket token allocations. + + update_token_economy_meta_bucket_allocations: (SUF) Update the meta bucket + allocations for the token economy. + +""" + # POLICY FUNCTIONS def generate_agent_meta_bucket_behavior(params, substep, state_history, prev_state, **kwargs): """ - Define the agent behavior for each agent type + Define the agent behavior for each agent type. + + Policy function. + + First, checks if the agent behaviour is set up to be stochastic. + If stochastic, agent actions are based on a weighted random choices. + If static, define the agent behavior for each agent type based on previous state. + If neither, raise an error. + + Returns: + A dict with key 'agent_behavior_dict' and value being a dict, mapping agent + types to agent behaviour. + + Raises: + ValueError: params['agent_behavior'] must be either 'stochastic' or 'static'. + KeyError: Missing required parameter. + """ try: @@ -133,7 +171,21 @@ def generate_agent_meta_bucket_behavior(params, substep, state_history, prev_sta def agent_meta_bucket_allocations(params, substep, state_history, prev_state, **kwargs): """ - Define the meta bucket token allocations of all agents with respect to 'sell' 'hold' and 'utility' + Define the meta bucket token allocations of all agents with respect to 'sell', + 'hold' and 'utility'. + + Policy function. + + Updates agent token allocations and updates the meta bucket allocations w.r.t. each agents contribution. + Note that protocol buckets are not used for meta bucket allocations + + Returns: + A dict which allows to group the agents according to the following keys: + 'meta_bucket_allocations','agent_allocations', 'agent_from_holding_allocations'. + Each agent from any of these groups reports the allocations for 'sell', + 'hold' and 'utility'. + + """ # get state variables @@ -204,7 +256,15 @@ def agent_meta_bucket_allocations(params, substep, state_history, prev_state, ** # STATE UPDATE FUNCTIONS def update_agent_meta_bucket_behavior(params, substep, state_history, prev_state, policy_input, **kwargs): """ - Function to update the agent behaviors + Function to update the agent behaviors. + + State update function. + + Returns: + A tuple ('agents', updated_agents), where updated_agents is a dict mapping + each agent to their updated behaviour. + + """ updated_agents = prev_state['agents'] agent_behavior_dict = policy_input['agent_behavior_dict'] @@ -216,7 +276,13 @@ def update_agent_meta_bucket_behavior(params, substep, state_history, prev_state def update_agent_meta_bucket_allocations(params, substep, state_history, prev_state, policy_input, **kwargs): """ - Function to update the agent meta bucket token allocations + Function to update the agent meta bucket token allocations. + + State update function. + + Returns: + A tuple ('agents', updated_agents), where updated_agents is a dict mapping + each agent to their updated meta bucket token allocation. """ # get state variables @@ -242,7 +308,14 @@ def update_agent_meta_bucket_allocations(params, substep, state_history, prev_st def update_token_economy_meta_bucket_allocations(params, substep, state_history, prev_state, policy_input, **kwargs): """ - Function to update the meta bucket allocations for the token economy + Function to update the meta bucket allocations for the token economy. + + State update function. + + Returns: + A tuple ('token_economy', updated_token_economy), where updated_token_economy is + a dict providing values of updated meta bucket allocations for, respectively, + token economy selling/utility/holding allocations and their cumulative values. """ # get state variables diff --git a/Model/parts/business/business_assumptions.py b/Model/parts/business/business_assumptions.py index 9a98aef..0d08818 100644 --- a/Model/parts/business/business_assumptions.py +++ b/Model/parts/business/business_assumptions.py @@ -1,9 +1,38 @@ +"""Set business assumption metrics or update business assumptions. + +Contains policy functions (PF) and state update functions (SUF) +relevant for behaviour of each type of agent and for meta bucket allocations. + + +Functions: + business_assumption_metrics: (PF): Set up the business assumption metrics. + + update_business_assumptions: (SUF): Update the business assumptions. + +""" + + from ..utils import * # POLICY FUNCTIONS def business_assumption_metrics(params, substep, state_history, prev_state, **kwargs): + """ + Set up the business assumption metrics. + + Policy function. + + Reads a range of parameters (originally from QTM input tab 'cadCAD_inputs'), and + the state of: cash balance, revenue streams. + Then calculates: expenditures, buyback, liquidity requirements, sum of raised capital, + and cash flow. + + Returns: + Returns dict that maps 'cash_flow' to 'buybacks' to their respective values for + the current time step. + + """ # parameters product_income_per_month = params['product_income_per_month'] @@ -78,7 +107,16 @@ def business_assumption_metrics(params, substep, state_history, prev_state, **kw # STATE UPDATE FUNCTIONS def update_business_assumptions(params, substep, state_history, prev_state, policy_input, **kwargs): """ - Function to update the business assumptions + Function to update the business assumptions. + + State update function. + + Uses cash flow and buyback variables to update business assumptions. + + Returns: + Returns a tuple ('business_assumptions', updated_business_assumptions), + where updated_business_assumptions gives latest buybacks and updated cash flow. + """ # parameters diff --git a/Model/parts/business/user_adoption.py b/Model/parts/business/user_adoption.py index 444fe98..8937605 100644 --- a/Model/parts/business/user_adoption.py +++ b/Model/parts/business/user_adoption.py @@ -1,3 +1,17 @@ +"""Calculate and update user adoption metrics. + +Contains policy functions (PF) and state update functions (SUF). + + +Functions: + calculate_user_adoption: Take in user adoption data and calculate the amount of adoption. + + user_adoption_metrics (PF): Calculate the metrics relevant for monitoring user adoption. + + update_user_adoption (SUF): Function to update the user adoption metrics. + +""" + import math from Model.parts.utils import * @@ -5,16 +19,20 @@ def calculate_user_adoption(initial_users,final_users,velocity,timestamp,total_days): """ - Definition: - Function to take in user adoption data and calculate the amount of adoption, can be used for token adoption and product users - - Parameters: + Take in user adoption data and calculate the amount of adoption. + + Can be used for token adoption and product users. + + Args: initial_users: starting amount of users final_users: ending amount of users velocity: speed of adoption on those users timstep: current timestep in days - total_days: length of full simulation + total_days: length of full simulation. + Returns: + Number representing the user adoption. + """ term1 = (1 / (1 + math.exp(-velocity * 0.002 * (timestamp - 1825) / velocity))) * final_users + initial_users @@ -29,7 +47,17 @@ def calculate_user_adoption(initial_users,final_users,velocity,timestamp,total_d # POLICY FUNCTIONS def user_adoption_metrics(params, substep, state_history, prev_state, **kwargs): """ - Calculate the initial token economy metrics, such as MC, FDV MC, circ. supply, and tokens locked. + Calculate the metrics relevant for monitoring user adoption. + + Policy function. + + Token adoption and product users are calculated according to the logic provided in the + calculate_user_adoption function. + + Returns: + A dict which provides information on product users, token holders, product + revenue and token buys. + """ current_month = prev_state['timestep'] @@ -84,7 +112,15 @@ def user_adoption_metrics(params, substep, state_history, prev_state, **kwargs): # STATE UPDATE FUNCTIONS def update_user_adoption(params, substep, state_history, prev_state, policy_input, **kwargs): """ - Function to update the user adoption metrics + Function to update the user adoption metrics. + + State update function. + + Returns: + A tuple ('user_adoption', updated_user_adoption), where updated_user_adoption + provides updated information on product users, token holders, product revenue + and token buys. + """ product_users = policy_input['ua_product_users'] diff --git a/Model/parts/ecosystem/__init__.py b/Model/parts/ecosystem/__init__.py index e69de29..1e41f15 100644 --- a/Model/parts/ecosystem/__init__.py +++ b/Model/parts/ecosystem/__init__.py @@ -0,0 +1,19 @@ +"""Describes the ecosystem level events. + +Contains policy functions and state update functions with the affect at the +level of the whole ecosystem, as well as affecting individual agents. + +Modules: + airdrops: Calculate and process airdrops. + + burn: Calculation and processing of token burning at ecosystem level. + + incentivisation: Calculation and processing of ecosystem incentivisation. + + liquidity_pool: Liquidity pool initialisation and updating after transactions. + + token_economy: Provide date and token economy metrics. + + vesting: Vesting tokens and updating the amount of vested tokens held. + +""" \ No newline at end of file diff --git a/Model/parts/ecosystem/airdrops.py b/Model/parts/ecosystem/airdrops.py index 5cbe83b..7517e77 100644 --- a/Model/parts/ecosystem/airdrops.py +++ b/Model/parts/ecosystem/airdrops.py @@ -1,9 +1,34 @@ +"""Calculate and process airdrops. + +Contains policy functions (PF) and state update functions (SUF) +relevant for behaviour of each type of agent and for meta bucket allocations. + + +Functions: + airdrops (PF): Policy function to calculate airdrop amount for current period. + + update_agents_after_airdrops (SUF): Function to update information on airdrop + receiving agent after airdrops distribution. + + update_token_economy_after_airdrops (SUF): Function to update the token economy + after airdrops distribution. + +""" + import pandas as pd # POLICY FUNCTIONS def airdrops(params, substep, state_history, prev_state, **kwargs): """ - Policy function to incentivise the ecosystem + Policy function to calculate airdrop amount for current period. + + Airdrop amounts are provided as percentages of the airdrop allocation for + the predefined airdrop dates. The amounts of airdropped tokens for each + date are calculated based on the total token supply, airdrop allocation + percentage and the airdrop amount. + + Returns: + A dict where key 'te_airdrop_tokens' gets assigned a nonnegative value. """ # get parameters total_token_supply = params['initial_total_supply'] @@ -35,7 +60,17 @@ def airdrops(params, substep, state_history, prev_state, **kwargs): # STATE UPDATE FUNCTIONS def update_agents_after_airdrops(params, substep, state_history, prev_state, policy_input, **kwargs): """ - Function to update the vested tokens for each investor based on some criteria + Function to update information on airdrop receiving agent after airdrops distribution. + + State update function. + + Returns: + Tuple ('agents', updated_agents), where updated_agents holds information on the agents + who are labeled as airdrop receivers. + + Raises: + ValueError: No airdrop receivers found; Request to add at least one. + """ # get parameters @@ -66,7 +101,15 @@ def update_agents_after_airdrops(params, substep, state_history, prev_state, pol def update_token_economy_after_airdrops(params, substep, state_history, prev_state, policy_input, **kwargs): """ - Function to update the token economy after incentivisation + Function to update the token economy after airdrops distribution. + + State update function. + + Returns: + Tuple ('token_economy', updated_token_economy), where updated_token_economy + is a dict which holds information on the tokens distributed as airdrops + in the current period (token amount, cumulative amount, USD value). + """ # get parameters diff --git a/Model/parts/ecosystem/burn.py b/Model/parts/ecosystem/burn.py index f6b7d69..2b234af 100644 --- a/Model/parts/ecosystem/burn.py +++ b/Model/parts/ecosystem/burn.py @@ -1,9 +1,30 @@ +"""Calculation and processing of token burning at ecosystem level. + +Contains policy functions (PF) and state update functions (SUF) +relevant for behaviour of each type of agent and for meta bucket allocations. + + +Functions: + burn_from_protocol_bucket (PF): Policy function to calculate current + burn token amount. + + update_protocol_bucket_agent_after_burn (SUF): Function to update + the protocol buckets after tokens burned. + + update_token_economy_after_protocol_bucket_burn (SUF): Function to update + the token economy after tokens burned. + +""" + import pandas as pd # POLICY FUNCTIONS def burn_from_protocol_bucket(params, substep, state_history, prev_state, **kwargs): """ - Policy function to incentivise the ecosystem + Policy function to calculate current burn token amount. + + Returns: + A dict where key 'burn_token_amount' gets assigned a nonnegative value. """ # get parameters total_token_supply = params['initial_total_supply'] @@ -27,7 +48,14 @@ def burn_from_protocol_bucket(params, substep, state_history, prev_state, **kwar # STATE UPDATE FUNCTIONS def update_protocol_bucket_agent_after_burn(params, substep, state_history, prev_state, policy_input, **kwargs): """ - Function to update the vested tokens for each investor based on some criteria + Function to update the protocol buckets after tokens burned. + + State update function. + + Returns: + Tuple ('agents', updated_agents), where updated_agents is a dict that maps + the protocol buckets into their respective updatek amounts of tokens, tokens + burned in the current period, and cumulatively. """ # get parameters burn_project_bucket = params['burn_project_bucket'] @@ -51,7 +79,15 @@ def update_protocol_bucket_agent_after_burn(params, substep, state_history, prev def update_token_economy_after_protocol_bucket_burn(params, substep, state_history, prev_state, policy_input, **kwargs): """ - Function to update the token economy after incentivisation + Function to update the token economy after tokens burned. + + State update function. + + Returns: + A tuple ('token_economy', updated_token_economy), where updated_token_economy + is a dict that reports respective updatek amounts of tokens, tokens + burned in the current period, and cumulatively at the token economy level. + """ # get parameters diff --git a/Model/parts/ecosystem/incentivisation.py b/Model/parts/ecosystem/incentivisation.py index 47f8c5d..a528b69 100644 --- a/Model/parts/ecosystem/incentivisation.py +++ b/Model/parts/ecosystem/incentivisation.py @@ -1,7 +1,32 @@ +"""Calculation and processing of ecosystem incentivisation. + +Contains policy functions (PF) and state update functions (SUF). + + +Functions: + incentivisation (PF): Policy function to incentivise the ecosystem. + + update_agents_after_incentivisation (SUF): Function to update the + vested tokens for each investor based on some criteria. + + update_token_economy_after_incentivisation (SUF): Function to update + the token economy after incentivisation. + + +""" + # POLICY FUNCTIONS def incentivisation(params, substep, state_history, prev_state, **kwargs): """ - Policy function to incentivise the ecosystem + Policy function to incentivise the ecosystem. + + The possible sources of incentivisation include minting and protocol bucket + vesting. + + Returns: + A dict which provides values for tokens intended for incentivisation for + the possible sources: minting and protocol bucket vesting. + """ # get parameters total_token_supply = params['initial_total_supply'] @@ -28,7 +53,18 @@ def incentivisation(params, substep, state_history, prev_state, **kwargs): # STATE UPDATE FUNCTIONS def update_agents_after_incentivisation(params, substep, state_history, prev_state, policy_input, **kwargs): """ - Function to update the vested tokens for each investor based on some criteria + Function to update the vested tokens for each investor based on some criteria. + + State update function. + + The amount of tokens in protocol buckets get decreased due to incentivisation. + The amount of tokens that the incentivisation receivers will receive, will + increase by their fraction of the incentivisation amount. + + Returns: + Tuple ('agents', updated_agents), where updated_agents is a dict that maps + the agent types (protocol buckets or incentivisation receivers) onto their + respective values after incentivisation. """ # get parameters incentivisation_payout_source = params['incentivisation_payout_source'] @@ -62,7 +98,13 @@ def update_agents_after_incentivisation(params, substep, state_history, prev_sta def update_token_economy_after_incentivisation(params, substep, state_history, prev_state, policy_input, **kwargs): """ - Function to update the token economy after incentivisation + Function to update the token economy after incentivisation. + + State update function. + + Returns: + Tuple ('token_economy', updated_token_economy), where updated_agents is a dict + that provides amounts of tokens that were vested / minted. """ # get parameters diff --git a/Model/parts/ecosystem/liquidity_pool.py b/Model/parts/ecosystem/liquidity_pool.py index c559399..26fd8fe 100644 --- a/Model/parts/ecosystem/liquidity_pool.py +++ b/Model/parts/ecosystem/liquidity_pool.py @@ -1,3 +1,39 @@ +"""Liquidity pool initialisation and updating after transactions. + +Contains policy functions (PF) and state update functions (SUF). + + +Functions: + initialize_liquidity_pool (PF): Function to initialize the liquidity pool in + the first timestep. + + liquidity_pool_tx1_after_adoption (PF): Function to calculate the liquidity pool + after the adoption buys. + + liquidity_pool_tx2_after_vesting_sell (PF): Function to calculate the liquidity + pool after the vesting sell. + + liquidity_pool_tx3_after_liquidity_addition (PF): Function to calculate the + liquidity pool after liquidity addition. + + liquidity_pool_tx4_after_buyback (PF): Function to calculate the liquidity pool + after buyback. + + update_lp_after_lp_seeding (SUF): Function to update the agents based on the + changes in business funds to seed the liquidity pool. + + update_agents_tx1_after_adoption (SUF): Function to update the agents after the + adoption buys. + + update_agents_tx2_after_vesting_sell (SUF): Function to update the agents after + the vesting sell. + + update_liquidity_pool_after_transaction (SUF): Update the liquidity pool after + adoption buys, vesting sell, liquidity addition or buyback. + +""" + + import numpy as np from Model.parts.utils import * @@ -5,7 +41,20 @@ # POLICY FUNCTIONS def initialize_liquidity_pool(params, substep, state_history, prev_state, **kwargs): """ - Function to initialize the liquidity pool in the first timestep + Function to initialize the liquidity pool in the first timestep. + + Policy function. + + Checks the current month. If it equals zero, the liquidity pool is initialised + from the system parameters, otherwise the function returns the previous state of + the liquidity pool. + + Returns: + A dict of the form {'liquidity_pool': liquidity_pool}. + + Raises: + ValueError: Insufficient capital raised or too high requirement for seeding + of DEX liquidity. """ # parameters required_usdc = params['initial_required_usdc'] @@ -39,7 +88,22 @@ def initialize_liquidity_pool(params, substep, state_history, prev_state, **kwar def liquidity_pool_tx1_after_adoption(params, substep, state_history, prev_state, **kwargs): """ - Function to calculate the liquidity pool after the adoption buys + Function to calculate the liquidity pool after the adoption buys. + + Policy function. + + Returns: + A dict which provides amount of native protocol tokens in LP, + amount of USDC in LP, value of the constant product invariant, + token price, and transaction flag. + + Attributes: + token_lp_weight (float): Weight of the token in the liquidity pool. + usdc_lp_weight (float): Weight of USDC in the liquidity pool. + + Raises: + AssertionError: Constant product has changed after the adoption buys. + """ # parameters @@ -74,7 +138,22 @@ def liquidity_pool_tx1_after_adoption(params, substep, state_history, prev_state def liquidity_pool_tx2_after_vesting_sell(params, substep, state_history, prev_state, **kwargs): """ - Function to calculate the liquidity pool after the vesting sell + Function to calculate the liquidity pool after the vesting sell. + + Policy function. + + Includes selling from airdrops and incentivisation allocations. + + Returns: + A dict which provides amount of native protocol tokens in LP, + amount of USDC in LP, value of the constant product invariant, + token price, mapping for agents selling from holding and + transaction flag. + + Attributes: + token_lp_weight (float): Weight of the token in the liquidity pool. + usdc_lp_weight (float): Weight of USDC in the liquidity pool. + """ # parameters @@ -130,7 +209,14 @@ def liquidity_pool_tx2_after_vesting_sell(params, substep, state_history, prev_s def liquidity_pool_tx3_after_liquidity_addition(params, substep, state_history, prev_state, **kwargs): """ - Function to calculate the liquidity pool after liquidity addition + Function to calculate the liquidity pool after liquidity addition. + + Policy function. + + Returns: + A dict which provides amount of native protocol tokens in LP, + amount of USDC in LP, value of the constant product invariant, + token price, and transaction flag. """ # parameters @@ -163,7 +249,22 @@ def liquidity_pool_tx3_after_liquidity_addition(params, substep, state_history, def liquidity_pool_tx4_after_buyback(params, substep, state_history, prev_state, **kwargs): """ - Function to calculate the liquidity pool after buyback + Function to calculate the liquidity pool after buyback. + + Policy function. + + Returns: + A dict which provides amount of native protocol tokens in LP, + amount of USDC in LP, value of the constant product invariant, + token price, and transaction flag. + + Attributes: + token_lp_weight (float): Weight of the token in the liquidity pool. + usdc_lp_weight (float): Weight of USDC in the liquidity pool. + + Raises: + AssertionError: Constant product has changed after the adoption buys. + """ # parameters @@ -201,6 +302,16 @@ def liquidity_pool_tx4_after_buyback(params, substep, state_history, prev_state, def update_lp_after_lp_seeding(params, substep, state_history, prev_state, policy_input, **kwargs): """ Function to update the agents based on the changes in business funds to seed the liquidity pool. + + State update function. + + Note: Important in the first time step when liquidity pool is initialised. For other + steps, the liquidity pool is not changed. + + Returns: + Tuple ('liquidity_pool', updated_liquidity_pool), where updated_liquidity_pool is + a dict storing elevant information about the liquidity pool. + """ # get policy inputs updated_liquidity_pool = policy_input['liquidity_pool'] @@ -209,7 +320,19 @@ def update_lp_after_lp_seeding(params, substep, state_history, prev_state, polic def update_agents_tx1_after_adoption(params, substep, state_history, prev_state, policy_input, **kwargs): """ - Function to update the agents after the adoption buys + Function to update the agents after the adoption buys. + + State update function. + + Tokens bought are distributed to the agents of 'market_investors' type. + + Returns: + Tuple ('agents', updated_agents), where updated_agents provide the information + on how the token amount changed for the agents of the 'market_investors' type. + + Raises: + ValueError: No market investors found; Request to add at least one. + """ # state variables liquidity_pool = prev_state['liquidity_pool'].copy() @@ -242,7 +365,16 @@ def update_agents_tx1_after_adoption(params, substep, state_history, prev_state, def update_agents_tx2_after_vesting_sell(params, substep, state_history, prev_state, policy_input, **kwargs): """ - Function to update the agents after the adoption buys + Function to update the agents after the after the vesting sell. + + State update function. + + Applies to the agents of the 'protocol_bucket' type. + + Returns: + Tuple ('agents', updated_agents), where updated_agents provide the information + on how the sell change token amount of the agents of the 'protocol_bucket' type. + """ # state variables updated_agents = prev_state['agents'].copy() @@ -260,7 +392,20 @@ def update_agents_tx2_after_vesting_sell(params, substep, state_history, prev_st def update_liquidity_pool_after_transaction(params, substep, state_history, prev_state, policy_input, **kwargs): """ - Function to update the liquidity pool after the adoption buys + Update the liquidity pool after adoption buys, vesting sell, liquidity addition + or buyback. + + State update function. + + Note: The type of transaction that brings the need for an update to the + liquidity pool is determined by the transaction flag 'tx'. + + Returns: + Tuple ('liquidity_pool', updated_liquidity_pool) with updated_liquidity_pool + being a dict that provides information on changed attributes of the + liquidity pool. + + """ # parameters initial_token_price = params['initial_token_price'] diff --git a/Model/parts/ecosystem/token_economy.py b/Model/parts/ecosystem/token_economy.py index 463752a..93afbf7 100644 --- a/Model/parts/ecosystem/token_economy.py +++ b/Model/parts/ecosystem/token_economy.py @@ -1,9 +1,32 @@ +"""Provide date and token economy metrics. + +Contains policy functions (PF) and state update functions (SUF). + + +Functions: + generate_date (PF): Generate the current date from timestep. + + token_economy_metrics (PF): Calculate the initial token economy metrics, + such as MC, FDV MC, circ. supply, and tokens locked. + + update_date (SUF):Function to update the current date of the timestep. + + update_token_economy (SUF): Function to update token economy attributes + and metrics. + +""" + import pandas as pd # POLICY FUNCTIONS def generate_date(params, substep, state_history, prev_state, **kwargs): """ - Generate the current date from timestep + Generate the current date from timestep. + + Policy function. + + Returns: + A dict which points to the current date. """ # parameters initial_date = pd.to_datetime(params['launch_date'], format='%d.%m.%y') @@ -18,7 +41,20 @@ def generate_date(params, substep, state_history, prev_state, **kwargs): def token_economy_metrics(params, substep, state_history, prev_state, **kwargs): """ - Calculate the initial token economy metrics, such as MC, FDV MC, circ. supply, and tokens locked. + Calculate the initial token economy metrics, such as MC, FDV MC, circ. + supply, and tokens locked. + + Policy function. + + Calculations take place as the last substep, to reflect changes that + happened to the token economy in the current timestep. Information + provided for: total supply, selling/utility/holding percentages, + circulating supply, unvested tokens, holding supply, and the metrics: + MC and FDV NC. + + Returns: + A dict which provides information about the updated token economy + attributes and metrics. """ # parameters total_token_supply = params['initial_total_supply'] @@ -75,7 +111,12 @@ def token_economy_metrics(params, substep, state_history, prev_state, **kwargs): # STATE UPDATE FUNCTIONS def update_date(params, substep, state_history, prev_state, policy_input, **kwargs): """ - Function to update the current date of the timestep + Function to update the current date of the timestep. + + State update function. + + Returns: + Tuple ('date', updated_date). """ # policy input / update logic updated_date = policy_input['new_date'] @@ -84,7 +125,16 @@ def update_date(params, substep, state_history, prev_state, policy_input, **kwar def update_token_economy(params, substep, state_history, prev_state, policy_input, **kwargs): """ - Function to update the agents based on the changes in business funds to seed the liquidity pool. + Function to update token economy attributes and metrics. + + State update function. + + Updates nformation for: total supply, selling/utility/holding percentages, + circulating supply, unvested tokens, holding supply, USD values of + incentivised tokens and airdrops and the metrics: MC and FDV NC. + + Returns: + Tuple ('token_economy', updated_token_economy). """ # get state variables updated_token_economy = prev_state['token_economy'].copy() diff --git a/Model/parts/ecosystem/vesting.py b/Model/parts/ecosystem/vesting.py index 2c9886a..02c0fc9 100644 --- a/Model/parts/ecosystem/vesting.py +++ b/Model/parts/ecosystem/vesting.py @@ -1,7 +1,24 @@ +"""Vesting tokens and updating the amount of vested tokens held. + +Contains policy functions (PF) and state update functions (SUF). + + +Functions: + vest_tokens (PF): Policy function to vest tokens for each stakeholder. + + update_agent_vested_tokens (SUF): Function to update the vested tokens + for each investor based on some criteria. +""" + # POLICIY FUNCTIONS def vest_tokens(params, substep, state_history, prev_state, **kwargs): """ Policy function to vest tokens for each stakeholder. + + Policy function. + + Returns: + A dict which mapping agents to their vested token amounts. """ agents = prev_state['agents'].copy() total_token_supply = params['initial_total_supply'] @@ -42,7 +59,14 @@ def vest_tokens(params, substep, state_history, prev_state, **kwargs): # STATE UPDATE FUNCTIONS def update_agent_vested_tokens(params, substep, state_history, prev_state, policy_input, **kwargs): """ - Function to update the vested tokens for each investor based on some criteria + Function to update the vested tokens for each investor based on some criteria. + + State update function. + + Returns: + Tuple ('agents', updated_agents), where updated_agents provide information + for all agents on updated token holding, amount of vested tokens in current + period and cumulatively. """ updated_agents = prev_state['agents'] agent_token_vesting_dict = policy_input['agent_token_vesting_dict'] diff --git a/Model/parts/utilities/__init__.py b/Model/parts/utilities/__init__.py index e69de29..07a8b26 100644 --- a/Model/parts/utilities/__init__.py +++ b/Model/parts/utilities/__init__.py @@ -0,0 +1,22 @@ +"""Provide calculations and help with resolving of the states. + +Contains functions that help to calculate how quantities relevant +for both policy functions and state update functions. These are both +at the agent or ecosystem level + +Modules: + burning: Calculation and processing of token burning at agect level. + + holding: Calculation and processing of holding token allocations. + + liquidity_mining: Calculation and processing of liquidity mining at agent level + + staking_base_apr: Calculation and processing of APR and APR allocation. + + staking_revenue_share: + + staking_vesting: + + transfer: + +""" \ No newline at end of file diff --git a/Model/parts/utilities/burning.py b/Model/parts/utilities/burning.py index 26a7eec..290a8d4 100644 --- a/Model/parts/utilities/burning.py +++ b/Model/parts/utilities/burning.py @@ -1,3 +1,17 @@ +"""Calculation and processing of token burning at agect level. + +Contains policy functions (PF) and state update functions (SUF). + + +Functions: + burning_agent_allocation (PF): Policy function to calculate the agent burning. + + update_burning_agent_allocation (SUF): Function to update agent burning allocations. + + update_burning_meta_allocation (SUF): Function to update meta burning allocations. + +""" + # POLICY FUNCTIONS def burning_agent_allocation(params, substep, state_history, prev_state, **kwargs): """ diff --git a/Model/parts/utilities/holding.py b/Model/parts/utilities/holding.py index c28bb11..70d5e81 100644 --- a/Model/parts/utilities/holding.py +++ b/Model/parts/utilities/holding.py @@ -1,7 +1,21 @@ +"""Calculation and processing of holding token allocations. + +Contains policy functions (PF) and state update functions (SUF). + + +Functions: + holding_agent_allocation (PF): Policy function to calculate the agent holding. + + update_agents_after_holding (SUF): Function to update agent holding allocations + + update_utilties_after_holding (SUF): Function to update holding token allocations. + +""" + # POLICY FUNCTIONS def holding_agent_allocation(params, substep, state_history, prev_state, **kwargs): """ - Policy function to calculate the agent holding + Policy function to calculate the agent holding. """ # get parameters @@ -76,7 +90,7 @@ def update_agents_after_holding(params, substep, state_history, prev_state, poli def update_utilties_after_holding(params, substep, state_history, prev_state, policy_input, **kwargs): """ - Function to update meta burning allocations + Function to update holding token allocations. """ # get parameters diff --git a/Model/parts/utilities/liquidity_mining.py b/Model/parts/utilities/liquidity_mining.py index 5513857..c6ce980 100644 --- a/Model/parts/utilities/liquidity_mining.py +++ b/Model/parts/utilities/liquidity_mining.py @@ -1,3 +1,18 @@ +"""Calculation and processing of liquidity mining at agent level. + +Contains policy functions (PF) and state update functions (SUF). + + +Functions: + staking_liquidity_mining_agent_allocation (PF): Policy function to calculate the agent liquidity mining + + update_agents_after_liquidity_mining (SUF): Function to update agent liquidity mining allocations + + update_utilties_after_liquidity_mining (SUF): Function to update meta liquidity mining allocations. + +""" + + # POLICY FUNCTIONS def staking_liquidity_mining_agent_allocation(params, substep, state_history, prev_state, **kwargs): """ diff --git a/Model/parts/utilities/staking_base_apr.py b/Model/parts/utilities/staking_base_apr.py index ab57471..8c9efb7 100644 --- a/Model/parts/utilities/staking_base_apr.py +++ b/Model/parts/utilities/staking_base_apr.py @@ -1,3 +1,17 @@ +"""Calculation and processing of APR and APR allocation. + +Contains policy functions (PF) and state update functions (SUF). + + +Functions: + staking_apr_allocation (PF): Policy function to for the staking apr calculation + + update_utilties_after_apr (SUF): Function to update the utilities after apr + + update_agents_after_apr (SUF): Function to update the utilities after apr. + +""" + # POLICIY FUNCTIONS def staking_apr_allocation(params, substep, state_history, prev_state, **kwargs): """ diff --git a/Model/parts/utils.py b/Model/parts/utils.py index fb13ebd..ca3e807 100644 --- a/Model/parts/utils.py +++ b/Model/parts/utils.py @@ -1,3 +1,40 @@ +"""Initialisation, testing, and minor helper functions. + +Functions: + convert_date: + + calculate_raised_capital: + + new_agent: + + generate_agents: + + create_parameter_list: + + compose_initial_parameters: + + calculate_investor_allocation: + + calc_initial_lp_tokens: + + initialize_dex_liquidity: + + generate_initial_token_economy_metrics: + + initialize_user_adoption: + + initialize_business_assumptions: + + initialize_utilities: + + test_timeseries: + + import_dummy_data: + + convert_to_json: + +""" + import numpy as np import math import uuid diff --git "a/UserInterface/Inputs \360\237\247\256.py" "b/UserInterface/Inputs \360\237\247\256.py" index a052bc7..5ae6df0 100644 --- "a/UserInterface/Inputs \360\237\247\256.py" +++ "b/UserInterface/Inputs \360\237\247\256.py" @@ -94,7 +94,7 @@ new_params = model_ui_inputs(input_file_path, uploaded_file, parameter_list) else: - input_file_name = 'Quantitative_Token_Model_V1.89_radCad_integration - radCAD_inputs DEFAULT.csv' + input_file_name = 'Quantitative_Token_Model_V1.89_radCAD_integration - radCAD_inputs DEFAULT.csv' input_file_path = input_file_base_path + input_file_name # get new parameters from UI