Skip to content

Latest commit

 

History

History
360 lines (280 loc) · 18.4 KB

README.md

File metadata and controls

360 lines (280 loc) · 18.4 KB
Raw

The Subspace Network Economic Digital Twin

A cadCAD Design Digital Twin for Subspace Network Economic Dynamics. image

*A stock and flow description of the SSC token dynamics being generated by the Subspace Economic Network Digital Twin.

The above model displays the SSC stocks, flows, and metrics that are defined in this software package. The purpose of this package is the generation of datasets that may be analyzed to discover insights about the system. Model development was at first motivated by the development of various specific experiments, and later adapted to a general workflow for parameter selection known as the Parameter Selection Under Uncertainty Framework, or PSUU. In addition to the data generating model package, there are workflows and analysis results provided in the form of jupyter notebooks. For convenience, the results of the notebooks can be viewed directly on github in the browser.

Table of Contents

  1. Stock and Flow Diagram
  2. Table of Contents
  3. Quick Start Guide
    1. Installation
    2. Usage
  4. The Subspace Economic Model
    1. Economic Modeling with cadCAD
    2. Goals of the System
    3. Model Terminology
    4. Structure of the Model
    5. Analysis Methodology
  5. Background
    1. Subspace
    2. Aligning Incentives for Optimal Scalability
    3. Recommended Readings from the Subnomicon
  6. Advanced Usage
    1. Modifying Default State
    2. Modifying Default Parameters
    3. Modifying Controllable Parameters
    4. Modifying Environmental Scenarios
    5. Modifying Logic Such as Reward Issuance
  7. Analysis Results
    1. Analysis Groups
    2. PSuU Analysis
  8. Additional Resources

Quick Start Guide

Installation

  1. Install System Requirements
  1. Clone the Repository
git clone https://github.com/blockscience/subspace && cd subspace
  1. Activate Python Virtual Environment

Option 1: Using venv virtual environment

# Create a virtual environment
python -m venv venv

# Activate the virtual environment
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# If you want to deactivate the virtual environment
deactivate

Option 2: Using python poetry

# Install dependencis
poetry install

# Activate the poetry shell
poetry shell

# To exit the poetry shell
exit

Usage

Inside of the subspace/ package directory and inside of your python virtual environment.

Run tests

pytest

Get Help on Available Options

python -m subspace_model --help
Usage: python -m subspace_model [OPTIONS]

Options:
  -e, --experiment [sanity_check_run|psuu]
                                  Select an experiment to run.
  -p, --pickle                    Pickle results to data/simulations/.
  -a, --run-all                   Run all experiments.
  -s, --samples INTEGER           Set Sample size; if not set runs default
                                  sample size.
  -d, --days INTEGER              Number of simulation days.
  -sw, --sweep_samples INTEGER    Number of sweep combinations to sample (if
                                  applicable for the experiment)
  --help                          Show this message and exit.

Generate a PSuU Dataset with 2 Monte Carlo runs and 2 parameter subsets and save the results

python -m subspace_model -e psuu -s 2 -sw 2 -p

Analyze Simulation Results in Jupyter

jupyter lab

Analyze the generated data.
Create a notebook to analyze the data like in local psuu timestep run analysis example.

Alternatively, skip the local data generation, and load a psuu timestep dataset directly from the cloud like the psuu single run analysis or load a trajectory dataset from the cloud like in psuu trajectory analysis notebooks.

The Subspace Economic Model

The Subspace Economic Model is a Digital Twin Stock & Flow representation for the SSC token dynamics as they flow through Subspace's distinct mechanisms. The parameters, mechanisms and their constituent logic are based on The Subnomicon and Token Economics design documents provided by the Subspace Team.

The digital twin is implemented as a python software package that enables data generation and analysis using cadcad and other python libraries. Model construction and data generation are performed using cadCAD. Research analysis is performed using python data analysis pipelines and machine learning for the purpose of selecting configuration parameters that increase the likelihood of achieving desired goals.

Economic Modeling with cadCAD

