TokenSPICE: EVM Agent-Based Token Simulator 🐟🌪️

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

It can help design, tune, and verify tokenized ecosystems. It's young but promising. We welcome you to contribute! 👋

Each "agent" is a class. Has a wallet, and does work to earn $. One models the system by wiring up agents, and tracking metrics (kpis). Agents may be written in pure Python, or with an EVM-based backend.
A "netlist" defines what you simulate, and how. It wires up a collection of agents to interact in a given way. You can write your own netlists to simulate whatever you like. The assets/netlists directory has examples.

Quick links:

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); more contributors have joined since.

🏗 Initial Setup
🏄 Do Simulations, Make Changes
🦑 Agents and Netlists
🐟 Updating Envt
🐡 Backlog
- Kanban Board
🐋 Benefits of EVM Agent Simulation
🦈 Resources
🏛 License

🏗 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

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

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

tsp is the command-line module. To see help, call it with no args.

tsp

Run simulation

Here's an example on a supplied netlist simplegrant.

Simulate the netlist, storing results to outdir_csv.

tsp run assets/netlists/simplegrant/netlist.py outdir_csv

Output plots to outdir_png, and view them.

tsp plot assets/netlists/simplegrant/netlist.py outdir_csv outdir_png
eog outdir_png

Here are example plots from wsloop netlist. They track token count, tokens minted, tokens burned, and tokens granted over a 20 year period.

🏄 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

About Agents

Agents are defined at assets/agents/.
All agents are written in Python
Each Agent has an AgentWallet, which holds a Web3Wallet. The Web3Wallet holds a private key and creates TXs.
Some agents may wrap smart contracts deployed to EVM, e.g. PoolAgent.
PoolAgent and many other EVM agents wrap Ocean or Balancer smart contracts, with Python driver middleware. A good Pythonic way to get familiar with the driver middleware is to play with ocean.py. (Note that TokenSPICE currently copies-and-pastes some of that code, there is not a dependency.)

About Netlists

The netlist defines what you simulate, and how.

Netlists are defined at assets/netlists/.

You can reuse existing ones or create your own. If you create your own, please add relevant unit tests.

For your own custom simulation, you can change any part of the netlist NETLISTX:

assets/netlists/NETLISTX/SimStrategy.py which holds SimStrategy class - Simulation run parameters
assets/netlists/NETLISTX/KPIs.py which holds KPIs class, netlist_createLogData function, and netlist_plotInstructions function - What metrics to log, and how to plot them
assets/netlists/NETLISTX/SimState.py which holds SimState class - system-level structure & parameters - how agents instantiated and connected
assets/agents/*Agent.py - Individual agent structure & parameters - each agent class. To change agent structure, you'll need to change its module (py or sol code). Unit tests are recommended.

Existing netlists include:

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. EVM.
(WIP) oceanv4 - Ocean Market V4 - safer staking. EVM.

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

Improve Continuous Integration - various issues, see kanban
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.

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

Fishnado image sources (CC): [1] [2]

🏛 License

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.

smejak/tokenspice

TokenSPICE: EVM Agent-Based Token Simulator 🐟🌪️

Contents

🏗 Initial Setup

Prerequisites

Set up environment

Get Ganache running

Deploy the smart contracts to ganache

Test one EVM-based test

First usage of tsp

Run simulation

🏄 Do Simulations, Make Changes

Do Once, At Session Start

Do >=1 Times in a Session

Test that everything is working

🦑 Agents and Netlists

About Agents

About Netlists

🐟 Updating Envt

🐡 Backlog

🐋 Benefits of EVM Agent Simulation

🦈 Resources

🏛 License