Token Mechanics
Token Mechanics
Agents
This table contains the agents that participate in a simulation. Agents are any element of the token economy capable of obtaining, keeping, or sending tokens. This may include the Treasury, token Stakeholders, protocol users, etc.
To complete the table, add one new line per agent you want to include, with the following information in the corresponding column for each:
Reference (Alphanumerical): a unique identifier to this agent for use within the spreadsheet. It will not be displayed anywhere in the dashboard. It must start with a letter and contain only letters, underscores (_), or numbers. The reference must be unique and is not case sensitive. It is a good practice to start with "A_..." for the reference.
Display Name (Text): Name of the agent, and how it will be displayed in the dashboard.
Token holding (Formula, optional): this is an optional feature to define the amount of tokens that an agent will try to hold at any point in the simulation, buying when below this number and selling when above. This is useful when there are token utilities related to the amount of tokens held. If left empty, it is NOT interpreted the same as "0": the agent may still hold tokens as a result of the token flows it may be part of, as defined in the Flows tab.
Token staking (Formula, optional): this is an optional feature to define the amount of tokens that an agent will stake at any point in the simulation. If it does not originally hold enough tokens, it will buy from the market until it has them. If left empty, it defaults to "0" tokens staked. This is only for convenience in terms of metrics, and any further effects or yields from the staking will need to be defined as additional user-defined Flows.
Staking locking period (Formula, optional, in seconds): this is an optional feature to determine the locking period of new tokens staked during the current time step. Locked tokens cannot be unstaked until the locking period finishes. This means that if the amount of desired staked tokens specified from the formula in the previous column (token staking) goes below the current amount of locked tokens, some amount will not be possible to be unstaked at that point, limiting the unstaking process in some situations.
Liquidity provision (Formula, optional): the ratio (from 0 to 1) of the tokens owned that the agent will supply for liquidity from their total token amount. If the field is left empty, no liquidity will be provided by this agent.
Note that in order to be able to trade against the simulated AMM market and define a token price, some liquidity needs to be provided to the market. This means that at least one of the agents in the simulation must provide liquidity (i.e. a non-zero "Liquidity Provision"), and they should have tokens available to provide in the first place, likely from a vesting allocation.
A good practice is to have a "Market Maker" agent with some allocation.
Variables
This table contains intermediate internal variables for computing the dynamics of the simulation. While not strictly necessary, using these intermediate variables will simplify the modeling process.
Variables defined here can be used as part of formulae present in other sections: Vesting, Agents, Flows, and Metrics. You can check out further information regarding the formulae and their syntax in the Formulae section.
To complete the table, add one new line per variable you want to include, with the following information in the corresponding column for each:
Reference (Alphanumerical): a unique identifier to this variable for use within the spreadsheet. It will not be displayed anywhere in the dashboard. It must start with a letter and contain only letters, underscores (_), or numbers. The reference must be unique and is not case sensitive. It is a good practice to start with "VA_..." for the reference.
Formula (Formula): mathematical expression defining the value of the variable throughout the simulation.
Observations (Text, optional): notes exclusively for internal documentation.
Predefined variables
WIP
Flows
This table contains flows of tokens between agents in the simulation, usually defining the core mechanics of the tokenomics. The flows modeled are by mathematical expressions.
Some important things to note about token flows are:
The flows are defined in amount of tokens transferred during a simulation time step. You can make use of the predefined variables in the formula defining the token flow in order to calculate this easily, specifically
time_stepandtoken_price.They have an origin and a destination agent. In the simulation step, the amount of steps specified by the result of the flow value formula will be subtracted from the origin agent and deposited to the destination agent.
The same agent can be the origin and/or destination of different token flows. However, same agent cannot be the origin and destination of a flow at the same time.
There are three special origins and destinations predefined:
market: with market as a source, the counterparty agent is buying tokens on the aggregated token market. With market as a destination, the counterparty agent is selling tokens on the market. These actions generate buying and selling pressure, and affect the price of the token depending on market liquidity.mint: only available as a source, the amount of tokens in the flow is created and added to the destination agent, increasing the total supply.burn: only available as a destination, the amount of tokens in the flow is destroyed and subtracted from to the origin agent, decreasing the total supply.
The net sum of the token flows affecting an agent on a simulation step should never leave an agent with a negative amount of tokens.
There are only two additional token flows between agents that are NOT defined in this section:
Vesting flows: the unlocking of allocated tokens from the vesting schedule defined in the Vesting section is performed automatically without having to define a token flow in the Flows table. Each simulation step, the corresponding vested tokens are aded to each agent.
Token holding formula: if you have defined a Token holding formula in the "Token holding (Optional)" column of the Agents section, this results in an additional flow between the agent and the market to buy or sell the amount of tokens needed to end up holding the amount of tokens specified by the formula by the end of each simulation step.
Note that both of these token flows are optional features that are there for convenience and that you could ignore them if so desired. Instead, you could opt to define the equivalent token flows manually through formulas in the Flows table.
To complete the table, add one new line per flow you want to include, with the following information in the corresponding column for each:
Reference (Alphanumerical): a unique identifier to this flow for use within the spreadsheet. It will not be displayed anywhere in the dashboard. It must start with a letter and contain only letters, underscores (_), or numbers. The reference must be unique and is not case sensitive. It is a good practice to start with "F_..." for the reference.
Display Name (Text): name of the flow, and how it will be displayed in the dashboard for buying/selling pressure graphs.
Value (Formula): the amount of token that is exchanged between agents for the current timestep.
Origin (Agent Reference): agent that sends tokens for the flow.
Destination (Agent Reference): agents that receives tokens from the flow
Last updated
