Giter Club home page Giter Club logo

darcspice's Introduction

DARC-SPICE: Multi-agent modeling tools for engineering value flows in decentralized autonomous research communities

Pytest Unit Testing MyPy Static Type Checking

Codacy Badge Codacy Badge

TokenSPICE simulates tokenized ecosystems via an agent-based approach, with EVM in-the-loop.

It can help in Token Engineering flows, to design, tune, and verify tokenized ecosystems. It's young but promising. We welcome you to contribute! ๐Ÿ‘‹

  • TokenSPICE simulates by simply running a loop. At each iteration, each agent in the netlist takes a step. That's it! Simple is good.
  • A netlist wires up a collection of agents to interact in a given way.ย Each agent is a class. It has an Ethereum wallet, and does work to earn money. Agents may be written in pure Python, or with an EVM-based backend.
  • One models a system by writing a netlist and tracking metrics (KPIs). One can write their own netlists and agents to simulate whatever they like. The assets/netlists directory has examples.

Contents

๐Ÿ‘ช Community

  • Discord: te-tokenspice, first time.
  • TokenSPICE hacking sessions: Mondays at 17.00 Berlin // 11.00 Eastern // 8.00 Pacific. 120 min. Zoom link, Meeting ID 698 532 3627, Passcode 2021-99564. Anyone is welcome to drop in! ๐Ÿ‘‹
  • Twitter: @tokenspice
  • Medium: @tokenspice

History:

๐Ÿ— Initial Setup

Prerequisites

  • Linux/MacOS
  • Python 3.8.5+

Set up environment

Open a new terminal and:

#clone repo
git clone https://github.com/oceanprotocol/tokenspice.git
cd tokenspice

#create a virtual environment
python3 -m venv venv

#activate env
source venv/bin/activate

#install dependencies. Install wheel first to avoid errors.
pip install wheel
pip install -r requirements.txt

Get Ganache running

Think of Ganache as local EVM blockchain network, with just one node.

Open a new terminal and:

#install Ganache (if you haven't yet)
npm install ganache-cli --global

#activate env't
cd tokenspice
source venv/bin/activate

#run ganache.py. It calls ganache cli and fills in many arguments for you.
./ganache.py

Deploy the smart contracts to ganache

Below, you will deploy smart contracts from Ocean Protocol. Those contracts include an ERC20 datatoken factory, ERC20 template, Balancer pool factory, Balancer pool template, and metadata management. Each contract has a corresponding Python wrapper in the web3engine directory. Then, Python agents in assets/agents use these wrappers.

You can add your own smart contracts by deploying them to EVM, then adding corresponding Python wrappers and agents to use them.

Let's do this. Open a new terminal and:

#Grab the contracts code from main, *OR* (see below)
git clone https://github.com/oceanprotocol/contracts

#OR grab from a branch. Here's Alex's V4 prototype branch
git clone --branch feature/1mm-prototype_alex https://github.com/oceanprotocol/contracts

#here's the v4 contracts repo, enjoy:)
#https://github.com/oceanprotocol/contracts/tree/v4main

Then, deploy. In that same terminal:

cd contracts

#one-time install
npm i

#compile .sol, deploy to ganache, update contracts/artifacts/*.json
npm run deploy

Finally, open tokenspice/tokenspice.ini and set ARTIFACTS_PATH = contracts/artifacts.

  • Now, TokenSPICE knows where to find each contract on ganache (address.json file)
  • And, it knows what each contract's interface is (*.json files).

Test one EVM-based test

Open a new terminal and:

#activate env't
source venv/bin/activate

#run test
pytest web3engine/test/test_btoken.py 

First usage of tsp

We use tsp for TokenSPICE in the command line.

First, add pwd to bash path. In the terminal:

export PATH=$PATH:.

To see help, call tsp with no args.

tsp

Run Simulations for Science Token Communities

This is an overview of how Opscientia is using DARC-SPICE for simulations of science token communities. It contains inoformation on how to run the existing simulations on your own machine, description of the agents and models, and a list of features open to contributors.

Firstly, make follow the setup guide above. There are currently six netlists simulating different science value flows. The description of the different models can be found in assets/netlists/opsci_naive/, assets/netlists/opsci_profit_sharing/ (contains information about profit_sharing, mult_profit_sharing, and mult_time_profit_sharing models), assets/netlists/opsci_public_funding_ps/.

