⚠ _Note: as of mid 2023, this codebase is not being maintained. It might work, it might not. If you find a bug, feel free to report it, but do not expect it to be fixed. If you do a PR where tests pass, we're happy to merge it. And feel free to fork this repo and change it as you wish (including bug fixes)._
TokenSPICE simulates tokenized ecosystems via an agent-based approach, with EVM in-the-loop.
It can help in [Token](https://blog.oceanprotocol.com/towards-a-practice-of-token-engineering-b02feeeff7ca)[Engineering](https://www.tokenengineering.org) 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.](https://www.goodreads.com/quotes/7144975-i-apologize-for-such-a-long-letter---i-didn-t)
- 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 [netlists](https://github.com/tokenspice/tokenspice/tree/main/netlists) directory has examples.
# Contents
-[🏗 Initial Setup](#-initial-setup)
-[🏄 Running, Debugging](#-running-debugging)
-[🦑 Agents and Netlists](#-agents-and-netlists)
-[🐟 Updating Envt](#-updating-envt)
-[🐡 Backlog](#-backlog)
-[🐋 Benefits of EVM Agent Simulation](#-benefits-of-evm-agent-simulation)
#install brownie packages (you can ignore FileExistsErrors)
./brownie-install.sh
```
**Potential issues & workarounds**
- Issue: Brownie doesn't support Python 3.11 yet. Workaround: before "install dependencies" step above, run `pip install vyper==0.3.7 --ignore-requires-python` and `sudo apt-get install python3.11-dev`
- Issue: MacOS might flag "Unsupported architecture". Workaround: install including ARCHFLAGS: `ARCHFLAGS="-arch x86_64" pip install -r requirements.txt`
## Run Ganache
From "Prerequisites", you should have Ganache installed.
Open a new console and go to tokenspice directory. Then:
```console
source venv/bin/activate
./ganache.py
```
This will start a Ganache chain, and populate 9 accounts.
## TokenSPICE CLI
`tsp` is the command-line interface for TokenSPICE.
Open a new console and go to tokenspice directory. Then:
```console
source venv/bin/activate
#add pwd to bash path
export PATH=$PATH:.
#see tsp help
tsp
```
## Compile the contracts
NOTE: if you have a directory named `contracts` from before, which is side-by-side with your `tokenspice` directory, you'll get [issues](https://github.com/tokenspice/tokenspice/issues/160). To avoid this, rename or move that contracts directory.
From the same terminal:
```console
#install 3rd party libs, then call "brownie compile"in sol057/ and sol080/
tsp compile
```
TokenSPICE sees smart contracts as classes. How:
- When it starts, it calls `brownie.project.load('./sol057', name="MyProject")` to load the ABIs in `./sol057/build/`. Similar for `sol080`.
- That's enough info to treat each contract in `sol057/contracts/` as a _class_. Then, call `deploy()` on it to create a new _object_.
# 🏄 Running, Debugging
## Testing
From terminal:
```console
#run single test. It uses brownie, which auto-starts Ganache local blockchain node.
To see the blockchain txs apart from the other logs: open a _new_ terminal and:
```console
#activate env't
cd tokenspice
source venv/bin/activate
#run ganache
export PATH=$PATH:.
tsp ganache
```
Now, from your original terminal:
```console
#run the sim. It will auto-connect to ganache
rm -rf outdir_csv;tsp run netlists/scheduler/netlist.py outdir_csv
```
For longer runs (eg wsloop), we can log to a file while watching the console in real-time:
```console
#run the sim in the background, logging to out.txt
rm -rf outdir_csv;tsp run netlists/wsloop/netlist.py outdir_csv > out.txt 2>&1 &
#monitor in real-time
tail -f out.txt
```
To kill a sim in the background:
```console
#find the background process
ps ax |grep "tsp run"
#example result:
#223429 pts/4 Rl 0:02 python ./tsp run netlists/wsloop/netlist.py outdir_csv
#to kill it:
kill 223429
```
## Debugging from Brownie Console
Brownie console is a Python console, with some extra Brownie goodness, so that we can interactively play with Solidity contracts as Python classes, and deployed Solidity contracts as Python objects.
From terminal:
```
#brownie needs a directory with ./contracts/. Go to one.
Agents are defined at `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`](https://github.com/tokenspice/tokenspice/blob/main/engine/AgentWallet.py), which holds a [`Web3Wallet`](https://github.com/tokenspice/tokenspice/blob/main/web3tools/web3wallet.py). The `Web3Wallet` holds a private key and creates transactions (txs).
## Netlists Basics
The netlist defines what you simulate, and how.
Netlists are defined at `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 `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](https://github.com/tokenspice/tokenspice/blob/main/netlists/simplegrant/about.md)(just Python) and [simplepool](https://github.com/tokenspice/tokenspice/blob/main/netlists/simplepool/about.md)(Python+EVM).
2.**For complex netlists.** Have one or more _separate files_ for each class and method given above, such as `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](https://github.com/tokenspice/tokenspice/blob/main/netlists/wsloop/about.md) netlist is a good example. It models the [Web3 Sustainability Loop](https://blog.oceanprotocol.com/the-web3-sustainability-loop-b2a4097a36e), which is inspired by the Amazon flywheel and used by [Ocean](https://www.oceanprotocol.com), [Boson](https://www.bosonprotocol.io/) 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`](https://github.com/tokenspice/tokenspice/blob/main/engine/SimStateBase.py) has details.
Every iteration of the engine make a call to each agent's `takeStep()` method. The implementation of [`GrantGivingAgent.takeStep()`](https://github.com/tokenspice/tokenspice/blob/main/agents/GrantGivingAgent.py) 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.
<imgsrc="images/takestep.png"width="100%">
## Netlist Examples
Here are some existing netlists.
-[simplegrant](netlists/simplegrant/about.md) - granter plus receiver, that's all. No EVM.
-[simplepool](netlists/simplepool/about.md) - publisher that periodically creates new pools. EVM.
-[scheduler](netlists/scheduler/about.md) - scheduled vesting from a wallet. EVM.
-[wsloop](netlists/wsloop/about.md) - Web3 Sustainability Loop. No EVM.
To learn more about how TokenSPICE netlists are structured, we refer you to the [simplegrant](netlists/simplegrant/about.md)(pure Python) and [simplepool](netlists/simplepool/about.md)(Python+EVM) netlists, which each have more thorough explainers.
# 🐡 Backlog
Larger things we'd like to see:
-**[Higher-level tools](README-tools.md)** that use TokenSPICE, including design entry, verification, design space exploration, and more.
- Improvements to TokenSPICE itself in the form of faster simulation speed, improved UX, and more.
See this board: https://github.com/orgs/tokenspice/projects/1/views/1
# 🐋 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.
- 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](https://medium.com/tokenspice), starting with ["Introducing TokenSPICE"](https://medium.com/tokenspice/introducing-tokenspice-fb4dac98bcf9)
* TE for Ocean V3 [[GSlides](https://docs.google.com/presentation/d/1DmC6wfyl7ZMjuB-h3Zbfy--xFuYSt3tGACpgfJH9ZFk/edit)] [[video](https://www.youtube.com/watch?v=ztnIf9gCsNI&ab_channel=TokenEngineering)] , TE Community Workshop, Dec 9, 2020
* TE for Ocean V4 [[GSlides](https://docs.google.com/presentation/d/1JfFi9hT4Lf3UQKfCXGDhA27YPpPcWsXU7YArfRGAmMQ/edit#slide=id.p1)] [[slides](http://trent.st/content/20210521%20Ocean%20Market%20Balancer%20Simulations%20For%20TE%20Academy.pdf)] [[video](https://www.youtube.com/watch?v=TDG53PTbqhQ&ab_channel=TokenEngineering)] , TE Academy, May 21, 2021
History:
- TokenSPICE was [initially built to model](https://github.com/tokenspice/tokenspice0.1) the [Web3 Sustainability Loop](https://blog.oceanprotocol.com/the-web3-sustainability-loop-b2a4097a36e). It's now been generalized to support EVM, on arbitary netlists.
- Most initial work was by [trentmc](https://github.com/trentmc)([Ocean Protocol](https://www.oceanprotocol.com)); [several more contributors](https://github.com/tokenspice/tokenspice/graphs/contributors) have joined since 👪👨👩👧👧
