Skip to content
/ ethereum-economic-model Public
forked from CADLabs/ethereum-economic-model

A modular dynamical-systems model of Ethereum's validator economics.

cadlabs.org

License

GPL-3.0 license
2 stars 33 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

rogervs/ethereum-economic-model

BranchesTags
 
 

Repository files navigation

CADLabs Ethereum Economic Model

Python package

A modular dynamical-systems model of Ethereum's validator economics, based on the open-source Python library radCAD, an extension to cadCAD.

Table of Contents

Introduction

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.

Model Features

  • Configurable to reflect protocol behaviour at different points in time of the development roadmap (referred to as "upgrade stages"):
    • Post Beacon Chain launch, pre EIP1559, pre PoS (validators receive PoS incentives, EIP1559 disabled, and PoW still in operation)
    • Post Beacon Chain launch, post EIP1559, pre PoS (validators receive PoS incentives, EIP1559 enabled with miners receiving priority fees, and PoW still in operation)
    • Post Beacon Chain launch, post EIP1559, post PoS (validators receive PoS incentives, EIP1559 enabled with validators receiving priority fees, and PoW deprecated)
  • Flexible calculation granularity: By default, State Variables, System Metrics, and System Parameters are calculated at epoch level and aggregated daily (~= 225 epochs). 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).
  • Supports state-space analysis (i.e. simulation of system state over time) and phase-space analysis (i.e. generation of all unique system states in a given experimental setup).
  • Customizable processes to set important variables such as ETH price, ETH staked, and EIP1559 transaction pricing.
  • 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 Ethereum implements new protocol improvements.
  • References to official Eth2 specs 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.

Directory Structure

  • data/: Datasets and API data sources (such as Etherscan.io and Beaconcha.in) used in the model
  • docs/: Misc. documentation such as auto-generated docs from Python docstrings and Markdown docs
  • experiments/: Analysis notebooks and experiment workflow (such as configuration and execution)
  • logs/: Experiment runtime log files
  • model/: Model software architecture (structural and configuration modules)
  • tests/: Unit and integration tests for model and notebooks

Model Architecture

The model/ directory contains the model's software architecture in the form of two categories of modules: structural modules and configuration modules.

Structural 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 EIP1559 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

Configuration Modules

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
simulation_configuration.py Simulation configuration such as the number of timesteps and Monte Carlo runs
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

Model Assumptions

The model implements the official Ethereum Specification wherever possible, but rests on a few default validator-level assumptions detailed in the ASSUMPTIONS.md document.

Mathematical Model Specification

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.

Note: While the implemented model reflects the official Ethereum Altair spec updates in the Blue Loop / v1.1.0-alpha.7 release, the Mathematical Model Specification is still being updated.

Differential Model Specification

The Differential Model Specification depicts the model's overall structure across System States, System Inputs, System Parameters, State Update Logic and System Metrics.

Environment Setup

  1. Clone or download the Git repository: git clone https://github.com/CADLabs/ethereum-model or using GitHub Desktop
  2. If completing the cadCAD Edu Masterclass MOOC, check out the version v1.0.0 tag: git checkout tags/v1.0.0
  3. Set up your development environment using of the following two options:

Option 1: Local Development Environment

This section describes how to set up a custom development environment using Python 3 and Jupyter.

Please note the following prerequisites before getting started:

  • Python: tested with versions 3.7, 3.8, 3.9
  • NodeJS might be needed if using Plotly with Jupyter Lab (Plotly works out the box when using the Anaconda/Conda package manager with Jupyter Lab or Jupyter Notebook)

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

Option 2: Docker Development Environment

Alternatively, you can set up your development environment using the pre-built Docker image with all the dependencies you need: CADLabs Jupyter Lab Environment

Known Issues

Plotly doesn't display in Jupyter Lab

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]

Windows Issues

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.

Simulation Experiments

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 experiments/notebooks/README.ipynb contains an overview of how to execute existing experiment notebooks, and how to configure and execute new ones.

Notebook 1. Model Validation

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.

Notebook 2. Validator Revenue and Profit Yields (Validator-level Analysis)

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.

  • Analysis 1: Revenue and Profit Yields Over Time
  • Analysis 2: Revenue and Profit Yields Over ETH Staked
  • Analysis 3: Revenue and Profit Yields Over ETH Price
  • Analysis 4: Profit Yields Over ETH Staked vs. ETH Price (Yield Surface)
  • Analysis 5: Profit Yields By Validator Environment Over Time

Notebook 3. Network Issuance and Inflation Rate (Network-level Analysis)

The purpose of this notebook is to explore ETH issuance and the resulting annualized inflation rate across different time horizons and scenarios.

  • Analysis: Inflation Rate and ETH Supply Over Time

Model Extension Roadmap

The modular nature of the model makes structural and experiment-level extensions straightforward. The Model Extension Roadmap provides some inspiration.

Tests

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

Change Log

See CHANGELOG.md for notable changes and versions.

Acknowledgements

Contributors ✨

Thanks goes to these wonderful contributors (see emoji key):


Antoine Rondelet
👀
Barnabé Monnot
💻 👀 🤔
Benjamin Scholtz
💻 🚇 👀 📖 🐛 🤔
Danillo Lessa Bernardineli
👀 🤔
JGBSci
💻 👀 📖 🐛 🤔
JoranHonig
👀
RogerVs
💻 🚇 👀 📖 🐛 🤔

Toby Russell
🖋
Vitor Marthendal Nunes
💻 🚇 👀 📖 🐛 🤔
carlwafe
👀
casparschwa
👀
witwiki
👀

This project follows the all-contributors specification. Contributions of any kind welcome!

License

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.0.0}
}

About

A modular dynamical-systems model of Ethereum's validator economics.

cadlabs.org

Resources

Readme

License

GPL-3.0 license
Activity

Stars

2 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

4 tags

Packages

No packages published

Languages

  • Jupyter Notebook 95.8%
  • Python 3.9%
  • Other 0.3%