What is cadCAD?
Complex Adaptive Dynamics Computer-Aided Design (cadCAD) is a python based modeling framework for modeling, simulation, and validation of complex systems designs.

What is being mapped with a general simulation?

  • cadCAD model is the rules of the game
  • cadCAD allows defines how stocks evolve each timestep to create data sets called trajectories.
  • the cadCAD model is a data generator
  • structure.py is a high-level big picture of those rules.
  • logic.py contains granular definitions of those rules.
  • the data has been generated through a representation of the system

What does the data look like?

  • Given a simulation run, data is output as a compressed pickle file (pandas dataframe)
  • The data contains the trajectories of the state variables and metrics of the system over all timesteps

What can be done with this data?

Given a model of a complex system, cadCAD can simulate the impact that a set of actions might have on it. This helps users make informed, rigorously tested decisions on how best to modify or interact with the system in order to achieve their goals. cadCAD supports different system modeling approaches and can be easily integrated with common empirical data science workflows. Monte Carlo methods, A/B testing, and parameter sweeping features are natively supported.

For more information on cadCAD:

Goals of the System

The purpose of the economic model is to enable the subspace team to optimize the following goals given their choices of initialization parameters for the system.

  1. Rational Economic Incentives
    • Ensuring the economic parameters encourage behaviors supporting the network's long-term viability and growth.
    • Incentives should be proportional to effort.
    • Participation is smooth.
  2. Community Incentivization
    • Creating incentives that encourage participation from all defined stakeholders (farmers, operators, nominators).
    • Community owned supply should be maximized
    • Rewards should be spread across as many actors as possible
    • Early adopters should be incentivized
  3. Supply and Demand Equilibrium / Distributional Equilibrium
    • Balancing the issuance and distribution of tokens to support both the network's scalability and the fair distribution of resources among participants.
    • Increase in supply (eg. space pledged and operator pools) should track increases in demand (eg. storage & compute fees).

Model Terminology

  • Fees: The payments for transactions on the network.
  • Rewards: The compensation for the work performed by the participants of the network via the issuance of the newly minted tokens by the protocol.
  • Issuance: The amount of tokens minted as a Reward per block, total for all recipients.
  • Proposer: Farmer who won the block solution challenge.
  • Voter: Farmer who won the vote solution challenge. The current ratio is, on average, 9 votes per block.
  • State: All state values of the system at a particular timestep.
  • Parameters: Inputs to the model fixed over a run.
  • Functional Parameters: Parameters that are callable, used to introduce stochasticity, behavioral logic, and mechanisms like the issuance function.
  • Logic: State update and policy functions that define how the system state updates given its current state and parameterization.
  • Run: Executing a model from its initial state, through T timesteps.
  • Monte Carlo: Collecting multiple runs over a single parameterization.
  • Subset: A particular parameterization of the model that may be probed using Monte Carlo.
  • Sweep: Systematically varying parameter values to explore their impact on the model through multiple runs.
  • Timestep: A discrete time interval at which the system's state is updated.
  • Simulation: Running the model over parameter sweeps and Monte Carlo runs.
  • Experiment: A structured set of simulation runs designed to test specific hypotheses or explore the effects of varying parameters.
  • Trajectory: The path taken by the system's state over time during a single run.
  • KPI (Key Performance Indicator): A metric used to evaluate the system's performance in achieving its objectives.
  • Success Criteria: Predefined conditions that determine whether the simulation results are considered successful.
  • PSuU (Parameter Selection under Uncertainty): A methodology for selecting robust parameters while considering system uncertainties.

Structure of the Model

The Subspace Network's economic model is built using cadCAD and is composed of the following python modules:

Python Module Purpose
types.py Type definitions for the model state and parameters.
const.py System constants
params.py System parameters, environmental parameters, and governance surface.
state.py System inital state.
logic.py Policy and state update logic.
structure.py The block update structure of the model.
__main__.py The command line interface to the subspace model.
experiments/experiment.py Defines experiments such as standard run and psuu.
experiments/logic.py Behavioral and mechanism logic for experiments.
psuu/ Pipeline components for analyzing PSuU datasets.