Before running simulations, make sure to create a new folder to save your data into. Here, we assume a local folder named simulation_data/ with csv/ and png/ folders within it. Below is a list of commands to run the simulations:

  1. Baseline model

Netlist code available at assets/netlists/opsci_naive/, agents assets/agents/opsci_agents/ and assets/agents/opsci_agents/profit_sharing_agents. Fixed netlist, for changing parameters, you'll need to change assets/netlists/opsci_naive/SimState.py.

  • run: tsp run assets/netlists/opsci_naive/netlist.py simulation_data/csv/opsci_naive_01
  • plot: tsp plot assets/netlists/opsci_naive/netlist.py simulation_data/csv/opsci_naive_01 simulation_data/png/opsci_naive_01
  1. Profit Sharing model

Netlist code available at assets/netlists/opsci_profit_sharing/, agents assets/agents/opsci_agents/profit_sharing_agents. To change simulation parameters, you'll need to change the constants at assets/netlists/opsci_profit_sharing/SimStrategy.py. Relevant parameters include: TICKS_BETWEEN_PROPOSALS,PRICE_OF_ASSETS, RATIO_FUNDS_TO_PUBLISH, TRANSACTION_FEES, FEES_TO_STAKERS, NUMBER_OF_RESEARCHERS, FUNDING_BOUNDARY.

  • run: tsp run assets/netlists/opsci_profit_sharing/netlist.py simulation_data/csv/opsci_profit_sharing_01
  • plot: tsp plot assets/netlists/opsci_profit_sharing/netlist.py simulation_data/csv/opsci_profit_sharing_01 simulation_data/png/opsci_profit_sharing_01
  1. Multiple Proposal Profit Sharing model

Netlist code available at assets/netlists/opsci_mult_profit_sharing/, agents assets/agents/opsci_agents/mult_agents. To change simulation parameters, you'll need to change the constants at assets/netlists/opsci_mult_profit_sharing/SimStrategy.py. Relevant parameters include: TICKS_BETWEEN_PROPOSALS,PRICE_OF_ASSETS, RATIO_FUNDS_TO_PUBLISH, TRANSACTION_FEES, FEES_TO_STAKERS, NUMBER_OF_RESEARCHERS, FUNDING_BOUNDARY, PROPOSALS_FUNDED_AT_A_TIME. Note: If you want to use PROPOSAL_SETUP, add it to the researchers in SimState.py.

  • run: tsp run assets/netlists/opsci_mult_profit_sharing/netlist.py simulation_data/csv/opsci_mult_profit_sharing_01
  • plot: tsp plot assets/netlists/opsci_mult_profit_sharing/netlist.py simulation_data/csv/opsci_mult_profit_sharing_01 simulation_data/png/opsci_mult_profit_sharing_01
  1. Multiple Proposal Rolling Basis Funding Profit Sharing model

Netlist code available at assets/netlists/opsci_mult_time_profit_sharing/, agents assets/agents/opsci_agents/mult_time_agents. To change simulation parameters, you'll need to change the constants at assets/netlists/opsci_mult_time_profit_sharing/SimStrategy.py. Relevant parameters include: PRICE_OF_ASSETS, RATIO_FUNDS_TO_PUBLISH, TRANSACTION_FEES, FEES_TO_STAKERS, NUMBER_OF_RESEARCHERS, FUNDING_BOUNDARY, PROPOSALS_FUNDED_AT_A_TIME, RANDOM_BUYING. Note: If you want to use PROPOSAL_SETUP, add it to the researchers in SimState.py; if RANDOM_BUYING = True, researchers will randomly buy assets from the knowledge market, causing significant fluctuations in data.

  • run: tsp run assets/netlists/opsci_mult_time_profit_sharing/netlist.py simulation_data/csv/opsci_mult_time_profit_sharing_01
  • plot: tsp plot assets/netlists/opsci_mult_time_profit_sharing/netlist.py simulation_data/csv/opsci_mult_time_profit_sharing_01 simulation_data/png/opsci_mult_time_profit_sharing_01
  1. Public Funding Profit Sharing model

