Rai is a decentralized protocol that reacts to market forces to modify the value of a collateralized asset. Rai allows anyone to leverage crypto assets to issue a "reflex bond" that follows the price of its underlying collateral in a less volatile way. The stated goal is to stabilize the secondary market price for RAI debt, using the redemption price as a stabilizer. The benefits of such stabilization is a reduction in the volatility of the market price, thereby increasing predictability, while at the same time creating a flexible response instrument that can counteract or dampen unanticipated market shocks (such as liquidity cascades arising outside of the system).
To achieve this goal, RL implemented a Proportional-Integral-Derivative (PID) controller, based upon a reference document approach for the Maker DAI market that was never implemented. This controller (described in more detail in what follows) is the most commonly implemented real-world stability controller type in the world, and both its modeling structure and its parameter tuning are well-researched problems.
The goals of this repository are to create a cadCAD model to simulate the Reflexer, Rai system with the Arbitrage Pricing Theory (APT) to act as “bridge” between CDP and secondary market. The simulations used here will help design the incorporation of PID controller into a closed-loop system, and select the parameters that optimize how the system responds to price changes in order to achieve overall objectives. In short,
- Smoothing of secondary market price movements without assuming a redemption price peg
- Stability of the controller for a range of exogenous shocks
- Graceful startup and shutdown of controller in response to system events
For a great, "plan English" overview of a PID controller, visit the Rai whitepaper
Mathematical representation:
See Documenting Model Selection Presentation for more information.
See Parameter overview here for more details about the parameters and KPIs
Click here to see model specifications
Click here to see model specifications
Click here to see model specifications
The current model, System Model v3.0, is a full system model with CDP and APT system model, using a stochastic Ethereum price and liquidity demand process as a driver, under different PI controller settings.System Model v2.0, integrates a CDP subsystem, a secondary market subsystem, and applies Arbitrage Pricing Theory (APT) to the System Model v1.0 model. The System Model v1.0 model consisted of an estimated "debt price" regressor model, and a fitted market model, with a PI controller in the loop.
The latest notebook would be the System Model v3.0 full system model notebook. The model code used within the notebook can be found in models/system_model_v3/.
The table of contents and glossary below should serve as a guide.
Each model is located under models/_, with a unique name for each experiment.
models/run.py- script to run simulation experimentsmodels/_/model- model configuration (e.g. PSUBs, state variables)models/_/model/parts- model logic, state update functions, and policy functions
Directories:
diagrams/- system diagrams, used in documentationexperiments/- experiment results, code, and run logs.exports/- exports from simulations, such as datasets, charts, etc.lib/- third party libraries modified for use within models and simulations, such as Scipy which had to be patchedlogs/- output directory for cadCAD model logs (local only, in.gitignore)models/- system and subsystem models, as well as ML/regression model developmentnotebooks/- lab notebooks for model simulation and visualization using cadCAD (some notebooks have synced.pytemplates, see "Jupyter Notebook" below)plots/- static plots used in notebookssimulations/- execution of simulation notebooks using Papermilltests/-pytesttests and misc. testing resourcesutils/- utility code used within notebooks, for example generating plots
Files:
shared.py- file containing shared notebook imports and setup
See GLOSSARY.md markdown file.
Full system model with CDP and APT system model, using a stochastic Ethereum price and liquidity demand process as a driver, under different PI controller settings.
- Model code:
models/system_model_v3/ - Debt Market Model Notebook:
notebooks/system_model_v3/debt_market_model.ipynb
Notebooks analysing the system and showcasing how to perform experiments and analysis.
- Full system model - simple run
- Full system model - MC
- Shock Test
- Grid Search Sensitivity-WIP
- RAI Mainnet subgraph access
- RAI Mainnet subgraph analysis
- Rai Price Correlation Analysis V1
- Rai Price Correlation Analysis V2
Additional experiment log files and notebooks can be found here
Click here for information about cadCAD parameter sweeping methodology.
- Note: Notebooks below here are not fully documented
Full system model with CDP, APT, and secondary market subsystems. See slides 17-21. Please see the below in this README about the Scipy patch that needs to be applied, and the Pickle files you'll need to download for the ML model.
- Model code:
models/system_model_v2/ - Notebooks:
notebooks/system_model_v2/
This version of the model is for understanding the debt mechanism. Experimentation of posit exogenous processes for debt price and market price, and test stability controller. See slides 13-16
Full system model with parameters for selecting & stress testing subsystems, such as the controller, the debt price regression model, and the fitted market model.
- Model code:
models/system_model_v1/ - Notebooks:
notebooks/system_model_v1/
- Market Price Driven Model: PI Controller Tuning
- The purpose of this experiment is to tune and test the PI controller, by driving the market price directly.
- Debt Price Driven Model: PI Controller Tuning
- The purpose of this experiment is to tune and test the PI controller, by driving the debt price directly.
- Debt Price Model & Market Model Validation
- The purpose of this experiment, is to validate the system model, using a debt market regression model trained using historical data.
- Model code:
cross-model/
- Model code:
models/market_model/
- Model code:
models/apt_model/
The following pickle files in models/pickles/ should be obtained from this IPFS link, and copied or linked into the repo. They are ignored in the .gitignore file to avoid hitting file size and bandwidth limits:
apt_debt_model_2020-11-28.pickle
You'll need to install swig for the auto-sklearn Python library:
brew install swig@3apt-get remove swig
apt-get install swig3.0
rm -rf /usr/bin/swig3.0 /usr/bin/swig
ln -s /usr/bin/swig3.0 /usr/bin/swigconda install gxx_linux-64 gcc_linux-64 swigYou'll need Python 3+ and NodeJS/NPM (v10.13.0) in your environment.
python3 -m venv venv
source venv/bin/activate
pip3 install wheel
pip3 install -r requirements.txt
jupyter labextension install jupyterlab-plotly@4.9.0 # --minimize=False
python -m ipykernel install --user --name python-reflexer --display-name "Python (Reflexer)"
jupyter-labThe Scipy minimize function needs to be patched. Apply the following patch, updating the path to scipy in your environment:
patch venv/lib/python3.8/site-packages/scipy/optimize/optimize.py lib/scipy.patchTo start Jupyter Lab, with all dependencies available:
source venv/bin/activate
jupyter-labSee relevant simulation notebooks.
Example model configuration and simulation execution:
from models.run import run
from models.config_wrapper import ConfigWrapper
import models.system_model_v2 as model
simulation = ConfigWrapper(model)
simulation.append()
result = run(drop_midsteps=True)- Tutorial This tutorial is the first in a series on numerical computation. The goal of this tutorials is to outline and define the key concepts of and present pseudo code for numerical integration for applications of signal processing and control theory in smart contracts.