Model token economies: burn tolls, staking yields, vesting, liquidity pools, multi-stream revenue. Python reference implementation + zero-build browser dashboard that runs the same math client-side.
By kcolbchain (est. 2015).
Most tokenomics spreadsheets hard-code three numbers, hide their assumptions, and plot a single line labelled "projected price". That is not a model — it is a slogan with a legend.
This repo provides:
- A small, readable Python library (
token_simulator/) with explicit parameters, deterministic trajectories, and unit tests. - A static browser dashboard (
web/) that runs the same model without a backend — adjust sliders and see supply / circulating / burn-rate / treasury / staker-APY evolve together. - Presets for real protocols (starting with
create-protocol-v4) so the library doubles as the economic-sim home for Create Protocol and future kcolbchain launches.
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
python -m token_simulator run --preset create-protocol-v4 --months 24Outputs a CSV trajectory plus a summary table. Scripts in examples/ show
how to load a preset, override a parameter, and plot.
python3 -m http.server -d web 8080
# open http://localhost:8080No build. Single index.html with the simulator inline. Tweak sliders,
switch presets, watch the plots update.
- Revenue streams — any number, each with its own volume curve and margin.
- Burn toll — a % of flow that burns native token via AMM buy-and-burn; burn size depends on pool depth, not just the toll rate.
- Vault yield — idle deposits auto-compound at a configurable APY, with an operating-cost line deducted first (not added on top, where most sims cheat).
- Vesting — per-bucket unlock schedules (team / community / treasury / liquidity / legacy) with independent sell-at-unlock rates.
- Endogenous price — supply shrink via burn + locked supply via staking feeds back into price via a simple constant-product pool. Not a prediction — a consistency check.
- Growth tapering — replace the classic constant-growth lie with a logistic curve so the sim can't claim 1.3×/mo forever.
- Cross-chain liquidity fragmentation.
- Competitor entry / exit.
- Governance actions (toll-rate changes) during the sim window.
- Regulatory shock.
- Speculative cycles — the model is consistency-checking, not price-prediction. If the sim says "burn rate > circulating within 3 years," that is a real alarm. If it says "FDV = $X at month 24," that is nonsense.
Monte Carlo mode (each parameter becomes a distribution, 10k trajectories, p5/p50/p95 reporting) is tracked in #1.
| Preset | Source |
|---|---|
create-protocol-v4 |
CR8 burn-toll + CR8-USD (see cr8-token-design-v4.md / cr8-simulation-parameters.md in internal docs) |
generic-fee-share |
Vanilla fee-share token, no burn, 70/30 revenue split — baseline to compare burn-toll against |
Add a preset: drop a YAML file under presets/, register it in
token_simulator/presets.py, and it appears in both the CLI and the
dashboard dropdown.
MIT.