{"id":19070823,"url":"https://github.com/mento-protocol/simulation","last_synced_at":"2026-06-17T18:32:06.809Z","repository":{"id":41308130,"uuid":"503366850","full_name":"mento-protocol/simulation","owner":"mento-protocol","description":null,"archived":false,"fork":false,"pushed_at":"2022-07-27T13:51:44.000Z","size":46262,"stargazers_count":2,"open_issues_count":21,"forks_count":1,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-02-22T03:44:08.043Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mento-protocol.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-06-14T13:14:58.000Z","updated_at":"2025-01-07T00:27:45.000Z","dependencies_parsed_at":"2022-08-19T08:51:12.727Z","dependency_job_id":null,"html_url":"https://github.com/mento-protocol/simulation","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mento-protocol/simulation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mento-protocol%2Fsimulation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mento-protocol%2Fsimulation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mento-protocol%2Fsimulation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mento-protocol%2Fsimulation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mento-protocol","download_url":"https://codeload.github.com/mento-protocol/simulation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mento-protocol%2Fsimulation/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34461616,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T01:20:45.248Z","updated_at":"2026-06-17T18:32:06.783Z","avatar_url":"https://github.com/mento-protocol.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mento2 Model\n\nA modular dynamical-systems model of the Mento2.0 design, based on the open-source Python library [radCAD](https://github.com/CADLabs/radCAD), an extension to [cadCAD](https://cadcad.org).\n\n* Latest model release version: [Private fork of Ethereum Economic Model / v0.0.0](https://github.com/mento-protocol/simulation/releases/tag/v0.0.0)\n\n## Table of Contents\n\n* [Introduction](#Introduction)\n  * [Model Features](#Model-Features)\n  * [Directory Structure](#Directory-Structure)\n  * [Model Architecture](#Model-Architecture)\n  * [Model Assumptions](#Model-Assumptions)\n  * [Mathematical Model Specification](#Mathematical-Model-Specification)\n  * [Differential Model Specification](#Differential-Model-Specification)\n* [Environment Setup](#Environment-Setup)\n* [Simulation Experiments](#Simulation-Experiments)\n* [Model Extension Roadmap](#Model-Extension-Roadmap)\n* [Tests](#Tests)\n* [Change Log](#Change-Log)\n* [Acknowledgements](#Acknowledgements)\n* [Contributors](#Contributors-)\n* [License](#License)\n\n---\n\n## Introduction\n\nThis repo features a cadCAD model for Mento2.0. The structure of this repo is heavily based on the [Ethereum Economic Model](https://github.com/CADLabs/ethereum-economic-model).\n\n### Model Features\n\n* Configurable to reflect protocol behaviour at different points in time of the development roadmap (referred to as \"upgrade stages\"):\n  * Exchange update?\n  * Reserve update?\n  * ...\n* Flexible calculation granularity: By default, State Variables, System Metrics, and System Parameters are calculated at block level and aggregated per epoch. Users can easily change epoch aggregation using the delta-time (`dt`) parameter. The model can be extended for slot-level granularity and analysis if that is desired (see [Model Extension Roadmap](#Model-Extension-Roadmap)).\n* Supports [state-space analysis](https://en.wikipedia.org/wiki/State-space_representation) (i.e. simulation of system state over time) and [phase-space analysis](https://en.wikipedia.org/wiki/Phase_space) (i.e. generation of all unique system states in a given experimental setup).\n* Customizable processes to set important variables such as CELO price, CELO staked, and gas pricing.\n* Modular model structure for convenient extension and modification. This allows different user groups to refactor the model for different purposes, rapidly test new incentive mechanisms, or update the model as CELO implements new protocol improvements.\n* References to official [Mento 2.0 specs (non-existent at this point!)](https://github.com/still-to-be-created) in Policy and State Update Function logic. This enables seamless onboarding of protocol developers and allows the more advanced cadCAD user to dig into the underlying protocol design that inspired the logic.\n\n### Directory Structure\n\n* [data/](data/): Datasets and API data sources used in the model\n* [docs/](docs/): Misc. documentation such as auto-generated docs from Python docstrings and Markdown docs\n* [experiments/](experiments/): Analysis notebooks and experiment workflow (such as configuration and execution)\n* [logs/](logs/): Experiment runtime log files\n* [model/](model/): Model software architecture (structural and configuration modules)\n* [tests/](tests/): Unit and integration tests for model and notebooks\n\n### Model Architecture\n\nThe [model/](model/) directory contains the model's software architecture in the form of two categories of modules: structural modules and configuration modules.\n\n#### Structural Modules\n\nThe model is composed of several structural modules in the [model/parts/](model/parts/) directory:\n\n| Module | Description |\n| --- | --- |\n| [celo_system.py](model/parts/celo_system.py) | General CELO mechanisms, such as managing the system upgrade process, the gas pricing mechanism, and updating the CELO price and CELO supply |\n| [reserve.py](model/parts/buy_and_sell.py) | Calculation of the mechanics when interacting with the CELO reserve |\n| [system_metrics.py](model/parts/system_metrics.py) | Calculation of metrics such as stability provider rewards |\n\n#### Configuration Modules\n\nThe model is configured using several configuration modules in the [model/](model/) directory:\n\n| Module | Description |\n| --- | --- |\n| [constants.py](model/constants.py) | Constants used in the model, e.g. number of blocks per epoch, Gwei in 1 CELO |\n| [state_update_blocks.py](model/state_update_blocks.py) | cadCAD model State Update Block structure, composed of Policy and State Update Functions |\n| [state_variables.py](model/state_variables.py) | Model State Variable definition, configuration, and defaults |\n| [stochastic_processes.py](model/stochastic_processes.py) | Helper functions to generate stochastic environmental processes |\n| [system_parameters.py](model/system_parameters.py) | Model System Parameter definition, configuration, and defaults |\n| [types.py](model/types.py) | Various Python types used in the model, such as the `Stage` Enum and calculation units |\n| [utils.py](model/utils.py) | Misc. utility and helper functions |\n\n### Model Assumptions\n\nThe model implements the official Ethereum Specification wherever possible, but rests on a few default network-level and validator-level assumptions detailed in the [ASSUMPTIONS.md](ASSUMPTIONS.md) document.\n\n### Mathematical Model Specification\n\nThe [Mathematical Model Specification](https://hackmd.io/@CADLabs/ryLrPm2T_) articulates the relevant system dynamics as a state-space representation, the mathematical modelling paradigm underlying the cadCAD simulation library. It can be understood as a minimum viable formalism necessary to enable solid cadCAD modelling.\n\n### Differential Model Specification\n\nThe [Differential Model Specification](https://hackmd.io/@CADLabs/HyENPQ36u) depicts the model's overall structure across System States, System Inputs, System Parameters, State Update Logic and System Metrics.\n\n## Environment Setup\n\n1. Clone or download the Git repository: `git clone https://github.com/mento-protocol/simulation` or using GitHub Desktop\n2. Pull data files via git-lfs: `git lfs pull`\n3. Set up your development environment using one of the following two options:\n\n\n### Option 1: Your usual python workflow\n\nYou can use your usual python workflow and install dependencies from the [Pipfile](Pipfile), for example using `virtualenv`\nor `Anaconda`.\n\n### Option 2: Using [Pyenv](https://github.com/pyenv/pyenv) and [Pipenv](https://github.com/pypa/pipenv)\n\nOur usual python workflow is with Pyenv and Pipenv. Pyenv is a package to manage different versions of python\nand Pipenv automatically creates virtual environments and installs and updates packages and dependencies. In your shell:\n\n1) Install [Pyenv](https://github.com/pyenv/pyenv)\n2) Install [Pipenv](https://github.com/pypa/pipenv)\n3) Navigate to your `\\simulation` folder\n4) install python 3.8.12: `pyenv install  3.8.12`\n5) Set your local python version `pyenv local  3.8.12`\n7) Install dependencies: `pipenv install --dev`\n8) Enter virtual environment: `pipenv shell`\n9) Local pre-commit setup: `pre-commit install`\n10) Install your virtual environment as jupyter kernel: `python -m ipykernel install --user --name=mento2-model`\n\nTo start Jupyter Notebook or Lab:\n```bash\njupyter notebook\n# Or:\njupyter lab\n```\n\n## Simulation Experiments\n\nThe [experiments/](experiments/) directory contains modules for configuring and executing simulation experiments, as well as performing post-processing of the results.\n\nThe [experiments/notebooks/](experiments/notebooks/) directory contains initial Mento experiment notebooks and analyses. These notebooks and analyses do not aim to comprehensively illuminate the Celo and Mento protocols, but rather to suggest insights into a few salient questions the Celo and Mento community has been discussing, and to serve as inspiration for researchers building out their own, customized analyses and structural model extensions.\n\nThe [Experiment README notebook](experiments/notebooks/0_README.ipynb) contains an overview of how to execute existing experiment notebooks, and how to configure and execute new ones.\n\n#### Notebook 1. Model Validation\n\nCould potentially contain a backtest of a Mento 1.0 model against empirical data.\n\n#### Notebook 2. Stability Provider Analysis\n\nThe purpose of this notebook is to explore the risks \u0026 returns that stability providers can expect.\n\n[comment]: \u003c\u003e (* Analysis 1: )\n\n[comment]: \u003c\u003e (* Analysis 2: )\n\n#### Notebook 3. Arbitrage Provider Analysis\n\nThe purpose of this notebook is to explore the risks \u0026 returns that arbitrage providers can expect.\n\n[comment]: \u003c\u003e (* Analysis: Inflation Rate and ETH Supply Over Time)\n\n## Model Extension Roadmap\n\nNothing here yet.\n\n## Tests\n\nWe use Pytest to test the `model` module code, as well as the notebooks.\n\nTo execute the Pytest tests:\n```bash\nsource venv/bin/activate\npython3 -m pytest tests\n```\n\nTo run the full GitHub Actions CI Workflow (see [.github/workflows](.github/workflows)):\n```bash\nsource venv/bin/activate\nmake test\n```\n\n## Acknowledgements\n\nThis Mento 2.0 analysis is a fork of the [Ethereum Economic Model](https://github.com/CADLabs/ethereum-economic-model). We actively try to stay as close as possible to the structure of the Ethereum Economic Model to make it easier for the broader community to follow our analysis.\n\nSince we borrow so heavily from previous work, we would like to thank:\n* [Ethereum Ecosystem Support Program](https://esp.ethereum.foundation/en/) for sponsoring the work on the Ethereum Economic Model and everyone who contributed to it.\n\n## Contributors ✨\n\n## License\nThe code repository `mento-protocol/simulation` is licensed under the GNU General Public License v3.0.\nPermissions of this strong copyleft license are conditioned on making available complete source code of licensed works and modifications, which include larger works using a licensed work under the same license. Copyright and license notices must be preserved. Contributors provide an express grant of patent rights.\nIf you'd like to cite this code and/or research, we suggest the following format:\n\u003e Mento Labs, Mento 2.0 Model, (2022), GitHub repository, https://github.com/mento-protocol/simulation\n\n\n```latex\n\n[comment]: \u003c\u003e (@misc{MentoLabs2022,)\n\n[comment]: \u003c\u003e (  author = {MentoLabs},)\n\n[comment]: \u003c\u003e (  title = {Mento 2.0 Model},)\n\n[comment]: \u003c\u003e (  year = {2022},)\n\n[comment]: \u003c\u003e (  publisher = {GitHub},)\n\n[comment]: \u003c\u003e (  journal = {GitHub repository},)\n\n[comment]: \u003c\u003e (  howpublished = {\\url{https://github.com/mento-protocol/simulation}},)\n\n[comment]: \u003c\u003e (  version = {v0.0.0})\n\n[comment]: \u003c\u003e (})\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmento-protocol%2Fsimulation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmento-protocol%2Fsimulation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmento-protocol%2Fsimulation/lists"}