{"id":41276527,"url":"https://github.com/blockscience/subspace","last_synced_at":"2026-01-23T02:34:55.443Z","repository":{"id":204891917,"uuid":"702748330","full_name":"BlockScience/subspace","owner":"BlockScience","description":"cadCAD Design Digital Twin for simulating the Subspace Network economic dynamics.","archived":false,"fork":false,"pushed_at":"2024-05-16T18:26:14.000Z","size":310082,"stargazers_count":5,"open_issues_count":0,"forks_count":4,"subscribers_count":8,"default_branch":"main","last_synced_at":"2024-05-17T00:01:56.379Z","etag":null,"topics":["cadcad","digital-twin","economics","subspace"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BlockScience.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-09T23:58:54.000Z","updated_at":"2024-05-16T18:26:18.000Z","dependencies_parsed_at":"2024-01-18T05:12:44.351Z","dependency_job_id":"53537bcc-6f34-45a6-ac61-94634acc5ad5","html_url":"https://github.com/BlockScience/subspace","commit_stats":{"total_commits":193,"total_committers":4,"mean_commits":48.25,"dds":0.4766839378238342,"last_synced_commit":"812661d89424b1ce344252cb25948e4b2fd8d5da"},"previous_names":["blockscience/subspace"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/BlockScience/subspace","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlockScience%2Fsubspace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlockScience%2Fsubspace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlockScience%2Fsubspace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlockScience%2Fsubspace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BlockScience","download_url":"https://codeload.github.com/BlockScience/subspace/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlockScience%2Fsubspace/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28678926,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-23T01:00:35.747Z","status":"online","status_checked_at":"2026-01-23T02:00:08.296Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cadcad","digital-twin","economics","subspace"],"created_at":"2026-01-23T02:34:54.769Z","updated_at":"2026-01-23T02:34:55.437Z","avatar_url":"https://github.com/BlockScience.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# The Subspace Network Economic Digital Twin \n\nA cadCAD Design Digital Twin for Subspace Network Economic Dynamics.\n![image](https://github.com/BlockScience/subspace/assets/31582215/109128b7-5085-47c6-99a9-a7fffd911e3d)\n\n\n*A stock and flow description of the SSC token dynamics being generated by the Subspace Economic Network Digital Twin. \n\nThe 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.  \n\n## Table of Contents\n1. [Stock and Flow Diagram](#the-subspace-network-economic-digital-twin)\n2. [Table of Contents](#table-of-contents)\n3. [Quick Start Guide](#quick-start-guide)\n    1. [Installation](#installation)\n    2. [Usage](#usage)\n4. [The Subspace Economic Model](#the-subspace-economic-model)\n    1. [Economic Modeling with cadCAD](#economic-modeling-with-cadcad)\n    2. [Goals of the System](#goals-of-the-system)\n    3. [Model Terminology](#model-terminology)\n    4. [Structure of the Model](#structure-of-the-model)\n    5. [Analysis Methodology](#analysis-methodology)\n5. [Background](#background)\n    1. [Subspace](#subspace)\n    2. [Aligning Incentives for Optimal Scalability](#aligning-incentives-for-optimal-scalability)\n    3. [Recommended Readings from the Subnomicon](#recommended-readings-from-the-subnomicon)\n6. [Advanced Usage](#advanced-usage)\n    1. [Modifying Default State](#modifying-default-state)\n    2. [Modifying Default Parameters](#modifying-default-parameters)\n    3. [Modifying Controllable Parameters](#modifying-controllable-parameters)\n    4. [Modifying Environmental Scenarios](#modifying-environmental-scenarios)\n    5. [Modifying Logic Such as Reward Issuance](#modifying-logic-such-as-reward-issuance)\n7. [Analysis Results](#analysis-results)\n    1. [Analysis Groups](#analysis-groups)\n    2. [PSuU Analysis](#psuu-analysis)\n8. [Additional Resources](#additional-resources)\n\n\n## Quick Start Guide\n\n### Installation\n\n1. Install System Requirements\n- [\u003e= Python 3.6](https://www.python.org/downloads/) \n- One of [`venv`](https://docs.python.org/3/library/venv.html) or [`poetry`](https://python-poetry.org/) for python virtual environment.\n\n2. Clone the Repository\n```bash\ngit clone https://github.com/blockscience/subspace \u0026\u0026 cd subspace\n```\n\n3. Activate Python Virtual Environment\n\n**Option 1**: Using `venv` virtual environment\n```bash\n# Create a virtual environment\npython -m venv venv\n\n# Activate the virtual environment\nsource venv/bin/activate\n\n# Install dependencies\npip install -r requirements.txt\n\n# If you want to deactivate the virtual environment\ndeactivate\n```\n\n**Option 2**: Using python poetry\n```bash\n# Install dependencis\npoetry install\n\n# Activate the poetry shell\npoetry shell\n\n# To exit the poetry shell\nexit\n```\n\n### Usage\nInside of the `subspace/` package directory and inside of\nyour python virtual environment.\n\nRun tests\n```bash\npytest\n```\n\nGet Help on Available Options\n```bash\npython -m subspace_model --help\n```\n\n```\nUsage: python -m subspace_model [OPTIONS]\n\nOptions:\n  -e, --experiment [sanity_check_run|psuu]\n                                  Select an experiment to run.\n  -p, --pickle                    Pickle results to data/simulations/.\n  -a, --run-all                   Run all experiments.\n  -s, --samples INTEGER           Set Sample size; if not set runs default\n                                  sample size.\n  -d, --days INTEGER              Number of simulation days.\n  -sw, --sweep_samples INTEGER    Number of sweep combinations to sample (if\n                                  applicable for the experiment)\n  --help                          Show this message and exit.\n```\n\nGenerate a PSuU Dataset with 2 Monte Carlo runs and 2 parameter subsets and save the results\n```bash\npython -m subspace_model -e psuu -s 2 -sw 2 -p\n```\n\nAnalyze Simulation Results in Jupyter\n```bash\njupyter lab\n```\n\nAnalyze the generated data.  \nCreate a notebook to analyze the data like in [local psuu timestep run analysis example](notebooks/exploratory/inspect_psuu_local.ipynb).\n\nAlternatively, skip the local data generation, and load a psuu timestep dataset directly from the cloud like the [psuu single run analysis](notebooks/workflows/psuu.ipynb) or load a trajectory dataset from the cloud like in [psuu trajectory analysis notebooks](notebooks/workflows/inspect_psuu_timestep_tensor.ipynb).\n\n\n\n## The Subspace Economic Model\n\nThe Subspace Economic Model is a Digital Twin Stock \u0026 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. \n\nThe digital twin is implemented as a python software package that enables data\ngeneration and analysis using cadcad and other python libraries. Model\nconstruction and data generation are performed using cadCAD. Research analysis\nis performed using python data analysis pipelines and machine learning for the\npurpose of selecting configuration parameters that increase the likelihood of\nachieving desired goals.\n\n\n### Economic Modeling with cadCAD\n\n**What is cadCAD?**  \nComplex Adaptive Dynamics Computer-Aided Design (cadCAD) is a python based\nmodeling framework for modeling, simulation, and validation of complex systems\ndesigns.\n\n**What is being mapped with a general simulation?**  \n- cadCAD model is the rules of the game\n- cadCAD allows defines how stocks evolve each timestep to create data sets called trajectories.\n- the cadCAD model is a data generator\n- [structure.py](subspace_model/structure.py) is a high-level big picture of those rules. \n- [logic.py](subspace_model/logic.py) contains granular definitions of those rules.\n- the data has been generated through a representation of the system\n\n**What does the data look like?**  \n- Given a simulation run, data is output as a compressed pickle file (pandas dataframe)\n- The data contains the trajectories of the state variables and metrics of the system over all timesteps\n\n**What can be done with this data?**  \n- See the [methodology](#methodology) and [analysis](#analysis-results) sections below\n\n\nGiven a model of a complex system, cadCAD can simulate the impact that a set of\nactions might have on it. This helps users make informed, rigorously tested\ndecisions on how best to modify or interact with the system in order to achieve\ntheir goals. cadCAD supports different system modeling approaches and can be\neasily integrated with common empirical data science workflows. Monte Carlo\nmethods, A/B testing, and parameter sweeping features are natively supported.\n\nFor more information on cadCAD:\n\n- https://community.cadcad.org/t/introduction-to-cadcad/15\n- https://community.cadcad.org/t/putting-cadcad-in-context/19\n- https://github.com/cadCAD-org/demos\n\n### Goals of the System\n\nThe 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.\n\n1. **Rational Economic Incentives** \n    - Ensuring the economic parameters encourage behaviors supporting the network's long-term viability and growth.\n    - Incentives should be proportional to effort. \n    - Participation is smooth.\n2. **Community Incentivization** \n    - Creating incentives that encourage participation from all defined stakeholders (farmers, operators, nominators).\n    - Community owned supply should be maximized\n    - Rewards should be spread across as many actors as possible\n    - Early adopters should be incentivized\n3. **Supply and Demand Equilibrium / Distributional Equilibrium** \n    - Balancing the issuance and distribution of tokens to support both the network's scalability and the fair distribution of resources among participants.\n    - Increase in supply (eg. space pledged and operator pools) should track increases in demand (eg. storage \u0026 compute fees).\n\n### Model Terminology\n- **Fees**: The payments for transactions on the network.\n- **Rewards**: The compensation for the work performed by the participants of the network via the issuance of the newly minted tokens by the protocol.\n- **Issuance:** The amount of tokens minted as a Reward per block, total for all recipients.\n- **Proposer:** Farmer who won the block solution challenge.\n- **Voter**: Farmer who won the vote solution challenge. The current ratio is, on average, 9 votes per block.\n- **State:** All state values of the system at a particular timestep.\n- **Parameters:** Inputs to the model fixed over a run.\n- **Functional Parameters:** Parameters that are callable, used to introduce stochasticity, behavioral logic, and mechanisms like the issuance function.\n- **Logic:** State update and policy functions that define how the system state updates given its current state and parameterization.\n- **Run:** Executing a model from its initial state, through T timesteps.\n- **Monte Carlo:** Collecting multiple runs over a single parameterization.\n- **Subset:** A particular parameterization of the model that may be probed using Monte Carlo.\n- **Sweep:** Systematically varying parameter values to explore their impact on the model through multiple runs.\n- **Timestep:** A discrete time interval at which the system's state is updated.\n- **Simulation:** Running the model over parameter sweeps and Monte Carlo runs.\n- **Experiment:** A structured set of simulation runs designed to test specific hypotheses or explore the effects of varying parameters.\n- **Trajectory:** The path taken by the system's state over time during a single run.\n- **KPI (Key Performance Indicator):** A metric used to evaluate the system's performance in achieving its objectives.\n- **Success Criteria:** Predefined conditions that determine whether the simulation results are considered successful.\n- **PSuU (Parameter Selection under Uncertainty):** A methodology for selecting robust parameters while considering system uncertainties.\n\n### Structure of the Model\n\nThe Subspace Network's economic model is built using cadCAD and is composed of the\nfollowing python modules:\n\n| Python Module | Purpose |\n|:--------|:--------|\n|  [types.py](subspace_model/types.py)  |  Type definitions for the model state and parameters.  |\n|  [const.py](subspace_model/const.py)  |  System constants  |\n|  [params.py](subspace_model/params.py)  |  System parameters, environmental parameters, and governance surface.  |\n|  [state.py](subspace_model/state.py)  |  System inital state.  |\n|  [logic.py](subspace_model/logic.py)  |  Policy and state update logic. |\n|  [structure.py](subspace_model/structure.py)  |  The block update structure of the model.  |\n|  [\\_\\_main\\_\\_.py](subspace_model/__main__.py)  |  The command line interface to the subspace model.  |\n|  [experiments/experiment.py](subspace_model/experiments/experiment.py)  |  Defines experiments such as standard run and psuu.  |\n|  [experiments/logic.py](subspace_model/experiments/logic.py)  |  Behavioral and mechanism logic for experiments.  |\n|  [psuu/](subspace_model/psuu/)  |  Pipeline components for analyzing PSuU datasets.  |\n\n\n### Analysis Methodology\n\nFor further information on the methodology used in this modeling work, please refer to the [Subspace PSUU Work Plan Methodology Document](resources/subspace-psuu-work-plan-methodology.md).\n\n\n## Background\n\n### Subspace\n\n\u003e Subspace is the first layer-one blockchain that can fully resolve the\n\u003e blockchain trilemma. Subspace is built from first principles to\n\u003e simultaneously achieve scalability, security and decentralization. At its core,\n\u003e Subspace introduces a novel storage-based consensus protocol that separates\n\u003e consensus from execution. This proposer-builder separation allows Subspace to\n\u003e independently scale transaction throughput and storage requirements while\n\u003e maintaining a fully decentralized blockchain. \n\n-[Subspace Subnomicon](https://subnomicon.subspace.network/docs/intro)\n\n### Aligning Incentives for Optimal Scalability\n\n\u003e Subspace includes a novel algorithm to dynamically adjust the cost of\n\u003e blockspace in response to changes in supply and demand to economically secure\n\u003e the network in an open environment. Such adjustment naturally keeps the network\n\u003e incentive compatible for farmers, providing storage and data availability\n\u003e bandwidth and for operators providing raw compute power.\n\u003e \n\u003e Subspace creates the world's first two-sided marketplace for blockspace,\n\u003e allowing it to have a dynamic on-chain cost-of-blockspace and a stable\n\u003e off-chain price-of-blockspace without relying on centralized control or\n\u003e coordination. On one side are the farmers, who collectively supply blockspace\n\u003e bandwidth through their storage of the blockchain history. On the other side\n\u003e are dApp developers and users, who demand blockspace to deploy and run their\n\u003e applications. Subspace's marketplace algorithm adjusts the on-chain\n\u003e cost-of-blockspace paid out to farmers based on real-time supply and demand.\n\u003e When demand is high, the cost rises to incentivize more farmers to join. When\n\u003e demand is low, the cost falls to disincentivize over-investment in storage.\n\u003e This dynamic adjustment process occurs transparently on-chain through the\n\u003e protocol rules.\n\u003e \n\u003e When combined with existing scalability frameworks, Subspace can achieve linear\n\u003e scaling of the blockspace as more nodes join the network without sacrificing\n\u003e security or decentralization.\n\n-[Subspace Subnomicon](https://subnomicon.subspace.network/docs/advancements#aligning-incentives-for-optimal-scalability)\n\n\n### Recommended Readings from the Subnomicon\n- [Architecture Overview](https://subnomicon.subspace.network/docs/overview)\n- [Advancing Blockchain](https://subnomicon.subspace.network/docs/advancements)\n- [Consensus](https://subnomicon.subspace.network/docs/category/consensus)\n- [Network Architecture](https://subnomicon.subspace.network/docs/category/network-architecture)\n- [Decoupled Execution](https://subnomicon.subspace.network/docs/category/decoupled-execution)\n- [Staking](https://subnomicon.subspace.network/docs/decex/staking)\n- [Rewards and Fees](https://subnomicon.subspace.network/docs/rewards_fees)\n- [Terminology](https://subnomicon.subspace.network/docs/terminology/)\n\n\n\n\n\n## Advanced Usage\n### Modifying Default State\n1. Navigate to [state.py](subspace_model/params.py)\n2. Change the appropriate values\n3. If adding or removing fields from state, be sure to update [types.py](subspace-parameter-selection-report/types.py)\n4. Run a simulation\n### Modifying Default Parameters\n1. Navigate to [params.py](https://github.com/BlockScience/subspace/blob/main/subspace_model/params.py#L37)\n2. Modify values in the `DEFAULT_PARAMS` dictionary\n3. If adding or removing fields from default params, be sure to update [types.py](subspace-parameter-selection-report/types.py)\n4. Run a simulation\n### Modifying Controllable Parameters\n1. Navigate to the governance surface definition in [params.py](https://github.com/BlockScience/subspace/blob/main/subspace_model/params.py#L97)\n2. Modify values in the `GOVERNANCE_SURFACE` dictionary\n3. Each parameter excepts a list of values to be swept over.\n4. Run a simulation\n### Modifying Environmental Scenarios\n1. Navigate to [params.py](https://github.com/BlockScience/subspace/blob/95ed541d2c149e0aebf76af6bbc10e10b832472c/subspace_model/params.py#L109)\n2. Modify values in the `ENVIRONMENTAL_SCENARIOS` dictionary\n3. Modify the list of values that is being passed to the `SCENARIO_GROUPS` function\n4. Optionally modify `SCENARIO_GROUPS` in [experiments/logic.py](https://github.com/BlockScience/subspace/blob/main/subspace_model/experiments/logic.py#L118)\n5. Run a simulation\n### Modifying Logic Such as Reward Issuance\n1. Navigate to [logic.py](https://github.com/BlockScience/subspace/blob/d5946f46d920545d6733a0758e30e58ea8d984be/subspace_model/logic.py#L72)\n2. Modify logic appropriately\n3. Run a simulation\n\n\n## Analysis Results\n\n### Analysis Groups\nFor a fully comprehensive review of research and analysis, see the following sections in the [notebooks](notebooks) directory:\n| Analysis Section | Purpose |\n|:--------|:--------|\n|  [Exploratory](notebooks/exploratory)  |  A set of notebooks that perform exploratory analysis on simulation results.  |\n|  [Per-Experiment](notebooks/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](subspace_model/experiments/experiment.py).  |\n|  [Research](notebooks/research)  |  A set of notebooks that perform verification, validation, and benchmarking of specific components of the system.  |\n|  [Workflows](notebooks/workflows)  |  A set of notebooks that showcase the parameter selection under uncertainty (PSuU) workflows.  |\n\n### PSuU Analysis\nThe following notebooks highlight the results of the subspace parameter selection research phase: \n| Notebook | Purpose |\n|:--------|:--------|\n|  [PSuU Timestep Analysis](notebooks/exploratory/inspect_psuu_timestep_tensor.ipynb)  |  This notebook explores a a set of runs from the PSuU timestep tensor.  |\n|  [PSuU Trajectory Analysis](notebooks/workflows/psuu.ipynb)  |  This notebook showcases the PSuU methodology workflow to produce parameter selection decision trees from the trajectory tensor.  |\n\nExample: PSuU Timestep Tensor Run Analysis\n![image](https://github.com/BlockScience/subspace/assets/31582215/9288b992-587d-4540-a426-032312bc8f4e)\n\nExample: PSuU Workflow Goal #1 Decision Tree over Controllable Parameters\n![image](https://github.com/BlockScience/subspace/assets/31582215/614107ac-74cf-4b06-b98f-2b538fc58be3)\n\nExample: PSuU Worklow Controllable Parameters Influence on KPIs\n![image](https://github.com/BlockScience/subspace/assets/31582215/6c8c0753-1eab-4b47-bc4c-e111e786ac51)\n\n\n\nFor a complete overview of the parameter selection research phase, please see the [Subspace Parameter Selection Report](resources/subspace-parameter-selection-report.md).\n\n\n## Additional Resources\n- [Subspace Work Plan Methodology](resources/subspace-psuu-work-plan-methodology.md)\n- [Subspace Parameter Selection Report](resources/subspace-parameter-selection-report.pdf)\n- [Hackmd Resources Collection](resources/)\n- [The Subnomicon](https://subnomicon.subspace.network/docs/intro)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblockscience%2Fsubspace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblockscience%2Fsubspace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblockscience%2Fsubspace/lists"}