Token Engineering: Modelling & Simulating Economic Systems

[Proposal setup] Proposal title

Please provide your proposal title

Token Engineering: Modelling & Simulating Economic Systems

[Proposal Summary] Budget Information

Enter the amount of funding you are requesting in ADA

100000

[Proposal Summary] Time

Please specify how many months you expect your project to last

12

[Proposal Summary] Translation Information

Please indicate if your proposal has been auto-translated

No

Original Language

en

[Proposal Summary] Problem Statement

What is the problem you want to solve?

Cardano's community governs network economics without tools to forecast a proposal's impact. This creates risk as even well-intentioned changes can be unintentionally detrimental to network resilence.

[Proposal Summary] Supporting Documentation

Supporting links

• https://tokenflows.xyz/
,
• https://github.com/tokenflows
,
• https://arxiv.org/ftp/arxiv/papers/1807/1807.11218.pdf
,
• https://cadcad.org/

[Proposal Summary] Project Dependencies

Does your project have any dependencies on other organizations, technical or otherwise?

No

Describe any dependencies or write 'No dependencies'

No dependencies

[Proposal Summary] Project Open Source

Will your project's outputs be fully open source?

Yes

License and Additional Information

It will be released under the Apache 2.0 License, which permits the community to freely use, inspect, modify, and distribute the output, as recommended by the fund guidelines.

[Theme Selection] Theme

Please choose the most relevant theme and tag related to the outcomes of your proposal

Developer Tools

[Campaign Category] Category Questions

Mention your open source license and describe your open source license rationale.

We chose the Apache 2.0 license to maximize adoption. Its permissive nature allows use in any project, open or proprietary. It offers explicit patent protection for users and contributors, discouraging patent lawsuits. This business-friendly license encourages commercial collaboration while requiring attribution to the original creators.

How do you make sure your source code is accessible to the public from project start, and people are informed?

This project will be made publicly available on a dedicated GitHub repository to embrace the principles of open-source development. Our organization will make sure the appropriate channels like our website are made to build awareness, and point visitors to our work.

How will you provide high quality documentation?

Documentation will be developed alongside the project and stored in the same repository as the code. Community contributions through clear guidelines and review processes can "Report an issue" which will feature on the documentation site will to allow users to easily provide feedback, ensuring the content remains accurate, relevant, and continuously improving.

[Your Project and Solution] Solution

Please describe your proposed solution and how it addresses the problem

Cardano's long-term resilience is not guaranteed by cryptography alone; It is an emergent property of a complex digital economy governed by its Proof-of-Stake incentive model. Key parameters, such as the desired number of stake pools (k) and the influence of an operator's pledge (a0), directly shape the behaviour of all network participants.

The community faces a challenge:

How do we make high-stakes governance decisions about these parameters responsibly? Proposals like CIP-50, which seek to adjust these levers, are currently debated with compelling arguments but without robust, data-driven forecasts of their likely impact. This is a significant risk. Foundational research on Reward Sharing Schemes (RSS) has shown that the dynamics of staking are highly complex and often counter-intuitive; simplistic "fair" models can unexpectedly lead to centralisation.

The Cardano community currently lacks an accessible, open-source, and well-maintained economic simulator to stress-test these proposals in a safe, virtual environment before they are deployed on the live network. This knowledge gap forces voters to rely on intuition rather than evidence, exposing the entire ecosystem to preventable risks.

We propose to build a critical piece of public infrastructure: an open-source economic simulator for Cardano's stake pool system. This project applies the rigorous discipline of Token Engineering (TE) to provide the community with the foresight needed for responsible governance.

Our solution leverages the deterministic nature of Cardano's eUTXO model, which eliminates entire classes of unpredictable behaviour common in account-based systems, allowing for more focused and powerful economic modelling.

We will deliver a comprehensive, user-focused toolset in three layers:

1. The Simulation Engine: We will develop an extensive cadCAD model of Cardano's stake pool delegation and reward mechanism. The model will be a faithful implementation of the game theory and mechanism design described in the foundational research paper on Cardano's RSS, parameterised by governance variables likek and a0.
2. Declarative Developer Environments: To make it accessible, we will build a reproducible Jupyter Notebook environment using Nix Flakes. This allows any developer, researcher, or curious community member to run the entire simulation environment with a single command, removing all setup and dependency challenges.
3. Analysis and Education: The output of this project is not just code, but knowledge. The simulator will be delivered through a series of documented Jupyter Notebooks that produce clear visualisations, comparative reports, and tutorials. This ensures the complex insights from simulations are translated into a format that the entire community can understand and use.

[Your Project and Solution] Impact

Please define the positive impact your project will have on the wider Cardano community

This project will provide an immediate and lasting positive impact on the Cardano community by directly improving the quality and safety of its decentralised governance process.

• Informed Governance: Our primary goal is to equip every ADA holder with a tool to independently verify and analyse the potential consequences of economic CIPs. By running simulations, a voter can see data-driven forecasts of how a change might affect network decentralisation, stake distribution, and the profitability of different types of stake pools.

• Systemic Risk Mitigation: The simulator will function as a "digital twin" of Cardano's economy, allowing for the rigorous stress-testing of the system in a safe environment. This mitigates the risk of deploying a parameter change that could inadvertently harm the network's health.

• Enhanced SPO Sustainability: Stake Pool Operators can use this tool to better understand the economic landscape, model their business viability under different network conditions, and make more informed decisions, strengthening the core infrastructure of the network.

• Strengthening Cardano's TE Ecosystem: This project will serve as a flagship example of applying Token Engineering in the eUTXO paradigm. By providing open-source tooling and education, we will contribute to the vital work of community hubs like Token Flows and CTEL, making Cardano a more attractive platform for sophisticated builders.

[Your Project and Solution] Capabilities & Feasibility

What is your capability to deliver your project with high levels of trust and accountability? How do you intend to validate if your approach is feasible?

Our team, Token Flows, is uniquely positioned to deliver this project, as it is a direct continuation and public release of our core work.

• Previous Work: We have invested in the understanding of the required disciplines. We even completed training in Token Engineering, Python, and cadCAD, and have studied the foundational economic ideas that underpin the discipline. Our prior work in Catalyst, such as the proposal to create TE educational content, demonstrates our long-standing commitment to this specific domain. We are not starting from zero.

• Cardano-Native Skills: Our team includes software engineers with years of experience in the Cardano ecosystem, including Haskell, Plutus, and Nix, alongside expertise in creating engaging technical and educational content.

• Realistic Scope: The project has a clear and focused scope, a realistic 12-month timeline, and no external dependencies, ensuring a high probability of successful and timely delivery.

[Milestones] Project Milestones

Milestone Title

Reproducible Jupyter Notebook Environment

Milestone Outputs

A publicly released and documented DivNix Nix Flake that provides a fully reproducible development environment containing all necessary Python packages for working with cadCAD and accessing on-chain data.

Acceptance Criteria

Nix Flake code and its supporting documentation are now published and publicly accessible on GitHub. This includes readme's and contribution docs with setup instructions and usage examples, ensuring the project is transparent and immediately available for feedback, and contribution.

Evidence of Completion

A link to the public GitHub repository and a screen-recorded video demonstrating the one-command setup process.

Delivery Month

2

Cost

22000

Progress

20 %

Milestone Title

Stake Pool cadCAD Model

Milestone Outputs

A complete cadCAD model of a Cardano stake pool, presented as an interactive and executable Jupyter Notebook. The notebook serves as a practical demonstration, showcasing the tooling's analytical feats.

Acceptance Criteria

The underlying Python code for the model and the explanatory Jupyter Notebook have been published to our public GitHub repository. raw the notebook offers an interactive, step-by-step narrative with visualizations, making the simulation both accessible and reproducible for the community.

Evidence of Completion

