Code and checks in TokenSPICE should strive to follow:
-[PEP 8](https://www.python.org/dev/peps/pep-0008/) Style Guide, [PEP 20](https://www.python.org/dev/peps/pep-0020/) The Zen of Python, [PEP 484](https://www.python.org/dev/peps/pep-0484/) Type Hints, [PEP 257](https://www.python.org/dev/peps/pep-0257/) Docstring conventions
- And, most specifically, [`google` docstring convention](https://google.github.io/styleguide/pyguide.html)[[2](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html)]. It's a good balance of compact, readable, and specific. Docstrings should include variable types if they are not explicitly type hints in code itself.
- pydocstyle v4.0.0 supports `google` docstring convention [[ref](http://www.pydocstyle.org/en/stable/error_codes.html#default-conventions)]. This means checks for all the errors except D203, D204, D213, D215, D400, D401, D404, D406, D407, D408, D409 and D413 .
```python
defmyfunction(param1,param2):
"""Example function with types documented in the docstring.
`PEP 484`_ type annotations are supported. If attribute, parameter, and
return types are annotated according to `PEP 484`_, they do not need to be
included in the docstring:
Args:
address: str -- Eth address
agents: set of Agent --
agent_ages: dict of {agent_name:str : agent_age:int} -- agent's ages
completed: list of int --
Returns:
bool: Success if True
"""
```
## On Tests
Ensure that the local tests are the same as remote; otherwise we'd end up fixing things we don't care about.
Codacy supports testing across many tools at once. It's easy to run remotely. However to use locally, `codacy-cli` runs slowly and churns the CPU. There are so many unimportant tests that it obscures the important ones.
Therefore, we _only_ use pylint. It's 80% of the benefit with 20% of the effort. Setup:
- Locally: just use `pylint`, not `codacy-cli`
- Remotely: use codacy, but only pylint is used
- For both, ignore the checks D203, D204, etc as specified in the Style Guide above
## Remote Tests
[Codacy](https://www.codacy.com) is automatically run _remotely_ for each commit of each PR.
-[Here's the Codacy TokenSPICE dashboard](https://app.codacy.com/gh/tokenspice/tokenspice/dashboard?branch=main), including links to tests. To access this, you need special permissions; ask Trent.
-[These "Code Patterns" settings](https://app.codacy.com/gh/tokenspice/tokenspice/patterns/list) specify what checks are run vs ignored.
## Local Tests
Use `pylint`. [Here's a pylint tutorial.](https://pylint.pycqa.org/en/latest/tutorial.html).
Here's an example. In the terminal:
```console
pylint *
```
Pylint auto-loads `./pylintrc` and uses its options, such as ignoring D203, D204.
Example pylint output:
```text
engine/SimEngine.py:9:0: W0611: Unused valuation imported from util (unused-import)
engine/AgentWallet.py:419:4: C0116: Missing function or method docstring (missing-function-docstring)
...
-----------------------------------
Your code has been rated at 8.07/10
```
To learn more about a complaint, some examples:
```console
pylint --help-msg=unused-import
pylint --help-msg=missing-function-docstring
```
## Local Fixes
There are a couple approaches to making fixes:
1. Use automated tools like [`black`](https://pypi.org/project/black/)
2. Manually
We recommend to start with (1), then clean the rest with (2).
TokenSPICE lends itself well to having tools built on top for design entry, verification, design space exploration, and more.
Here are some such tools, largely inspired by tools from circuit land.
- Each tool can have just a backend, or both a backend and frontend. A frontend with good UX can make a huge difference.
- Each tool can be applied for the initial design, before deployment. And, they can be used in real-time against *live chains*, for real-time verification, optimization, etc. How: grab the latest chain’s snapshot into ganache, run a local verification etc for a few seconds or minutes, then do transaction(s) on the live chain. This can lead to trading systems, failure monitoring, more.
## Design entry tools
- Schematic editor - be able to input netlists by editing a schematic. Examples:
-[System Dynamics](https://systemdynamics.org/what-is-system-dynamics/): [stock and flow diagrams](https://www.google.com/search?q=stock+and+flow+diagram&sxsrf=AOaemvK9W36reEyVfw54RGs3JmLiwZbTDQ:1643101186893&source=lnms&tbm=isch&sa=X&ved=2ahUKEwj358v0xMz1AhUXSPEDHZU7CwkQ_AUoAXoECAEQAw&cshid=1643101212647476&biw=1514&bih=934&dpr=1) in [Stella](https://www.iseesystems.com/store/products/stella-professional.aspx) and [Vensim](https://vensim.com/)(commercial); [full sw list](https://en.wikipedia.org/wiki/Comparison_of_system_dynamics_software)
-[Data pipelines via StreamSets](https://streamsets.com/learn/data-pipelines/)
- Auto schematic import - input a netlist, auto-generate a schematic visually. Uses optimization etc.
- Waveform viewer - build on `tsp.do_plot` with more a interactive tool. [Examples from circuits](https://www.google.com/search?q=spice+waveform+viewer&sxsrf=ALeKk02nY3U9rkOZuz58PNXWjoFY4MCcUQ:1626255741604&source=lnms&tbm=isch&sa=X&ved=2ahUKEwj9zareouLxAhXm-ioKHW0MCtgQ_AUoAXoECAEQAw&biw=1600&bih=721).
## Verification tools
Base tools:
- Corner simulation tool - simulate at pre-specified "corners". Corners are a small handful of points in random variable or worst-case variable space to simulate against. Enables rapid design-space exploration, because each you only simulate each design on corners
- Worst-case verification - verification across worst-case variables. E.g. via global optimization across worst-case variables. E.g. global synthesis across worst-case variables and agent python structures. Include corner extraction feature.
- 3-sigma verification - verification across random variables. E.g. via Monte Carlo analysis where all samples are drawn from the random variables' pdf, and each sample is simulated. Be able to simulate across >=1 worst-case corners; include stastitical extraction feature.
Advanced tools:
- High-sigma verification - verification across random variables, where catastrophic failure happens rarely, e.g. 1 in a million times (4.5 sigma) or 1 in a billion (6 sigma). E.g. using tricks from "rare event estimation" literature or [this book](https://www.amazon.com/Variation-Aware-Design-Custom-Integrated-Circuits/dp/146142268X). Be able to simulate across >=1 worst-case corners; include stastitical extraction feature.
- System identification - auto-extract a TokenSPICE netlist from raw blockchain info. To make it more tractable, use a parameterized netlist and Solidity code where possible. Ie "whitebox" not "blackbox".
- Behavioral modeling - auto-extract a lower-fidelity / faster-simulating TokenSPICE netlist from a higher-fidelity TokenSPICE netlist & simulation run, with minimal loss of error.
- Mixed-signal verification - include digital verification in the loop. Example: replace ganache with [hevm](https://fv.ethereum.org/2020/07/28/symbolic-hevm-release), which does fuzzing etc on Solidity.
- Sweep analysis - sweep design variables one at a time. Ignore interactions.
Advanced tools:
- Fast sweep analysis - sweep across all design variables including interactions, but without combinatorial explosion via model-in-the-loop
- Local optimization - search across design variables to optimize for objectives & constraints
- Global optimization - search across all design variables, with affordances to not get stuck
Extra-advanced tools:
- Synthesis - search design variables *and structure*. E.g. Evolve solidity or EVM bytecode. AI DAOs that own themselves. Go nuts:)
- Variation-aware synthesis - all of the above at once. This isn’t easy! But it’s possible. Example: use MOJITO (http://trent.st/mojito/), but use TokenSPICE (not SPICE) and Solidity building blocks (not circuit ones)
## More "Larger" Ideas for TokenSPICE
- "tsp publish" - publish sim results to Ocean
- Use Ocean to manage IP: contracts, agents, netlists, results. Or, using brownie pm? Result: TokenSPICE itself becomes super small, just an engine
- TokenSPICE inputs SPICE netlists. Pros: well-defined, battle-tested, built-in hierarchy, IP mgmt hooks, specifications of time series, compact, interoperability with SPICE tools.
- How to build / test the "SPICE format" and IP ideas: Make MOJITO work at the same time
- Deploy to pypi. Make it easy to install separately
⚠ _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 👪👨👩👧👧
