A modular dynamical-systems model of the Mento2.0 design, based on the open-source Python library radCAD, an extension to cadCAD.
This repo features a cadCAD model for Mento2.0. The structure of this repo is heavily based on the Ethereum Economic Model.
dt) parameter. The model can be extended for slot-level granularity and analysis if that is desired (see Model Extension Roadmap).The model/ directory contains the model's software architecture in the form of two categories of modules: structural modules and configuration modules.
The model is composed of several structural modules in the model/parts/ directory:
| Module | Description |
|---|---|
| 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 |
| reserve.py | Calculation of the mechanics when interacting with the CELO reserve |
| system_metrics.py | Calculation of metrics such as stability provider rewards |
The model is configured using several configuration modules in the model/ directory:
| Module | Description |
|---|---|
| constants.py | Constants used in the model, e.g. number of blocks per epoch, Gwei in 1 CELO |
| state_update_blocks.py | cadCAD model State Update Block structure, composed of Policy and State Update Functions |
| state_variables.py | Model State Variable definition, configuration, and defaults |
| stochastic_processes.py | Helper functions to generate stochastic environmental processes |
| system_parameters.py | Model System Parameter definition, configuration, and defaults |
| types.py | Various Python types used in the model, such as the Stage Enum and calculation units |
| utils.py | Misc. utility and helper functions |
The 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 document.
The Mathematical Model Specification 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.
The Differential Model Specification depicts the model's overall structure across System States, System Inputs, System Parameters, State Update Logic and System Metrics.
git clone https://github.com/mento-protocol/simulation or using GitHub Desktopgit lfs pullYou can use your usual python workflow and install dependencies from the Pipfile, for example using virtualenv
or Anaconda.
Our usual python workflow is with Pyenv and Pipenv. Pyenv is a package to manage different versions of python and Pipenv automatically creates virtual environments and installs and updates packages and dependencies. In your shell:
1) Install Pyenv
2) Install Pipenv
3) Navigate to your \simulation folder
4) install python 3.8.12: pyenv install 3.8.12
5) Set your local python version pyenv local 3.8.12
7) Install dependencies: pipenv install --dev
8) Enter virtual environment: pipenv shell
9) Local pre-commit setup: pre-commit install
10) Install your virtual environment as jupyter kernel: python -m ipykernel install --user --name=mento2-model
To start Jupyter Notebook or Lab:
jupyter notebook
# Or:
jupyter labThe experiments/ directory contains modules for configuring and executing simulation experiments, as well as performing post-processing of the results.
The 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.
The Experiment README notebook contains an overview of how to execute existing experiment notebooks, and how to configure and execute new ones.
Could potentially contain a backtest of a Mento 1.0 model against empirical data.
The purpose of this notebook is to explore the risks & returns that stability providers can expect.
The purpose of this notebook is to explore the risks & returns that arbitrage providers can expect.
Nothing here yet.
We use Pytest to test the model module code, as well as the notebooks.
To execute the Pytest tests:
source venv/bin/activate
python3 -m pytest testsTo run the full GitHub Actions CI Workflow (see .github/workflows):
source venv/bin/activate
make testThis Mento 2.0 analysis is a fork of the 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.
Since we borrow so heavily from previous work, we would like to thank:
The code repository mento-protocol/simulation is licensed under the GNU General Public License v3.0.
Permissions 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.
If you'd like to cite this code and/or research, we suggest the following format:
Mento Labs, Mento 2.0 Model, (2022), GitHub repository, https://github.com/mento-protocol/simulation
[comment]: <> (@misc{MentoLabs2022,)
[comment]: <> ( author = {MentoLabs},)
[comment]: <> ( title = {Mento 2.0 Model},)
[comment]: <> ( year = {2022},)
[comment]: <> ( publisher = {GitHub},)
[comment]: <> ( journal = {GitHub repository},)
[comment]: <> ( howpublished = {\url{https://github.com/mento-protocol/simulation}},)
[comment]: <> ( version = {v0.0.0})
[comment]: <> (})