Analysis Methodology

For further information on the methodology used in this modeling work, please refer to the Subspace PSUU Work Plan Methodology Document.

Background

Subspace

Subspace is the first layer-one blockchain that can fully resolve the blockchain trilemma. Subspace is built from first principles to simultaneously achieve scalability, security and decentralization. At its core, Subspace introduces a novel storage-based consensus protocol that separates consensus from execution. This proposer-builder separation allows Subspace to independently scale transaction throughput and storage requirements while maintaining a fully decentralized blockchain.

-Subspace Subnomicon

Aligning Incentives for Optimal Scalability

Subspace includes a novel algorithm to dynamically adjust the cost of blockspace in response to changes in supply and demand to economically secure the network in an open environment. Such adjustment naturally keeps the network incentive compatible for farmers, providing storage and data availability bandwidth and for operators providing raw compute power.

Subspace creates the world's first two-sided marketplace for blockspace, allowing it to have a dynamic on-chain cost-of-blockspace and a stable off-chain price-of-blockspace without relying on centralized control or coordination. On one side are the farmers, who collectively supply blockspace bandwidth through their storage of the blockchain history. On the other side are dApp developers and users, who demand blockspace to deploy and run their applications. Subspace's marketplace algorithm adjusts the on-chain cost-of-blockspace paid out to farmers based on real-time supply and demand. When demand is high, the cost rises to incentivize more farmers to join. When demand is low, the cost falls to disincentivize over-investment in storage. This dynamic adjustment process occurs transparently on-chain through the protocol rules.

When combined with existing scalability frameworks, Subspace can achieve linear scaling of the blockspace as more nodes join the network without sacrificing security or decentralization.

-Subspace Subnomicon

Recommended Readings from the Subnomicon

Advanced Usage

Modifying Default State

  1. Navigate to state.py
  2. Change the appropriate values
  3. If adding or removing fields from state, be sure to update types.py
  4. Run a simulation

Modifying Default Parameters

  1. Navigate to params.py
  2. Modify values in the DEFAULT_PARAMS dictionary
  3. If adding or removing fields from default params, be sure to update types.py
  4. Run a simulation

Modifying Controllable Parameters

  1. Navigate to the governance surface definition in params.py
  2. Modify values in the GOVERNANCE_SURFACE dictionary
  3. Each parameter excepts a list of values to be swept over.
  4. Run a simulation

Modifying Environmental Scenarios

  1. Navigate to params.py
  2. Modify values in the ENVIRONMENTAL_SCENARIOS dictionary
  3. Modify the list of values that is being passed to the SCENARIO_GROUPS function
  4. Optionally modify SCENARIO_GROUPS in experiments/logic.py
  5. Run a simulation

Modifying Logic Such as Reward Issuance

  1. Navigate to logic.py
  2. Modify logic appropriately
  3. Run a simulation

Analysis Results

Analysis Groups

For a fully comprehensive review of research and analysis, see the following sections in the notebooks directory:

Analysis Section Purpose
Exploratory A set of notebooks that perform exploratory analysis on simulation results.
Per-Experiment A set of templated notebooks that correspond to a series of experiments designed throughout the research phase of this project. The notebooks in this directory correspond to the functions found in experiment.py.
Research A set of notebooks that perform verification, validation, and benchmarking of specific components of the system.
Workflows A set of notebooks that showcase the parameter selection under uncertainty (PSuU) workflows.

PSuU Analysis

The following notebooks highlight the results of the subspace parameter selection research phase:

Notebook Purpose
PSuU Timestep Analysis This notebook explores a a set of runs from the PSuU timestep tensor.
PSuU Trajectory Analysis This notebook showcases the PSuU methodology workflow to produce parameter selection decision trees from the trajectory tensor.

Example: PSuU Timestep Tensor Run Analysis image

Example: PSuU Workflow Goal #1 Decision Tree over Controllable Parameters image

Example: PSuU Worklow Controllable Parameters Influence on KPIs image

For a complete overview of the parameter selection research phase, please see the Subspace Parameter Selection Report.

Additional Resources