Netlist code available at assets/netlists/opsci_public_funding_ps/, agents assets/agents/opsci_pp_agents/. To change simulation parameters, you'll need to change the constants at assets/netlists/opsci_public_funding_ps/SimStrategy.py. Relevant parameters include: PRICE_OF_ASSETS, RATIO_FUNDS_TO_PUBLISH, TRANSACTION_FEES, FEES_TO_STAKERS, NUMBER_OF_RESEARCHERS, FUNDING_BOUNDARY, PROPOSALS_FUNDED_AT_A_TIME, PRIVATE_PUBLISH_COST, ASSET_COSTS. Note: If you want to use PROPOSAL_SETUP, add it to the researchers in SimState.py.

  • run: tsp run assets/netlists/opsci_public_funding_ps/netlist.py simulation_data/csv/opsci_public_funding_ps_01
  • plot: tsp plot assets/netlists/opsci_public_funding_ps/netlist.py simulation_data/csv/opsci_public_funding_ps_01 simulation_data/png/opsci_public_funding_ps_01
  1. Public Funding Profit Sharing model with Community Growth

Netlist code available at assets/netlists/growth_public_funding_ps/, agents assets/agents/opsci_pp_agents/. To change simulation parameters, you'll need to change the constants at assets/netlists/growth_public_funding_ps/SimStrategy.py. Relevant parameters include: PRICE_OF_ASSETS, RATIO_FUNDS_TO_PUBLISH, TRANSACTION_FEES, FEES_TO_STAKERS, NUMBER_OF_RESEARCHERS, FUNDING_BOUNDARY, PROPOSALS_FUNDED_AT_A_TIME, PRIVATE_PUBLISH_COST, ASSET_COSTS. Note: If you want to use PROPOSAL_SETUP, add it to the researchers in SimState.py. The main addition to this netlist is the ReseracherGeneratorAgent. To change the growth function and condition for the generator, change generator_cond_type, generator_type, time_interval, and start_gen in SimState.py in the ResearcherGeneratorAgent.

  • run: tsp run assets/netlists/growth_public_funding_ps/netlist.py simulation_data/csv/opsci_public_funding_ps_01
  • plot: tsp plot assets/netlists/opsci_public_funding_ps/netlist.py simulation_data/csv/opsci_public_funding_ps_01 simulation_data/png/opsci_public_funding_ps_01

Future contributions

For anyone interested in expanding the functionality of TokenSPICE for open science, here is a list of netlists and features that would be helpful.

  • SourceCred implementation for higher level resolution of community contributions
  • peer review actions and rewards for researchers
  • quadratic funding model
  • token ecosystem with a minter (tracking supply, price, different reward distribution experiments)

๐Ÿ„ Do Simulations, Make Changes

Do Once, At Session Start

Start chain. Open a new terminal and:

cd ~/code/tokenspice
source venv/bin/activate
./ganache.py

Deploy contracts. Open a new terminal and:

cd ~/code/contracts
npm run deploy

Do >=1 Times in a Session

Update simulation code. Open a new terminal. In it:

cd ~/code/tokenspice
source venv/bin/activate

#then use editor to change assets/netlists/foo.py

Run tests. In the same terminal as before:

#run a single pytest-based test
pytest web3engine/test/test_btoken.py::test_ERC20

#run a single pytest-based test file
pytest web3engine/test/test_btoken.py 

#run all tests in util/ directory
pytest util

#run all tests except web3engine/ (slow)
pytest --ignore=web3engine

#run all tests
pytest

#run static type-checking. Dynamic is automatic.
mypy --config-file mypy.ini ./

Test that everything is working

source venv/bin/activate
pytest

Commit changes.

git add <changed filename>
git status -s [[check status]]
git commit -m <my commit message>
git push

#or

git status -s [[check status]]
git commit -am <my commit message>
git push

๐Ÿฆ‘ Agents and Netlists

Agents Basics

Agents are defined at assets/agents/. Agents are in a separate directory than netlists, to facilitate reuse across many netlists.

All agents are written in Python. Some may include EVM behavior (more on this later).

Each Agent has an AgentWallet, which holds a Web3Wallet. The Web3Wallet holds a private key and creates transactions (txs).

Netlists Basics

The netlist defines what you simulate, and how.

Netlists are defined at assets/netlists/. You can reuse existing netlists or create your own.

What A Netlist Definition Mustย Hold