A link to the specific Notebook file on GitHub and a short video walking through the model's components and running a basic simulation.

Delivery Month

2

Cost

34000

Progress

40 %

Milestone Title

Chain Data Integration

Milestone Outputs

An extension to the Nix flake and model Notebook to set up pre-computed summaries of on-chain data in Postgres, and provide a configuration to enable use with Google BigQuery for more upto date simulation.

Acceptance Criteria

All required code modifications for the proposed features, spanning Nix, Python, and Jupyter Notebooks, will be officially committed and released to our GitHub repository. This is accompanied by updated documentation that details the use along with examples, ensuring that the new functionalities are transparent and accessible to the broader community.

Evidence of Completion

A link to the relevant code commits on GitHub and a video demonstrating the model running a simulation using data queried from the blockchain.

Delivery Month

2

Cost

22000

Progress

80 %

Milestone Title

Tutorial Video and Documentation

Milestone Outputs

A comprehensive video tutorial has been produced and published on our official YouTube channel. This visual guide provides a practical, step-by-step walkthrough of the project's key features and common use cases. This tutorial is complemented by detailed supporting documentation, which will be hosted on the Tokenflows website and YouTube channel, serving as a permanent, resource with written instructions and code examples.

Acceptance Criteria

The acceptance criteria for this are met when the video is published and publicly accessible on YouTube, and all associated written documentation is live on the project website and repository Verification requires confirming that both the video and documentation can be accessed directly via stable public links.

Evidence of Completion

Completion is demonstrated by the public release of our educational materials. The comprehensive video tutorial is now live on our official YouTube channel, and the supporting documentation is hosted on the project website, both accessible via the supported links. These resources serve as proof that the work has been delivered.

Delivery Month

1

Cost

22000

Progress

100 %

[Final Pitch] Budget & Costs

Please provide a cost breakdown of the proposed work and resources

Token Engineering & cadCAD Development: 52,000 ADA

• This covers the core research into Cardano's Reward Sharing Scheme , designing the system architecture, and the complex software development of the cadCAD model itself. This is the most significant portion of the work.

Nix Environment & Tooling: 19,000 ADA

• This covers the specialised work of creating a frictionless, reproducible development environment using Nix Flakes. This is critical for user experience and ensuring the tool's wide adoption by developers and researchers.

Educational Content Production: 22,000 ADA

• This covers the creation of high-quality supporting materials, including the scripting, recording, and professional editing of the video tutorial, as well as writing the comprehensive documentation and final report.

Project Management & Contingency (7,000 ADA):

• This allocation covers project management overhead and provides a small contingency fund (7%) for unforeseen complexities—a best practice for ensuring the project can handle unexpected challenges and deliver on its promises without requiring additional funding.

Total Budget Request: 100,000 ADA

[Final Pitch] Value for Money

How does the cost of the project represent value for the Cardano ecosystem?

This proposal represents an future investment for the Cardano ecosystem. The core question for this assessment is, "Can community members experiment and analyse proposed parameter changes and model stake pool operations effectivily." Thereby contribute directly to the governance of the network economic decissions.

The value proposition is threefold:

1. High Leverage: The 100,000 ADA investment produces an open-source "digital twin" of Cardano's multi-billion ADA staking economy. This tool has infinite leverage; it can be used by thousands of community members, stake pool operators, and developers for years to come to safeguard and improve the entire network.
2. Risk Reduction: The cost of making a single poor governance decision regarding Cardano's economic parameters could easily run into the millions of ADA in terms of lost network value or security vulnerabilities. This project provides a powerful tool to mitigate that risk for a fraction of the potential cost of inaction.
3. Establish a Public Good: We are not building a private, proprietary product. We are creating a piece of public infrastructure that strengthens the intelligence and effectiveness of Cardano's decentralised governance a core value proposition of the entire ecosystem. The cost is modest for a deliverable that enhances the integrity of the whole system

[Required Acknowledgements] Consent & Confirmation

Terms and Conditions:

Yes