l-wegner / tokenspice

EVM agent-based token simulator 🐟🌪️

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:

• Discord: te-tokenspice, First time
• Twitter: @tokenspice
• Documentation

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.

Contents

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

🏗 Initial Setup

Set up environment

Open a new terminal and:

#ensure brownie's *not* installed. It causes problems
pip uninstall eth-brownie

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

#make sure we're not in env't; remove old env'ts
conda deactivate
conda remove --name tokenspiceenv --all

#create a python-anaconda env't in location ~/anaconda3/envs/tokenspiceenv
conda env create -f environment.yml

#activate env't
conda activate tokenspiceenv

Get Ganache running

Open a new terminal and:

cd tokenspice

#activate env't
conda activate tokenspiceenv

#run ganache
./ganache.py

Note: you could run ganache directly, but then you have to add many special arguments. The script above does that for you.

Deploy the smart contracts to ganache

Open a separate terminal.

#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

conda activate tokenspiceenv
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.

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
conda activate tokenspiceenv
./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
conda activate tokenspiceenv

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

Run tests. In the same terminal as before:

#run a single pytest-based test
pytest assets/agents/test/test_DataconsumerAgent.py::test_buyDT

#run a single pytest-based test file
pytest assets/agents/test/test_DataconsumerAgent.py

#run all tests in engine/ directory
pytest assets

#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

conda activate tokenspiceenv
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.

To change dependencies, first update environment.yml. Then:

#make sure env't is active
conda activate tokenspiceenv

#main update. The 'prune' part gets rid of unused pkgs
conda env update --name tokenspiceenv --file environment.yml --prune

Leave environment:

conda deactivate

Delete environment:

conda remove --name tokenspiceenv --all

🐡 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

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.