A modular dynamical-systems model of Ethereum's validator economics
A modular dynamical-systems model of Ethereum's validator economics, based on the open-source Python library radCAD, an extension to cadCAD.
This open-source model was developed in collaboration with the Ethereum Robust Incentives Group and funded by an Ethereum ESP (Ecosystem Support Program) grant. While originally scoped with purely modelling-educational intent as part of the cadCAD Edu online course "cadCAD Masterclass: Ethereum Validator Economics", it has evolved to become a highly versatile, customizable and extensible research model that includes a list of model extension ideas. The model is focused on epoch- and population-level Ethereum validator economics across different deployment types and β at least in its initial setup β abstracts from slot- and agent-level dynamics. Please see Model Assumptions for further context.
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 |
---|---|
ethereum_system.py | General Ethereum mechanisms, such as managing the system upgrade process, the EIP-1559 transaction pricing mechanism, and updating the ETH price and ETH supply |
pos_incentives.py | Calculation of PoS incentives such as attestation and block proposal rewards and penalties |
system_metrics.py | Calculation of metrics such as validator operational costs and yields |
validators.py | Validator processes such as validator activation, staking, and uptime |
utils/ethereum_spec.py | Relevant extracts from the official Eth2 spec |
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 epochs in a year, Gwei in 1 Ether |
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/CADLabs/ethereum-model
or using GitHub Desktopgit checkout v.1.1.7
This option guides you through setting up a cross-platform, beginner-friendly (yet more than capable enough for the advanced user) development environment using Anaconda to install Python 3 and Jupyter. There is also a video that accompanies this option and walks through all the steps: Model Quick-Start Guide
This option guides you through how to set up a custom development environment using Python 3 and Jupyter.
Please note the following prerequisites before getting started:
First, set up a Python 3 virtualenv development environment (or use the equivalent Anaconda step):
# Create a virtual environment using Python 3 venv module
python3 -m venv venv
# Activate virtual environment
source venv/bin/activate
Make sure to activate the virtual environment before each of the following steps.
Secondly, install the Python 3 dependencies using Pip, from the requirements.txt file within your new virtual environment:
# Install Python 3 dependencies inside virtual environment
pip install -r requirements.txt
To create a new Jupyter Kernel specifically for this environment, execute the following command:
python3 -m ipykernel install --user --name python-cadlabs-eth-model --display-name "Python (CADLabs Ethereum Economic Model)"
You'll then be able to select the kernel with display name Python (CADLabs Ethereum Economic Model)
to use for your notebook from within Jupyter.
To start Jupyter Notebook or Lab (see notes about issues with using Plotly with Jupyter Lab):
jupyter notebook
# Or:
jupyter lab
For more advanced Unix/macOS users, a Makefile is also included for convenience that simply executes all the setup steps. For example, to setup your environment and start Jupyter Lab:
# Setup environment
make setup
# Start Jupyter Lab
make start-lab
Alternatively, you can set up your development environment using the pre-built Docker image with all the dependencies you need: CADLabs Jupyter Lab Environment
To install and use Plotly with Jupyter Lab, you might need NodeJS installed to build Node dependencies, unless you're using the Anaconda/Conda package manager to manage your environment. Alternatively, use Jupyter Notebook which works out the box with Plotly.
See https://plotly.com/python/getting-started/
You might need to install the following "lab extension":
jupyter labextension install [email protected]
If you receive the following error and you use Anaconda, try: conda install -c anaconda pywin32
DLL load failed while importing win32api: The specified procedure could not be found.
The 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 validator-level and network-level experiment notebooks and analyses. These notebooks and analyses do not aim to comprehensively illuminate the Ethereum protocol, but rather to suggest insights into a few salient questions the Ethereum 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.
The purpose of this notebook is to recreate selected simulations from the widely acknowledged Hoban/Borgers Ethereum 2.0 Economic Model using the CADLabs model, and to compare the results. We suggest that the CADLabs model has a high degree of validity.
The purpose of this notebook is to explore the returns validators can expect from staking in the Ethereum protocol across different time horizons, adoption scenarios, ETH price scenarios and validator environments.
The purpose of this notebook is to explore ETH issuance and the resulting annualized inflation rate across different time horizons and scenarios.
The modular nature of the model makes structural and experiment-level extensions straightforward. The Model Extension Roadmap provides some inspiration.
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 tests
To run the full GitHub Actions CI Workflow (see .github/workflows):
source venv/bin/activate
make test
See CHANGELOG.md for notable changes and versions.
Thanks goes to these wonderful contributors (see emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
The code repository CADLabs/ethereum-economic-model
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:
CADLabs, Ethereum Economic Model, (2021), GitHub repository, https://github.com/CADLabs/ethereum-economic-model
@misc{CADLabs2021,
author = {CADLabs},
title = {Ethereum Economic Model},
year = {2021},
publisher = {GitHub},
journal = {GitHub repository},
howpublished = {\url{https://github.com/CADLabs/ethereum-economic-model}},
version = {v1.1.7}
}