threefold.incatokens #

see examples/threefold/incatokens/incatokens_simulate.vsh for example of how to use

fn play(mut plbook PlayBook) !

fn simulate_auction(config AuctionConfig) !AuctionResult

simulate_auction performs a simplified Dutch auction simulation. It determines the market-clearing price based on total demand and token supply.

fn simulation_get(name string) !&Simulation

fn simulation_new(params SimulationParams) !&Simulation

Create simulation from parameters struct - MAIN ENTRY POINT

enum EpochType {
	auction_only
	hybrid
	amm_only
}

struct AMMPool {
pub mut:
	tokens f64 // The total number of tokens in the pool.
	usdc   f64 // The total amount of USDC (stablecoin) in the pool.
	k      f64 // The constant product (k = tokens * usdc).
}

AMMPool represents a simple Automated Market Maker pool. It uses the constant product formula (x * y = k) to determine prices.

fn (mut pool AMMPool) add_liquidity(tokens f64, usdc f64)

add_liquidity adds tokens and USDC to the pool, updating the constant product. This function is used to provide liquidity to the AMM.

fn (mut pool AMMPool) trade(usdc_amount f64) !

trade executes a swap by adding USDC to the pool and removing tokens. The amount of tokens removed is calculated to maintain the constant product k.

fn (pool AMMPool) get_price() f64

get_price calculates the current price of a single token in USDC. The price is determined by the ratio of USDC to tokens in the pool.

struct AuctionConfig {
pub mut:
	demand       f64 // The total USD demand from all participants.
	min_price    f64 // The minimum acceptable price per token (reserve price).
	token_supply f64 // The total number of tokens available for sale.
}

AuctionConfig contains the parameters for simulating a Dutch auction.

struct AuctionResult {
pub mut:
	tokens_sold      f64  // The total number of tokens sold.
	clearing_price   f64  // The final price per token.
	usd_raised       f64  // The total funds raised.
	fully_subscribed bool // True if all tokens were sold.
}

AuctionResult holds the outcome of a simulated Dutch auction.

struct EconomicsConfig {
pub mut:
	epoch1_floor_uplift        f64 = 1.20
	epochn_floor_uplift        f64 = 1.20
	amm_liquidity_depth_factor f64 = 2.0
}

EconomicsConfig defines economic parameters affecting token pricing

struct Epoch {
pub mut:
	index            int
	type_            EpochType
	start_month      int
	end_month        int
	auction_share    f64
	amm_share        f64
	tokens_allocated f64
	auction_demand   f64
	amm_net_trade    f64
	treasury_raised  f64
	final_price      f64
	tokens_spillover f64
}

Epoch represents a phase in the token release schedule

struct InvestorRound {
pub mut:
	name           string
	allocation_pct f64
	price          f64
	vesting        VestingSchedule
}

InvestorRound represents an investment round

struct InvestorRoundConfig {
pub mut:
	name           string
	allocation_pct f64
	price          f64
	vesting        VestingConfig
}

InvestorRoundConfig defines parameters for each investment round

struct OutputConfig {
pub mut:
	export_dir      string = './output'
	generate_csv    bool   = true
	generate_charts bool   = true
	generate_report bool   = true
}

OutputConfig defines where and how to generate outputs

struct ReportData {
pub mut:
	sim             &Simulation
	generation_date string
	total_raised    f64
	initial_price   f64
}

Struct to hold all data for the report template

struct Scenario {
pub mut:
	name          string
	demands       []f64
	amm_trades    []f64
	epochs        []Epoch
	final_metrics ScenarioMetrics
}

Scenario represents a market scenario

struct ScenarioConfig {
pub mut:
	name       string
	demands    []f64
	amm_trades []f64
}

ScenarioConfig defines a single scenario with market conditions

struct ScenarioMetrics {
pub mut:
	treasury_total           f64
	final_price              f64
	investor_roi             map[string]f64
	market_cap_final         f64
	circulating_supply_final f64
}

ScenarioMetrics holds the final results of a scenario

struct Simulation {
pub mut:
	// Core identification
	name string

	// Configuration (embedded)
	params SimulationParams

	// Derived data
	investor_rounds  []InvestorRound
	team_vesting     VestingSchedule
	treasury_vesting VestingSchedule

	// Runtime state
	scenarios map[string]&Scenario

	// Spreadsheets for tracking
	price_sheet      &spreadsheet.Sheet
	token_sheet      &spreadsheet.Sheet
	investment_sheet &spreadsheet.Sheet
	vesting_sheet    &spreadsheet.Sheet
}

Simulation holds the main simulation state

fn (mut sim Simulation) create_vesting_schedules() !

Create vesting schedule in spreadsheet

fn (sim Simulation) export_all(export_dir string) !

Export all simulation data

fn (sim Simulation) export_csv(sheet_name string, path string) !

Export data to CSV

fn (sim Simulation) generate_market_cap_chart() !echarts.EChartsOption

Generate market cap chart

fn (sim Simulation) generate_price_chart() !echarts.EChartsOption

Generate price evolution chart

fn (sim Simulation) generate_report(output_dir string) !

fn (sim Simulation) generate_scenario_section(scenario_name string) !string

Generate a single scenario section for use in templates

fn (mut sim Simulation) generate_vesting_chart() !echarts.EChartsOption

Generate vesting schedule chart

fn (mut sim Simulation) run_scenario(name string, demands []f64, amm_trades []f64) !&Scenario

Run a scenario with given demands and AMM trades

fn (mut sim Simulation) run_simulation() !

Main simulation runner - single entry point

struct SimulationConfig {
pub mut:
	nrcol    int    = 60 // Number of months to simulate
	currency string = 'USD'
}

SimulationConfig defines technical simulation parameters

struct SimulationParams {
pub mut:
	name            string
	distribution    TokenDistribution
	investor_rounds []InvestorRoundConfig
	vesting         VestingConfigs
	economics       EconomicsConfig
	simulation      SimulationConfig
	scenarios       []ScenarioConfig
	output          OutputConfig
}

SimulationParams is the main configuration struct containing all parameters

struct TokenDistribution {
pub mut:
	total_supply f64 = 10_10000000000
	public_pct   f64 = 0.50
	team_pct     f64 = 0.15
	treasury_pct f64 = 0.15
	investor_pct f64 = 0.20
}

TokenDistribution defines how tokens are allocated across different categories

struct VestingConfig {
pub mut:
	cliff_months   int = 6
	vesting_months int = 24
}

VestingConfig defines cliff and vesting periods

struct VestingConfigs {
pub mut:
	team     VestingConfig
	treasury VestingConfig
}

VestingConfigs groups all vesting configurations

struct VestingSchedule {
pub mut:
	cliff_months       int
	vesting_months     int
	initial_unlock_pct f64 // Percentage of tokens unlocked at month 0
}

VestingSchedule defines cliff and vesting periods