TokenSPICE expects a netlist module (in a netlist.py file) that defines these specific classes and functions:

  • SimStrategy class: simulation run parameters
  • KPIs class and netlist_createLogData() function: what metrics to log during the run
  • netlist_plotInstructions() function: how to plot the metrics after the run
  • SimState class: system-level structure & parameters, i.e. how agents are instantiated and connected. It imports agents defined in assets/agents/*Agent.py. Some agents use EVM. You can add and edit Agents to suit your needs.

How to Implement Netlists

There are two practical ways to specify SimStrategy, KPIs, and so on for netlist.py:

  1. For simple netlists. Have just one file (netlist.py) to hold all the code for each class and method given above. This is appropriate for simple netlists, like simplegrant (just Python) and simplepool (Python+EVM).

  2. For complex netlists. Have one or more separate files for each class and method given above, such as assets/netlists/NETLISTX/SimStrategy.py. Then, import them all into netlist.py file to unify their scope to a single module (netlist). This allows for arbitrary levels of netlist complexity. The wsloop netlist is a good example. It models the Web3 Sustainability Loop, which is inspired by the Amazon flywheel and used by Ocean, Boson and others as their system-level token design.

Agent.takeStep() method

The class SimState defines which agents are used. Some agents even spawn other agents. Each agent object is stored in the SimState.agents object, a dict with some added querying abilities. Key SimState methods to access this object are addAgent(agent), getAgent(name:str), allAgents(), and numAgents(). SimStateBase has details.

Every iteration of the engine make a call to each agent's takeStep() method. The implementation of GrantGivingAgent.takeStep() is shown below. Lines 26โ€“33 determine whether it should disburse funds on this tick. Lines 35โ€“37 do the disbursal if appropriate. There are no real constraints on how an agent's takeStep() is implemented. This which gives great TokenSPICE flexibility in agent-based simulation. For example, it can loop in EVM, like we show later.

Netlistย Examples

Here are some existing netlists.

  • simplegrant - granter plus receiver, that's all. No EVM.
  • simplepool - publisher that periodically creates new pools. EVM.
  • wsloop - Web3 Sustainability Loop. No EVM.
  • (WIP) oceanv3 - Ocean Market V3 - initial design. EVM.
  • (WIP) oceanv4 - Ocean Market V4 - solves rug pulls. EVM.

To learn more about how TokenSPICE netlists are structured, we refer you to the simplegrant (pure Python) and simplepool (Python+EVM) netlists, which each have more thorough explainers.

๐ŸŸ Updating Envt

You don't need this info at the beginning, but it's good to know about as you make changes.

First, ensure your env't is active.

source venv/bin/activate

Install or uninstall packages using pip:

#Install
pip install package-name

#Uninstall
pip uninstall package-name

Update requirements.txt:

pip freeze > requirements.txt

๐Ÿก Backlog

Kanban Board

Some larger issues include:

  • Finish + verify Ocean V3 agents #28. AKA: System identification: high-fidelity model of Ocean V3 (w/ Balancer V1); fit the model to observed on-chain dynamics
  • Finish + verify Ocean V4 agents #29. AKA: Verification: high-fidelity model of Ocean V4 (w/ Balancer V2) base design, and the efficacy of each proposed mechanism.

In the longer term, we can expect:

  • Improvements to TokenSPICE itself in the form of faster simulation speed, improved UX, and more.
  • Higher-level tools that use TokenSPICE, including design entry, verification, design space exploration, and more.

๐Ÿ‹ Benefits of EVM Agent Simulation

TokenSPICE and other EVM agent simulators have these benefits:

  • Faster and less error prone, because the model = the Solidity code. Donโ€™t have to port any existing Solidity code into Python, just wrap it. Donโ€™t have to write lower-fidelity equations.
  • Enables rapid iterations of writing Solidity code -> simulating -> changing Solidity code -> simulating.
  • Super high fidelity simulations, since it uses the actual code itself. Enables modeling of design, random and worst-case variables.
  • Mental model is general enough to extend to Vyper, LLL, and direct EVM bytecode. Can extend to non-EVM blockchain, and multi-chain scenarios.
  • Opportunity for real-time analysis / optimization / etc against live chains: grab the latest chainโ€™s snapshot into ganache, run a local analysis / optimization etc for a few seconds or minutes, then do transaction(s) on the live chain. This can lead to trading systems, failure monitoring, more.

๐Ÿฆˆ Resources

Here are further resources.

Art:

๐Ÿ› License

Copyright ((C)) 2021 Ocean Protocol Foundation

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

darcspice's People

Contributors

bhargavkakadiya avatar johannsuarez avatar officialnico avatar richardblythman avatar smejak avatar trangnv avatar trentmc avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.