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

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
• 🏗 Initial Setup
• 🏄 Do Simulations, Make Changes
• 🦑 Agents and Netlists
• 🐟 Updating Envt
• 🐡 Backlog
  • Kanban Board
• 🐋 Benefits of EVM Agent Simulation
• 🦈 Resources
• 🏛 License

👪 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:

• TokenSPICE was initially built to model the Web3 Sustainability Loop. It's now been generalized to support EVM, on arbitary netlists.
• Most initial work was by trentmc (Ocean Protocol); several more contributors have joined since 👪👨‍👩‍👧‍👧

🏗 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

2. 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

3. 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

4. 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

5. 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

6. 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.

• TokenSPICE medium posts, starting with "Introducing TokenSPICE"
• Intro to SPICE & TokenSPICE [Gslides - short] [Gslides - long]
• TE for Ocean V3 [Gslides] [video] , TE Community Workshop, Dec 9, 2020
• TE for Ocean V4 [GSlides] [slides] [video] , TE Academy, May 21, 2021

Art:

• TokenSPICE logos
• Fishnado image sources (CC): [1] [2]

🏛 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.